[Mailman-Developers] Re: [Mailman-Users] * Mailman Docs Moving *

Barry A. Warsaw barry@zope.com
Wed, 29 Aug 2001 23:44:12 -0400


>>>>> "PS" == Phil Stracchino <alaric@babcom.com> writes:

    PS> Does anyone know of a texi2man tool?  I know that texi2html
    PS> exists.

I'm not aware of one, but I'm Cc'ing Fred Drake, who knows everything
there is to know about documentation. :)

    PS> (Personally, I detest the info format and the move from man to
    PS> info.  The man format was simple, lightweight and easy to use,
    PS> whereas info is cryptic and complex.  I've always wondered
    PS> whether there was any technical reason behind the info system,
    PS> or whether it was just Stallman's desire to leverage emacs
    PS> into everything he could possibly shoehorn it into.  And
    PS> personally, I care little for what he blesses -- the man has
    PS> gone from being the leader of the solution to being part of
    PS> the problem.)

Leaving politics aside, what I like about texinfo (or latex as with
the Python documentation) is that you can write it with any text
editor/word processor in the world.  That means that anybody can
contribute documentation.  It's also fairly easy to generate
PostScript for hardcopy, or HTML for online browsing, among other
formats.  The toolchain is widely available and stable.  And there's
enough semantic and structural markup so that it shouldn't be hard to
convert it to the document format du jour (e.g. DocBook, but I could
be blowing it out my ass on that one ;).

I really like how the Python documentation is done.  It has way more
than we need for Mailman so I'm not suggesting it.  I'm trying to
avoid the endless religious arguments about documentation format by
just saying texinfo is Good Enough, I have a lot of experience writing
stuff in it, and it should be easy enough to learn for anybody who can
contribute.

As for man pages, I don't disagree that they're damn useful.  I
/would/ like to see man pages for all the bin/* scripts, but that's
just a tiny fraction of the potentially useful Mailman documentation
we could provide.  And I don't think the description of system use
from -- 1) the user's point of view; 2) the list owner/moderator's
point of view; 3) the site administrators point of view -- would be
well served by man page format.

-Barry