On Sat, 17 May 2014 17:19:46 +0200 (CEST) Christophe <[email protected]> wrote:
> > Also, it would be nice if the source and webpage FAQs were the same. > > One option that could work would be to use something like texinfo, > > where the main FAQ is written in some format that can be exported to > > plaintext for the source and html for the webpage. Maybe there's an > > even better solution? > > There are plenty of solution... > - the current hype is probably Markdown syntax, which has the > advantage that the text remains directly readable (for the FAQ > distributed in plain as part of the package), but it requires > contributors to install the appropriate tools to check it will > convert ok to HTML; If I may add my 2 cents. Recently at work, I was asked to make some research around markup languages with producing documentation in various format out of it. Markdown indeed get the hype right now, but have several limitations (several flavors, troublesome PDF generation via pandoc, lack of marks corresponding to the document elements and so on). If all what is needed is an HTML and pure text formats, then maybe MD is enough, but sooner or later it may be a burden to get over those limitations. OTOH I would recommend reStructuredText, which have much more complete feature set, and what's more important - it is easily modifiable and extendible (I've done both). It has several output formats provided out of the box, and several others as separate 3rd party modules (including PDF output, which unlike pandoc doesn't require LaTeX). Python community gladly use reST as a standalone tool, or indirectly with more sophisticated ways (Sphinx, ReadTheDocs). Other option which works beautifully in larger communities would be some wiki, however I remember that it doesn't work well with wmaker in the past. -- Roman Dobosz <[email protected]> -- To unsubscribe, send mail to [email protected].
