Re: FAQ format

[John W. Eaton]

On 26-Mar-2009, Thomas Weber wrote:

| On Wed, Mar 25, 2009 at 02:12:11PM -0400, John W. Eaton wrote:
| > Having it as an HTML document might be OK too, as it would look better
| > on the web, but I find editing HTML to be relatively unpleasant.
| > 
| > Comments?
| 
| Are you aware of ReStructuredText?
| http://docutils.sourceforge.net/rst.html

No.  Thanks for the pointer.

| Pure ASCII, Emacs mode available and both HTML and LaTeX can be
| generated from it.
| Debian package is 'python-docutils'. 
| 
| Example for an .rst file and the resulting HTML output:
| http://tw-math.de/~weber/using-debbugs.rst
| http://tw-math.de/~weber/using-debbugs.html
| 
| I'd say that the FAQ as text/.rst document shipped in the source tarball
| is sufficient, though. Otherwise, we'll add a dependency on doctuils for
| building Octave.

Couldn't we make it a developer dependency by shipping the generated
files in the tarballs?  Then you would not need this extra tool to
build the sources from a normal distribution, but you would need it to
build Octave from sources.  But even there, we could ignore errors, or
skip this part if the rst converter is not available.  It doesn't seem
like failing to convert the FAQ from the rst input to HTML should
cause much trouble since it would already be readable in the rst
source form.

Thanks,

jwe