Re: [Groff] Simplifying groff documentation

[Gunnar Ritter]

"Eric S. Raymond" <address@hidden> wrote:

> Werner LEMBERG <address@hidden>: 
> > > I think it might not be a bad idea for troff to throw warnings when
> > > a man page uses a troff request outside the safe set.  Note that I 
> > > am *not* recommending this measure for troff documents other than
> > > man pages.
> > 
> > Hmm.  This is doable by redefining the requests, but it means an
> > update to the man macros each time I add something new.
>
> I can imagine doing it with redefinitions, but I think it would probably
> be best to write a troff-level hook that lets a macro package declare
> a safe set to troff.

I doubt it is useful at all. It is perfectly okay to use
statements outside the "safe" set if they do not do harm
when a viewer just discards them. For example, most viewers
will be unable to interpret the ".in \w'troff'u" proposed
for the synopsis, but this is not a problem since it is
clear what the context is anyway, and leaving it out can
at most result in a negligible formatting flaw.

The important aspect is not to hide relevant information
in "unsafe" statements. Otherwise, most of them are not
really a problem.

> On a related topic, there are a couple of man macro extensions that would go 
> a long way towards eliminating the need for people to do ugly troff
> hackery.

Whatever macros we invent in this discussion are destined
to remain irrelevant. The groff -man extensions have been
around for years, but nobody except the groff maintainers
cared. -mdoc has been around for over a decade, and it has
failed to gain any acceptance outside the BSD niche. All
we would achieve are, again, failures with programs that
do not understand our extensions.

        Gunnar