Date: Sat, 15 Jul 2000 03:10:36 +0000 From: Nik Clayton <nik@freebsd.org> To: Neil Blakey-Milner <nbm@mithrandr.moria.org> Cc: Ben Smithurst <ben@FreeBSD.org>, Nik Clayton <nik@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: FAQ addition Message-ID: <20000715031036.A20004@kilt.nothing-going-on.org> In-Reply-To: <20000714102522.A61949@mithrandr.moria.org>; from nbm@mithrandr.moria.org on Fri, Jul 14, 2000 at 10:25:22AM %2B0200 References: <396A79E9.F3AD3D1@home.com> <20000713011414.B11472@kilt.nothing-going-on.org> <20000713213435.M48641@strontium.scientia.demon.co.uk> <20000714102522.A61949@mithrandr.moria.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Jul 14, 2000 at 10:25:22AM +0200, Neil Blakey-Milner wrote:
> Also <application> instead of <command>. My (limited) understanding is
> when you're talking about a program or group of programs, it's
> <application>, and if you're talking about a somewhat specific command
> (like "rm -rf /"), it's <command>. You could just skip that, and use
> &man.top.1; *grin*.
>
> Nik, can you give me a refresher? (:
S'in the primer.
N
==
4.2.5.2. Applications, commands, options, and cites
You will frequently want to refer to both applications and commands
when writing for the Handbook. The distinction between them is simple:
an application is the name for a suite (or possibly just 1) of
programs that fulfil a particular task. A command is the name of a
program that the user can run.
In addition, you will occasionally need to list one or more of the
options that a command might take.
Finally, you will often want to list a command with its manual section
number, in the ``command(number)'' format so common in Unix manuals.
Mark up application names with <application>.
When you want to list a command with its manual section number (which
should be most of the time) the DocBook element is <citerefentry>.
This will contain a further two elements, <refentrytitle> and
<manvolnum>. The content of <refentrytitle> is the name of the
command, and the content of <manvolnum> is the manual page section.
This can be cumbersome to write, and so a series of general entities
have been created to make this easier. Each entity takes the form
&man.manual-page.manual-section;.
The file that contains these entities is in
doc/share/sgml/man-refs.ent, and can be referred to using this FPI:
PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"
Therefore, the introduction to your documentation will probably look
like this:
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//E
N">
%man;
...
]>
Use <command> when you want to include a command name ``in-line'' but
present it as something the user should type in.
Use <option> to mark up a command's options.
This can be confusing, and sometimes the choice is not always clear.
Hopefully this example makes it clearer.
Example 4-36. Applications, commands, and options.
Use:
<para><application>Sendmail</application> is the most
widely used Unix mail application.</para>
<para><application>Sendmail</application> includes the
<citerefentry>
<refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, &man.sendmail.8;, and &man.newaliases.8;
programs.</para>
<para>One of the command line parameters to <citerefentry>
<refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>, <option>-bp</option>, will display the current
status of messages in the mail queue. Check this on the command
line by running <command>sendmail -bp</command>.</para>
Appearance:
Sendmail is the most widely used Unix mail application.
Sendmail includes the sendmail(8), mailq(8), and newaliases(8) programs.
One of the command line parameters to sendmail(8)
, -bp, will display the current status of messages in the mail queue.
Check this on the command line by running sendmail -bp.
==
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000715031036.A20004>