[Geany] the fine manual

John Gabriele jmg3000 at xxxxx
Wed Aug 1 17:01:15 UTC 2007


On 8/1/07, Enrico Tröger <enrico.troeger at uvena.de> wrote:
> 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.

It looks like, with docbook, you can use lots of tags if you like:

<screen><prompt>%</prompt><userinput><command>./configure</command></userinput></screen>

but you don't always have to. So, what the current manual sometimes
inconsistently ends up with is some sections where the author is using
lots of tags, and other sections where the author is scraping by with
as few as possible.

> > [snip] 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.

Ah. Good memory! Yes, Markdown. Turned out, Markdown is very good for
small documents that are getting converted only to html. It's missing
some important features though (like tables and definition lists), and
is probably not suitable (IMO) for software manuals. Very useful for
things like wiki's though.

> > [snip]
>
> Wow, it looks very promising. I must admit your stylesheet is very
> nice, IMO not yet perfect,

Right. For one thing, I failed to put in a style to render those
"notes" sections correctly.

> but much cooler than mine(which was just
> stolen from Xfce ;-)).

Thanks. It's the style I use for my own notes online.

---John


More information about the Users mailing list