Re: [docbook-tc] Bob's action item

[Bob Stayton <bobs@sco.com>]

On Mon, Mar 24, 2003 at 03:11:44PM -0800, Dennis Evans wrote:
> Bob,
> 
> I have a question. I see how the sgml is translated into HTML but how would 
> this be handled when the output is nroff?

However you want it to be.  8^)

There is no standard mechanism in man to handle multiple
names and purposes.  The trick is to get the information
into the whatis database so apropos can find it.
For our HTML man pages, we embed the extra information
in comments and our makewhatis utility knows how to
extract it.  Our man command also knows how to display
HTML man pages (basically using lynx -dump), so we don't
ship many nroff man pages anymore.

But the same idea could be done for nroff files, that is,
embed it in comments and extract in the field.

bobs

> 
> 
> Bob Stayton wrote:
> > I'm following up on one of my action items.  This is
> > regarding the suggestion to permit more than a single
> > refnamediv in a refentry.  My task was to provide an
> > example of a reference page that included multiple names
> > and purposes for a set of related functions.
> > 
> > See this example for a set of related commands:
> > 
> > http://uw713doc.caldera.com/en/man/html.1/ls.1.html
> > 
> > This page documents several variations on the Unix "ls" 
> > command.  They all share the same options, so creating
> > separate reference pages for each would be a lot of
> > duplication.  But each has a somewhat different function,
> > so we wanted a separate purpose phrase that would go into
> > the man whatis database so the extra keywords
> > could be searched on with man -k.
> > 
> > An example with several related programming functions
> > would be:
> > 
> > http://uw713doc.caldera.com/en/man/html.3S/fprintf.3S.html
> > 
> > If you view HTML source on either of these, you will see
> > a set of HTML comments that look like this:
> > 
> > <!--Meta N2 "lc"-->
> > <!--Meta D2 "list contents of directory in columns"-->
> > <!--Meta N2 "l"-->
> > <!--Meta D2 "list contents of directory in long format"-->
> > <!--Meta N2 "lf"-->
> > <!--Meta D2 "list contents of directory in columns indicating object type"-->
> > <!--Meta N2 "lr"-->
> > <!--Meta D2 "list contents of directory recursively in columns"-->
> > <!--Meta N2 "lx"-->
> > <!--Meta D2 "list contents of directory in columns sorted horizontally"-->
> > 
> > The UnixWare makewhatis tool looks for such comments and
> > adds these extra names and purpose lines to the whatis
> > database.  
> > 
> > 
> > Bob Stayton                                 400 Encinal Street
> > Publications Architect                      Santa Cruz, CA  95060
> > Technical Publications                      voice: (831) 427-7796
> > The SCO Group                               fax:   (831) 429-1887
> >                                             email: bobs@sco.com
> > 
> > 
> 
> 
> -- 
> Dennis A. Evans, Documentation Tools Developer
> 
> Sun Microsystems, Inc.               dennis.evans@sun.com
> 901 San Antonio Road, MS MPK17-101   650 786-5451
> Palo Alto, CA 94303-4900             650 786-5723 fax
> 
> 

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com