[Doc-SIG] some ideas for reStructuredText & document model

Tony J Ibbs (Tibs) tony@lsl.co.uk
Thu, 28 Feb 2002 10:37:40 -0000


David Goodger started to play with ideas after producing HTML output
(neat stuff, by the way, although see [1]_ at the bottom):
> - Change footnote syntax from ``.. [1]`` to ``_[1]``? Has this been
>   discussed before?

I've an idea it has, but can't remember details.

Hmm. Colour me ambivalent on this one - I quite like being able to scan
down the left hand side of the text looking for "..<space>" to allow me
to find the things being referenced.

>   Example, current syntax::
>
>       .. [GVR2001] Python Documentation; van Rossum, Drake, et al.;
>          http://www.python.org/doc/
>
>   Proposed new syntax::
>
>       _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
>       http://www.python.org/doc/
>
>   Note that the body of the footnote need not be indented.

I'd suggest producing an example with mixed footnotes and reference
targets (sorry, forget the correct terminology) - I've certainly found
it useful to have a group of these together at the end of a section of
text, and the common left hand margin style makes that look visually
neater.

The ultimate test is surely how well the plain text reads when cast in
either manner - as I say, I suspect the footnote targets will still be
easier to find, in plaintext, with the ".." notation.

 > - Differentiate author-date "citations" (``[GVR2002]``) from numbered
>   footnotes? Create a new set of DTD elements: "citation" and
>   "citation_reference"?

Surely that's a presentation issue, and thus only relevant to the
Writer? - i.e., if the footnote is numbered (or anonymously numbered)
then present it one way, otherwise another.

Presentation is an issue for the output phase, not the parser (and
*will* differ according to the abilities of the target format).

> - Render footnote references as superscripts without "[]"? (But only
>   if we differentiate numerical footnotes from textual citations.)

This is definitely a Writer issue - many HTML browsers, for instance,
are rubbish at presenting superscripts (and I'd want to check our what
lynx or links did with superscripts, too!), so if your HTML Writer were
to adopt this approach, you might well get complaints. In a [La]TeX
Writer, though, this would be more appropriate.

> - Make footnotes two-way, GNU-style? What if there are multiple
>   references to a single footnote?

Again, this is a Writer issue. In HTML, for linkages that are singular
in both directions, having the back link can be very convenient. What to
do about linkages that are multiple in the reverse direction is, of
course, up to the person writing the Writer...

> - Directive ideas: TOC (GNU-style two-way), endnotes *here*,
>   citations *here*.

Surely also influenced by a command line option, in the same way that
the choice of fold in or call out indirect hyperlinks is a run time
choice?

(a [set of] command line option[s] to say that all notes or footnotes or
whatever are to be gathered together at the end (of the document,
section, etc.), and what the section they are gathered into should be
called, are surely things to consider strongly as options to the Writer,
and thus also command line options to the interface to the system using
that Writer)

> - Add a list of pending transforms to the document node, generated by
>   directives? Or add an element, "pending" perhaps, which encapsulates
>   the transform, the point at which to apply it, and any data
>   required.

Not sure I understand this, but I'm behind in my understanding of the
system at the moment anyway...

> - Add a "sidebar" element to the DTD? Like a generic admonition or
>   floating mini-section. Useful for TOC, system messages section,
>   abstract, etc.

Presentation again - it's usefulness depends entirely upon the target
format (keep thinking of plain text, LaTeX and PDF as alternatives to
HTML!)

> - Add character processing? For example:
>
>   - "--" -> em-dash (or "--" -> en-dash, and "---" -> em-dash)

Some of us would quite like these particular cases - I'd look for
pre-existing conventions, though, as to how many hyphens mean what.

>   - convert quotes to curly quote entities

A presentation issue - for HTML, don't bother, as it's essentially
impossible. For [La]TeX, don't bother as it will do it for you
anyway(!).

>   - various forms of ":-)" to smily icons

Can we all say "ick"?

>   - others?

Forced linebreak (without paragraph break) and non-breaking space are
the other obvious ones, but syntax is problematical (as we've found
before!).

>   How to represent entities in the text though? Unicode?

I'd say that this is definitely getting too ambitious for this stage of
the project. Also, bear in mind that over the next few years Unicode
support in filesystems is presumably going to start to happen (cf. the
PEP on the Python list for Unicode Python files!), so "someone else" may
lead us to this.

Tibs

(who still thinks that "::" blocks should be indented in the HTML output
for neat appearance, but realises that others may disagree)

-------------------
.. [1] In the output at
   http://structuredtext.sourceforge.net/spec/test.html,
   the example admonitions are uniformly set into boxes
   that are wider than my browser page. This presumably
   means that something in the document is of fixed
   width, rather than relative. I suspect it may actually
   be the fault of the "docinfo" table at the top of
   the document, in particular the "copyright" field,
   which is also too wide. I don't, however, understand
   stylesheets well enough to see any obvious problem...

--
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.)