<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 >