[Geany] the fine manual

[John Gabriele]

Updating Geany's manual is, IMO, a bit of a chore. Just my preference
I suppose, but working with docbook to write docs seems way too
onerous. There's a lot of tags to remember, and the whole thing is
very <emphasis>very</emphasis> verbose. But most of all, docbook is
not very pretty to read in source form.

Anyway, I was thinking of making a small update to the manual, but
then figured I'd first try to improve the situation. A while back, I
asked Enrico (hi Enrico!) about what he thought of using something
instead of docbook. I can't find the email right now, but the response
was something fairly close to, "well, come up with something and we'll
have a look".

So, after having looked at many different doc markup schemes in the
meantime (at things like Texinfo, Perl POD, Perl 6 Pod, TeX, LaTeX,
Markdown, Textile, and so on), I finally found something that was easy
to read and write, fairly good looking (even as plain text), capable
for large documents, well-supported, and that is able to act as a
source format to be converted to various other formats:
reStructuredText (aka "reST").

Fast forward to today, I went ahead and manually converted the manual
to reST. Here's the result:

* http://www.milliwatt-software.com/jmg/temp/geany.txt -- the source text
* http://www.milliwatt-software.com/jmg/temp/geany.html -- default style
* http://www.milliwatt-software.com/jmg/temp/geany2.html -- with Geany
stylesheet
* http://www.milliwatt-software.com/jmg/temp/geany3.html -- with my
own stylesheet

If you want to convert the above source text file to html yourself,
install the python-docutils package and run the file through like so::

    rst2html geany.txt > geany.html

That package also comes with ``rst2latex``, which can then be used to
produce a pdf, if you so desire (I haven't tried it). Run ``rst2html
--help`` for more info on the various options for converting to html
(there's a bunch).

Some changes in the above version of the manual (none cast in stone)
you'll notice:

1. It's all rendered as just one big html page (headings link back to
table of contents).
2. Some of the larger tables have been changed to definition lists
just because they were easier to type in that way.
3. The text of the GPL was flattened and just put in as a preformatted
block (a straight copy/paste from the COPYING file).
4. The "contributing to this doc" section was modified to reflect this
doc's source format.

Also a few small grammatical and spelling corrections were made.

I think it would be great to see the official manual switch to reST,
and keeping the manual up-to-date should be rather easier. Have a look
at the source text, and see if you think reading and writing it is
preferable to dealing with ... [gulp]... docbook. ;)

---John