[Docutils-checkins] docutils/spec/rst reStructuredText.txt,1.3,1.4

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

Update of /cvsroot/docutils/docutils/spec/rst
In directory usw-pr-cvs1:/tmp/cvs-serv26508/docutils/spec/rst

Modified Files:
	reStructuredText.txt 
Log Message:
  - Clarified purpose of directives.

Index: reStructuredText.txt
===================================================================
RCS file: /cvsroot/docutils/docutils/spec/rst/reStructuredText.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** reStructuredText.txt	30 Apr 2002 02:22:22 -0000	1.3
--- reStructuredText.txt	10 May 2002 03:50:05 -0000	1.4
***************
*** 1582,1585 ****
--- 1582,1605 ----
  DTD elements: depend on the directive.
  
+ Directives are an extension mechanism for reStructuredText, a way of
+ adding support for new constructs without adding new syntax.
+ Directives which have been implemented and registered in the reference
+ reStructuredText parser are described in the `reStructuredText
+ Directives`_ document.  For example, here's how an image may be
+ placed::
+ 
+     .. image:: mylogo.png
+ 
+ A figure (a graphic with a caption) may placed like this::
+ 
+     .. figure:: larch.png
+        The larch.
+ 
+ An admonition (note, caution, etc.) contains other body elements::
+ 
+     .. note:: This is a paragraph
+ 
+        - Here is a bullet list.
+ 
  Directives are indicated by an explicit markup start (".. ") followed
  by the directive type, two colons, and whitespace.  Directive types
***************
*** 1610,1649 ****
  following indented text.
  
- Directives which have been implemented and registered in the reference
- reStructuredText parser are described in the `reStructuredText
- Directives`_ document.  Below are examples of implemented directives.
- 
  Directives are meant for the arbitrary processing of their contents
  (the directive data & text block), which can be transformed into
! something possibly unrelated to the original text.  Directives are
! used as an extension mechanism for reStructuredText, a way of adding
! support for new constructs without adding new syntax.  For example,
! here's how an image may be placed::
! 
!     .. image:: mylogo.png
! 
! A figure (a graphic with a caption) may placed like this::
! 
!     .. figure:: larch.png
!        The larch.
! 
! An admonition (note, caution, etc.) contains other body elements::
! 
!     .. note:: This is a paragraph
! 
!        - Here is a bullet list.
! 
! It may also be possible for directives to be used as pragmas, to
! modify the behavior of the parser, such as to experiment with
! alternate syntax.  There is no parser support for this functionality
! at present; if a reasonable need for pragma directives is found, they
! may be supported.
  
! Directives normally do not survive as "directive" elements past the
! parsing stage; they are a *parser construct* only, and have no
! intrinsic meaning outside of reStructuredText.  Instead, the parser
! will transform recognized directives into (possibly specialized)
! document elements.  Unknown directives will trigger level-3 (error)
! system messages.
  
  Syntax diagram::
--- 1630,1647 ----
  following indented text.
  
  Directives are meant for the arbitrary processing of their contents
  (the directive data & text block), which can be transformed into
! something possibly unrelated to the original text.  It may also be
! possible for directives to be used as pragmas, to modify the behavior
! of the parser, such as to experiment with alternate syntax.  There is
! no parser support for this functionality at present; if a reasonable
! need for pragma directives is found, they may be supported.
  
! Directives do not survive as "directive" elements past the parsing
! stage; they are a *parser construct* only, and have no intrinsic
! meaning outside of reStructuredText.  Instead, the parser will
! transform recognized directives into (possibly specialized) document
! elements.  Unknown directives will trigger level-3 (error) system
! messages.
  
  Syntax diagram::