|
[20091007]
|
man(1) can handle *roff files, now
What, *roff - never heared of? You should - it's the formatting language
that predates HTML and TeX for some many years, and which all *nix
manpages are written in:
% cat /usr/share/man/man1/ls.1
...
.Dd September 25, 2008
.Dt LS 1
.Os
.Sh NAME
.Nm ls
.Nd list directory contents
.Sh SYNOPSIS
.Nm
.Op Fl AaBbCcdFfghikLlmnopqRrSsTtuWwx1
.Op Ar
...
There are many formatting commands, all starting with a dot as
first character, and the various commands are grouped in so-called
macro packages. Example files in the old-school "man" format
and the newer "mandoc" format can be found in
man(7)
and
mdoc(7)
manpages on any NetBSD installation, templates can be found
in /usr/share/misc/man.template and .../mdoc.template.
And in /usr/share/man. :-)
Now, with the new change to man(1), you can simply type
"man /usr/share/man/man1/ls.1" and the formatted manpage
will be shown, just like it always did for "man ls".
The fine difference is that the latter command really just
shows you a preformatted file (from /usr/share/man/cat1),
while the former now really formats the given file on the
fly, and shows you the result.
Before the new change to man(1), you had to run the
formatting tool with the right set of parameters for macro
packages and possibly other options manually. Usually,
the command is something like
nroff -mandoc /usr/share/man/man1/ls.1 | more
for terminal output. NetBSD's "nroff" command is really from
the GNU *roff utilities, and using groff(1) it is also
possible to produce PostScript output for pretty-printing:
groff -Tps -mandoc /usr/share/man/man1/ls.1 >ls.ps
lp -dPS ls.ps
There are more options when running nroff(1)/groff(1),
plus manpages can be stored in compressed format, see
/etc/man.conf for some ideas. All this is now hidden
behind an easy run of man(1).
For a more in-depth introduction of the Unix documentation
tools (and many more things!), I recommend reading Kernighan/Pike's
Unix Programming Environment.
[Tags: groff, nroff, roff]
|
