[Doc-SIG] Producing output

[Tony J Ibbs (Tibs)]

Paul Moore wrote:
> OK, looks like I accidentally volunteered myself :-)

Welcome aboard (from someone hanging off the side on a raft at the
moment!).

> I grabbed the latest daily snapshot of the RST and DPS
> projects. Looks like that is enough to start with.

Probably. ``restructuredtext/tools/quicktest.py`` is an example of an
initial "output command". Also, see below.

I found studying dps/dps/nodes.py (is that right?) fairly instructive -
that's the datastructure we're working with.

> Is there anything else I need?

Well, it's worth keeping up to date with dps and reST sources. If you've
got CVS, no problem, but I don't and thus I just grab the snapshots,
well, daily.

It may or may not be relevant, but I'm working on Windows/NT at work,
using Python 2.1, and on Debian at home, using Python 2.2a1 (soon to be
a3). I know David is working on a Mac, and I know it's been agreed not
to support Python 1.5.2 (so += and list comprehensions are OK, but
better not to use generators yet!).

As I said before, I'd recomment working on DPS documents until the
Python parsing is done - that's useful enough!

> I just picked up Tibs' pydps stuff as well.
> I can't work out (yet) if that's also relevant.

OK. Mostly not. pydps.py is a fairly grotty user interface (!) - but the
"text" argument leads to some code that (like quicktest) parses and
presents a DPS text file.

It *might* be worth looking at the *structure* (but not the code!) of
html.py - I think that the use of a baseclass that implements the
formatting of a DPS, and can be subclassed for (e.g.) Python is a Good
Thing (I don't particularly care what it's called). I like the meme of
using a callable class - there are *so many* variables that one *might*
want to change in a formatter, but normally don't, that I think using a
class / class instance to hold them is useful. It means that the actual
``__call__`` can be kept fairly simple, and it also makes it easier to
"reuse" a particular formatter instance for more than one document.

The reason I say that the *code* of html.py might not be relevant is
that it is *very* quick and dirty - it doesn't assume direct knowledge
of the DPS node tree (at the moment) but just, well, hopes that if
``write_html()`` is called on each node, then something good will
happen. Of course, later on some propagation of information round the
code will be needed (if only to get the page title established!), but
quick and dirty gets me something I can work with now.

> I'll do some scratching of the output itch, but my biggest itch at the
> moment is for documentation of the internal phases (parser,
> intermediate representation, output?) and the data structures used to
> communicate between them.

As I said, reading nodes.py is useful. It's sufficiently close to
XML/DOM that you can leverage off any knowledge of that to work out what
is going on. The *advantage* is that David has some more useful methods
in there that are not (necessarily) in DOM.

> As I say, I'll look at something, too. Probably (La)TeX, as I
> can get PDF from that. But I'm low on tuits, so it may take a
> while before I get anything useful...

LaTeX is good because it's another popular format, and we'd need to do
it eventually.
 It's the one I would have probably gone for next (well, I prefer TeX to
LaTeX for this sort of simple document, but whatever).

On the other hand, this could be a really good opportunity to learn how
to use the ReportLab (http://www.reportlab.com/) stuff as well, and
produce PDF directly. Mind you, someone will get round to that someday
(maybe even ReportLab, I suppose, if DPS takes off).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)