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>