"G. Branden Robinson" <g.branden.robin...@gmail.com> writes:
> 1. podlators/Pod::Man -- a proud exception to some of the
> generalizations above. First, it's been around probably longer than
> any of these others, maybe by a margin of decades. Second, it was
> initially developed by people who seemed to have a good grasp of the
> man(7) macro language and the underlying roff(7) one--in other
> words, old school Unix graybeards who knew their way around troff
> sufficiently to submit a USENIX paper. A dying breed. Third, the
> long-time maintainer is Russ Allbery, whom I trust needs no
> introduction to this list's readers; Russ has approached the
> groff@gnu list with questions when he's had them (a rare occurrence,
> because the guy seems to generally know what he's doing--somebody
> should nominate him for TC or something[1]).
In case anyone is curious about the history:
Back in the Perl 4 days, Larry Wall used to embed documentation in his
Perl scripts by putting carefully-chosen characters at the start of the
file so that it became both a valid Perl script and a valid roff document.
When I first learned UNIX properly, and Perl, and free software
development, around 1993 and 1994, it was by looking at Perl 4 scripts,
both those written by Larry Wall and by colleagues of mine that used the
same technique. That's what got me started on the design pattern of
embedding the documentation for a script in the script itself, which to
this day I still consider the killer feature of POD (you can never be
without the documentation of a Perl script), and I'm always sad that so
few other languages have adopted it.
When Perl 5 came along, and POD came along with it, Tom Christiansen wrote
a script called pod2man. Tom knew roff extremely well, for good or for
ill; the incredibly complex macros that attempted to manually format
various non-US-ASCII characters for troff output have provoked many
maintenance challenges over the years, although I think he largely cribbed
them from elsewhere. This was before I got involved in the Perl community
heavily. Most of the original design decisions are his.
I sadly forget what made me decide that I really wanted to work on POD
formatting in 1999, although for some years I'd maintained Stanford's TeX
installation and was generally interested in document formatting. I
started with Pod::Text, I think because I didn't like something about the
output of the Pod::Text that came with Perl. Shortly thereafter (and my
recollection was that it was at Tom's prompting), I took on pod2man as
well and rewrote it as a Perl module instead of a standalone script.
At the time that I started maintaining it, I did not know roff well. I had
written a few man pages directly in roff, but I always used LaTeX for
writing longer documents. (I was at Stanford University, after all, so
hopefully the roff partisans will forgive me.) [1] When I picked up
Pod::Man maintenance, I had no idea what I was doing, so I sat down and
read CSTR 54 (the AT&T Bell Labs troff user manual), and then I re-read it
multiple times while reading the pod2man source code until I (thought I)
understood every construction that was used in its output.
I still don't consider myself a roff expert of any kind, since I never
write roff directly, I only write Perl code to write roff. :) If it's not
in CSTR 54, I probably don't know it, and I usually have at least a few
dumb misunderstandings when any roff issue comes up. I try to make up for
it by asking questions and being extremely conservative about changes, in
the grounds that if people have been using a program for 25 years and very
rarely report bugs to me, that probably means it's mostly working and I
should try not to break it. But periodically some bug crops up, and I
usually go back and read CSTR 54 to try to figure out how to solve it.
Recently I've made quite a few major changes to try to update Pod::Man for
a world in which the correct solution to many problems it was attempting
to solve via awkward workarounds, such as trying to generate nice paired
quotes, is now "use Unicode if you want Unicode." So it now supports
Unicode input and output and I have deleted a lot of the pre-Unicode
troff-specific workarounds. Those changes largely made it into Perl 5.38
and later.
Any history would not be complete without mentioning Sean Burke, who
completely rewrote the POD parsing machinery for Perl and adapted both
Pod::Text and Pod::Man to the new parsing structure, which was an immense
amount of work that I am very grateful for not having to do.
I should probably note that while I was subscribed to the groff mailing
list for a while, I dropped off again in an attempt to reduce the amount
of stuff I was trying to keep track of. Absolutely nothing against the
great people on the list, just my own regrettable lack of time and
continued state of being behind on most non-work projects. But I will
certainly hop back on if something related to Pod::Man comes up.
[1] A very minor bit of personal trivia: Due to a kind of hilarious
combination of my dad's career path, my fascination with computers,
and my family's love of hobby projects, I wrote several middle school
papers in VAX DIGITAL Standard Runoff and in fact still have the
original source. DSR was one of the inspirations for roff, although
they don't have a lot common in terms of syntax other than the leading
period. roff felt very familiar when I encountered it some time later.
--
Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>
