groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Groff] Re: Avoiding the pod2man mistake


From: Ralph Corderoy
Subject: [Groff] Re: Avoiding the pod2man mistake
Date: Fri, 29 Dec 2006 17:14:37 +0000

Hi Eric,

> Ralph Corderoy <address@hidden>:
> > 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.

Hey, if it was easy, someone else would have already done it.  :-)

> 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.

I guess doclifter has to recognise the common additions, e.g. .Vb, in
their various forms over time in order to know it's safe to assume what
they do.  It groks POD's, and the X Consortium's, and could also manage
a canned set we put together too.

> 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.  

You live in an ivory tower of free software.  Some of us have worked in
environments where -man comes from the closed-source vendor and the man
page has to work there too to be useful.  Having a man page that
requires groff and its -man is akin to needing texinfo -- it won't be
there.

> 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.

Poorer grokkers can just code that .Vb means verbatim and if the
definition in the header actually meant 'Visual BASIC code example' then
that's just another flaw they've got.

> Werner, I know it looks like an easy compromise, a soft option.  But
> don't go there.  *Bad* idea...

Man pages work across Unix, they're not Free Software OS only.  The
solution needs to work across Unix where -man hasn't changed in years
and won't.

Cheers,


Ralph.






reply via email to

[Prev in Thread] Current Thread [Next in Thread]