DocumentationOptions

We have selected AsciiDoc as our documentation format. This page remains in case this information might be useful in the future.

h1. Documentation

I have been hunting around on the net in search of a means to document the Larceny project that provides us with the following:

• A single source for our documentation
• An easy-to-use interface, namely the ability to type near-plain text (e.g. WikiFormatting)
• The ability to convert the original documentation into a number of alternative formats (e.g. HTML, LaTeX, PDF)

reStructuredText

One promising option that I have found is reStructuredText (RST). RST is supported by the Trac Wiki through the use of processors. It appears to be as easy to use as WikiFormatting, and provides similar options for formatting, sectioning, etc. WikiRestructuredText contains more details on the use of RST in the Wiki.

NOTE: I believe that we need to install the Python docutils package on the machine hosting Trac because the RST samples on WikiRestructuredText aren't appearing correctly.

Additionally, it is the docutils package that will provide us with a means to translate RST into HTML and LaTeX files (and subsequently PDFs). I have downloaded the latest version of this package and installed it on my machine at home and have had good success in creating both of the above mentioned formats from a sample RST file I created. I derived the content of the sample file from the RationalizingLarceny Wiki page so the content should be familiar.

• RST Example
• RST->HTML
• RST->LaTeX2e
• RST->LaTeX2e->PDF

Because the text-only version of the Wiki pages will look similar to this,

{{{
#!rst

 ...page content...

}}}

we will need to extract the real RST from within the curly braces and #!rst declaration. Assuming that the first two lines of the file contain the three braces and the declaration, and the last line of the file contains the closing curly braces, the following shell command should strip the unwanted characters nicely:

tail +3 filename | tac | tail +2 | tac

Now ... is there a way to mass export pages from the Wiki? Specifically, could we export the subset of pages from the Wiki that are only documentation pages? Perhaps through trac-admin ... ?

AsciiDoc

AsciiDoc is another option that JesseTov and PnkFelix came across. It seems very comprehensive; it has a backend for DocBook, which seems like its primary target, but there is also an experimental LaTeX backend.

http://www.methods.co.nz/asciidoc/