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

[Fred L. Drake, Jr.]

Barry A. Warsaw writes:
 > 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

  That's true for man pages as well, but the markup is a bit more
obscure and more presentation-driven than it should be, but that's a
minor issue given the heavy use of convention in man pages.

 > 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

  This is true for man pages as well; a properly-written & marked man
page can have a very nice printed form.

 > 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'm standing back!  ;-)  But this is where Texinfo improves on the
troff -man markup; it generally relies less on convention and
template-driven authoring to get the job done, so is easier to
convert.

 > 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

  Both more and less, as we've discussed.

 > 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.

  My keyboard doesn't have an "@" key.  ;-)

 > 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.

  I agree.  DocBook would solve both the general documentation and man
page problem.  So go with DocBook like I told you.  ;-)
  Seriously, the common tools for DocBook leave something to be
desired, especially for typeset formats.  Writting a better tool would
not be terribly hard these days, especially if you went with the XML
version of DocBook.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation