<HTML ><HEAD ><TITLE >How do I document several programs/functions in a single man page?</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 should a formatted man page look?" HREF="q3.html"><LINK REL="NEXT" TITLE="Which macro package should I use?" HREF="q5.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="q3.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="q5.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="Q4" ></A >4. How do I document several programs/functions in a single man page?</H1 ><P >Many programs (<TT CLASS="LITERAL" >grep</TT >, <TT CLASS="LITERAL" >egrep</TT >) and functions (<TT CLASS="LITERAL" >printf</TT >, <TT CLASS="LITERAL" >fprintf</TT >, ...) are documented in a single man page. However, these man pages would be quite useless if they were only accessible under one name. We cannot expect a user to remember that the <TT CLASS="LITERAL" >egrep</TT > man page is actually the <TT CLASS="LITERAL" >grep</TT > man page. It is therefore necessary to have the man page available under different names. You have several possibilities to achieve this:</P ><P ></P ><OL TYPE="1" ><LI ><P >have identical copies for each name.</P ></LI ><LI ><P >connect all man pages using hard links.</P ></LI ><LI ><P >symbolic links pointing to the actual man page.</P ></LI ><LI ><P >use <TT CLASS="LITERAL" >groff</TT >'s `source' mechanism provided by the <TT CLASS="LITERAL" >.so</TT > macro.</P ></LI ></OL ><P >The first way is obviously a waste of disk space. The second is not recommended because intelligent versions of the <TT CLASS="LITERAL" >catman</TT > program can save a lot of work by looking at the the file type or contents. Hard links will prevent <TT CLASS="LITERAL" >catman</TT > from being clever. (Note that <TT CLASS="LITERAL" >catman</TT >'s purpose is to format all man pages so they can be displayed quickly.) The third alternative has a slight drawback: if flexibility is a concern, you have to be aware that there are file systems that do not support symbolic links. The upshot of this is that the Best Thing (TM) is using <TT CLASS="LITERAL" >groff</TT >'s source mechanism. Here's how to do it: If you want to have your man page available under the names `foo' and `bar' in section 1, then put the man page in foo.1 and have bar.1 look like this:</P ><P ><TT CLASS="LITERAL" >.so man1/foo.1</TT ></P ><P >It is important to specify the <TT CLASS="LITERAL" >man1/</TT > directory part as well as the file name `foo.1' because when <TT CLASS="LITERAL" >groff</TT > is run by the browser it will have the manual base directory as its current working directory (cwd) and <TT CLASS="LITERAL" >groff</TT > interprets <TT CLASS="LITERAL" >.so</TT > arguments relative to the cwd.</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="q3.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="q5.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >How should a formatted man page look?</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" > </TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Which macro package should I use?</TD ></TR ></TABLE ></DIV ></BODY ></HTML >