258 lines
4.3 KiB
HTML
258 lines
4.3 KiB
HTML
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Polishing your 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="What are the font
|
|
conventions?"
|
|
HREF="q8.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="How do I get a plain text man
|
|
page without all that ^H^_ stuff?"
|
|
HREF="q10.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="q8.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="q10.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="SECT1"
|
|
><H1
|
|
CLASS="SECT1"
|
|
><A
|
|
NAME="Q9"
|
|
></A
|
|
>9. Polishing your man
|
|
page</H1
|
|
><P
|
|
>Following are some guidelines that increase reliability,
|
|
readability and 'formatability' of your
|
|
documentation.</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
>Test examples to make sure they work (use cut and paste to
|
|
give your shell the exact wording from the man page). Copy the
|
|
output of your command into your man page, don't just type what
|
|
you <EM
|
|
>think</EM
|
|
> your program will print.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Proof read, ispell, and have someone else read it, especially
|
|
if you are not a native English speaker. The HOWTO you are reading
|
|
has passed the latter test (special thanks to Michael Miller for a
|
|
particular heroic contribution! All the remaining rough edges are
|
|
entirely my fault). Additional volunteers are always
|
|
welcome.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Test your man page: Does <TT
|
|
CLASS="LITERAL"
|
|
>groff</TT
|
|
> complain
|
|
when you format your man page? It's nice to have the
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>groff</TT
|
|
> command line in a comment. Does the
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>man</TT
|
|
>(1) command complain when you call
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>man yourprog</TT
|
|
>? Does it produce the expected
|
|
result? Will <TT
|
|
CLASS="LITERAL"
|
|
>xman</TT
|
|
>(1x) and
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>tkman</TT
|
|
>(1tk) cope with your manual? XFree86 3.1
|
|
has xman 3.1.6 - X11R6, it will try to uncompress
|
|
using<TT
|
|
CLASS="LITERAL"
|
|
>gzip -c -d < %s > %s zcat < %s >
|
|
%s</TT
|
|
></P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Will <TT
|
|
CLASS="LITERAL"
|
|
>makewhatis</TT
|
|
>(8) be able to extract the
|
|
one-line description from the NAME section?</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Translate your man page to HTML format using
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>rman</TT
|
|
> from <A
|
|
HREF="http://polyglotman.sourceforge.net/"
|
|
TARGET="_top"
|
|
>http://polyglotman.sourceforge.net/</A
|
|
>, and view the result with a
|
|
a set of web browsers (netscape, mozilla, opera, lynx, ...) Check that
|
|
the cross-references among your man pages work as hyperlinks in the
|
|
generated HTML. If your software package has a web site, post its man
|
|
pages there, and keep them up-to-date.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>The <TT
|
|
CLASS="LITERAL"
|
|
>rman</TT
|
|
> utility can also translate man pages
|
|
into LaTeX, RTF, SGML, and other formats; check these out if you want
|
|
to incorporate your man pages in a book or other larger document.</P
|
|
><P
|
|
></P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Try translating your man page to HTML using
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>man2html</TT
|
|
>, which has been part of the Linux man
|
|
package since man-1.4. The <TT
|
|
CLASS="LITERAL"
|
|
>man2html</TT
|
|
> utility is a less
|
|
ambitious translator than <TT
|
|
CLASS="LITERAL"
|
|
>rman</TT
|
|
>, but almost every
|
|
Linux user has it already, so it is worth making sure that
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>man2html</TT
|
|
> does not choke on your man page.</P
|
|
></LI
|
|
></UL
|
|
></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="q8.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="q10.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>What are the font
|
|
conventions?</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>How do I get a plain text man
|
|
page without all that ^H^_ stuff?</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |