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
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
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.htmlThat 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:
- 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
On 8/1/07, Andy Elvey andy.elvey@paradise.net.nz wrote:
On Tue, 2007-07-31 at 21:57 -0400, John Gabriele wrote:
[snip]
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 [snip]
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.
Hi Andy,
Yeah, there's a lot of markup tools out there. Some are easier to read, but are more limited. Others give you lots and lots of easy markup syntax, but that syntax can interfere too much with your main text. Some have better (or more) format conversion tools than others. They all also have varying levels of community support, maturity, extensibility, and ease of use. I settled on reST for my own docs because it provides a pretty good mix.
---John
On Wed, 2007-08-01 at 10:59 -0400, John Gabriele wrote:
On 8/1/07, Andy Elvey andy.elvey@paradise.net.nz wrote:
On Tue, 2007-07-31 at 21:57 -0400, John Gabriele wrote:
[snip]
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 [snip]
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.
Hi Andy,
Yeah, there's a lot of markup tools out there. Some are easier to read, but are more limited. Others give you lots and lots of easy markup syntax, but that syntax can interfere too much with your main text. Some have better (or more) format conversion tools than others. They all also have varying levels of community support, maturity, extensibility, and ease of use. I settled on reST for my own docs because it provides a pretty good mix.
---John
Hi John - That's fine! I've heard that reST is very good. Yes - lots of tools out there for doing docs, that's for sure... :-) - Andy
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@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
style
- http://www.milliwatt-software.com/jmg/temp/geany2.html -- with Geany
stylesheet
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
On 8/1/07, Enrico Tröger enrico.troeger@uvena.de wrote:
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@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
On Wed, 1 Aug 2007 13:01:15 -0400, "John Gabriele" jmg3000@gmail.com wrote:
On 8/1/07, Enrico Tröger enrico.troeger@uvena.de wrote:
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@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.
Just to be clear: I _don't_ like the above tag construction. But sometimes such things are necessary ;-(.
[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.
You should quickly define it under a restrictive license or I'll steal it too ;-).
Regards, Enrico
On 8/1/07, John Gabriele jmg3000@gmail.com wrote:
On 8/1/07, Enrico Tröger enrico.troeger@uvena.de wrote:
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@gmail.com wrote:
[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.
Ah. I see. It would probably be easier to start with the default style and add tweaks to it, as described here: http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
---John
On 08/01/2007 05:13:27 PM, Enrico Tröger wrote:
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@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. [...] 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:
Did it take long to convert? Seems like a lot of work.
source
text
style
Geany
stylesheet
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?
I think it looks good, I don't mind docbook, but it would be easier to write reST. But is it equivalent - can it split up the generated HTML into one page per chapter/per section etc? Also can it generate PDFs?
Regards, Nick
P.S. for anyone interested: link: http://docutils.sourceforge.net/rst.html fedora package name: python-docutils
Nick Treleaven wrote:
I think it looks good, I don't mind docbook, but it would be easier to write reST. But is it equivalent - can it split up the generated HTML into one page per chapter/per section etc? Also can it generate PDFs?
I like the all-in-one page documentation. It's easier for downloading...
Best regards Andreas
On 8/2/07, Nick Treleaven nick.treleaven@btinternet.com wrote:
On 08/01/2007 05:13:27 PM, Enrico Tröger wrote:
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@gmail.com wrote:
[snip]
Fast forward to today, I went ahead and manually converted the
manual
to reST. Here's the result:
Did it take long to convert? Seems like a lot of work.
Yeah, took a good part of a day. A lot of copying/pasting, reformatting, proofing, and using the Shift-Alt-P Ctrl-1 key combo (Ctrl-1 mapped to ``fmt -w72``). After doing a little bit, I guess I got carried away. I think it's because I'm too lazy to write in docbook. ;)
[snip]
What do you think?
I think it looks good, I don't mind docbook, but it would be easier to write reST. But is it equivalent - can it split up the generated HTML into one page per chapter/per section etc?
It doesn't look like the stock ``rst2html`` command will currently do that.
Also can it generate PDFs?
I think, currently, you need to get to pdf via LaTeX::
$ rst2latex geany.txt geany.tex $ pdflatex geany.tex
I had to remove a unicode arrow character from geany.txt (now updated) to get that to work. Results are here: http://www.milliwatt-software.com/jmg/temp/geany.pdf
Andreas wrote:
I like the all-in-one page documentation. It's easier for downloading...
Me too. Also, navigation works well, since you can click on all the headings and be brought back up to the table of contents.
---John
On Thu, 2 Aug 2007 12:24:46 -0400, "John Gabriele" jmg3000@gmail.com wrote:
On 8/2/07, Nick Treleaven nick.treleaven@btinternet.com wrote:
On 08/01/2007 05:13:27 PM, Enrico Tröger wrote:
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@gmail.com wrote:
[snip]
Fast forward to today, I went ahead and manually converted the
manual
to reST. Here's the result:
Did it take long to convert? Seems like a lot of work.
Yeah, took a good part of a day. A lot of copying/pasting, reformatting, proofing, and using the Shift-Alt-P Ctrl-1 key combo
Didn't you started on the generated geany.txt? I guess this would had been much easier than converting from geany.docbook?
Also can it generate PDFs?
I think, currently, you need to get to pdf via LaTeX::
$ rst2latex geany.txt geany.tex $ pdflatex geany.tex
"jw -b pdf geany.docbook" (the way we create the pdf files at the moment) does nearly the same. Generated PDFs from docbook source files are always intermediately converted into LaTeX. So, no big difference.
Andreas wrote:
I like the all-in-one page documentation. It's easier for downloading...
Me too. Also, navigation works well, since you can click on all the headings and be brought back up to the table of contents.
But it can be annoying when reading a long documentation with lots of text. There are still people out there without broadband connections (like me at the moment). But now, our documentation isn't that big ;-).
Regards, Enrico
On 8/3/07, Enrico Tröger enrico.troeger@uvena.de wrote:
On Thu, 2 Aug 2007 12:24:46 -0400, "John Gabriele" jmg3000@gmail.com wrote:
On 8/2/07, Nick Treleaven nick.treleaven@btinternet.com wrote:
On 08/01/2007 05:13:27 PM, Enrico Tröger wrote: [snip]
Did it take long to convert? Seems like a lot of work.
Yeah, took a good part of a day. A lot of copying/pasting, reformatting, proofing, and using the Shift-Alt-P Ctrl-1 key combo
Didn't you started on the generated geany.txt? I guess this would had been much easier than converting from geany.docbook?
No. I a rare short circuit that occurred somewhere between my keyboard and chair, I managed to completely overlook the existence of the generated geany.txt file. I created the reST geany.txt straight from the html output as displayed in my browser. This wasn't as bad as it sounds though: I started with the table of contents, filled in the section/subsection/subsubsection underline-style markup, and then had a nice skeleton to fill in piece-by-piece as time allowed throughout the day.
Actually, using the generated geany.txt may not even have been any easier, since there's a lot of funny characters I'd have had to replace, and formatting would've needed tweaking just as with the other method. Anyhow, water under the bridge.
Converting directly from geany.docbook would've been the hardest. I've tried it before (using lots of regexes in my editor), and it gets old fast. :)
Also can it generate PDFs?
I think, currently, you need to get to pdf via LaTeX::
$ rst2latex geany.txt geany.tex $ pdflatex geany.tex"jw -b pdf geany.docbook" (the way we create the pdf files at the moment) does nearly the same. Generated PDFs from docbook source files are always intermediately converted into LaTeX. So, no big difference.
I asked about this on the relevant ML, and there's currently a ``rst2odt`` tool being worked on. It's alpha at the moment. Haven't tried it out yet.
---John
Enrico wrote:
John wrote:
Andreas wrote:
I like the all-in-one page documentation. It's easier for downloading...
Me too. Also, navigation works well, since you can click on all the headings and be brought back up to the table of contents.
But it can be annoying when reading a long documentation with lots of text. There are still people out there without broadband connections (like me at the moment). But now, our documentation isn't that big ;-).
The current stable implementation does not produce multiple html files.
However, there is currently a Google SOC project afoot which will provide multiple html file output. Seems to be actively being worked on.
---John
On Tue, 31 Jul 2007 21:57:40 -0400, "John Gabriele" jmg3000@gmail.com wrote:
Some changes in the above version of the manual (none cast in stone) you'll notice: [...]
Yesterday we changed our documentation format to reST. Thank you very much John for your great work in converting the old to the new format.
Online version is available in plain text at http://geany.uvena.de/manual/geany.txt which will be taken from SVN every night(UTC) and http://geany.uvena.de/manual/index.html will be generated afterwards.
Regards, Enrico