[Docutils-checkins] docutils/docs/ref/rst directives.txt,1.68,1.69

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

Update of /cvsroot/docutils/docutils/docs/ref/rst
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv29873/docs/ref/rst

Modified Files:
	directives.txt 
Log Message:
Added warning about "raw" overuse/abuse

Index: directives.txt
===================================================================
RCS file: /cvsroot/docutils/docutils/docs/ref/rst/directives.txt,v
retrieving revision 1.68
retrieving revision 1.69
diff -u -d -r1.68 -r1.69
--- directives.txt	6 Nov 2004 17:13:44 -0000	1.68
+++ directives.txt	6 Nov 2004 19:51:17 -0000	1.69
@@ -1067,6 +1067,19 @@
 :Directive Content: Stored verbatim, uninterpreted.  None (empty) if a
                     "file" or "url" option given.
 
+.. WARNING::
+
+   The "raw" directive is a stop-gap measure allowing the author to
+   bypass reStructuredText's markup.  It is a "power-user" feature
+   that should not be overused or abused.  The use of "raw" ties
+   documents to specific output formats and makes them less portable.
+
+   If you often need to use the "raw" directive or a "raw"-derived
+   interpreted text role, that is a sign either of overuse/abuse or
+   that functionality may be missing from reStructuredText.  Please
+   describe your situation in email to
+   doc...@li....
+
 The "raw" directive indicates non-reStructuredText data that is to be
 passed untouched to the Writer.  The names of the output formats are
 given in the directive arguments.  The interpretation of the raw data
@@ -1303,7 +1316,7 @@
 
 :Directive Type: "role"
 :Doctree Element: None; affects subsequent parsing.
-:Directive Arguments: Two; one required (role name), one optional
+:Directive Arguments: Two; one required (new role name), one optional
                       (base role name, in parentheses).
 :Directive Options: Possible (depends on base role).
 :Directive Content: depends on base role.