[csw-maintainers] /testing spamassassin, bind, dhcp, dnstop

[James Lee]

On 24/02/10, 00:09:22, Sebastian Kayser wrote
regarding Re: [csw-maintainers] /testing spamassassin, bind, dhcp, 
dnstop:

> James helped out to dig deeper into what exactly is going on here (I
> faced a similar problem with autossh). The root cause as well as a
> possible workaround are described in [1].

> In short:

> * man page is written with roff macros from the doc macro package
> (grog(1) can help to determine this), thus formatting it with the
> an/man macro package - which is what man does by default - fails.

> * "groff -m doc -Tascii -P-cuob " can be used to produce a
> pre-formatted man page which can then be placed in
> /opt/csw/share/man/catman from where it will simply be read
> instead of being run through the roff chain.

In the general case make sure the flags for egn, tbl, etc. are added if
needed, eg, -e -t. grog will advise but it's easier to add always even
when not needed. The proof is in typing man and reading the output after
you have installed your package.



> The second step is my simplistic approach after reading into the basics
> of roff a bit, so there might be very well a "better" approach ... but
> again, it does the job (and even better than the ugly workaround posted
> earlier).

This works and is the least effort so do it. Some people are in the
habit of removing the cat files but this dates from when it paid to keep
the formatted pages in cat, see catman(1). To prevent removal of package
files setting no write permission on the package cat files would help.



Man uses environmental variables TCAT and TROFF, eg for fancy man
pages to the screen (-t was intended for printing):

$ export TROFF="groff"
$ export TCAT="/opt/csw/bin/gsview" # or gv or ...
$ man -t ls

depending on your shell...
$ alias man='man -t'
$ man ls

however the man command missed a trick, man needs the equivalent for
nroff. You can get close by hijacking the troff formatting:

$ export TROFF="gnroff"
$ export TCAT="more"
$ man -t ls

unfortunately man adds "-man" always so TROFF="gnroff -mdoc" doesn't
work so this does not work for groff mdoc pages but does for groff man
pages. NBG:

$ export TROFF="gnroff -mdoc"
$ export TCAT="more"
$ man -t groff_mdoc



It is possible to provide an alternate groff aware man command but a
lot of the Solaris man pages are in SGML (Standard Generalized Markup
Language) sgml(5) format and any substitute man command would have to
work with the system man pages too. Here's a man system:
http://primates.ximian.com/~flucifredi/man/)
but I can't see that it is SGML aware so is of limited help.





The best idea is to support, promote and provide traditional man pages.
This isn't always easy, I do write roff macro packages to format my
documents but was defeating by the groff man page conversion and (not
worth my time, I pre-formatted into cat - spend time on useful tasks).




> There is also some background on man vs. doc macro packages geared
> towards man page writers at [2]. Quote: "do yourself a favor: use
> tmac.an -- use of any other macro package is considered harmful."

The bit I liked in groff_mdoc was "The -mdoc package attempts to
simplify the process of writing a man page." - oh thanks.




James.