Menu
▾
▴
[Docutils-checkins] docutils/docs/dev/rst alternatives.txt,1.33,1.34
|
From: David G. <go...@us...> - 2004-10-05 01:23:17
|
Update of /cvsroot/docutils/docutils/docs/dev/rst In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30524/docs/dev/rst Modified Files: alternatives.txt Log Message: implemented line blocks Index: alternatives.txt =================================================================== RCS file: /cvsroot/docutils/docutils/docs/dev/rst/alternatives.txt,v retrieving revision 1.33 retrieving revision 1.34 diff -u -d -r1.33 -r1.34 --- alternatives.txt 14 Jun 2004 19:48:38 -0000 1.33 +++ alternatives.txt 5 Oct 2004 01:23:03 -0000 1.34 @@ -1226,6 +1226,219 @@ .. _HTML: http://www.w3.org/MarkUp/ +Syntax for Line Blocks +====================== + +* An early idea: How about a literal-block-like prefix, perhaps + "``;;``"? (It is, after all, a *semi-literal* literal block, no?) + Example:: + + Take it away, Eric the Orchestra Leader! ;; + + A one, two, a one two three four + + Half a bee, philosophically, + must, *ipso facto*, half not be. + But half the bee has got to be, + *vis a vis* its entity. D'you see? + + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? + + Singing... + + Kinda lame. + +* Another idea: in an ordinary paragraph, if the first line ends with + a backslash (escaping the newline), interpret the entire paragraph + as a verse block? For example:: + + Add just one backslash\ + And this paragraph becomes + An awful haiku + + (Awful, and arguably invalid, since in Japanese the word "haiku" + contains three syllables not two.) + + This idea was superceded by the rules for escaped whitespace, useful + for `character-level inline markup`_. + +* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed + a "plain list" syntax (and also provided a patch):: + + | John Doe + | President, SuperDuper Corp. + | jd...@ex... + + __ http://thread.gmane.org/gmane.text.docutils.devel/1187 + + This syntax is very natural. However, these "plain lists" seem very + similar to line blocks, and I see so little intrinsic "list-ness" + that I'm loathe to add a new object. I used the term "blurbs" to + remove the "list" connotation from the originally proposed name. + Perhaps line blocks could be refined to add the two properties they + currently lack: + + A) long lines wrap nicely + B) HTML output doesn't look like program code in non-CSS web + browsers + + (A) is an issue of all 3 aspects of Docutils: syntax (construct + behaviour), internal representation, and output. (B) is partly an + issue of internal representation but mostly of output. + +ReStructuredText will redefine line blocks with the "|"-quoting +syntax. The following is my current thinking. + + +Syntax +------ + +Perhaps line block syntax like this would do:: + + | M6: James Bond + | MIB: Mr. J. + | IMF: not decided yet, but probably one of the following: + | Ethan Hunt + | Jim Phelps + | Claire Phelps + | CIA: Felix Leiter + +Note that the "nested" list does not have nested syntax (the "|" are +not further indented); the leading whitespace would still be +significant somehow (more below). As for long lines in the input, +this could suffice:: + + | John Doe + | Founder, President, Chief Executive Officer, Cook, Bottle + Washer, and All-Round Great Guy + | SuperDuper Corp. + | jd...@ex... + +The lack of "|" on the third line indicates that it's a continuation +of the second line, wrapped. + +I don't see much point in allowing arbitrary nested content. Multiple +paragraphs or bullet lists inside a "blurb" doesn't make sense to me. +Simple nested line blocks should suffice. + + +Internal Representation +----------------------- + +Line blocks are currently represented as text blobs as follows:: + + <!ELEMENT line_block %text.model;> + <!ATTLIST line_block + %basic.atts; + %fixedspace.att;> + +Instead, we could represent each line by a separate element:: + + <!ELEMENT line_block (line+)> + <!ATTLIST line_block %basic.atts;> + + <!ELEMENT line %text.model;> + <!ATTLIST line %basic.atts;> + +We'd keep the significance of the leading whitespace of each line +either by converting it to non-breaking spaces at output, or with a +per-line margin. Non-breaking spaces are simpler (for HTML, anyway) +but kludgey, and wouldn't support indented long lines that wrap. But +should inter-word whitespace (i.e., not leading whitespace) be +preserved? Currently it is preserved in line blocks. + +Representing a more complex line block may be tricky:: + + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + +Perhaps the representation could allow for nested line blocks:: + + <!ELEMENT line_block (line | line_block)+> + +With this model, leading whitespace would no longer be significant. +Instead, left margins are implied by the nesting. The example above +could be represented as follows:: + + <line_block> + <line> + But can a bee be said to be + <line_block> + <line> + or not to be an entire bee, + <line_block> + <line> + when half the bee is not a bee, + <line_block> + <line> + due to some ancient injury? + +I wasn't sure what to do about even more complex line blocks:: + + | Indented + | Not indented + | Indented a bit + | A bit more + | Only one space + +How should that be parsed and nested? Should the first line have +the same nesting level (== indentation in the output) as the fourth +line, or the same as the last line? Mark Nodine suggested that such +line blocks be parsed similarly to complexly-nested block quotes, +which seems reasonable. In the example above, this would result in +the nesting of first line matching the last line's nesting. In +other words, the nesting would be relative to neighboring lines +only. + + +Output +------ + +In HTML, line blocks are currently output as "<pre>" blocks, which +gives us significant whitespace and line breaks, but doesn't allow +long lines to wrap and causes monospaced output without stylesheets. +Instead, we could output "<div>" elements parallelling the +representation above, where each nested <div class="line_block"> would +have an increased left margin (specified in the stylesheet). + +Jarno suggested the following HTML output:: + + <div class="line_block"> + <span class="line">First, top level line</span><br class="hidden"/> + <div class="line_block"><span class="hidden"> </span> + <span class="line">Second, once nested</span><br class="hidden"/> + <span class="line">Third, once nested</span><br class="hidden"/> + ... + </div> + ... + </div> + +The ``<br class="hidden" />`` and ``<span +class="hidden"> </span>`` are meant to support non-CSS and +non-graphical browsers. I understand the case for "br", but I'm not +so sure about hidden " ". I question how much effort should be +put toward supporting non-graphical and especially non-CSS browsers, +at least for html4css1.py output. + +Should the lines themselves be ``<span>`` or ``<div>``? I don't like +mixing inline and block-level elements. + + +Implementation Plan +------------------- + +We'll leave the old implementation in place (via the "line-block" +directive only) until all Writers have been updated to support the new +syntax & implementation. The "line-block" directive can then be +updated to use the new internal representation, and its documentation +will be updated to recommend the new syntax. + + ----------------- Not Implemented ----------------- @@ -1922,219 +2135,6 @@ IOW, the parser ought to be as permissive as possible. -Syntax for Line Blocks -====================== - -* An early idea: How about a literal-block-like prefix, perhaps - "``;;``"? (It is, after all, a *semi-literal* literal block, no?) - Example:: - - Take it away, Eric the Orchestra Leader! ;; - - A one, two, a one two three four - - Half a bee, philosophically, - must, *ipso facto*, half not be. - But half the bee has got to be, - *vis a vis* its entity. D'you see? - - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... - - Kinda lame. - -* Another idea: in an ordinary paragraph, if the first line ends with - a backslash (escaping the newline), interpret the entire paragraph - as a verse block? For example:: - - Add just one backslash\ - And this paragraph becomes - An awful haiku - - (Awful, and arguably invalid, since in Japanese the word "haiku" - contains three syllables not two.) - - This idea was superceded by the rules for escaped whitespace, useful - for `character-level inline markup`_. - -* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed - a "plain list" syntax (and also provided a patch):: - - | John Doe - | President, SuperDuper Corp. - | jd...@ex... - - __ http://thread.gmane.org/gmane.text.docutils.devel/1187 - - This syntax is very natural. However, these "plain lists" seem very - similar to line blocks, and I see so little intrinsic "list-ness" - that I'm loathe to add a new object. I used the term "blurbs" to - remove the "list" connotation from the originally proposed name. - Perhaps line blocks could be refined to add the two properties they - currently lack: - - A) long lines wrap nicely - B) HTML output doesn't look like program code in non-CSS web - browsers - - (A) is an issue of all 3 aspects of Docutils: syntax (construct - behaviour), internal representation, and output. (B) is partly an - issue of internal representation but mostly of output. - -ReStructuredText will redefine line blocks with the "|"-quoting -syntax. The following is my current thinking. - - -Syntax ------- - -Perhaps line block syntax like this would do:: - - | M6: James Bond - | MIB: Mr. J. - | IMF: not decided yet, but probably one of the following: - | Ethan Hunt - | Jim Phelps - | Claire Phelps - | CIA: Felix Leiter - -Note that the "nested" list does not have nested syntax (the "|" are -not further indented); the leading whitespace would still be -significant somehow (more below). As for long lines in the input, -this could suffice:: - - | John Doe - | Founder, President, Chief Executive Officer, Cook, Bottle - Washer, and All-Round Great Guy - | SuperDuper Corp. - | jd...@ex... - -The lack of "|" on the third line indicates that it's a continuation -of the second line, wrapped. - -I don't see much point in allowing arbitrary nested content. Multiple -paragraphs or bullet lists inside a "blurb" doesn't make sense to me. -Simple nested line blocks should suffice. - - -Internal Representation ------------------------ - -Line blocks are currently represented as text blobs as follows:: - - <!ELEMENT line_block %text.model;> - <!ATTLIST line_block - %basic.atts; - %fixedspace.att;> - -Instead, we could represent each line by a separate element:: - - <!ELEMENT line_block (line+)> - <!ATTLIST line_block %basic.atts;> - - <!ELEMENT line %text.model;> - <!ATTLIST line %basic.atts;> - -We'd keep the significance of the leading whitespace of each line -either by converting it to non-breaking spaces at output, or with a -per-line margin. Non-breaking spaces are simpler (for HTML, anyway) -but kludgey, and wouldn't support indented long lines that wrap. But -should inter-word whitespace (i.e., not leading whitespace) be -preserved? Currently it is preserved in line blocks. - -Representing a more complex line block may be tricky:: - - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - -Perhaps the representation could allow for nested line blocks:: - - <!ELEMENT line_block (line | line_block)+> - -With this model, leading whitespace would no longer be significant. -Instead, left margins are implied by the nesting. The example above -could be represented as follows:: - - <line_block> - <line> - But can a bee be said to be - <line_block> - <line> - or not to be an entire bee, - <line_block> - <line> - when half the bee is not a bee, - <line_block> - <line> - due to some ancient injury? - -I wasn't sure what to do about even more complex line blocks:: - - | Indented - | Not indented - | Indented a bit - | A bit more - | Only one space - -How should that be parsed and nested? Should the first line have -the same nesting level (== indentation in the output) as the fourth -line, or the same as the last line? Mark Nodine suggested that such -line blocks be parsed similarly to complexly-nested block quotes, -which seems reasonable. In the example above, this would result in -the nesting of first line matching the last line's nesting. In -other words, the nesting would be relative to neighboring lines -only. - - -Output ------- - -In HTML, line blocks are currently output as "<pre>" blocks, which -gives us significant whitespace and line breaks, but doesn't allow -long lines to wrap and causes monospaced output without stylesheets. -Instead, we could output "<div>" elements parallelling the -representation above, where each nested <div class="line_block"> would -have an increased left margin (specified in the stylesheet). - -Jarno suggested the following HTML output:: - - <div class="line_block"> - <span class="line">First, top level line</span><br class="hidden"/> - <div class="line_block"><span class="hidden"> </span> - <span class="line">Second, once nested</span><br class="hidden"/> - <span class="line">Third, once nested</span><br class="hidden"/> - ... - </div> - ... - </div> - -The ``<br class="hidden" />`` and ``<span -class="hidden"> </span>`` are meant to support non-CSS and -non-graphical browsers. I understand the case for "br", but I'm not -so sure about hidden " ". I question how much effort should be -put toward supporting non-graphical and especially non-CSS browsers, -at least for html4css1.py output. - -Should the lines themselves be ``<span>`` or ``<div>``? I don't like -mixing inline and block-level elements. - - -Implementation Plan -------------------- - -We'll leave the old implementation in place (via the "line-block" -directive only) until all Writers have been updated to support the new -syntax & implementation. The "line-block" directive can then be -updated to use the new internal representation, and its documentation -will be updated to recommend the new syntax. - - List-Driven Tables ================== |