[Doc-SIG] Producing output

[Tony J Ibbs (Tibs)]

Moore, Paul (erm, Paul Moore) wrote:
> This is probably documented somewhere, but I couldn't find
> it, so I wonder if I'm asking the wrong questions...

No, it's not documented anywhere yet...

> 1. Given a text file in RST format, how do I produce nicely formatted
>    output? ... Note that "nicely formatted" to me
>    generally means something like PDF, or something (eg, (La-)TeX),
>    which can be transformed into PDF. HTML is *not* what I have in
>    mind...

Does XML meet your requirements?

`restructuredtext/tools/quicktest.py` will emit XML, and there are DTDs
around (i.e., somewhere in the source tree) describing it.

I'm not up-to-date enough with the TeX world to know if there are XML to
TeX translators. Does ReportLabs PDF engine take XML as input?

But also see below...

> 2. Given a Python module with RST docstrings, the same question.
>
> Maybe the answer in both cases is "you can't - we haven't got
> that far yet".

Indeed, that is the case.

> Which is fine, but I'd say that getting some form of output
> formatter is a priority, so that you can start getting
> feedback from the unwashed masses like me, who are only
> looking for something they can use...

Oh, we know, and we also want to be able to use the stuff! But time is
only linear...

At the moment, David is concentrating (I believe) on getting all of the
DPS/reST engines working, to do what is in the specs. At the rate he's
going, I don't know how much longer that will take him. Garth Kidd has
done some work as well, I believe, but again on innards.

Outside that effort (and unfortunately not in CVS), I've been working on
some code that parses Python files, extracting useful information (using
Tools/compiler) and producing an "extended" DPS nodes tree that includes
Python source information as well as any docstrings. This is seriously
unfinished (although also almost useful) and currently has output
alternatives XML ('cos it's totally trivial) and HTML (being worked on).
I've chosen HTML because (a) it's a quick fix (LaTeX or PDF would have a
longer generate/consider/change cycle), (b) it's early on the list of
wishes (*lots* of people can "read" HTML) and (c) it's viewable on all
the machines I work on. pydps (for so it is called) can be found at:

	http://www.tibsnjoan.co.uk/reST/pydps.tgz

which is updated every day or so. It doesn't have a decent user
interface (that's niggling at me enough it may change relatively soon),
and still needs a scad more work just to present all of the information
it should, but it's growing rapidly (well, sort of rapidly).

In many ways, the HTML output phase is the least important - the
derivation of a DPS node tree for Python, and the production of *an*
example of an output formatter, is more important (than the specific
format).

Personally (check with David for a more informed opinion!) I'd say that
it would not hurt to have an alternative effort looking at producing
LaTeX or PDF output from a DPS document (I'd advise leaving the
full-blown Python thing until what I'm working on is a bit more mature).
Working from the DPS node tree is quite fun, and we should be able to
stand two independent efforts! I have some ideas on the *form* that an
output parser should take (I like a Writer class that has a __call__
method that does the work), but that's just *my* idea, and I haven't had
feedback from David about what he thinks of this, or how he sees
different formatters integrating into DPS in detail (I suspect he hasn't
*got* detailed ideas yet).

(NB: the *way* that my HTML writer works is *not* something I'd
recommend - it is exceedingly dumb)

It may be worth your joining the DPS and restructured text development
lists (and CVS checking lists) - see

	http://sourceforge.net/mail/?group_id=26626
	http://sourceforge.net/mail/?group_id=7050

(which are linked to off the DPS and reStructuredText home pages).

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)