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