[IPython-user] Time for documentation infrastructure overhaul?

Nicolas Pernetty nicopernetty@yahoo...
Wed Aug 22 18:36:51 CDT 2007


On Tue, 21 Aug 2007 22:51:21 -0600, "Fernando Perez"
<fperez.net@gmail.com> wrote :

> > May I humbly suggest using Docbook ?
> > Docbook can be directly converted to HTML (using simple xsltproc)
> > and can be easily converted to LaTeX (and so PDF) using dblatex
> > (http://dblatex.sourceforge.net/).
> >
> > Dblatex is written in Python and is actively maintained by his very
> > responsive author.
> >
> > Using Docbook/XML you can be as modular as you want and still
> > retained the ability to generate individual documents as well as
> > the whole.
> >
> > I'd give a hand to convert Ipython docs to Docbook if you want (but
> > I don't know reStructuredText...).
> 
> Many thanks for the offer, but I think that docbook is going in the
> opposite direction that we want.  I suspect that if people found
> editing LyX was a hurdle, Docbook isn't going to fare a whole lot
> better.  As Stefan mentioned, Lyx can already write out docbook, so we
> could be using that today if we wanted.
> 
> But the point is to have the docs in a simple, plaintext format that
> is easy to edit with any editor and minimal markup.  The ipython docs
> need to be functional but not a work of art in typesetting, and we
> have no complex mathematics to worry about (the uncontested domain of
> latex/lyx).  I wrote the original manual in Lyx simply because I write
> *everything* in latex/lyx, but I realize that's not a very common
> workflow in other fields.  And recently I've become quite fond of
> reST: it's trivial to pick up, anyone can just type it in without
> markup and it works correctly, and prettyfing contributions to
> complete the markup is very easy (at least with Emacs' superb reST
> mode).
> 
> The fact that the core Python team has gone with this toolchain is
> also a plus to follow this direction: the more standard tools we use,
> the better supported we'll be, since we can ride on their efforts.
> 
> Maintaining the docs is something that should be as low effort as
> possible, else it will take already limited resources away, or simply
> won't get done.
> 
> I'll be glad to entertain the views of others if you think that
> docbook would make life easier, but I'll need to hear very good
> arguments on how a docbook-based workflow would be a LOT easier than
> Lyx/latex.


No problem, I understand perfectly.
The really real edge that got dblatex is to offer a standard
docbook/XML syntax coupled with an ability to use the powerful equation
engine of LateX.
It's just a shame that it's not popular enough...

I've practised a lot LaTeX and I find it almost impossible to deal with
if you don't dig deep inside the subtil mechanism.

Docbook (with dblatex) is really simpler and can produce a very
acceptable PDF document. You just have to learn some tags...

For Ipython, surely ReST would be the optimum solution. But if there is
a ReST->Docbook converter, you should take the time to try dblatex and
be astonished by the result...

And don't forget that MoinMoin can produce Docbook...

Regards,



More information about the IPython-user mailing list