[Structuredtext-checkins] CVS: restructuredtext/spec rst-notes.txt,1.41,1.42
Status: Pre-Alpha
Brought to you by:
goodger
|
From: David G. <go...@us...> - 2002-04-18 02:43:25
|
Update of /cvsroot/structuredtext/restructuredtext/spec
In directory usw-pr-cvs1:/tmp/cvs-serv12854/restructuredtext/spec
Modified Files:
rst-notes.txt
Log Message:
Fixed whitespace & updated
Index: rst-notes.txt
===================================================================
RCS file: /cvsroot/structuredtext/restructuredtext/spec/rst-notes.txt,v
retrieving revision 1.41
retrieving revision 1.42
diff -C2 -d -r1.41 -r1.42
*** rst-notes.txt 13 Apr 2002 16:27:04 -0000 1.41
--- rst-notes.txt 18 Apr 2002 02:43:22 -0000 1.42
***************
*** 26,30 ****
- Create a standalone reStructuredText -> HTML/XML converter (stdin ->
! stdout filter). (Flesh out tools/quicktest.py.)
- Allow very long titles (on two or more lines)?
--- 26,30 ----
- Create a standalone reStructuredText -> HTML/XML converter (stdin ->
! stdout filter). (Flesh out tools/quicktest.py.)
- Allow very long titles (on two or more lines)?
***************
*** 33,48 ****
allowed to be very long (two or more lines) also?
! - Allow hyperlink references to targets in other documents? Not in an
HTML-centric way, though (it's trivial to say
``http://www.whatever.com/doc#name``, and useless in non-HTML
! contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
2001-08-10.
! - Add character processing? For example:
- ``--`` -> em-dash (or ``--`` -> en-dash, and ``---`` -> em-dash).
(Look for pre-existing conventions.)
! - Convert quotes to curly quote entities. (Essentially impossible
! for HTML? Unnecessary for TeX. An output issue?)
- Various forms of ``:-)`` to smiley icons.
- ``"\ "`` -> .
--- 33,48 ----
allowed to be very long (two or more lines) also?
! - Allow hyperlink references to targets in other documents? Not in an
HTML-centric way, though (it's trivial to say
``http://www.whatever.com/doc#name``, and useless in non-HTML
! contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
2001-08-10.
! - Add character processing? For example:
- ``--`` -> em-dash (or ``--`` -> en-dash, and ``---`` -> em-dash).
(Look for pre-existing conventions.)
! - Convert quotes to curly quote entities. (Essentially impossible
! for HTML? Unnecessary for TeX. An output issue?)
- Various forms of ``:-)`` to smiley icons.
- ``"\ "`` -> .
***************
*** 52,56 ****
- Others?
! How to represent character entities in the text though? Probably as
Unicode.
--- 52,56 ----
- Others?
! How to represent character entities in the text though? Probably as
Unicode.
***************
*** 58,66 ****
the writer?
! - Implement the header row separator modification to table.el. (Wrote
! to Takaaki Ota & the table.el mailing list on 2001-08-12,
! suggesting support for '=====' header rows. On 2001-08-17 he
! replied, saying he'd put it on his to-do list, but don't hold your
! breath.)
- Tony says inline markup rule 7 could do with a *little* more
--- 58,65 ----
the writer?
! - Implement the header row separator modification to table.el. (Wrote
! to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
! support for '=====' header rows. On 2001-08-17 he replied, saying
! he'd put it on his to-do list, but "don't hold your breath".)
- Tony says inline markup rule 7 could do with a *little* more
***************
*** 80,85 ****
- Tighten up the spec for indentation of "constructs using complex
! markers": field lists and option lists? Bodies may begin on the same
! line as the marker or on a subsequent line (with blank lines
optional). Require that for bodies beginning on the same line as
the marker, all lines be in strict alignment. Currently, this is
--- 79,84 ----
- Tighten up the spec for indentation of "constructs using complex
! markers": field lists and option lists? Bodies may begin on the
! same line as the marker or on a subsequent line (with blank lines
optional). Require that for bodies beginning on the same line as
the marker, all lines be in strict alignment. Currently, this is
***************
*** 90,94 ****
This proposal would make the above example illegal, instead
! requiring strict alignment. A field body may either begin on the
same line::
--- 89,93 ----
This proposal would make the above example illegal, instead
! requiring strict alignment. A field body may either begin on the
same line::
***************
*** 116,136 ****
numbering; add support to .contents; could be cmdline option also)
! - misc.raw, .include (``#include`` one file in another; but how to
! parse wrt sections, reference names, conflicts?), .exec
! (execute Python code & insert the results; dangerous?), .eval
! (evaluate an expression & insert the text; at parse time or
! substitution time?)
! - block.qa (Questions & Answers; implement as a generic two-column
! marked list?)
! - colorize.python (Colorize Python code. Fine for HTML output, what
! about other formats? Revert to a literal block? Do we need some
! kind of "alternate" mechanism? Perhaps use a "pending" transform,
! which could switch its output based on the "format" in use. Use a
! factory function "transformFF()" which returns either
! "HTMLTransform()" instance or "GenericTransform" instance?)
! - text.date (for substitutions)
- Combined with misc.include, implement canned macros?
--- 115,143 ----
numbering; add support to .contents; could be cmdline option also)
! - misc.raw
! - misc.include: ``#include`` one file in another. But how to
! parse wrt sections, reference names, conflicts?
! - misc.exec: Execute Python code & insert the results. Perhaps
! dangerous?
! - misc.eval: Evaluate an expression & insert the text. At parse
! time or at substitution time?
!
! - block.qa: Questions & Answers. Implement as a generic two-column
! marked list? Or as a standalone construct?
!
! - block.columns: Multi-column table/list, with number of columns as
! argument.
!
! - colorize.python: Colorize Python code. Fine for HTML output, but
! what about other formats? Revert to a literal block? Do we need
! some kind of "alternate" mechanism? Perhaps use a "pending"
! transform, which could switch its output based on the "format" in
! use. Use a factory function "transformFF()" which returns either
! "HTMLTransform()" instance or "GenericTransform" instance?
!
! - text.date: Datestamp. For substitutions.
- Combined with misc.include, implement canned macros?
***************
*** 140,149 ****
- Use the language module for directive attribute names?
- Allow syntax constructs to be added or disabled at run-time.
! - Make footnotes two-way, GNU-style? What if there are multiple
references to a single footnote?
! - Add RFC-822 header parsing (for PEP, email Readers).
- Change ``.. meta::`` to use a "pending" element, only activated for
--- 147,158 ----
- Use the language module for directive attribute names?
+ - Add more attributes to the image directive: align, border?
+
- Allow syntax constructs to be added or disabled at run-time.
! - Make footnotes two-way, GNU-style? What if there are multiple
references to a single footnote?
! - Add RFC-2822 header parsing (for PEP, email Readers).
- Change ``.. meta::`` to use a "pending" element, only activated for
***************
*** 169,183 ****
construct, such as a literal block?
! Both could be solved using empty comments (#2 already exists for a
! block quote after a literal block). But that's a hack.
See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's
"Structuring: a summary; and an attempt at EBNF", item 4.
Or Not To Do?
=============
! This is the realm of the possible but questionably probable. These
ideas are kept here as a record of what has been proposed, for
posterity and in case any of them prove to be useful.
--- 178,206 ----
construct, such as a literal block?
! Both could be solved using empty comments (problem 2 already exists
! for a block quote after a literal block). But that's a hack.
See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's
"Structuring: a summary; and an attempt at EBNF", item 4.
+ - Add a "verse" construct, for paragraphs with linebreaks preserved?
+ A directive would be easy; what about a literal-block-like prefix,
+ perhaps ';;'? E.g.::
+
+ Take it away, Eric the orchestra leader! ;;
+
+ Half a bee,
+ Philosophically,
+ Must ipso-facto
+ Half not be.
+ You see?
+
+ ...
+
Or Not To Do?
=============
! This is the realm of the possible but questionably probable. These
ideas are kept here as a record of what has been proposed, for
posterity and in case any of them prove to be useful.
***************
*** 188,193 ****
(A future revision of this specification may allow for compound
! enumerators, such as '1.a.' or '1(a)', to allow for nested enumerated
! lists without indentation.)
--- 211,216 ----
(A future revision of this specification may allow for compound
! enumerators, such as '1.1.' or '1.a.' or '1(a)', to allow for nested
! enumerated lists without indentation.)
***************
*** 195,199 ****
------------------------------
! Add these? Example::
#. Item 1.
--- 218,222 ----
------------------------------
! Add these? Example::
#. Item 1.
***************
*** 201,205 ****
#. Item 3.
! Arabic numerals only, or any sequence if first initialized? For
example::
--- 224,228 ----
#. Item 3.
! Arabic numerals only, or any sequence if first initialized? For
example::
***************
*** 209,228 ****
- Two-For-One Literal Blocks
- --------------------------
-
- [Aside: One possible variation is for meta-documentation (perhaps an
- extension?): use triple-colons (':::') or a directive ('..
- literal-parsed::') to indicate 'take the following literal block, mark
- it up as a literal block, then copy it and mark it up as if it weren't
- a literal block'. The implementation may insert text in-between, such
- as 'Marked up as:', or may alter the formatting (different font, set
- in a colored box, whatever).]
-
-
Sloppy Indentation of List Items
--------------------------------
! Perhaps the indentation shouldn't be so strict. Currently, this is
required::
--- 232,239 ----
Sloppy Indentation of List Items
--------------------------------
! Perhaps the indentation shouldn't be so strict. Currently, this is
required::
***************
*** 239,243 ****
1. First para.
! Block quote. (no good: requires some indent relative to first
para)
--- 250,254 ----
1. First para.
! Block quote. (no good: requires some indent relative to first
para)
***************
*** 250,254 ****
Literal block?
! Hmm... Non-strict indentation isn't such a good idea.
--- 261,265 ----
Literal block?
! Hmm... Non-strict indentation isn't such a good idea.
***************
*** 264,272 ****
Change that to *require* a blank line above and below, to reduce
! ambiguity. This "loosening" may be added later, once the parser's been
! nailed down. However, a serious drawback of this approach is to limit
! the content of each list item to a single paragraph. Garth Kidd is
! attempting to work out a consistent set of rules for "lazy
! indentation".
--- 275,281 ----
Change that to *require* a blank line above and below, to reduce
! ambiguity. This "loosening" may be added later, once the parser's
! been nailed down. However, a serious drawback of this approach is to
! limit the content of each list item to a single paragraph.
***************
*** 274,287 ****
`````````````````````````````````
! Consider a paragraph in a word processor. It is a single logical line
of text which ends with a newline, soft-wrapped arbitrarily at the
! right edge of the page or screen. We can think of a plaintext
paragraph in the same way, as a single logical line of text, ending
with two newlines (a blank line) instead of one, and which may contain
arbitrary line breaks (newlines) where it was accidentally
! hard-wrapped by an application. We can compensate for the accidental
hard-wrapping by "unwrapping" every unindented second and subsequent
! line. The indentation of the first line of a paragraph or list item
! would determine the indentation for the entire element. Blank lines
would be required between list items when using lazy indentation.
--- 283,296 ----
`````````````````````````````````
! Consider a paragraph in a word processor. It is a single logical line
of text which ends with a newline, soft-wrapped arbitrarily at the
! right edge of the page or screen. We can think of a plaintext
paragraph in the same way, as a single logical line of text, ending
with two newlines (a blank line) instead of one, and which may contain
arbitrary line breaks (newlines) where it was accidentally
! hard-wrapped by an application. We can compensate for the accidental
hard-wrapping by "unwrapping" every unindented second and subsequent
! line. The indentation of the first line of a paragraph or list item
! would determine the indentation for the entire element. Blank lines
would be required between list items when using lazy indentation.
***************
*** 309,318 ****
Term
! Definition. The indentation of the term is
required, as is the indentation of the definition's
first line.
When the definition extends to more than
! one line, lazy indentation may occur. (This is the second
paragraph of the definition.)
--- 318,327 ----
Term
! Definition. The indentation of the term is
required, as is the indentation of the definition's
first line.
When the definition extends to more than
! one line, lazy indentation may occur. (This is the second
paragraph of the definition.)
***************
*** 341,347 ****
Literal blocks and block quotes would still require consistent
! indentation for all their lines. For block quotes, we might be able to
! get away with only requiring that the first line of each contained
! element be indented. For example::
Here's a paragraph.
--- 350,356 ----
Literal blocks and block quotes would still require consistent
! indentation for all their lines. For block quotes, we might be able
! to get away with only requiring that the first line of each contained
! element be indented. For example::
Here's a paragraph.
***************
*** 356,364 ****
bullet list inside the block quote.
! Although feasible, this form of lazy indentation has problems. The
document structure and hierarchy is not obvious from the indentation,
! making the source plaintext difficult to read. This will also make
keeping track of the indentation while writing difficult and
! error-prone. However, these problems may be acceptable for Wikis and
email mode, where we may be able to rely on less complex structure
(few nested lists, for example).
--- 365,373 ----
bullet list inside the block quote.
! Although feasible, this form of lazy indentation has problems. The
document structure and hierarchy is not obvious from the indentation,
! making the source plaintext difficult to read. This will also make
keeping track of the indentation while writing difficult and
! error-prone. However, these problems may be acceptable for Wikis and
email mode, where we may be able to rely on less complex structure
(few nested lists, for example).
|