develooper Front page | perl.perl5.porters | Postings from March 2011

Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)

Thread Previous | Thread Next
Tom Christiansen
March 4, 2011 09:53
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)
Message ID:
brian d foy wrote at 9:40am CST on Friday, Marth 4th, 2011:

> If you're talking about translating the Pod constructs to
> *roff, I say we do the best we can and not worry about some
> ideas that *roff might not be able to handle. We wouldn't
> cripple the man pages, but we wouldn't let them hold back the
> pod either.

Oh?  What sort of things might those be, Brian?  

As far as I know, troff should be able to accommodate 
anything in pod.  After all, troff is bazoodles of times 
more-complicated/unplain than pod is!  Roff is unpod.

If you mean some of the meta-stuff like C<< X<> >> indexing and 
C<<  =for stopwords >> and stuff, well, that isn't really its job.
That's for a higher-level tool.

Speaking of high-level stuff, for a long while, only pod2man 
alone handled such user-friendly dwimmercraft as this:

    Besides the obvious pod conversions, Pod::Man also takes
    care of formatting func(), func(3), and simple variable
    references like $foo or @bar so you don't have to use code
    escapes for them; complex expressions like $fred{'stuff'}
    will still need to be escaped, though.  It also translates
    dashes that aren't used as hyphens into en dashes, makes
    long dashes--like this--into proper em dashes, fixes
    "paired quotes," makes C++ look right, puts a little space
    between double underscores, makes ALLCAPS a teeny bit
    smaller in troff, and escapes stuff that *roff treats as
    special so that you don't have to.

Being smart like that to "just do the right thing" is very in 
keeping with pod.  Don't make programmers be page-layerouters.  :)

I'm sure it must have been a bit gnarly for Russ Allbery 
when he created a Pod::Man to emulate the old behavior:

    # For right now, default to turning on all of the magic.
    $$self{MAGIC_CPP}       = 1;
    $$self{MAGIC_EMDASH}    = 1;
    $$self{MAGIC_FUNC}      = 1;
    $$self{MAGIC_MANREF}    = 1;
    $$self{MAGIC_SMALLCAPS} = 1;
    $$self{MAGIC_VARS}      = 1;

But he did so, and it looks good; pod2man is still the best way
to generate Postscript/PDF to send to the printer.

I don't believe Allison's Pod::Pseudopod does any of that magic.
Pod::Html has a little bit of that, just functions and manpages 
I think.  It doesn't use CSS to get proper sᴍᴀʟʟ ᴄᴀᴘs in the font.

I am quite surprised and perhaps even a bit distressed to see 
that pod2html never got rewritten to inherit from something more 
robust in its parsing.

No wonder I keep getting bug reports on it. :(


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About