docbook: Thread: markup for debian package names

Is there a standard on what to use for a debian package name? It's not
really software so I don't want to use "application", it's a package...
nor is it a "command".

For those interested, here's the context:

<itemizedlist>
        <listitem>2.4.20 kernel</listitem>
        <listitem>ACPI patch that exactly matches the kernel 
        version</listitem>
        <listitem>debian packages: make, bzip2, gcc, libc6-dev, tk8.3,
        libncurses5-dev, kernel-package</listitem>
        <listitem>after you've patched the kernel add the debian packages:
acpid,
        acpi (Debian testing and unstable only)</listitem>
</itemizedlist>

Thoughts on what I should be using? I didn't have any HTML markup for them
in this section. Later I use the generic <var> when referring to them.

emma

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

Hi Emma,

That's a tough call.  An "application" is the name of a program, but if
you can type in the name of the program and run it, it's a "command."
However, since everything in Linux is a file, it's also a "filename!"

Consider this.  If you use <application> it will not change the font of
the text at all, but could be useful in indexing for instances of the
name in the tags.  If you use <command>, it will bold the text and use a
slightly different font, if you want the text to appear that way.  The
<filename> also changes the text font, but doesn't bold it.

Mind that these are based on the stylesheet being used.  IMO it's a
judgment call you'll need to make depending on what suits your own style
(what you think you can remember to use consistently).

Maybe someone else's input can help if this answer wasn't enough!

Tab


On Mon, 2003-06-16 at 14:10, Emma Jane Hogbin wrote:
> Is there a standard on what to use for a debian package name? It's not
> really software so I don't want to use "application", it's a package...
> nor is it a "command".
> 
> For those interested, here's the context:
> 
> <itemizedlist>
>         <listitem>2.4.20 kernel</listitem>
>         <listitem>ACPI patch that exactly matches the kernel 
>         version</listitem>
>         <listitem>debian packages: make, bzip2, gcc, libc6-dev, tk8.3,
>         libncurses5-dev, kernel-package</listitem>
>         <listitem>after you've patched the kernel add the debian packages:
> acpid,
>         acpi (Debian testing and unstable only)</listitem>
> </itemizedlist>
> 
> Thoughts on what I should be using? I didn't have any HTML markup for them
> in this section. Later I use the generic <var> when referring to them.
> 
> emma
-- 
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

On Mon, Jun 16, 2003 at 07:23:18PM -0700, Tabatha Marshall wrote:
> That's a tough call.  An "application" is the name of a program, but if
> you can type in the name of the program and run it, it's a "command."
> However, since everything in Linux is a file, it's also a "filename!"

I'm still not entirely sure what to do with debian packages. 

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>.

For example:

<para>There are a few different applications/daemons you will want to
install on your system: <application>acpid</application> (the daemon that will
control your hardware states),
<application>acpi</application> (the interface to monitor events and
states) are the base install. 
<application>acpi</application> Debian package is only available in
testing and unstable. If
you're running stable you won't be able to install it without playing
around with apt and your <filename>list.sources</filename> file. You can
probably
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
<option>. Another example of option would be:
	<command>vi <option>filename</option></command>
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>

If you want to, you *can* read the whole output of dmesg, but it makes
your life easier to use the <option>.

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

emma :)

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

On Mon, 2003-06-16 at 22:02, Emma Jane Hogbin wrote:
> On Mon, Jun 16, 2003 at 07:23:18PM -0700, Tabatha Marshall wrote:
> > That's a tough call.  An "application" is the name of a program, but if
> > you can type in the name of the program and run it, it's a "command."
> > However, since everything in Linux is a file, it's also a "filename!"
> 
> I'm still not entirely sure what to do with debian packages. 
> 
> 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>.

Looks like you've exercised good judgment to me!  :D

The LDP wouldn't ever get too picky over things like that.  You could
always explain the use of your conventions if a reviewer ever brought it
up.  Personally, I'm always pleased when an author takes the initiative
and uses the tags that are available.  I try not to change things when I
see it consistently throughout the source.

Your convention is thought out and makes perfect sense.

