Re: [Docutils-develop] "code-block" directive example

[G. M. <mi...@us...>]

On  7.06.07, Gael Varoquaux wrote:

> I am really happy to see interest in a code-block directive. Such a
> directive would be very useful for me.

> I wrote a light version of directive using no external packages (ie
> without pigment), but that only highlights Python. It does output latex
> and newlatex, thought.

> It is sitting in the patch tracker, waiting for review and comments.
> http://sourceforge.net/tracker/index.php?func=detail&aid=1595345&group_id=38414&atid=422032

Did you follow the tedious discussion of syntax highlight issues and a
code-block directive in docutils-users? In a `post to the docutils users
list`__, David Goodger concluded:
  
  * If reST is to grow a code-block (or sourcecode or syntax-highlight
    or whatever) directive, it must be independent of the output format.
  
  * The result will be stored in a literal_block node in the document
    tree.  There will be no new element.
    
  ...  
  
__ http://article.gmane.org/gmane.text.docutils.user/3923


If I got this right, your patch would need to 

* parse the content of a code-block directive into a <literal-block>
  doctree element with <inline> nodes for the tokens (analog to
  `myfunction.py.xml`_). 
  
* not insert output-specific content and not bother about the output. 

Fixing writers that fail to render the "classified" <inline> elements is
a separate issue.

.. _myfunction.py.xml: http://pylit.berlios.de/features/myfunction.py.xml


> Maybe we can join forces and make a directive that uses Pygment when it
> can and falls back to this code elsewhere (ie no Pygment, or non Pygment
> compatible ouput).


Before putting too much effort in a "fallback parser", I would wait for a
decision whether

1. it is OK for Docutils to depend on another package (here `Pygments`),

   -> Pygments might become a requirement for docutils, 

2. there should not be any dependency on non-standard Python extensions
   in the Docutils core. 
  
   -> A "Pygments-based" code-block directive could become a "parallel
      project".

3. Docutils will support optional features that are only available if
   a recommended package or module is installed.
  
   -> code-block directive content would be 
   
      - rendered with syntax highlight if ``import pygments`` works,
      
      - output as "ordinary" literal-block (preserve space, mono-coloured
        fixed-width font) if ``import pygments`` fails.
	
  
Case 2 and 3 could be combined with an internal fallback for Python code
(i.e. your patch).  

In any case, it would be desirable to have a common syntax for "parsed
source code blocks", i.e. for compatibility of reST documents, I'd like
to see a ``.. code-block::`` directive in the docutils core even in 
case 2.


> This has been sitting in the patch tracker for a wee while. I seems the
> best way to get it in would be to modify it so that it can be checked in
> the sandbox and get test and review through the sandbox. Am I wrong ?

Putting the example code and documentation for a code-block directive in
the sandbox seems "the right thing".

May I apply for read-write access to the sandbox? 
(My berlios.de user name is 'milde'.)

Günter