[Geany] the fine manual

[Enrico Tröger]

On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" <jmg3000 at gmail.com>
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.
I don't think so. DocBook is IMO a nice format for writing larger
documents and mainly you don't need so many tags. Just a question of
personal preference.

> 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".
Yes. Didn't you talk about Markdown in that mail and suggested to send
a sample chapter in Markdown to get an impression? I had a short look at
Markdown at that time and AFAIK it has some kind of Wikisyntax. I
didn't like it very much.

> 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
Wow, it looks very promising. I must admit your stylesheet is very
nice, IMO not yet perfect, but much cooler than mine(which was just
stolen from Xfce ;-)).

Another advantage is that it doesn't need as many dependencies as
docbook and probably is easier to use at all (yes, using the docbook
tools to generate something from the source can be a mess ;-( ).

I think we could change not yet completely sure but it looks nice. What
do you think?

Regards,
Enrico

-- 
Get my GPG key from http://www.uvena.de/pub.key
Powered by Debian GNU/Linux, GnuPG and Sylpheed.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://lists.geany.org/pipermail/users/attachments/20070801/4323fc4a/attachment.pgp>