[Structuredtext-checkins] CVS: restructuredtext/spec rst-notes.txt,1.41,1.42

[David G. <go...@us...>]

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