Re: gEDA-user: git based wiki

[Peter TB Brett <peter@xxxxxxxxxxxxx>]

If we're talking about changing things, here's my totally unreasonable and unrealistic documentation system wishlist.

- Markup: should look as much like a "plain" text document as possible, so that it's easy to read and edit the documentation without having to continually process it to double-check that it's going to come out right.  Nice-looking tables are essential.  Bonus points for syntax highlighting mode for Emacs.  An example of IMHO *lovely* markup is reStructured Text.

- Conversion: should be able to convert the *same* sources to man pages and DocBook XML, and onward to XHTML / HTMLHelp / PDF etc.  This is essential so that people who want to contribute to any gEDA documentation only need to learn one markup syntax.  An example of IMHO excellent conversion support is ASCIIDoc.  The git docs use it especially effectively.

- Version control: reference docs should be maintained in-tree so that each branch (e.g. stable and unstable) has its documentation alongside it.  Not so fussed about things like "getting started" guides.  It's really good for developers to be in the habit of updating docs in the same patch as changing behaviour.  Lots of systems can support this.  Would need a "docs coordinator" or something to assist people who want to help with documentation work but don't have git expertise.

         Peter

-- 
Peter Brett <peter@xxxxxxxxxxxxx>
Remote Sensing Research Group
Surrey Space Centre



_______________________________________________
geda-user mailing list
geda-user@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user