I took a look at what you have so far.  I haven't seen a lot of notes
done as entities, they're usually done inline (and LDP has graphics for
that...I have a copy of them locally if you don't but want to see 'em),
but that's NOT to say it's wrong...just different!

Looking forward to seeing your submission come through when it's all
ready!

Tab

-- 
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

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 --- ####@####.####

On Tue, Jun 17, 2003 at 01:35:19AM -0500, Martin A. Brown wrote:
>  : 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>
>  :
<snip>
> Because "-V" is a command-line option passed to the "acpi" binary,
> I'd suggest this instead:
>   <command>acpi <option>-V</option></command>

Fixed these.

>  : <option>. Another example of option would be:
>  : 	<command>vi <option>filename</option></command>

Changed this to <filename> (instead 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.

Totally re-wrote this one to:
<userinput>
        <command>dmesg</command> |
        <command>grep <parameter>ACPI.*Subsystem\ revision</parameter></command>
</userinput>

> 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).

Fixed, thank you.

> 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.

Thanks :)

> 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.

So far I've probably spent about 6 hours on it. Which is about 4 hours
more than I thought it would take me. Part of the problem for me is having
to figure out what markup I should/could be using for things that there
are no equivalent HTML tags for. I actually teach XHTML, CSS and
Javascript at the community college level. The concept of markup and
checking to see what the required structure for elements is very easy for
me. Finding an appropriate model has been much more difficult.

This is a useful page:
http://tldp.org/LDP/LDP-Author-Guide/writing-docbook.html
but it doesn't have most of the examples that I needed help with.

One thing about that file shouldn't 
Directories	
<filename id="directory">directory</filename>

be class="directory", not id="directory"? ids ought to be unique on the
page....
http://www.docbook.org/tdg/simple/en/html/filename.html

emma

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

On Tue, 2003-06-17 at 09:21, Emma Jane Hogbin wrote:
> So far I've probably spent about 6 hours on it. Which is about 4 hours
> more than I thought it would take me. Part of the problem for me is having
> to figure out what markup I should/could be using for things that there
> are no equivalent HTML tags for. I actually teach XHTML, CSS and
> Javascript at the community college level. The concept of markup and
> checking to see what the required structure for elements is very easy for
> me. Finding an appropriate model has been much more difficult.
> 
> This is a useful page:
> http://tldp.org/LDP/LDP-Author-Guide/writing-docbook.html
> but it doesn't have most of the examples that I needed help with.

I see you're already using the guide, based on your example below! That
guide always been my main source for examples.  When that fails though,
I have the PSGML in Emacs so I can go find the next valid
tag...sometimes it gives me good ideas of which I can choose from to
use.

> One thing about that file shouldn't 
> Directories	
> <filename id="directory">directory</filename>
> 
> be class="directory", not id="directory"? ids ought to be unique on the
> page....
> http://www.docbook.org/tdg/simple/en/html/filename.html

When I went to the page you quoted above, it showed the example at the
bottom correctly.  It is <filename class="directory"> (you can also use
single quotes I think, if you're consistent throughout).  In any case,
you may notice the choices by referring to the tables above when the
example is unclear.  That usually solves the problem.

Tab

-- 
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

On Tue, Jun 17, 2003 at 06:35:50PM -0700, Tabatha Marshall wrote:
> > One thing about that file shouldn't 
> > Directories	
> > <filename id="directory">directory</filename>
> > 
> > be class="directory", not id="directory"? ids ought to be unique on the
> > page....
> 
> When I went to the page you quoted above, it showed the example at the
> bottom correctly.  It is <filename class="directory"> (you can also use
> single quotes I think, if you're consistent throughout).  In any case,
> you may notice the choices by referring to the tables above when the
> example is unclear.  That usually solves the problem.

http://tldp.org/LDP/LDP-Author-Guide/writing-docbook.html
this is the page with what I think has an error. Scroll about half way
down to see the entries for Directories. In the middle column it lists:
	<filename id="directory">directory</filename>

The other page I'd listed was the docbook page which lists what I think is
the correct way.

emma

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