From: Robert Lipe <robertlipe@us...> - 2006-11-30 18:17:44
I've been giving a lot of attention to our doc in recent weeks. With
Ron's help, we've implemented a new standard that really helps the
visual presentation of our doc.
So far, we've used <screen format="linespecific"> for just about
everything we wanted to emphasize. One problem with this is that almost
none of what we used it for actually WAS screen output. The bigger
problem with it was that it required manual line breaks which didn't
work well in a variety of screen sizes and output media.
If you are showing a command meant to be typed by a user, mark it as
<command> without any backslashes. That will let us render it like this:
If you have a program listing, market it as <programlisting>. That lets
us turn on horizontal scrollbars when needed like this:
(Resize your browser window to be small if you have no idea what I'm
I'm not done tweaking the formatting and content of things yet but
that's a never-ending task. I just wanted to write down the rules of
the game since we are changing them a little bit.
I do intend to add a "conventions used in this document" and an internal
guide to docbook market within the next few days.
From: Ron Parker <ron@pa...> - 2006-12-05 15:55:53
Robert Lipe wrote:
> If you are showing a command meant to be typed by a user, mark it as
> <command> without any backslashes. That will let us render it like this:
Just a note: upon further consideration, we've changed this to
<userinput> instead of <command>. We're formatting <userinput> as a
block item rather than the default inline item, so keep that in mind
when doing the docbook dance. You might find that the output looks
better if you put user input in its own paragraph or other properly
On a mostly-unrelated note, I've just committed a change to the xsl
that's used to generate the PDF doc so that the presentation of user
input more closely matches what you see in the HTML doc.