Texinfo version of the documentation

Is there already a toolchain for converting ReST into Texinfo, maybe via docbook?

Stefan wrote today:

> Not knowing exactly how you generate your documentation, it's hard for
> me to help, but at least if you can generate docbook output (which you
> supposedly can from ReST), you can pass it on to docbook2x to get
> Texinfo output. Or maybe Pandoc can do it better straight from ReST to
> Texinfo.

So they would be worth looking into.

Giving pandoc a quick try, it doesn't look like it supports the ".. include::" directive. So it seems that you can render individual pages, but not the whole group together.

It would seem that going via rst2latex and then something from there? I don't specifically know of an rst2docbook, but maybe I just missed it.

Interestingly while searching for info about converting, I came across:
http://blog.sandipb.net/2005/06/06/reformatted-bazaar-docs/

Which is about converting the Baz 1.x documentation.
And this:
http://stackoverflow.com/questions/1054903/how-do-you-get-python-documentation-in-texinfo-info-format

From just a couple months ago, which seems to say it still isn't really available, though there does seem to be a rst2info that is being worked on.

> Giving pandoc a quick try, it doesn't look like it supports the "..
> include::" directive. So it seems that you can render individual pages,
> but not the whole group together.

Maybe contacting the Pandoc authors about it could help address
this limitation.

> It would seem that going via rst2latex and then something from there?

Usually once you get to LaTeX, you're too low-level and can't generate
good Texinfo from it any more.

> I don't specifically know of an rst2docbook, but maybe I just
> missed it.

Wikipedia says that JRst can do it.

        Stefan

It seems to me that we won't stop using rst anytime soon so, since:
- we are already moving to sphinx for the web site,
- sphinx is used by the python project and as such is the most likely candidate to be used for the
  bzrlib documentation (which AFAIK is produced only partially and punctually as of today),

we'd better look at helping the sphinx project produces a texinfo builder/writer.

From http://<email address hidden>/13813064.html, I understand
that it shouldn't be that hard so I'll look into starting a bzr-specific one and see how it turns out.

I've got an "alpha" version of a sphinx texinfo builder. It was more work than I anticipated but this is
mainly due to learning rest/sphinx/texinfo data and processing models.

It can produce texinfo files for all the bzr documentation and makeinfo can process them without errors.
There are a few warnings related to Top nodes, but this is expected since this part is not yet implemented.

The actual limitations are:
- not all rest constructs are translated yet,
- files are not grouped to reduce the number of info files,
- I had to workaround some small bugs in sphinx/docutils (I need feedback from knowledgeable people
  here as I may misunderstand some points).

All in all, I think it's a good base to discuss with the sphinx maintainers and texinfo experts.
See the associated branch https://code.edge.launchpad.net/~vila/bzr/219334-texinfo for the code.

well done!

I see you put this back to in progress: is that true? Perhaps we'd be better off filing and triaging bugs for shortcomings in what has been landed. (In particular I wonder if it's installed in the package?)

Well, I'm not actively working on it but it's not fixed released either, the implementation is more a proof of concept at this point and based on sphinx < 1.0.

We could switch to the "file bugs for remaining problems" when it can be used at least on maverick/natty and produce some minimally usable doc.

Vincent, was this perhaps fixed with your changes from today?

@jelmer: You're right. It doesn't make sense anymore to track progress on the texinfo doc with this bug.

The work is not finished but trunk now carries a version that should work with all the sphinx versions I've been able to test so we'd better file new bugs for the remaining problems (including switching to sphinx on pqm, using proper references (instead of http urls) and finishing the texinfo implementation).

@Stefan: Given the wide range of the bug, I'm closing it to better track progress, it doesn't mean the provided tools address your original report but we need more focused bugs from now on.

Where can I find the ReST sources of the bazaar documentation?

I want to try converting the ReST source to .org then .org to TeXinfo.

Thanks.

@Bastien: I'm not sure what you call '.org' but using 'make texinfo-sphinx' will generate both the '.texi' files and the '.info' ones.