From owner-freebsd-doc  Sun Jul 16 16: 0:49 2000
Delivered-To: freebsd-doc@freebsd.org
Received: from nothing-going-on.demon.co.uk (unknown [206.79.44.65])
	by hub.freebsd.org (Postfix) with ESMTP
	id EC36937BF2D; Sun, 16 Jul 2000 15:59:59 -0700 (PDT)
	(envelope-from nik@nothing-going-on.demon.co.uk)
Received: (from nik@localhost)
	by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id DAA20473;
	Sat, 15 Jul 2000 03:10:36 GMT
	(envelope-from nik)
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>
References: <396A79E9.F3AD3D1@home.com> <20000713011414.B11472@kilt.nothing-going-on.org> <20000713213435.M48641@strontium.scientia.demon.co.uk> <20000714102522.A61949@mithrandr.moria.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.2i
In-Reply-To: <20000714102522.A61949@mithrandr.moria.org>; from nbm@mithrandr.moria.org on Fri, Jul 14, 2000 at 10:25:22AM +0200
Organization: FreeBSD Project <URL:http://www.freebsd.org/>
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

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