docbook: Thread: markup for shell input

This is my current sentence:

Do a <programlisting>locate &lt;file&gt;</programlisting>
if they're not where I think they should be.

I don't really want the <prompt> bit in there was well. How should locate
and file be marked up though? Maybe something like this:
	<programlisting><command>locate</command>
<userinput>&lt;file&gt;</userinput></programlisting>

does that look right?

thanks!	

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

Hi there again, Emma Jane,

 : This is my current sentence:

 : Do a <programlisting>locate &lt;file&gt;</programlisting>
 : if they're not where I think they should be.

I think this is entirely up to you.

 : I don't really want the <prompt> bit in there was well. How should locate
 : and file be marked up though? Maybe something like this:
 : 	<programlisting><command>locate</command>
 : <userinput>&lt;file&gt;</userinput></programlisting>

Here's how I would write that, if I were to use the programlisting
tag:

<programlisting><command>locate</command> <replaceable>file</replaceable></programlisting>

Note, that many XSLT processors will treat white space is
significant inside a programlisting element, so you probably do not
want to have a newline in the middle of your programlisting element.

 : does that look right?

I think you'll find the userinput element more natural in flowing
text...then you don't have to worry about line breaks.

<userinput><command>locate</command>
<replaceable>file</replaceable></userinput>

Smiles,

-Martin

Emma Jane Hogbin wrote:
> This is my current sentence:
> 
> Do a <programlisting>locate &lt;file&gt;</programlisting>
> if they're not where I think they should be.
> 
> I don't really want the <prompt> bit in there was well. How should locate
> and file be marked up though? Maybe something like this:
> 	<programlisting><command>locate</command>
> <userinput>&lt;file&gt;</userinput></programlisting>
> 
> does that look right?
> 
> thanks!	
> 

How about:

Do a <command>locate <parameter>file</parameter></command> if they're 
not where they should be.

Or if you are giving a literal filename, for example readme.txt:

Do a <command>locate <filename>readme.txt</filename></command> if 
they're not where they should be.

-Dave

On Mon, Jun 16, 2003 at 05:00:42PM -0500, Martin A. Brown wrote:
> Hi there again, Emma Jane,

Heh. Bored of me yet? ;)

> I think this is entirely up to you.

Noo! Don't tell me DocBook is flexible!

> Note, that many XSLT processors will treat white space is
> significant inside a programlisting element, so you probably do not
> want to have a newline in the middle of your programlisting element.
<snip>
> I think you'll find the userinput element more natural in flowing
> text...then you don't have to worry about line breaks.

Yeah, I didn't realize progralisting preserved whitespace. I'm going
through now and changing them to userinput. I'm also going through and
adding <para> to the insides of all my <listitems>. What a PITA that one
is.

emma :)

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

On Mon, Jun 16, 2003 at 05:19:47PM -0500, David Horton wrote:
> Do a <command>locate <parameter>file</parameter></command> if they're 
> not where they should be.

What's the difference between:
parameter http://docbook.org/tdg/en/html/parameter.html
parameter - A value or a symbolic reference to a value
A Parameter identifies something passed from one part of a computer system
to another. 

option http://docbook.org/tdg/en/html/option.html
option - An option for a software command
Option identifies an optional argument to a software command.

Shouldn't the file (in the example above) be marked up with an <option>
not a <parameter>?
	
I understand that
	replaceable http://docbook.org/tdg/en/html/replaceable.html
means "I'm not telling you what you should actually type, instead you
should REPLACE this word with the value that's appropriate for you."
 
> Or if you are giving a literal filename, for example readme.txt:
> Do a <command>locate <filename>readme.txt</filename></command> if 
> they're not where they should be.


Hmm. I'd not been wrapping my options/parameters with the command tag.
Instead I'd been doing it like this:
<userinput>
	<command>cd</command>
        <filename class="directory">/usr/src</filename>
</userinput>

I'd love to shorten it to remove the <userinput> if I can. thoughts?

emma :)


-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

Emma Jane Hogbin wrote:
> On Mon, Jun 16, 2003 at 05:19:47PM -0500, David Horton wrote:
> 
>>Do a <command>locate <parameter>file</parameter></command> if they're 
>>not where they should be.
> 
> 
> What's the difference between:
> parameter http://docbook.org/tdg/en/html/parameter.html
> parameter - A value or a symbolic reference to a value
> A Parameter identifies something passed from one part of a computer system
> to another. 
> 
> option http://docbook.org/tdg/en/html/option.html
> option - An option for a software command
> Option identifies an optional argument to a software command.
> 
> Shouldn't the file (in the example above) be marked up with an <option>
> not a <parameter>?
> 	

My understanding of an <option> is that the command can function without 
having it.  For example:

<command>getty <option>9600</option> 
<parameter>/dev/ttyS1</parameter></command>

I don't think getty will freak out if you do not give it a baudrate, but 
it might have a problem if no tty line is given.

In your example I was thinking that "locate" by itself does not do much, 
so it is required to have a filename given too.  That's my logic anyway.


> I understand that
> 	replaceable http://docbook.org/tdg/en/html/replaceable.html
> means "I'm not telling you what you should actually type, instead you
> should REPLACE this word with the value that's appropriate for you."
>  
> 

Sounds good.


>>Or if you are giving a literal filename, for example readme.txt:
>>Do a <command>locate <filename>readme.txt</filename></command> if 
>>they're not where they should be.
> 
> 
> 
> Hmm. I'd not been wrapping my options/parameters with the command tag.
> Instead I'd been doing it like this:
> <userinput>
> 	<command>cd</command>
>         <filename class="directory">/usr/src</filename>
> </userinput>
> 

I don't really know what's considered best form.  It just feels right to 
me that a command is something like "ls -l" or "find / -name foo.c".  I 
think it's kosher to write it either way since <parameter> and <option> 
can be a children of <command> or stand alone.  I usually just think of 
how I would say it in English.  Would I say, type the command "ls" with 
the optional parameter "-l" or would I say, type the command "ls -l"? 
Since I choose the latter, it makes since to me that "ls -l" constitutes 
the command.  Marking up the "-l" as an optional parameter is just icing 
on the cake.


> I'd love to shorten it to remove the <userinput> if I can. thoughts?
> 

I think you can do whatever makes you happy.  That's what I do, which is 
why you should not take any of what I just said as the gospel truth. 
'Cause I'm pretty new at all this and I'm just applying logic like my 
"ls -l" example as I go along.

-Dave