300 lines
5.0 KiB
HTML
300 lines
5.0 KiB
HTML
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>What preprocessors may 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="Which macro package should I
|
|
use?"
|
|
HREF="q5.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Should I distribute source
|
|
and/or already formatted documentation?"
|
|
HREF="q7.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="q5.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="q7.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="SECT1"
|
|
><H1
|
|
CLASS="SECT1"
|
|
><A
|
|
NAME="Q6"
|
|
></A
|
|
>6. What preprocessors may I
|
|
use?</H1
|
|
><P
|
|
>Groff comes with at least three preprocessors,
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>tbl</TT
|
|
>, <TT
|
|
CLASS="LITERAL"
|
|
>eqn</TT
|
|
>, and
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>pic</TT
|
|
> (on some systems they are named
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>gtbl</TT
|
|
>, <TT
|
|
CLASS="LITERAL"
|
|
>geqn</TT
|
|
> and
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>gpic</TT
|
|
>.) Their purpose is to translate
|
|
preprocessor macros and their data to regular troff input.
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>Tbl</TT
|
|
> is a table preprocessor,
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>eqn</TT
|
|
> is an equations/maths preprocessor and
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>pic</TT
|
|
> is a picture preprocessor. Please refer to
|
|
the man pages for more information on what functionality they
|
|
provide. To put it in a nutshell: don't write man pages
|
|
requiring <EM
|
|
>any</EM
|
|
> preprocessor. Eqn will generally
|
|
produce terrible output for typewriter-like devices, unfortunately
|
|
the type of device 99% of all man pages are viewed on (well, at
|
|
least I do). For example, XAllocColor.3x uses a few formulas with
|
|
exponentiation. Due to the nature of typewriter-like devices, the
|
|
exponent will be on the same line as the base. N to the power of
|
|
two appears as `N2'. <TT
|
|
CLASS="LITERAL"
|
|
>Tbl</TT
|
|
> should be avoided
|
|
because all xman programs I have seen fail on them. Xman 3.1.6 uses
|
|
the following command to format man pages, e.g. signal(7):</P
|
|
><P
|
|
><TT
|
|
CLASS="LITERAL"
|
|
>gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff
|
|
-Tascii -man /tmp/xmana01760 2> /dev/null</TT
|
|
></P
|
|
><P
|
|
>which screws up for sources using <TT
|
|
CLASS="LITERAL"
|
|
>gtbl</TT
|
|
>,
|
|
because <TT
|
|
CLASS="LITERAL"
|
|
>gtbl</TT
|
|
> output is fed again into
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>gtbl</TT
|
|
>. The effect is a man page without your
|
|
table. I don't know if it's a bug or a feature that
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>gtbl</TT
|
|
> chokes on its own output or if xman could
|
|
be a little smarter and not use <TT
|
|
CLASS="LITERAL"
|
|
>gtbl</TT
|
|
> twice.
|
|
Furthermore, some systems use <TT
|
|
CLASS="LITERAL"
|
|
>grog</TT
|
|
> to determine
|
|
what options to pass to groff. Unfortunately grog sometimes guesses
|
|
wrong and recommends <TT
|
|
CLASS="LITERAL"
|
|
>groff -t</TT
|
|
> when in fact
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>tbl</TT
|
|
> must not be used. We are basically left with
|
|
two workarounds for tables:</P
|
|
><P
|
|
></P
|
|
><OL
|
|
TYPE="1"
|
|
><LI
|
|
><P
|
|
>Format the table yourself manually and put it between .nf and
|
|
.fi lines so that it will be left unformatted. You won't have
|
|
bold and italics this way but this beats having your table
|
|
swallowed any day.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
>Use any <TT
|
|
CLASS="LITERAL"
|
|
>tbl</TT
|
|
> macros you like but distribute
|
|
the <TT
|
|
CLASS="LITERAL"
|
|
>tbl</TT
|
|
> output instead of the input. There is
|
|
however this quirk with <TT
|
|
CLASS="LITERAL"
|
|
>grog</TT
|
|
> who thinks that any
|
|
file containing a line starting with <TT
|
|
CLASS="LITERAL"
|
|
>.TS</TT
|
|
>
|
|
requires <TT
|
|
CLASS="LITERAL"
|
|
>tbl</TT
|
|
>. <TT
|
|
CLASS="LITERAL"
|
|
>Tbl</TT
|
|
> output for
|
|
some reason unbeknownst to me still contains <TT
|
|
CLASS="LITERAL"
|
|
>.TS</TT
|
|
>
|
|
and <TT
|
|
CLASS="LITERAL"
|
|
>.TE</TT
|
|
>. It seems you can simply remove them and
|
|
have the result still look okay. YMMV, so please test this with
|
|
your particular man page.</P
|
|
></LI
|
|
></OL
|
|
><P
|
|
>I have yet to see a man page requiring <TT
|
|
CLASS="LITERAL"
|
|
>pic</TT
|
|
>
|
|
preprocessing. But I would not like it. As you can see above,
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>xman</TT
|
|
> will not use it and
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>groff</TT
|
|
> will certainly do the funky wadakiki on
|
|
the input.</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="q5.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="q7.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Which macro package should I
|
|
use?</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Should I distribute source
|
|
and/or already formatted documentation?</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |