Ralph Corderoy <[EMAIL PROTECTED]>:
> It seems modern-day perl(1) still does that to an extent, e.g. .Vb and
> .Ve for verbatim text and lots of strings for accents, etc. Perhaps
> groff's guide to writing a man page should stick to `standard' macros in
> -man and provide a suitably licensed header for non-standard ones the
> author can embed in their man page. Ends up with multiple copies of
> course but my man/man1 directory already has 357 definitions of .Vb, not
> necessarily all the same. Probably Perl's POD has caused this.
Yes. And it's because of the pod2man example that I don't at *all* like
the idea of having "standard" macros that are locally defined everywhere.
pod2man has been a large source of heartburn and complications in
implementing doclifter.
When doclifter interprets pod2man files, it looks for a standard pod2man
header and rips it out, because the pod2man macros are so snarled and
badly written that attempting to interpret them is a lose. There are
many comments in the doclifter source of the form "kluge around pod2man
brain death here".
But ripping out the standard header has its own perils. What doclifter does
is substitute its own implementations of the pod2man macros. What if these
have actually been modified locally? Supposing they haven't been, what if
I fail to correctly emulate an edge case that a page depends on and I
have not grokked? The number of dodgy special cases I've had to implement
to cope with this situation would curl your hair; I'm actually rather
amazed that the resulting pile of kludges works at all.
There are similar issues with a smaller but significant class of
X Consortium pages. That's what persuades me that this is not a unique
evil of pod2man but a general problem with canned local headers.
I suppose one possible reply is "but we're not going to do things in
our local definitions so horrible that you'll have no choice but to
ignore them". The road to hell is paved with such good intentions.
No. If we're going to extend man, we should do it properly, with the
new definitions in the man package itself. I have seen the result of
defining "standard" local headers and I know they are far too likely
to turn into a nasty complexity and maintainability problem down the
road.
They're especially a problem for rendering programs less adaptable
than doclifter and implementors less doggedly persistent than I am...
and if you've been wondering why I worked on doclifter for *five years*
before making any public noise about it, now you have a clue.
Werner, I know it looks like an easy compromise, a soft option. But don't
go there. *Bad* idea...
--
<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>
_______________________________________________
Groff mailing list
Groff@gnu.org
http://lists.gnu.org/mailman/listinfo/groff
