293 lines
4.9 KiB
HTML
293 lines
4.9 KiB
HTML
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Which macro package should I
|
|
use?</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="Linux Man Page Howto"
|
|
HREF="index.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="How do I document several programs/functions in a
|
|
single man page?"
|
|
HREF="q4.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="What preprocessors may I
|
|
use?"
|
|
HREF="q6.html"></HEAD
|
|
><BODY
|
|
CLASS="SECT1"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>Linux Man Page Howto</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="q4.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="q6.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="SECT1"
|
|
><H1
|
|
CLASS="SECT1"
|
|
><A
|
|
NAME="Q5"
|
|
></A
|
|
>5. Which macro package should I
|
|
use?</H1
|
|
><P
|
|
>There are a number of macro packages especially designed for
|
|
use in writing man pages. Usually they are in the groff macro
|
|
directory /usr/lib/groff/tmac. The file names are
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>tmac.</TT
|
|
><something>, where <something>
|
|
is the argument to groff's -m option. Groff will use
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>tmac.</TT
|
|
><something> when it is given the
|
|
`<TT
|
|
CLASS="LITERAL"
|
|
>-m</TT
|
|
> <something>' option. Often the
|
|
blank between `<TT
|
|
CLASS="LITERAL"
|
|
>-m</TT
|
|
>' and
|
|
`<something>' is omitted so we may say `<TT
|
|
CLASS="LITERAL"
|
|
>groff
|
|
-man</TT
|
|
>' when we are formatting man pages using the
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>tmac.an</TT
|
|
> macro package. That's the reason for
|
|
the strange name `tmac.an'. Besides tmac.an there is another
|
|
popular macro package, <TT
|
|
CLASS="LITERAL"
|
|
>tmac.doc</TT
|
|
>, which
|
|
originated at the University of California at Berkeley. Many BSD
|
|
man pages use it and it seems that UCB has made it its standard for
|
|
documentation. The <TT
|
|
CLASS="LITERAL"
|
|
>tmac.doc</TT
|
|
> macros are much more
|
|
flexible but alas, there are manual browsers that will not use them
|
|
but always call <TT
|
|
CLASS="LITERAL"
|
|
>groff -man</TT
|
|
>. For example, all
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>xman</TT
|
|
> programs I have seen will screw up on man
|
|
pages requiring <TT
|
|
CLASS="LITERAL"
|
|
>tmac.doc</TT
|
|
>. So do yourself a
|
|
favor: use <TT
|
|
CLASS="LITERAL"
|
|
>tmac.an</TT
|
|
> -- use of any other macro
|
|
package is considered harmful. <TT
|
|
CLASS="LITERAL"
|
|
>tmac.andoc</TT
|
|
> is a
|
|
pseudo macro package that takes a look at the source and then loads
|
|
either <TT
|
|
CLASS="LITERAL"
|
|
>tmac.an</TT
|
|
> or <TT
|
|
CLASS="LITERAL"
|
|
>tmac.doc</TT
|
|
>.
|
|
Actually, any man page browser should use it but to this point, not
|
|
all of them do, so it is best we cling to ye olde
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>tmac.an</TT
|
|
>. Anything I tell you from now on and
|
|
concerning macros only holds true for <TT
|
|
CLASS="LITERAL"
|
|
>tmac.an</TT
|
|
>.
|
|
If you want to use the <TT
|
|
CLASS="LITERAL"
|
|
>tmac.doc</TT
|
|
> macros anyway,
|
|
have a look at the tutorial sampler, <A
|
|
HREF="http://www.freebsd.org/cgi/man.cgi?query=mdoc.samples"
|
|
TARGET="_top"
|
|
><TT
|
|
CLASS="LITERAL"
|
|
>mdoc.samples</TT
|
|
></A
|
|
>.
|
|
Some distros (I'm told) also come with mdoc(7), mdoc.samples(7) and
|
|
groff_man(7).</P
|
|
><P
|
|
>The definitive dope for <TT
|
|
CLASS="LITERAL"
|
|
>troff</TT
|
|
>, with all
|
|
macros explained, is the <EM
|
|
>Troff User's
|
|
Manual</EM
|
|
>, available as
|
|
<A
|
|
HREF="http://cm.bell-labs.com/sys/doc/troff.html"
|
|
TARGET="_top"
|
|
>html</A
|
|
>,
|
|
<A
|
|
HREF="http://cm.bell-labs.com/sys/doc/troff.ps"
|
|
TARGET="_top"
|
|
>PostScript
|
|
(ps, 760K)</A
|
|
> or
|
|
<A
|
|
HREF="http://cm.bell-labs.com/sys/doc/troff.pdf"
|
|
TARGET="_top"
|
|
>Portable
|
|
Document Format (pdf, 240K)</A
|
|
>. by Jospeh F. Ossanna and Brian
|
|
W. Kernighan, revised November 1992. AT&T Bell Labs have made
|
|
it publicly available. Don't forget to check out the late great
|
|
<A
|
|
HREF="http://www.kohala.com/start/"
|
|
TARGET="_top"
|
|
>W. Richard Steven's
|
|
homepage</A
|
|
> (famous for <EM
|
|
>Unix Network
|
|
Programming</EM
|
|
> as well as the <EM
|
|
>TCP/IP
|
|
Illustrated</EM
|
|
> trilogy), who also has a list of
|
|
<A
|
|
HREF="http://www.kohala.com/start/troff/troff.html"
|
|
TARGET="_top"
|
|
>Troff
|
|
Resources</A
|
|
> including <TT
|
|
CLASS="LITERAL"
|
|
>tbl</TT
|
|
>,
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>eqn</TT
|
|
>, <TT
|
|
CLASS="LITERAL"
|
|
>pic</TT
|
|
> and other
|
|
filters.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="q4.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="q6.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>How do I document several programs/functions in a
|
|
single man page?</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>What preprocessors may I
|
|
use?</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |