docbook: markup for shell input
Subject:
Re: markup for shell input
From:
David Horton ####@####.####
Date:
16 Jun 2003 22:54:49 -0000
Message-Id: <3EEE4C12.7030901@megsinet.net>
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
