Wouldn’t a better solution be to get the Python docutils package to convert reStructuredText to texinfo?

Having two sources for the documentation will just result in things getting out of sync, so unless you can convince people to switch to texinfo completely, then it probably won’t get accepted.

My personal view is that using reStructuredText as a source for making documentation was a bad idea. The syntax of the markup is limited (from my brief look at it), and sooner or later it just would not scale up. This is the sideeffect of using a markup meant for code documentation. Probably the authors just wanted a quick way to jot down their thoughts.

However, having a serious markup source like Texinfo is the only way to ensure that the documentation efforts are scalable in the future.

Some people prefer Docbook, but I think writing in Docbook gets in the way of writing. Writing proper XML is best left to machines. Texinfo is as much logical-structure oriented as docbook, and therefore using texinfo’s docbook translation (using `makeinfo –docbook`) doesn’t cause any loss in document structure semantics.

Call it under-confidence if you will, I find it unlikely that I would be able to convince the authors to switch to texinfo. I am hoping to convert and maintain the texinfo sources for the entire bazaar documentation(including keeping it in sync with the original sources), till the authors switch to a more sensible markup (I would be quite ok if they decide to use docbook directly, or even OOo).

In that case, you’d do better trying to convince people to switch to texinfo as a source. I do wonder why you’d choose texinfo over something like docbook/xml though.

I think you are underestimating what the docutils package can do though — it seems expressive enough, and the tools available seem okay too. Are there particular things you want to express in the documentation that reStructuredText can’t handle?

I am hoping that people would like the work I am doing over the docs. I have tried writing some years before in docbook, and won’t like to repeat that experience. Unless there are better frontends in the market, writing in XML for even a medium size document is a major PIA – you have to end each tag, remember the scores of tags, the order in which they should work, etc.

Writing in texinfo is like writing a few years back in linuxdoc – easy. The biggest fear of people is loss of structure. Texinfo counters this by keeping a simpler set of commands which are anyway fullfeatured. Not all sections have to be end-tagged, simply because many combinations are logical and intuitive. e.g. a chapter finishes where the other begins. XML makes us write and remember too much.

I haven’t seen any structural features in reStructuredText. I admit that I haven’t looked at it closely. But:

• Can it handle automatic table of contents generation? This is a major grouse that I have with markdown.
• Can it handle indices? or multiple indices?
• Can it handle splitting of the source files (@include in texinfo)
• Can it be converted to structured docbook xml?
• How good are the conversion tools to other formats, especially pdf? I mean out of the box. texinfo has a very professional looking (even though orthodox) look about it.
• Can it handle automatic numbering of chapters, and unnumbered chapters?

If we are looking for a documentation tool which can handle much higher volume of content in the future, we have to look for all these features. Can reStructuredText handle these? Or are you just confident about its future?

I haven’t seen any structural features in reStructuredText. I admit that
I haven’t looked at it closely.

Since you’re proposing changing away from it, you may want to learn more:

http://docutils.sourceforge.net/
http://docutils.sourceforge.net/docs/user/rst/quickstart.html
http://docutils.sourceforge.net/docs/ref/rst/directives.html

But:
* Can it handle automatic table of contents generation?

Yes, with the ‘contents’ directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents

• Can it handle indices? or multiple indices?

Yes, text can be marked up with any of a number of predefined or user-defined roles, and later indexed based on these roles. http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text

• Can it handle splitting of the source files (@include in texinfo)

Yes, with the ‘include’ directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

• How good are the conversion tools to other formats, especially pdf?

It has ‘rst2html’ and ‘rst2latex’ tools bundled. The docutils module provides writers for several other formats.

• Can it be converted to structured docbook xml?

A DocBook XML writer is currently in development.

• Can it handle automatic numbering of chapters,

Yes, with the ‘section-autonumbering’ directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#automatic-section-numbering

and unnumbered chapters?

Not sure what this means.

Well, I must say I have a new found respect for reStructuredText after seeing http://docutils.sourceforge.net/sandbox/grubert/test.pdf. Even though it doesn’t come anywhere near the feature-set that texinfo provides (you really should look at its manual closely too), it does cover all the essential requirements to some level. I really must say texinfo shines in the depth of features. e.g. indices are far more advanced, cross-references look saner in texinfo, a very high emphasis on semantic content, etc.

A major problem with reSt that you really should be considering before putting in further effort in to creating such content, is that it is nowhere as semantic oriented as texinfo and docbook is. Do you know that there are probably five different semantic tags which all render fix-width code in texinfo – @code, @samp,@file,@command,@env, @var, etc. When you write in reSt, you are only mentioning the text as literal. The rest of the semantics is lost. How can any XML or docbook converter in the future going to restore this semantics? reSt content would be totally unsuitable for any professional printing work, and would require large amounts of further input to restore semantics ( e.g. the book designer might want to render executable commands diferently from program variables, etc.)

Another issue that I am getting from looking at reSt syntax, is that in the quest to make a ‘formatting-as-it-looks’, the language seems to have taken over all available punctuation marks. This gives me the same feeling while looking at, say Perl code. I look at the page and I know that after a few days I will keep wondering: “so how many underscores or periods did that need again?” or “damn, i forgot to quote the text with backticks”.

And with the preponderence of features similar to markdown, both have the same problem of trying to tackle the problem of readability. Why! When the user is likely to look at HTML or PDF outputs all the time, it doesnt matter if you write:

@url(here,"http://some/website") .... some long text

or,
here <http://some/website&gt;_ …. some long text

… because they should render the same.