docbook: markup for debian package names
Subject:
Re: markup for debian package names
From:
"Martin A. Brown" ####@####.####
Date:
17 Jun 2003 06:34:59 -0000
Message-Id: <Pine.LNX.4.55.0306170105140.9585@enclitic.wonderfrog.net>
Hello there Emma,
: In the mean time I've made the following convention for myself:
: if I'm referring to something that I can get manpages for then I
: call it an <application>. If I'm referring to actually typing the
: word in at the prompt then I call it a <command>.
Seems perfectly reasonable to me. I have wrestled with the question
of an application vs. a command before, and I have always (rather
lamely) used <constant>, which I know to be wrong. The good thing
is that I have made a habit of using entities....
I think I'll take your lead here (thanks for explaining your
rationale), and alter my entity.
[...snipped a bunch of good stuff...]
: also compile from source. If you do get <application>acpi</application>
: installed you can use it to monitor your system like this: <command>acpi
: <parameter>-V</parameter></command>
:
: In this case I'm using <parameter> instead of option because you really do
: have to use -V to get the output that I show. If it doesn't matter which
: you choose (e.g. module or compile directly into the kernel) then I use
OK! I'm not sure I'm correct here, but this seems counter to the
general meanings of the words parameter and option in command-line
semantics.
Because "-V" is a command-line option passed to the "acpi" binary,
I'd suggest this instead:
<command>acpi <option>-V</option></command>
: <option>. Another example of option would be:
: <command>vi <option>filename</option></command>
Similarly, I would say the above is better as:
<command>vi <replaceable>filename</replaceable></command>
or
<command>vi <parameter>filename</parameter></command>
Because calling "vi" with this positional parameter is distinctly
not an option to "vi", but rather an argument, correct?
: You don't have to put the filename there, but it does make things a little
: faster. And my last example of <option>
: <command>dmesg
: <option>| grep ACPI.*Subsystem\ revision</option></command>
I think you mean "option" only in the sense of "optional". There is
a DocBook tag "optional", which may be what you intend here.
Because "grep" is a command in its own right, it doesn't strike me
as an accurate way to mark up the text.
: If you want to, you *can* read the whole output of dmesg, but it makes
: your life easier to use the <option>.
Indeed....grep is my best friend. It's a lonely life on the command
line, but at least there's grep! :)
NOW! I must refer you to Tabatha's remarks of her previous email.
I seriously doubt that any TLDP reviewer (currently Tabatha,
although others recently expressed interest and willingness to help)
will refuse to accept your document because of such choices.
<joke>So...put your tags up! This is a markup.</joke>
: For those of you who are interested, I'm about 3/4 done the
: HTML->DocBook conversion. The file is currently available here:
: http://xtrinsic.com/geek/articles/drafts/acpi.sgml
I looked it over briefly, and it validates pretty well as XML (I
don't know how to do the SGML stuff), but I did find to oddities you
may wish to examine.
You have two "</articleinfo>" tags, one at line 37 and one at line
50.
You have no "</revision>" tag after line 42 (and before line 43).
Now, I have to say--that's starting to look like some good
DocBook--sure there's a bit more to go before you are done, but it
looks (generally) pretty good to me.
I don't know if you are concerned about this, but after writing some
DocBook for a while, I decided that I was going to stop using the
tags <sect1/> <sect2/>, and instead use <section/>. This allows me
to move sections around freely without worrying too much about
nesting. An unintended benefit (for me) is my lack of concern now
about depth of nested sections. I don't see any reason for you to
change what you have done, though....
I'd love to know (if you feel like sharing your experience) how much
time you spent learning the DocBook structure and tags, and how
difficult the experience was.
Ciao for now,
-Martin
--
Martin A. Brown --- Wonderfrog Enterprises --- ####@####.####
