(note message id intentionally broke to start new thread)
On Fri, 2004-08-27 at 16:33, Karsten Wade wrote:
For expediency, I'm prepared to just submit the patch to the Doc Guide, rolling in some other dangling issues I can include. Tammy would see the CVS report and can address any mistakes and expand/modify.
Darn that cowboy mentality!
For those who chomp at the bit, you can see that I am the same myself. The above is a perfect example. Even I get impatient at process, though I recognize we need it more than I need to feel comfortable.
1. I don't own the document, although Tammy said I could do some minor bugfixes and commit them to CVS. What I just wrote is a whole new <section> not a minor fix, so that requires a new bug for tracking work on the Documentation Guide:
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131160
with an attachment of a diff against current CVS and then ....
2. An editor to look it over, which can be the first person who grabs it and confirms what I did, and who can then move it on to block bug # 129722 (ready to publish) for Tammy (in her role as a document owner) to pick up and commit to CVS, then (in the role of website maintainer) update f.r.c/participate/documentation-guide/.
To make this easier, I have opted to host this as a DRAFT version at the following URL:
http://people.redhat.com/kwade/patches/fedora-docs/documentation-guide-quaid...
The editor will want to a) wordsmith, and b) check the technical details, such as steps and information shown. Also, a check of the DocBook XML is in order.
Note thought that I broke rules from the Documentation Guide:
1. I used a meaningful ID for <sect1>, dropping the location and section specific information. At this point, the most legitimate debate is between "similar-to-title" and "s.similar.to.title", the latter being Norm Walsh's current usage.
2. My <screen> tags themselves are not flush left, although the content is. I think that information described on this page:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen....
is a legacy SGML problem. My builds show that the following:
<screen> foo </screen> <screen> foo </screen> <screen> foo </screen>
renders as:
foo foo foo
Obviously the contents of the <screen/> are highly sensitive to whitespace issues, and in fact could perhaps be CDATA containers instead to totally make them ignored by the toolchain. Either way, I don't think the <screen> tags need to be flush left, nor the the <computeroutput/> container. I'd like to recommend this for a change in the Documentation Guide, and will file a bugzilla with patch if there is no technical objection.
- Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/
On Fri, 2004-08-27 at 21:34, Karsten Wade wrote:
(note message id intentionally broke to start new thread)
I probably should have done that, sorry.
[...snip...]
- I don't own the document, although Tammy said I could do some minor
bugfixes and commit them to CVS. What I just wrote is a whole new
<section> not a minor fix, so that requires a new bug for tracking work on the Documentation Guide:
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131160
with an attachment of a diff against current CVS and then ....
- An editor to look it over, which can be the first person who grabs it
and confirms what I did, and who can then move it on to block bug # 129722 (ready to publish) for Tammy (in her role as a document owner) to pick up and commit to CVS, then (in the role of website maintainer) update f.r.c/participate/documentation-guide/.
I'll take you up on that, seeing as how I haven't hit the hay quite yet.
To make this easier, I have opted to host this as a DRAFT version at the following URL:
http://people.redhat.com/kwade/patches/fedora-docs/documentation-guide-quaid...
The editor will want to a) wordsmith, and b) check the technical details, such as steps and information shown. Also, a check of the DocBook XML is in order.
Honestly, I didn't see much to do with (a). I made a couple of changes which I thought at the time were good ideas. On the other hand, I'm getting sleepy.
Note thought that I broke rules from the Documentation Guide:
- I used a meaningful ID for <sect1>, dropping the location and section
specific information. At this point, the most legitimate debate is between "similar-to-title" and "s.similar.to.title", the latter being Norm Walsh's current usage.
I like using meaningful ID's; I have moved to using <section> tags, with "sn-meaningful-title". Modularity, check. Easy to grab all element-related ID's with a regex, also check.
- My <screen> tags themselves are not flush left, although the content
is. I think that information described on this page:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen....
is a legacy SGML problem. My builds show that the following:
<screen>foo </screen>
<screen> foo </screen> <screen> foo </screen>
renders as:
foo foo foo
Obviously the contents of the <screen/> are highly sensitive to whitespace issues, and in fact could perhaps be CDATA containers instead to totally make them ignored by the toolchain. Either way, I don't think the <screen> tags need to be flush left, nor the the <computeroutput/> container. I'd like to recommend this for a change in the Documentation Guide, and will file a bugzilla with patch if there is no technical objection.
I have seen the most problem in the PDF builds, but the HTML builds also seem to do funny stuff with more vertical space if you don't run your first and last text against the opening and closing <screen> tags, respectively. In other words, given these two examples:
<!-- first example --> <screen> <computeroutput> foo bar </computeroutput> </screen>
<!-- second example --> <screen><computeroutput>foo bar</computeroutput></screen>
The second example renders into a more pleasing vertical context, without a lot of wasted space. The PDF, IIRC, was particularly ugly if you didn't use the second form, but I seem to remember the HTML also was noticeably different.
I posted an additive patch to Bugzilla for you to take a look at. I feel a little strange correcting work by someone who does this for a living, when I'm more of a dilettante. Hope the editing sparks something positive.
- Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/
Very good movie! Not that it's necessarily going to be at a Guerilla Drive-In, but if you like "Run Lola Run," you should see Tom Tykwer's film of Krzysztof Kieslowki's "Heaven," if you haven't already. (Sorry for going OT at the end there. Now I'm going TB as well.)
On Sat, 2004-08-28 at 05:47, Paul W. Frields wrote:
I have seen the most problem in the PDF builds, but the HTML builds also seem to do funny stuff with more vertical space if you don't run your first and last text against the opening and closing <screen> tags, respectively. In other words, given these two examples:
<!-- first example -->
<screen> <computeroutput> foo bar </computeroutput> </screen>
<!-- second example -->
<screen><computeroutput>foo bar</computeroutput></screen>
The second example renders into a more pleasing vertical context, without a lot of wasted space. The PDF, IIRC, was particularly ugly if you didn't use the second form, but I seem to remember the HTML also was noticeably different.
What processing tools Paul? And why is computeroutput necessary within screen? I'd have thought an either or was more reasonable for the processor to sort out?
On Sat, 2004-08-28 at 06:30, Dave Pawson wrote:
I have seen the most problem in the PDF builds, but the HTML builds also seem to do funny stuff with more vertical space if you don't run your first and last text against the opening and closing <screen> tags, respectively. In other words, given these two examples:
<!-- first example -->
<screen> <computeroutput> foo bar </computeroutput> </screen>
<!-- second example -->
<screen><computeroutput>foo bar</computeroutput></screen>
The second example renders into a more pleasing vertical context, without a lot of wasted space. The PDF, IIRC, was particularly ugly if you didn't use the second form, but I seem to remember the HTML also was noticeably different.
What processing tools Paul? And why is computeroutput necessary within screen? I'd have thought an either or was more reasonable for the processor to sort out?
I'm using the standard toolset and practices from the Documentation Guide. Maybe that piece should be revisited in the Documentation Guide, which indicates the proper syntax looks like this:
<screen><userinput>cmd -i arg1</userinput> <computeroutput>Uh-uh, you can't do that.</computeroutput></screen>
I certainly have no problem doing it some other way... If someone knows that this is wrong or confusing to most (or all?) toolsets, file a bug against the documentation-guide so we can track and fix it.
On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote:
On Sat, 2004-08-28 at 06:30, Dave Pawson wrote:
What processing tools Paul? And why is computeroutput necessary within screen? I'd have thought an either or was more reasonable for the processor to sort out?
I am advocating:
<screen> <![CDATA[ foo { bar () } ]]> </screen>
Same for <programlisting/> blocks.
This material, in the Fedora Doc Guide, is historical practice that we can (and should) revise.
I'm using the standard toolset and practices from the Documentation Guide. Maybe that piece should be revisited in the Documentation Guide, which indicates the proper syntax looks like this:
<screen><userinput>cmd -i arg1</userinput> <computeroutput>Uh-uh, you can't do that.</computeroutput></screen>
That's not what I see on this page:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen....
- Karsten
On Mon, 2004-08-30 at 17:40, Karsten Wade wrote:
On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote:
On Sat, 2004-08-28 at 06:30, Dave Pawson wrote:
What processing tools Paul? And why is computeroutput necessary within screen? I'd have thought an either or was more reasonable for the processor to sort out?
I am advocating:
<screen> <![CDATA[ foo { bar () } ]]> </screen>
Same for <programlisting/> blocks.
This material, in the Fedora Doc Guide, is historical practice that we can (and should) revise.
I'm using the standard toolset and practices from the Documentation Guide. Maybe that piece should be revisited in the Documentation Guide, which indicates the proper syntax looks like this:
<screen><userinput>cmd -i arg1</userinput> <computeroutput>Uh-uh, you can't do that.</computeroutput></screen>
That's not what I see on this page:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen....
You're right. I think I changed this in my usage because the extra linefeeds were causing the PDF rendering to use WAY too much vertical space. Would a bug report for that go against xmlto, then? And how does your recommendation fare for those purposes?
On Mon, 2004-08-30 at 15:11, Paul W. Frields wrote:
On Mon, 2004-08-30 at 17:40, Karsten Wade wrote:
That's not what I see on this page:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen....
You're right. I think I changed this in my usage because the extra linefeeds were causing the PDF rendering to use WAY too much vertical space. Would a bug report for that go against xmlto, then? And how does your recommendation fare for those purposes?
Hey, you're doing great if you can even get a PDF. :) I must be doing something in the SGML way that xmlto doesn't like.
It sounds like starting with a bug to xmlto would be a good idea; I created a sample XML document that shows all the variations; the source and PDF output can be attached to the bug report:
http://people.redhat.com/kwade/fedora-docs/process-docs/xmlto-whitespace-tes...
I pasted the TXT output below this message, for discussion
FWIW, this PDF builds for me, so my non-PDF building docs must have an error of some kind in the XML.
I do know that we will need to keep our content on separate lines than the tags. This is a sanity checking device. If you have a code or configuration file:
foo { bar { some.call () } }
and the first and lines of that are flush with tags, e.g.:
<programlisting>foo { bar { some.call () } }</programlisting>
it is hard to tell if the code indenting is correct, which matters in many contexts. This simple example is easy to fix, but complex examples are much harder, as I have personally experienced many times.
## begin sample output
xmlto test of whitespace usage
Karsten Wade
Copyright © 2004 Red Hat, Inc. _________________________________________________________
Table of Contents
xmlto test
xmlto test
Here are some self-referential examples:
Example 1. Stacked Tags - Source
<screen><computeroutput>foo { bar { some.call () } }</computeroutput></screen>
Example 2. Stacked Tags - Output foo { bar { some.call () } }
Example 3. Stacked and Broke - Source
<screen><computeroutput> foo { bar { some.call () } } </computeroutput></screen>
Example 4. Stacked and Broke - Output foo { bar { some.call () } }
Example 5. All Flush Left - Source
<screen> <computeroutput> foo { bar { some.call () } } </computeroutput> </screen>
Example 6. All Flush Left - Output
foo { bar { some.call () } }
Example 7. Only Content Flush Left - Source
<screen> <computeroutput> foo { bar { some.call () } } </computeroutput> </screen>
Example 8. Only Content Flush Left - Output
foo { bar { some.call () } }
## end sample output
On Mon, 2004-08-30 at 21:21, Karsten Wade wrote:
I do know that we will need to keep our content on separate lines than the tags. This is a sanity checking device. If you have a code or configuration file:
foo { bar { some.call () } }
and the first and lines of that are flush with tags, e.g.:
<programlisting>foo { bar { some.call () } }</programlisting>
it is hard to tell if the code indenting is correct, which matters in many contexts. This simple example is easy to fix, but complex examples are much harder, as I have personally experienced many times.
Agreed. I didn't like having to stack tags one bit from a readability standpoint, but I figured the end justified the means (i.e. readable output). If this part of xmlto (or something else) needs fixing, it would be great if someone could identify what's broken.
With regard to your test ([...snipped...]), I think that examples 1-2 prove my point. Example 2 shows a rendering with the least amount of extra vertical whitespace surrounding the actual code snippet. That's what I was seeing as well, and why I started stacking tags.
If wiser heads think that I am putting the cart before the horse there, I'm happy to comply. Just means I can read it easier while editing, anyway! :-)
On Tue, 2004-08-31 at 11:15, Paul W. Frields wrote:
Agreed. I didn't like having to stack tags one bit from a readability standpoint, but I figured the end justified the means (i.e. readable output). If this part of xmlto (or something else) needs fixing, it would be great if someone could identify what's broken.
With regard to your test ([...snipped...]), I think that examples 1-2 prove my point. Example 2 shows a rendering with the least amount of extra vertical whitespace surrounding the actual code snippet. That's what I was seeing as well, and why I started stacking tags.
It looks like it is just a function of the whitespace. The new line following the <computeroutput> tag is interpreted and inserted into the output. I think it's a visual thing we shouldn't worry about; it doesn't make the output an harder to read with the extra line, but it makes the XML lots easier to read and maintain.
- Karsten
On Mon, 2004-08-30 at 23:11, Paul W. Frields wrote:
You're right. I think I changed this in my usage because the extra linefeeds were causing the PDF rendering to use WAY too much vertical space.
If the xml-pdf processor is fop, check out the known bug list; Whitespace expectation in the xslt stylsheets are a long way ahead of fop, which is catching up quite markedly.
On Mon, 2004-08-30 at 17:40, Karsten Wade wrote:
On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote:
On Sat, 2004-08-28 at 06:30, Dave Pawson wrote:
What processing tools Paul? And why is computeroutput necessary within screen? I'd have thought an either or was more reasonable for the processor to sort out?
I am advocating:
<screen> <![CDATA[ foo { bar () } ]]> </screen>
Same for <programlisting/> blocks.
This material, in the Fedora Doc Guide, is historical practice that we can (and should) revise.
There are 2 reasons why the style guide says to include computeroutput or userinput tags inside screen tags:
1. Technically, the content is computeroutput or userinput and should be marked accordingly to make it more correct 2. Marking them as computeroutput and userinput allows the text to be styled using CSS for the HTML version.
Tammy
I'm using the standard toolset and practices from the Documentation Guide. Maybe that piece should be revisited in the Documentation Guide, which indicates the proper syntax looks like this:
<screen><userinput>cmd -i arg1</userinput> <computeroutput>Uh-uh, you can't do that.</computeroutput></screen>
That's not what I see on this page:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen....
- Karsten
-- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
On Mon, 2004-08-30 at 18:41, Tammy Fox wrote:
On Mon, 2004-08-30 at 17:40, Karsten Wade wrote:
On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote:
On Sat, 2004-08-28 at 06:30, Dave Pawson wrote:
What processing tools Paul? And why is computeroutput necessary within screen? I'd have thought an either or was more reasonable for the processor to sort out?
I am advocating:
<screen> <![CDATA[ foo { bar () } ]]> </screen>
Same for <programlisting/> blocks.
This material, in the Fedora Doc Guide, is historical practice that we can (and should) revise.
There are 2 reasons why the style guide says to include computeroutput or userinput tags inside screen tags:
- Technically, the content is computeroutput or userinput and should be
marked accordingly to make it more correct 2. Marking them as computeroutput and userinput allows the text to be styled using CSS for the HTML version.
We've moved into very fine lines of distinction here.
In many situations, I'm not even sure I want any styling for the contents of _some_ of my <screen> and <programlisting> blocks (esp. <programlisting>). It should be unstyled fixed-width fonts, no bold, no extra fancy characters, no matter if it's utf-8 or iso-whatever.
However, Tammy's poing in 1) above is important -- perhaps the only thing that _should_ be in a <screen> block is STDIN (<userinput>) or STDOUT (<computeroutput>).
If that is the case, then we wouldn't use CDATA blocks for <screen>. FWIW, putting CDATA in e.g. <computeroutput/> does not validate, but it does build PDF and HTML.
It seems that my examples using foo {} is actually incorrect; that should be a <programlisting> block which should probably always use CDATA.
Sounds like I might be reversing myself!
How about this:
* We modify current usage rules to show a couple of acceptable styles and which ones are likely to break or cause problems. Specify that the point is not XML styling but quality of output -- if your code gets the desired output of no extra vertical or horizontal whitespace in PDF or HTML, then it's fine.
* <screen> has <computeroutput> or <userinput> within it to be semantically correct.
* <programlisting> always uses a CDATA section to preserve every detail from processing (XSL and CSS included).
- Karsten
On Tue, 2004-08-31 at 18:33, Karsten Wade wrote:
In many situations, I'm not even sure I want any styling for the contents of _some_ of my <screen> and <programlisting> blocks (esp. <programlisting>). It should be unstyled fixed-width fonts, no bold, no extra fancy characters, no matter if it's utf-8 or iso-whatever.
<grin/> Which is a pretty good definition of a style IMHO.
If that is the case, then we wouldn't use CDATA blocks for <screen>. FWIW, putting CDATA in e.g. <computeroutput/> does not validate, but it does build PDF and HTML.
Its not a validity issue. Simply well-formedness.
- We modify current usage rules to show a couple of acceptable styles
and which ones are likely to break or cause problems. Specify that the point is not XML styling but quality of output -- if your code gets the desired output of no extra vertical or horizontal whitespace in PDF or HTML, then it's fine.
-1. I'd have thought the project needs valid XML instances.
- <screen> has <computeroutput> or <userinput> within it to be
semantically correct.
Why isn't screen 'right' for the contents of the screen? Or if you are talking about a programs output, or a user input, then use computeroutput or userinput.
- <programlisting> always uses a CDATA section to preserve every detail
from processing (XSL and CSS included).
But thats the point of stylesheets Karsten, to apply style.
http://www.w3.org/TR/2004/REC-xml-20040204/#sec-cdata-sect
An example of a CDATA section, in which "<greeting>" and "</greeting>" are recognized as character data, not markup:
<![CDATA[<greeting>Hello, world!</greeting>]]>
That's all CDATA sections do.
On Tue, 2004-08-31 at 10:48, Dave Pawson wrote:
On Tue, 2004-08-31 at 18:33, Karsten Wade wrote:
In many situations, I'm not even sure I want any styling for the contents of _some_ of my <screen> and <programlisting> blocks (esp. <programlisting>). It should be unstyled fixed-width fonts, no bold, no extra fancy characters, no matter if it's utf-8 or iso-whatever.
<grin/> Which is a pretty good definition of a style IMHO.
Ha! You caught me there.
You can tell by my flip-flopping and half-thought-through opinions that I'm not quite sure what is the best thing to do, which usually means it's time to pick something that works and move on.
If that is the case, then we wouldn't use CDATA blocks for <screen>. FWIW, putting CDATA in e.g. <computeroutput/> does not validate, but it does build PDF and HTML.
Its not a validity issue. Simply well-formedness.
Odd, I did C-c C-v and got some validation errors, which, uh, aren't occurring now. *shrug*
- We modify current usage rules to show a couple of acceptable styles
and which ones are likely to break or cause problems. Specify that the point is not XML styling but quality of output -- if your code gets the desired output of no extra vertical or horizontal whitespace in PDF or HTML, then it's fine.
-1. I'd have thought the project needs valid XML instances.
Which instances are valid and which are not?
I only meant, valid XML usage. Is there only one "right way"? If so, then I guess this whole discussion is no longer moot!
- <screen> has <computeroutput> or <userinput> within it to be
semantically correct.
Why isn't screen 'right' for the contents of the screen? Or if you are talking about a programs output, or a user input, then use computeroutput or userinput.
I would reckon that the usage came about this way from wanting to mark all user input as <userinput> and all screen output as <computeroutput>, whether it is inline in a <para/> or blocked in a <screen/>.
The idea would be, it should be marked as <...input/> or <...output/> in all instances.
However, those tags cannot stand alone the way <screen> can. <screen/> must be used to get the desired styling output. Just putting <para> tags around the <...put/> tags would not be the same thing, semantically or stylistically.
I'm guessing as to that reasoning; Ed or Tammy would be better to answer that.
That reasoning makes some amount of sense to me.
- <programlisting> always uses a CDATA section to preserve every detail
from processing (XSL and CSS included).
But thats the point of stylesheets Karsten, to apply style.
http://www.w3.org/TR/2004/REC-xml-20040204/#sec-cdata-sect
An example of a CDATA section, in which "<greeting>" and "</greeting>" are recognized as character data, not markup:
<![CDATA[<greeting>Hello, world!</greeting>]]>
That's all CDATA sections do.
Okay, I concede that I'm getting myself into a confused corner.
For maintainability and ease of handing off documents to others for editing and writing, I find using CDATA inside <programlisting> to be invaluable. Perhaps we don't make this a hard requirement, just fix the stylesheets so <programlisting> content output looks the same regardless of CDATA usage (it may already do that), and leave it up to the author.
- Karsten
On Mon, 2004-08-30 at 22:40, Karsten Wade wrote:
I am advocating:
<screen> <![CDATA[ foo { bar () } ]]> </screen>
Same for <programlisting/> blocks.
Which is identical to <screen> < blah blah, </screen>
I.e. Just a processor frig.
In the example you've shown they are identical, with / without CDATA wrapper, since there is nothing needing escaping.
On Tue, 2004-08-31 at 10:05, Dave Pawson wrote:
On Mon, 2004-08-30 at 22:40, Karsten Wade wrote:
I am advocating:
<screen> <![CDATA[ foo { bar () } ]]> </screen>
Same for <programlisting/> blocks.
Which is identical to
<screen> < blah blah, </screen>
I.e. Just a processor frig.
In the example you've shown they are identical, with / without CDATA wrapper, since there is nothing needing escaping.
Don't let the example rule the usage.
Anyone who has had to convert many lines of XML, HTML, or other languages to use entities such as < and > knows what a pain it is to maintain. You can't tell from the source what you are looking at.
- Karsten
On Tue, 2004-08-31 at 18:12, Karsten Wade wrote:
Don't let the example rule the usage.
My point was they are identical. There is no advantage one to the other.
Anyone who has had to convert many lines of XML, HTML, or other languages to use entities such as < and > knows what a pain it is to maintain. You can't tell from the source what you are looking at.
Which is why I a) process heavy markup externally. 1. replace & 2. replace < b) use emacs colouring to 'see' the content.
On Fri, 2004-08-27 at 21:47, Paul W. Frields wrote:
On Fri, 2004-08-27 at 21:34, Karsten Wade wrote:
Note thought that I broke rules from the Documentation Guide:
- I used a meaningful ID for <sect1>, dropping the location and section
specific information. At this point, the most legitimate debate is between "similar-to-title" and "s.similar.to.title", the latter being Norm Walsh's current usage.
I like using meaningful ID's; I have moved to using <section> tags, with "sn-meaningful-title". Modularity, check. Easy to grab all element-related ID's with a regex, also check.
Okay, so the proposals for new ID generation rules are:
1. "similar-to-title" 2. "s.similar.to.title" 3. "sn-similar-to-title"
I combined "meaningful" and "similar to" under the idea that an ID should closely match the title and have the same meaning as title, but not necessarily be the same length as the title (which could be very long).
I have seen the most problem in the PDF builds, but the HTML builds also seem to do funny stuff with more vertical space if you don't run your first and last text against the opening and closing <screen> tags, respectively. In other words, given these two examples:
<!-- first example -->
<screen> <computeroutput> foo bar </computeroutput> </screen>
<!-- second example -->
<screen><computeroutput>foo bar</computeroutput></screen>
The second example renders into a more pleasing vertical context, without a lot of wasted space. The PDF, IIRC, was particularly ugly if you didn't use the second form, but I seem to remember the HTML also was noticeably different.
I can't get anything to build PDF right now to test this, but in HTML I see the same thing as output, so am not sure of the advantage of the different way you suggest it.
I do notice that doing sgml-fill-paragraph will make them line up like:
<screen><computeroutput>foo bar</computeroutput></screen>
Then introducing the line break gets the functionality you mention.
Ultimately, I think we will want to drop the redundant <computeroutput> and use a CDATA container instead. In that case, _all_ whitespace will be considered for certain. All content will need to use the left margin of the XML as starting point for indention.
I posted an additive patch to Bugzilla for you to take a look at. I feel a little strange correcting work by someone who does this for a living, when I'm more of a dilettante. Hope the editing sparks something positive.
I'll look today.
- Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/
Very good movie! Not that it's necessarily going to be at a Guerilla Drive-In, but if you like "Run Lola Run," you should see Tom Tykwer's film of Krzysztof Kieslowki's "Heaven," if you haven't already. (Sorry for going OT at the end there. Now I'm going TB as well.)
I'll suggest it; I've seen RLR before, it was a cool experience. I may throw up some paras about it on blogs.redhat.com/people.
- Karsten
Karsten Wade wrote:
Okay, so the proposals for new ID generation rules are:
- "similar-to-title"
- "s.similar.to.title"
- "sn-similar-to-title"
I vote for
1 (b). s.similar-to-title
as it provides a different separator to distinguish structural info from semantic, content-related info.
I have seen the most problem in the PDF builds, but the HTML builds also seem to do funny stuff with more vertical space if you don't run your first and last text against the opening and closing <screen> tags, respectively. In other words, given these two examples:
<!-- first example -->
<screen> <computeroutput> foo bar </computeroutput> </screen>
<!-- second example -->
<screen><computeroutput>foo bar</computeroutput></screen>
The second example renders into a more pleasing vertical context, without a lot of wasted space. The PDF, IIRC, was particularly ugly if you didn't use the second form, but I seem to remember the HTML also was noticeably different.
I can't get anything to build PDF right now to test this, but in HTML I see the same thing as output, so am not sure of the advantage of the different way you suggest it.
I do notice that doing sgml-fill-paragraph will make them line up like:
<screen><computeroutput>foo bar</computeroutput></screen>
Then introducing the line break gets the functionality you mention.
Ultimately, I think we will want to drop the redundant <computeroutput> and use a CDATA container instead. In that case, _all_ whitespace will be considered for certain. All content will need to use the left margin of the XML as starting point for indention.
FWIW, I've switched over to <screen><![CDATA[ ...verbatim content... ]]></screen> with no ill effects (yet).
Example:
<screen><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">]]></screen>
There are those times when having the capability of just dumping your content into a CDATA section can really simplify the markup.
OTOH, if the HTML/CSS styling issue Tammy brings up presents problems, then I'd support using <computeroutput>.
FWIW, the <screen><computeroutput> combo doesn't seem to add anymore semantic info due to overlap in meaning between the two elements.
My $0.02, Mark
On Sat, 2004-08-28 at 02:34, Karsten Wade wrote:
- My <screen> tags themselves are not flush left, although the content
is.
My builds show that the following:
<screen>foo </screen>
<screen> foo </screen> <screen> foo </screen>
renders as:
foo foo foo
Obviously the contents of the <screen/> are highly sensitive to whitespace issues,
Yes, whitespace is respected within the tags. Since a dtd is in use, the intertag space is non-existant to the parser.
and in fact could perhaps be CDATA containers instead to totally make them ignored by the toolchain. Either way, I don't think the <screen> tags need to be flush left, nor the the <computeroutput/> container. I'd like to recommend this for a change in the Documentation Guide, and will file a bugzilla with patch if there is no technical objection.
No bug. Just XML :-) Without a schema, you'd have to tell the processor something about whitespace treatment, collapse or preserve.
-
Dave Pawson -
Karsten Wade -
Mark Johnson -
Paul W. Frields -
Tammy Fox