making python man pages looks hard

[Fred L. Drake, Jr.]

Dan Connolly <connolly at w3.org> wrote:
 > The source format is LaTeX. Converting from LaTeX is hard/messy:

Dan,
  It sure is!  You'll get no argument from me on that one.

 > For example, I conjecture that it is impossible to write a program that
 > will extract the third word from a TeX document. It would be an easy
 > task for 80% of the TeX documents out there -- just skip over some
 > formatting stuff and grab the third bunch of characters surrounded by

  Not impossible, but painful enough in the general case that I have
no plans to write the code to do it (in any language!).

Fredrik Lundh writes:
 > luckily, Fred Drake has already made most of the hard work
 > here -- check the Doc/tools/sgmlconv directory:

  Dang, my secret has been found!  ;-)
  Yes, there's a good bit of potentially interesting material there.

 > not sure how incomplete, though.  I don't have things setup
 > so I can try the current release of this (from the CVS archive),
 > but maybe Fred can give us a status update?

  I don't have time today, but I'll try to send a status report to the 
Python doc-sig next week.  For anyone interested but not subscribed to 
the doc-sig mailing list, see http://www.python.org/sigs/doc-sig/ for
information.

 > anyway, if this stuff works, writing an esis2man converter
 > cannot be *that* hard.

  Parsing esis isn't hard (it's in the XML package!), and generating
man pages isn't hard ("print" is a language statement in Python,
right?).  The difficulty is the semantic mapping; what do you want on
you manpages, how do you want them organized, etc.  The existing
structure may not be trivial to transform into manpages, regardless of 
syntax.  Having a DOM instance for the library reference doesn't make
manpages a one-liner.  ;-)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake at acm.org>
Corporation for National Research Initiatives