Re: [docbook] how to represent userinput with a command option?

[Matthew Braun <mbraun@urbana.css.mot.com>]

"Robert P. J. Day" <rpjday@mindspring.com> writes:

>let's say i wanted to, as part of a <screen>, show a sample command
>  $ wc [-w] letter
>now, the standard way to represent userinput is to display it in
>bold, to emphasize that it's typed by the user.  so, as a first
>attempt:
>
><pr>$</pr> <ui>wc <op><o>-w</o></op> letter</ui>
>
>there is one major problem with how this is rendered, in that, ideally
>the entire command should be displayed in bold, *except* for the square
>brackets.  (if they're also displayed in bold, too many students will
>assume that they should type them.)
[...]

>  ouch.  is there a semantically more reasonable way to do this?
>i mean, it seems to work but, yeesh.

The thing is, something like:
     <pr>$</pr> <ui>wc <op><o>-w</o></op> letter</ui>

is IMHO semantically questionable, as it seems to be mixing <userinput>
with <cmdsynopsis>, since the brackets aren't user input.  The convention
in most books is that once you start a line with a prompt, whatever
follows can be typed verbatim.  If you don't want it typed as-is, but
just want to illustrate the command syntax, you don't add a prompt.  I'd
say that your 2nd markup, painful though it is, is...more correct.

You may want to consider how your readers will interpret this screen.
I'm used to screen shots which "Show me literal command X, and literal
output Y", so that I can determine the correspondence between the two.
By bringing optional input onto the screen, how does a reader determine
what was really typed, since what was typed has been mixed with something
(valid but) untyped?  This would make it more difficult to intuitively
correlate the command with its output.

Providing a command synopsis, and then illlustating the different options
with individual invocations might be clearer, like so:

   <screen>
    <pr>$</pr> <ui>wc letter</ui>
    <computeroutput>31  228   2182</computeroutput>

    <pr>$</pr> <ui>wc -w letter</ui>
    <computeroutput>228<computeroutput>
   </screen>


					m@

+-mbraun@urbana.css.mot.com-+- I was chasin' a ghost pale and white ----------+
|   Matt Braun -- Motorola, |    and hard to see;  The boys in blue from      |
|Urbana/Champaign Design Ctr|  Peculiar School are hangin' out in the dark    |
+CellularSubscriberSomething+-- and they're lookin' for me. ------------[SR]-+