David Goodger wrote:
> Tibs wrote:
> > The problem is writing the directives that take reST
> > input for one column of a table and put out the result of processing
> > it (e.g., to HTML) as the other column,
> That directive shouldn't be difficult to write. Section titles and
> transitions present a problem, but with some care everything else
> should be easy. Or we can just build a bunch of two-column tables,
> duplicate the examples, and put "::" before the ones on the left.
OK. An answer of "that's not as scary as you thought" is always good to
> I introduced a colleague to Docutils recently and let him loose with
> the docs. He professed confusion with the non-standard terms
> "fold-in" and "call-out", and I've seen confusion from others as well.
> I think we should reconsider this complexity. In a generated
> quickref, the reference style would be the default of the output
> format, "fold-in" for HTML, and "call-out" for a paper-only format.
The names of the two styles certainly don't help - good naming is one of
the hardest bits of any task, and I don't think I did particularly well
there. On the other hand, they *are* two different things, and both
styles are important - what *are* they called?
Anyway, whilst I personally like the idea of having both styles
available, it seems eminently sensible to say that one gets the style
(most) appropriate to the output format, and dropping the ability to ask
for either - at least until someone needs it enough to write the code to
However, in that case I still think the quickref has to say "well, there
are these two possible styles of output, and you'll get the one best
suited to your output medium" - it sounds a *bit* as if you're instead
saying that the quickref output to HTML would only describe the style
produced for HTML, which wouldn't be very helpful if I were using a
web-page of the quickref to consult whilst thinking about how my
document would appear in (for instance) PDF (or if I'd printed out the
quickref, from some random output format, long since having forgotten
which, and am referring to the paper copy).
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.)