added syntax definition proposal

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@5461 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 30 insertions, 0 deletions

diff --git a/sandbox/code-block-directive/docs/syntax-highlight.txt b/sandbox/code-block-directive/docs/syntax-highlight.txt
index 7aac07bab..7f7d1a1e2 100644
--- a/sandbox/code-block-directive/docs/syntax-highlight.txt
+++ b/sandbox/code-block-directive/docs/syntax-highlight.txt
@@ -106,6 +106,36 @@ block directive`_).
 `code-block` directive proposal
 -------------------------------
 
+Syntax
+""""""
+
+This is the first draft for the definition analogue to other directives in 
+``directives.txt``. Comments welcome.
+
+:Directive Type: "code-block"
+:Doctree Element: literal_block
+:Directive Arguments: One or more, optional (class names).
+:Directive Options: None.
+:Directive Content: Becomes the body of the literal block.
+
+Unlike an ordinary literal block, the "code-block" directive constructs a
+literal block where the text is parsed as source code and syntax highlight
+rules for `language` are applied. If syntax rules for `language` are not
+known to docutils, it is rendered like an ordinary literal block.
+
+For example, the following snipped is parsed and marked up as python source 
+code. The actual rendering depends on the style-sheet. ::
+
+  .. code-block:: python
+
+    def my_function():
+        "just a test"
+        print 8/2
+
+If the language argument is missing, a default language should be used.
+Additional arguments might be used and e.g. passed to the pygments_ parser
+or (as class arguments) the output document.
+
 
 Reading
 """""""