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. :(
--tom
