[Geany] the fine manual

[Andy Elvey]

On Tue, 2007-07-31 at 21:57 -0400, John Gabriele wrote:
> 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

 Hi John - 
You could try what Boost::Spirit uses for its docs - QuickBook, I
believe it's called. Haven't actually used it myself, but it looks very
straightforward.  

Here's the URL for it - 
http://www.boost.org/tools/quickbook/doc/html/quickbook/intro.html 

Just my 2c worth.....  ;-)   
- Andy