diff options
| author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2007-06-08 16:05:01 +0000 |
|---|---|---|
| committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2007-06-08 16:05:01 +0000 |
| commit | 0784ae4285103bb3098e482fc4f915b977fdf6db (patch) | |
| tree | c44f93238162a571b54c12a352c53b1850ec1281 /sandbox/code-block-directive/docs | |
| parent | 698b0e9f6dd70ef89d4e47783efbaff903e3155a (diff) | |
| download | docutils-0784ae4285103bb3098e482fc4f915b977fdf6db.tar.gz | |
New sandbox project for development of a code-block directive
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@5229 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'sandbox/code-block-directive/docs')
15 files changed, 1833 insertions, 0 deletions
diff --git a/sandbox/code-block-directive/docs/for-else-test.py.html b/sandbox/code-block-directive/docs/for-else-test.py.html new file mode 100644 index 000000000..bc3ca5fb9 --- /dev/null +++ b/sandbox/code-block-directive/docs/for-else-test.py.html @@ -0,0 +1,179 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> +<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> +<title>Example for syntax highlight with Pygments</title> +<style type="text/css"> + +/* Stylesheet for pygments enhanced reStructured Text */ +/* ================================================== */ + +/* :Author: Guenter Milde */ +/* :Copyright: 2007 G. Milde */ +/* This stylesheet is released under the GPL v. 2 or later */ + +/* This stylesheet provides syntax highlight for documents generated with a */ +/* pygments_ enhanced reStructured Text -> html converter. */ + +/* import the default docutils style sheet */ +/* --------------------------------------- */ + +/* :: */ + +@import url("/stylesheets/html4css1.css"); + +/* Indent the code block */ +/* --------------------- */ + +/* Content copied from the `html4css1.css` rule for literal blocks. */ +/* Selector adapted to the output of Pygments_. */ + +div.highlight { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee + } + + +/* Colour code blocks */ +/* ------------------ */ + +/* Pygments_ has an option to generate stylesheets for html and latex. */ +/* The following code is generated with the command */ +/* `pygmentize -S default -f html > pygments-default.css`:: */ + +.c { color: #008800; font-style: italic } /* Comment */ +.err { border: 1px solid #FF0000 } /* Error */ +.k { color: #AA22FF; font-weight: bold } /* Keyword */ +.o { color: #666666 } /* Operator */ +.cm { color: #008800; font-style: italic } /* Comment.Multiline */ +.cp { color: #008800 } /* Comment.Preproc */ +.c1 { color: #008800; font-style: italic } /* Comment.Single */ +.gd { color: #A00000 } /* Generic.Deleted */ +.ge { font-style: italic } /* Generic.Emph */ +.gr { color: #FF0000 } /* Generic.Error */ +.gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.gi { color: #00A000 } /* Generic.Inserted */ +.go { color: #808080 } /* Generic.Output */ +.gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.gt { color: #0040D0 } /* Generic.Traceback */ +.kc { color: #AA22FF; font-weight: bold } /* Keyword.Constant */ +.kd { color: #AA22FF; font-weight: bold } /* Keyword.Declaration */ +.kp { color: #AA22FF } /* Keyword.Pseudo */ +.kr { color: #AA22FF; font-weight: bold } /* Keyword.Reserved */ +.kt { color: #AA22FF; font-weight: bold } /* Keyword.Type */ +.m { color: #666666 } /* Literal.Number */ +.s { color: #BB4444 } /* Literal.String */ +.na { color: #BB4444 } /* Name.Attribute */ +.nb { color: #AA22FF } /* Name.Builtin */ +.nc { color: #0000FF } /* Name.Class */ +.no { color: #880000 } /* Name.Constant */ +.nd { color: #AA22FF } /* Name.Decorator */ +.ni { color: #999999; font-weight: bold } /* Name.Entity */ +.ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +.nf { color: #00A000 } /* Name.Function */ +.nl { color: #A0A000 } /* Name.Label */ +.nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.nt { color: #008000; font-weight: bold } /* Name.Tag */ +.nv { color: #B8860B } /* Name.Variable */ +.ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.mf { color: #666666 } /* Literal.Number.Float */ +.mh { color: #666666 } /* Literal.Number.Hex */ +.mi { color: #666666 } /* Literal.Number.Integer */ +.mo { color: #666666 } /* Literal.Number.Oct */ +.sb { color: #BB4444 } /* Literal.String.Backtick */ +.sc { color: #BB4444 } /* Literal.String.Char */ +.sd { color: #BB4444; font-style: italic } /* Literal.String.Doc */ +.s2 { color: #BB4444 } /* Literal.String.Double */ +.se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +.sh { color: #BB4444 } /* Literal.String.Heredoc */ +.si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +.sx { color: #008000 } /* Literal.String.Other */ +.sr { color: #BB6688 } /* Literal.String.Regex */ +.s1 { color: #BB4444 } /* Literal.String.Single */ +.ss { color: #B8860B } /* Literal.String.Symbol */ +.bp { color: #AA22FF } /* Name.Builtin.Pseudo */ +.vc { color: #B8860B } /* Name.Variable.Class */ +.vg { color: #B8860B } /* Name.Variable.Global */ +.vi { color: #B8860B } /* Name.Variable.Instance */ +.il { color: #666666 } /* Literal.Number.Integer.Long */ + +/* .. _pygments: http://pygments.org/ */ + +</style> +</head> +<body> +<div class="document" id="example-for-syntax-highlight-with-pygments"> +<h1 class="title">Example for syntax highlight with Pygments</h1> +<!-- # -*- rst-mode -*- --> +<p>Translate this document to HTML with a pygments enhanced frontend:</p> +<pre class="literal-block"> +rst2html-pygments --stylesheet=pygments-default.css +</pre> +<p>or to LaTeX with:</p> +<pre class="literal-block"> +rst2latex-pygments --stylesheet=pygments-default.sty +</pre> +<p>to gain syntax highlight in the output.</p> +<!-- Run the doctests with ``pylit - -doctest for-else-test.py``. --> +<div class="section"> +<h1><a id="for-else-test" name="for-else-test">for-else-test</a></h1> +<p>Test the flow in a <cite>for</cite> loop with <cite>else</cite> statement.</p> +<p>First define a simple <cite>for</cite> loop.</p> +<div class="highlight"><pre><span class="k">def</span> <span class="nf">loop1</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span> + <span class="sd">"""simple for loop with `else` statement"""</span> + <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span> + <span class="k">print</span> <span class="n">i</span> + <span class="k">else</span><span class="p">:</span> + <span class="k">print</span> <span class="s">"iterable empty"</span> + <span class="k">print</span> <span class="s">"Ende"</span> +</pre></div> +<p>Now test it:</p> +<p>The first test runs as I expect: iterator empty -> else clause applies:</p> +<div class="highlight"><pre><span class="gp">>>> </span><span class="n">loop1</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span> +<span class="go">iterable empty</span> +<span class="go">Ende</span> +</pre></div> +<p>However, the else clause even runs if the iterator is not empty in the first +place but after it is "spent":</p> +<div class="highlight"><pre><span class="gp">>>> </span><span class="n">loop1</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">))</span> +<span class="go">0</span> +<span class="go">1</span> +<span class="go">2</span> +<span class="go">iterable empty</span> +<span class="go">Ende</span> +</pre></div> +<p>It seems like the else clause can only be prevented, if we break out of +the loop. Let's try</p> +<div class="highlight"><pre><span class="k">def</span> <span class="nf">loop2</span><span class="p">(</span><span class="n">iterable</span><span class="p">):</span> + <span class="sd">"""for loop with `break` and `else` statement"""</span> + <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">iterable</span><span class="p">:</span> + <span class="k">print</span> <span class="n">i</span> + <span class="k">break</span> + <span class="k">else</span><span class="p">:</span> + <span class="k">print</span> <span class="s">"iterable empty"</span> + <span class="k">print</span> <span class="s">"Ende"</span> +</pre></div> +<p>And indeed, the else clause is skipped after breaking out of the loop:</p> +<div class="highlight"><pre><span class="gp">>>> </span><span class="n">loop2</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">))</span> +<span class="go">0</span> +<span class="go">Ende</span> +</pre></div> +<p>The empty iterator runs as expected:</p> +<div class="highlight"><pre><span class="gp">>>> </span><span class="n">loop2</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span> +<span class="go">iterable empty</span> +<span class="go">Ende</span> +</pre></div> +</div> +</div> +<div class="footer"> +<hr class="footer" /> +Generated on: 2007-05-29. + +</div> +</body> +</html> diff --git a/sandbox/code-block-directive/docs/for-else-test.py.pdf b/sandbox/code-block-directive/docs/for-else-test.py.pdf Binary files differnew file mode 100644 index 000000000..b8e63b5e8 --- /dev/null +++ b/sandbox/code-block-directive/docs/for-else-test.py.pdf diff --git a/sandbox/code-block-directive/docs/for-else-test.py.tex b/sandbox/code-block-directive/docs/for-else-test.py.tex new file mode 100644 index 000000000..b664d4865 --- /dev/null +++ b/sandbox/code-block-directive/docs/for-else-test.py.tex @@ -0,0 +1,166 @@ +\documentclass[10pt,a4paper,english]{article} +\usepackage{babel} +\usepackage{ae} +\usepackage{aeguill} +\usepackage{shortvrb} +\usepackage[latin1]{inputenc} +\usepackage{tabularx} +\usepackage{longtable} +\setlength{\extrarowheight}{2pt} +\usepackage{amsmath} +\usepackage{graphicx} +\usepackage{color} +\usepackage{multirow} +\usepackage{ifthen} +\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} +\usepackage[DIV12]{typearea} +%% generator Docutils: http://docutils.sourceforge.net/ +\newlength{\admonitionwidth} +\setlength{\admonitionwidth}{0.9\textwidth} +\newlength{\docinfowidth} +\setlength{\docinfowidth}{0.9\textwidth} +\newlength{\locallinewidth} +\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} +\newenvironment{optionlist}[1] +{\begin{list}{} + {\setlength{\labelwidth}{#1} + \setlength{\rightmargin}{1cm} + \setlength{\leftmargin}{\rightmargin} + \addtolength{\leftmargin}{\labelwidth} + \addtolength{\leftmargin}{\labelsep} + \renewcommand{\makelabel}{\optionlistlabel}} +}{\end{list}} +\newlength{\lineblockindentation} +\setlength{\lineblockindentation}{2.5em} +\newenvironment{lineblock}[1] +{\begin{list}{} + {\setlength{\partopsep}{\parskip} + \addtolength{\partopsep}{\baselineskip} + \topsep0pt\itemsep0.15\baselineskip\parsep0pt + \leftmargin#1} + \raggedright} +{\end{list}} +% begin: floats for footnotes tweaking. +\setlength{\floatsep}{0.5em} +\setlength{\textfloatsep}{\fill} +\addtolength{\textfloatsep}{3em} +\renewcommand{\textfraction}{0.5} +\renewcommand{\topfraction}{0.5} +\renewcommand{\bottomfraction}{0.5} +\setcounter{totalnumber}{50} +\setcounter{topnumber}{50} +\setcounter{bottomnumber}{50} +% end floats for footnotes +% some commands, that could be overwritten in the style file. +\newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}} +\newcommand{\titlereference}[1]{\textsl{#1}} +% end of "some commands" +\input{pygments-default.sty} +\title{Example for syntax highlight with Pygments} +\author{} +\date{} +\hypersetup{ +pdftitle={Example for syntax highlight with Pygments} +} +\raggedbottom +\begin{document} +\maketitle + + +\setlength{\locallinewidth}{\linewidth} +% # -*- rst-mode -*- + +Translate this document to HTML with a pygments enhanced frontend: +\begin{quote}{\ttfamily \raggedright \noindent +rst2html-pygments~-{}-stylesheet=pygments-default.css +}\end{quote} + +or to LaTeX with: +\begin{quote}{\ttfamily \raggedright \noindent +rst2latex-pygments~-{}-stylesheet=pygments-default.sty +}\end{quote} + +to gain syntax highlight in the output. +% Run the doctests with ``pylit --doctest for-else-test.py``. + + +%___________________________________________________________________________ + +\hypertarget{for-else-test}{} +\pdfbookmark[0]{for-else-test}{for-else-test} +\section*{for-else-test} + +Test the flow in a \titlereference{for} loop with \titlereference{else} statement. + +First define a simple \titlereference{for} loop. +\begin{Verbatim}[commandchars=@\[\]] +@Cax[def] @CaJ[loop1](iterable): + @Car["""simple for loop with `else` statement"""] + @Cax[for] i @Cam[in] iterable: + @Cax[print] i + @Cax[else]: + @Cax[print] @Cad["]@Cad[iterable empty]@Cad["] + @Cax[print] @Cad["]@Cad[Ende]@Cad["] + +\end{Verbatim} + +Now test it: + +The first test runs as I expect: iterator empty -{\textgreater} else clause applies: +\begin{Verbatim}[commandchars=@\[\]] +@CaN[>>> ]loop1(@CaW[range](@Cag[0])) +@Caa[iterable empty] +@Caa[Ende] + +\end{Verbatim} + +However, the else clause even runs if the iterator is not empty in the first +place but after it is ``spent'': +\begin{Verbatim}[commandchars=@\[\]] +@CaN[>>> ]loop1(@CaW[range](@Cag[3])) +@Caa[0] +@Caa[1] +@Caa[2] +@Caa[iterable empty] +@Caa[Ende] + +\end{Verbatim} + +It seems like the else clause can only be prevented, if we break out of +the loop. Let's try +\begin{Verbatim}[commandchars=@\[\]] +@Cax[def] @CaJ[loop2](iterable): + @Car["""for loop with `break` and `else` statement"""] + @Cax[for] i @Cam[in] iterable: + @Cax[print] i + @Cax[break] + @Cax[else]: + @Cax[print] @Cad["]@Cad[iterable empty]@Cad["] + @Cax[print] @Cad["]@Cad[Ende]@Cad["] + +\end{Verbatim} + +And indeed, the else clause is skipped after breaking out of the loop: +\begin{Verbatim}[commandchars=@\[\]] +@CaN[>>> ]loop2(@CaW[range](@Cag[3])) +@Caa[0] +@Caa[Ende] + +\end{Verbatim} + +The empty iterator runs as expected: +\begin{Verbatim}[commandchars=@\[\]] +@CaN[>>> ]loop2(@CaW[range](@Cag[0])) +@Caa[iterable empty] +@Caa[Ende] + +\end{Verbatim} + +\begin{center}\small + +Generated on: 2007-04-24. + + +\end{center} + +\end{document} diff --git a/sandbox/code-block-directive/docs/for-else-test.py.txt b/sandbox/code-block-directive/docs/for-else-test.py.txt new file mode 100644 index 000000000..b5ba05848 --- /dev/null +++ b/sandbox/code-block-directive/docs/for-else-test.py.txt @@ -0,0 +1,87 @@ +.. # -*- rst-mode -*- + +Example for syntax highlight with Pygments +========================================== + +Translate this document to HTML with a pygments enhanced frontend:: + + rst2html-pygments --stylesheet=pygments-default.css + +or to LaTeX with:: + + rst2latex-pygments --stylesheet=pygments-default.sty + +to gain syntax highlight in the output. + +.. Run the doctests with ``pylit --doctest for-else-test.py``. + + +for-else-test +------------- + +Test the flow in a `for` loop with `else` statement. + +First define a simple `for` loop. + +.. code-block:: python + + def loop1(iterable): + """simple for loop with `else` statement""" + for i in iterable: + print i + else: + print "iterable empty" + print "Ende" + +Now test it: + +The first test runs as I expect: iterator empty -> else clause applies: + +.. code-block:: pycon + + >>> loop1(range(0)) + iterable empty + Ende + +However, the else clause even runs if the iterator is not empty in the first +place but after it is "spent": + +.. code-block:: pycon + + >>> loop1(range(3)) + 0 + 1 + 2 + iterable empty + Ende + +It seems like the else clause can only be prevented, if we break out of +the loop. Let's try + +.. code-block:: python + + def loop2(iterable): + """for loop with `break` and `else` statement""" + for i in iterable: + print i + break + else: + print "iterable empty" + print "Ende" + +And indeed, the else clause is skipped after breaking out of the loop: + +.. code-block:: pycon + + >>> loop2(range(3)) + 0 + Ende + +The empty iterator runs as expected: + +.. code-block:: pycon + + >>> loop2(range(0)) + iterable empty + Ende + diff --git a/sandbox/code-block-directive/docs/myfunction.py.html b/sandbox/code-block-directive/docs/myfunction.py.html new file mode 100644 index 000000000..eb3365b00 --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.html @@ -0,0 +1,29 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> +<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> +<title></title> +<link rel="stylesheet" href="../tools/pygments-default.css" type="text/css" /> +</head> +<body> +<div class="document"> +<p>This is a test of the new code-block directive:</p> +<!-- Translate this document to HTML with a pygments enhanced frontend, e.g. + +rst2html-highlight - -stylesheet=pygments-default.css - -link-stylesheet --> +<pre class="code-block python literal-block"> +<span class="k">def</span> <span class="nf">my_function</span><span class="p">():</span> + <span class="s">"just a test"</span> + <span class="k">print</span> <span class="mi">8</span><span class="o">/</span><span class="mi">2</span> + +</pre> +</div> +<div class="footer"> +<hr class="footer" /> +Generated on: 2007-06-05. + +</div> +</body> +</html> diff --git a/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.pdf b/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.pdf Binary files differnew file mode 100644 index 000000000..658eb59d7 --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.pdf diff --git a/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.tex b/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.tex new file mode 100644 index 000000000..d2d67cfea --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.newlatex2e.tex @@ -0,0 +1,209 @@ +% Generated by Docutils 0.4.1 <http://docutils.sourceforge.net>. + +% Docutils settings: +\providecommand{\Dlanguageiso}{en} +\providecommand{\Dlanguagebabel}{english} + +% Docutils stylesheet: +\input{/usr/lib/python2.4/site-packages/docutils/writers/newlatex2e/base.tex} + +% Default definitions for Docutils nodes: +\providecommand{\DNText}[1]{#1} +\providecommand{\DNabbreviation}[1]{#1} +\providecommand{\DNacronym}[1]{#1} +\providecommand{\DNaddress}[1]{#1} +\providecommand{\DNadmonition}[1]{#1} +\providecommand{\DNattention}[1]{#1} +\providecommand{\DNattribution}[1]{#1} +\providecommand{\DNauthor}[1]{#1} +\providecommand{\DNauthors}[1]{#1} +\providecommand{\DNblockquote}[1]{#1} +\providecommand{\DNbulletlist}[1]{#1} +\providecommand{\DNcaption}[1]{#1} +\providecommand{\DNcaution}[1]{#1} +\providecommand{\DNcitation}[1]{#1} +\providecommand{\DNcitationreference}[1]{#1} +\providecommand{\DNclassifier}[1]{#1} +\providecommand{\DNcolspec}[1]{#1} +\providecommand{\DNcomment}[1]{#1} +\providecommand{\DNcompound}[1]{#1} +\providecommand{\DNcontact}[1]{#1} +\providecommand{\DNcontainer}[1]{#1} +\providecommand{\DNcopyright}[1]{#1} +\providecommand{\DNdanger}[1]{#1} +\providecommand{\DNdate}[1]{#1} +\providecommand{\DNdecoration}[1]{#1} +\providecommand{\DNdefinition}[1]{#1} +\providecommand{\DNdefinitionlist}[1]{#1} +\providecommand{\DNdefinitionlistitem}[1]{#1} +\providecommand{\DNdescription}[1]{#1} +\providecommand{\DNdocinfo}[1]{#1} +\providecommand{\DNdoctestblock}[1]{#1} +\providecommand{\DNdocument}[1]{#1} +\providecommand{\DNemphasis}[1]{#1} +\providecommand{\DNentry}[1]{#1} +\providecommand{\DNenumeratedlist}[1]{#1} +\providecommand{\DNerror}[1]{#1} +\providecommand{\DNfield}[1]{#1} +\providecommand{\DNfieldbody}[1]{#1} +\providecommand{\DNfieldlist}[1]{#1} +\providecommand{\DNfieldname}[1]{#1} +\providecommand{\DNfigure}[1]{#1} +\providecommand{\DNfooter}[1]{#1} +\providecommand{\DNfootnote}[1]{#1} +\providecommand{\DNfootnotereference}[1]{#1} +\providecommand{\DNgenerated}[1]{#1} +\providecommand{\DNheader}[1]{#1} +\providecommand{\DNhint}[1]{#1} +\providecommand{\DNimage}[1]{#1} +\providecommand{\DNimportant}[1]{#1} +\providecommand{\DNinline}[1]{#1} +\providecommand{\DNlabel}[1]{#1} +\providecommand{\DNlegend}[1]{#1} +\providecommand{\DNline}[1]{#1} +\providecommand{\DNlineblock}[1]{#1} +\providecommand{\DNlistitem}[1]{#1} +\providecommand{\DNliteral}[1]{#1} +\providecommand{\DNliteralblock}[1]{#1} +\providecommand{\DNnote}[1]{#1} +\providecommand{\DNoption}[1]{#1} +\providecommand{\DNoptionargument}[1]{#1} +\providecommand{\DNoptiongroup}[1]{#1} +\providecommand{\DNoptionlist}[1]{#1} +\providecommand{\DNoptionlistitem}[1]{#1} +\providecommand{\DNoptionstring}[1]{#1} +\providecommand{\DNorganization}[1]{#1} +\providecommand{\DNparagraph}[1]{#1} +\providecommand{\DNpending}[1]{#1} +\providecommand{\DNproblematic}[1]{#1} +\providecommand{\DNraw}[1]{#1} +\providecommand{\DNreference}[1]{#1} +\providecommand{\DNrevision}[1]{#1} +\providecommand{\DNrow}[1]{#1} +\providecommand{\DNrubric}[1]{#1} +\providecommand{\DNsection}[1]{#1} +\providecommand{\DNsidebar}[1]{#1} +\providecommand{\DNstatus}[1]{#1} +\providecommand{\DNstrong}[1]{#1} +\providecommand{\DNsubscript}[1]{#1} +\providecommand{\DNsubstitutiondefinition}[1]{#1} +\providecommand{\DNsubstitutionreference}[1]{#1} +\providecommand{\DNsubtitle}[1]{#1} +\providecommand{\DNsuperscript}[1]{#1} +\providecommand{\DNsystemmessage}[1]{#1} +\providecommand{\DNtable}[1]{#1} +\providecommand{\DNtarget}[1]{#1} +\providecommand{\DNtbody}[1]{#1} +\providecommand{\DNterm}[1]{#1} +\providecommand{\DNtgroup}[1]{#1} +\providecommand{\DNthead}[1]{#1} +\providecommand{\DNtip}[1]{#1} +\providecommand{\DNtitle}[1]{#1} +\providecommand{\DNtitlereference}[1]{#1} +\providecommand{\DNtopic}[1]{#1} +\providecommand{\DNtransition}[1]{#1} +\providecommand{\DNversion}[1]{#1} +\providecommand{\DNwarning}[1]{#1} + +% Auxiliary definitions: +\providecommand{\Dsetattr}[2]{} +\providecommand{\Dparent}{} % variable +\providecommand{\Dattr}[5]{#5} +\providecommand{\Dattrlen}{} % variable +\providecommand{\Dtitleastext}{x} % variable +\providecommand{\Dsinglebackref}{} % variable +\providecommand{\Dmultiplebackrefs}{} % variable +\providecommand{\Dparagraphindented}{false} % variable + + +\Dvisitdocument% + \Dattr{}{source}{/home/milde/.python/PyLit/trunk/rstdocs/features/myfunction.py.txt}{document}{% + }% + \renewcommand{\Dparent}{document}% + \DNdecoration{% + \renewcommand{\Dparent}{decoration}% + \DNfooter{% + \renewcommand{\Dparagraphindented}{false}% + \renewcommand{\Dparent}{footer}% + \DNparagraph{% + Generated{ }on:{ }2007{-}06{-}05.{ }% + }% + }% + }% + \renewcommand{\Dparagraphindented}{true}% + \renewcommand{\Dparent}{document}% + \DNparagraph{% + This{ }is{ }a{ }test{ }of{ }the{ }new{ }code{-}block{ }directive:% + }% + \Dauxiliaryspace% + \renewcommand{\Dparent}{document}% + \DNcomment{% + \Dattr{}{xml:space}{preserve}{comment}{% + % Translate this document to HTML with a pygments enhanced frontend, e.g. + % + % rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet + }}% + \renewcommand{\Dparent}{document}% + \def\DcurrentNliteralblockAraw_content{[u'def my_function():', u' "{}just a test"{}', u' print 8/2']}% + \DNliteralblock{% + \renewcommand{\Dattrlen}{2}% + \Dattr{1}{classes}{code-block}{literalblock}{% + \Dattr{2}{classes}{python}{literalblock}{% + \Dattr{}{raw_content}{[u'def my_function():', u' "{}just a test"{}', u' print 8/2']}{literalblock}{% + \Dattr{}{xml:space}{preserve}{literalblock}{% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{k}{inline}{% + def% + }}% + ~% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{nf}{inline}{% + my{\Dtextunderscore}function% + }}% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{p}{inline}{% + ():% + }}% + \mbox{}\\~~~~% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{s}{inline}{% + {"}just~a~test{"}% + }}% + \mbox{}\\~~~~% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{k}{inline}{% + print% + }}% + ~% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{mi}{inline}{% + 8% + }}% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{o}{inline}{% + /% + }}% + \renewcommand{\Dparent}{literalblock}% + \DNinline{% + \renewcommand{\Dattrlen}{1}% + \Dattr{1}{classes}{mi}{inline}{% + 2% + }}% + \mbox{}\\% + }}}}}% + \let\DcurrentNliteralblockAraw_content=\relax% +\Ddepartdocument% diff --git a/sandbox/code-block-directive/docs/myfunction.py.pseudoxml b/sandbox/code-block-directive/docs/myfunction.py.pseudoxml new file mode 100644 index 000000000..6a71c2ede --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.pseudoxml @@ -0,0 +1,35 @@ +<document source="/home/milde/.python/PyLit/trunk/rstdocs/features/myfunction.py.txt"> + <decoration> + <footer> + <paragraph> + Generated on: 2007-06-05. + <paragraph> + This is a test of the new code-block directive: + <comment xml:space="preserve"> + Translate this document to HTML with a pygments enhanced frontend, e.g. + + rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet + <literal_block classes="code-block python" raw_content="[u'def my_function():', u' "just a test"', u' print 8/2']" xml:space="preserve"> + <inline classes="k"> + def + + <inline classes="nf"> + my_function + <inline classes="p"> + (): + + + <inline classes="s"> + "just a test" + + + <inline classes="k"> + print + + <inline classes="mi"> + 8 + <inline classes="o"> + / + <inline classes="mi"> + 2 + diff --git a/sandbox/code-block-directive/docs/myfunction.py.tex b/sandbox/code-block-directive/docs/myfunction.py.tex new file mode 100644 index 000000000..d8c934c7a --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.tex @@ -0,0 +1,84 @@ +\documentclass[10pt,a4paper,english]{article} +\usepackage{babel} +\usepackage{ae} +\usepackage{aeguill} +\usepackage{shortvrb} +\usepackage[latin1]{inputenc} +\usepackage{tabularx} +\usepackage{longtable} +\setlength{\extrarowheight}{2pt} +\usepackage{amsmath} +\usepackage{graphicx} +\usepackage{color} +\usepackage{multirow} +\usepackage{ifthen} +\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} +\usepackage[DIV12]{typearea} +%% generator Docutils: http://docutils.sourceforge.net/ +\newlength{\admonitionwidth} +\setlength{\admonitionwidth}{0.9\textwidth} +\newlength{\docinfowidth} +\setlength{\docinfowidth}{0.9\textwidth} +\newlength{\locallinewidth} +\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} +\newenvironment{optionlist}[1] +{\begin{list}{} + {\setlength{\labelwidth}{#1} + \setlength{\rightmargin}{1cm} + \setlength{\leftmargin}{\rightmargin} + \addtolength{\leftmargin}{\labelwidth} + \addtolength{\leftmargin}{\labelsep} + \renewcommand{\makelabel}{\optionlistlabel}} +}{\end{list}} +\newlength{\lineblockindentation} +\setlength{\lineblockindentation}{2.5em} +\newenvironment{lineblock}[1] +{\begin{list}{} + {\setlength{\partopsep}{\parskip} + \addtolength{\partopsep}{\baselineskip} + \topsep0pt\itemsep0.15\baselineskip\parsep0pt + \leftmargin#1} + \raggedright} +{\end{list}} +% begin: floats for footnotes tweaking. +\setlength{\floatsep}{0.5em} +\setlength{\textfloatsep}{\fill} +\addtolength{\textfloatsep}{3em} +\renewcommand{\textfraction}{0.5} +\renewcommand{\topfraction}{0.5} +\renewcommand{\bottomfraction}{0.5} +\setcounter{totalnumber}{50} +\setcounter{topnumber}{50} +\setcounter{bottomnumber}{50} +% end floats for footnotes +% some commands, that could be overwritten in the style file. +\newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}} +\newcommand{\titlereference}[1]{\textsl{#1}} +% end of "some commands" +\title{} +\author{} +\date{} +\raggedbottom +\begin{document} + +\setlength{\locallinewidth}{\linewidth} + +This is a test of the new code-block directive: +% Translate this document to HTML with a pygments enhanced frontend, e.g. +% +% rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet +\begin{quote}{\ttfamily \raggedright \noindent +\docutilsroleNone{def}~\docutilsroleNone{my{\_}function}\docutilsroleNone{():}~\\ +~~~~\docutilsroleNone{"just~a~test"}~\\ +~~~~\docutilsroleNone{print}~\docutilsroleNone{8}\docutilsroleNone{/}\docutilsroleNone{2}~\\ + +}\end{quote} + +\begin{center}\small + +Generated on: 2007-06-05. + + +\end{center} + +\end{document} diff --git a/sandbox/code-block-directive/docs/myfunction.py.txt b/sandbox/code-block-directive/docs/myfunction.py.txt new file mode 100644 index 000000000..926733dc0 --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.txt @@ -0,0 +1,11 @@ +This is a test of the new code-block directive: + +.. Translate this document to HTML with a pygments enhanced frontend, e.g. + + rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet + +.. code-block:: python + + def my_function(): + "just a test" + print 8/2 diff --git a/sandbox/code-block-directive/docs/myfunction.py.xml b/sandbox/code-block-directive/docs/myfunction.py.xml new file mode 100644 index 000000000..564e57e17 --- /dev/null +++ b/sandbox/code-block-directive/docs/myfunction.py.xml @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd"> +<!-- Generated by Docutils 0.4.1 --> +<document source="/home/milde/.python/PyLit/trunk/rstdocs/features/myfunction.py.txt"><decoration><footer><paragraph>Generated on: 2007-06-05. +</paragraph></footer></decoration><paragraph>This is a test of the new code-block directive:</paragraph><comment xml:space="preserve">Translate this document to HTML with a pygments enhanced frontend, e.g. + +rst2html-highlight --stylesheet=pygments-default.css --link-stylesheet</comment><literal_block classes="code-block python" raw_content="[u'def my_function():', u' "just a test"', u' print 8/2']" xml:space="preserve"><inline classes="k">def</inline> <inline classes="nf">my_function</inline><inline classes="p">():</inline> + <inline classes="s">"just a test"</inline> + <inline classes="k">print</inline> <inline classes="mi">8</inline><inline classes="o">/</inline><inline classes="mi">2</inline> +</literal_block></document> diff --git a/sandbox/code-block-directive/docs/pygments_code_block_directive.py.html b/sandbox/code-block-directive/docs/pygments_code_block_directive.py.html new file mode 100644 index 000000000..15af90a8c --- /dev/null +++ b/sandbox/code-block-directive/docs/pygments_code_block_directive.py.html @@ -0,0 +1,137 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> +<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> +<title></title> +<meta name="author" content="a Pygments author|contributor; Felix Wiemann; Guenter Milde" /> +<meta name="date" content="$Date$" /> +<meta name="copyright" content="This module has been placed in the public domain." /> +<link rel="stylesheet" href="/usr/lib/python2.4/site-packages/docutils/writers/html4css1/html4css1.css" type="text/css" /> +</head> +<body> +<div class="document"> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Author:</th> +<td>a Pygments author|contributor; Felix Wiemann; Guenter Milde</td></tr> +<tr><th class="docinfo-name">Date:</th> +<td>$Date$</td></tr> +<tr><th class="docinfo-name">Copyright:</th> +<td>This module has been placed in the public domain.</td></tr> +</tbody> +</table> +<!-- #!/usr/bin/python --> +<p>This is a merge of <a class="reference" href="http://pygments.org/docs/rstdirective/">Using Pygments in ReST documents</a> from the <a class="reference" href="http://pygments.org/">pygments</a> +documentation, and a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3689">proof of concept</a> by Felix Wiemann.</p> +<table border="1" class="docutils"> +<colgroup> +<col width="14%" /> +<col width="86%" /> +</colgroup> +<tbody valign="top"> +<tr><td>2007-06-01</td> +<td>Removed redundancy from class values.</td> +</tr> +<tr><td>2007-06-04</td> +<td>Merge of successive tokens of same type +(code taken from pygments.formatters.others).</td> +</tr> +<tr><td>2007-06-05</td> +<td>Separate docutils formatter script +Use pygments' CSS class names (like the html formatter) +allowing the use of pygments-produced style sheets.</td> +</tr> +</tbody> +</table> +<pre class="literal-block"> +"""Define and register a code-block directive using pygments +""" +</pre> +<div class="section"> +<h1><a id="requirements" name="requirements">Requirements</a></h1> +<pre class="literal-block"> +from docutils import nodes +from docutils.parsers.rst import directives +import pygments +from pygments.lexers import get_lexer_by_name +from pygments_docutils_formatter import DocutilsFormatter +</pre> +</div> +<div class="section"> +<h1><a id="customisation" name="customisation">Customisation</a></h1> +<p>Do not insert inline nodes for the following tokens. +(You could add e.g. Token.Punctuation like <tt class="docutils literal"><span class="pre">['',</span> <span class="pre">'p']</span></tt>.)</p> +<pre class="literal-block"> +unstyled_tokens = [''] +</pre> +</div> +<div class="section"> +<h1><a id="code-block-directive" name="code-block-directive">code_block_directive</a></h1> +<pre class="literal-block"> +def code_block_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + language = arguments[0] + # create a literal block element and set class argument + code_block = nodes.literal_block(raw_content=content, + classes=["code-block", language]) + # Get lexer for language (use text as fallback) + try: + lexer = get_lexer_by_name(language) + except ValueError: + lexer = get_lexer_by_name('text') + + # parse content with pygments + tokens = list(pygments.lex(u'\n'.join(content), lexer)) + + for cls, value in DocutilsFormatter(tokens): + if cls in unstyled_tokens: + # insert as Text to decrease the verbosity of the output. + code_block += nodes.Text(value, value) + else: + code_block += nodes.inline(value, value, classes=[cls]) + + return [code_block] +</pre> +</div> +<div class="section"> +<h1><a id="register-directive" name="register-directive">Register Directive</a></h1> +<pre class="literal-block"> +code_block_directive.arguments = (1, 0, 1) +code_block_directive.content = 1 +directives.register_directive('code-block', code_block_directive) +</pre> +</div> +<div class="section"> +<h1><a id="test-output" name="test-output">Test output</a></h1> +<p>If called from the command line, call the docutils publisher to render the +input:</p> +<pre class="literal-block"> +if __name__ == '__main__': + from docutils.core import publish_cmdline, default_description + description = "code-block directive test output" + default_description + try: + import locale + locale.setlocale(locale.LC_ALL, '') + except: + pass + # Uncomment the desired output format: + publish_cmdline(writer_name='pseudoxml', description=description) + # publish_cmdline(writer_name='xml', description=description) + # publish_cmdline(writer_name='html', description=description) + # publish_cmdline(writer_name='latex', description=description) + # publish_cmdline(writer_name='newlatex2e', description=description) +</pre> +</div> +</div> +<div class="footer"> +<hr class="footer" /> +<a class="reference" href="pygments_code_block_directive.py.txt">View document source</a>. +Generated on: 2007-06-05. + +</div> +</body> +</html> diff --git a/sandbox/code-block-directive/docs/pygments_with_docutils-latex-problems.txt b/sandbox/code-block-directive/docs/pygments_with_docutils-latex-problems.txt new file mode 100644 index 000000000..99ca7a48f --- /dev/null +++ b/sandbox/code-block-directive/docs/pygments_with_docutils-latex-problems.txt @@ -0,0 +1,27 @@ +Now to some of the details (This is rather for LaTeX inclined + +> > * latex-output seems even less usable. + +This is actually an understatement: + +Currently, an inline node with a class unknown to the latex writer like:: + + <inline classes="keyword"> + def + +is converted to a function:: + + \docutilsroleNone{def} + +which is not defined in the preamble and hence leads to an error if the +documents is translated to PDF. + +IMO, the missing feature is a "failsave" handling of class information: + + In HTML, the semantic syntax markup can be simply stored in a class + argument to a <span> element. It can be used by the CSS stylesheet for + syntax highlight and is simply ignored if no CSS rule for the given + class exists. + +LaTeX does not have a "class" attribute, so some emulation of this +concept is needed. Maybe we can use a \newcommand with optional argument? diff --git a/sandbox/code-block-directive/docs/syntax-highlight.html b/sandbox/code-block-directive/docs/syntax-highlight.html new file mode 100644 index 000000000..1591b6777 --- /dev/null +++ b/sandbox/code-block-directive/docs/syntax-highlight.html @@ -0,0 +1,417 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> +<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" /> +<title>Syntax Highlight</title> +<link rel="stylesheet" href="../../../../../lib/python2.4/site-packages/docutils/writers/html4css1/html4css1.css" type="text/css" /> +</head> +<body> +<div class="document" id="syntax-highlight"> +<h1 class="title">Syntax Highlight</h1> +<!-- -*- rst-mode -*- --> +<div class="contents topic"> +<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> +<ul class="auto-toc simple"> +<li><a class="reference" href="#existing-highlighting-additions-to-docutils" id="id9" name="id9">1 Existing highlighting additions to docutils</a></li> +<li><a class="reference" href="#pygments-enhanced-docutils-front-ends" id="id10" name="id10">2 Pygments enhanced docutils front-ends</a><ul class="auto-toc"> +<li><a class="reference" href="#example" id="id11" name="id11">2.1 Example</a></li> +</ul> +</li> +<li><a class="reference" href="#proposal-for-a-code-block-directive-in-docutils" id="id12" name="id12">3 Proposal for a code-block directive in docutils</a><ul class="auto-toc"> +<li><a class="reference" href="#parsing" id="id13" name="id13">3.1 Parsing</a></li> +<li><a class="reference" href="#writing" id="id14" name="id14">3.2 Writing</a></li> +<li><a class="reference" href="#todo" id="id15" name="id15">3.3 TODO</a></li> +</ul> +</li> +<li><a class="reference" href="#configurable-literal-block-directive" id="id16" name="id16">4 Configurable literal block directive</a><ul class="auto-toc"> +<li><a class="reference" href="#goal" id="id17" name="id17">4.1 Goal</a></li> +<li><a class="reference" href="#inline-analogon" id="id18" name="id18">4.2 Inline analogon</a></li> +<li><a class="reference" href="#proposal-make-the-default-literal-block-role-configurable" id="id19" name="id19">4.3 Proposal: make the default "literal block" role configurable.</a><ul class="auto-toc"> +<li><a class="reference" href="#motivation" id="id20" name="id20">4.3.1 Motivation</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference" href="#odtwriter" id="id21" name="id21">5 Odtwriter</a></li> +<li><a class="reference" href="#syntax-highlight-with-the-listings-sty-latex-package" id="id22" name="id22">6 Syntax highlight with the <tt class="docutils literal"><span class="pre">listings.sty</span></tt> LaTeX package</a></li> +</ul> +</div> +<p>Syntax highlighting significantly enhances the readability of code. +So it is almost a must for pretty-printing a literate program.</p> +<p><a class="reference" href="http://pylit.berlios.de">PyLit</a> uses <a class="reference" href="http://docutils.sourceforge.net/">docutils</a> as pretty-printing back end. However, in the current +version, docutils does not highlight literal blocks. This may change in the +future, as in a mail on +<a class="reference" href="http://sourceforge.net/mailarchive/message.php?msg_id=12921194">Questions about writing programming manuals and scientific documents</a>, +docutils main developer David Goodger wrote:</p> +<blockquote> +I'd be happy to include Python source colouring support, and other +languages would be welcome too. A multi-language solution would be +useful, of course. My issue is providing support for all output formats +-- HTML and LaTeX and XML and anything in the future -- simultaneously. +Just HTML isn't good enough. Until there is a generic-output solution, +this will be something users will have to put together themselves.</blockquote> +<div class="section"> +<h1><a class="toc-backref" href="#id9" id="existing-highlighting-additions-to-docutils" name="existing-highlighting-additions-to-docutils">1 Existing highlighting additions to docutils</a></h1> +<p>There are already docutils extensions providing syntax colouring, e.g:</p> +<ul class="simple"> +<li><a class="reference" href="http://silvercity.sourceforge.net/">SilverCity</a> is a C++ library and Python extension that can provide lexical +analysis for over 20 different programming languages. A <a class="reference" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170">recipe</a> +for a "code-block" directive provides syntax highlight by SilverCity.</li> +</ul> +<ul class="simple"> +<li>The <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> LaTeX package provides highly customisable and advanced +syntax highlight, though only for LaTeX (and LaTeX derived PS|PDF). +A <a class="reference" href="http://article.gmane.org/gmane.text.docutils.devel/3914">patch</a> mailed by Gael Varoquaux uses the listings package for a +"code-block" directive with syntax highlight.</li> +</ul> +<ul class="simple"> +<li><a class="reference" href="http://trac.edgewall.org/">Trac</a> has <a class="reference" href="http://trac.edgewall.org/wiki/WikiRestructuredText">reStructuredText support</a> and offers syntax highlighting with +a "code-block" directive using GNU <a class="reference" href="http://www.gnu.org/software/enscript/enscript.html">Enscript</a>, <a class="reference" href="http://silvercity.sourceforge.net/">SilverCity</a>, or <a class="reference" href="http://pygments.org/">Pygments</a>.</li> +</ul> +<ul class="simple"> +<li>The <a class="reference" href="http://www.voidspace.org.uk/python/rest2web/">rest2web</a> site builder provides the <a class="reference" href="http://www.voidspace.org.uk/python/rest2web/macros.html#colorize">colorize</a> macro (using the +<a class="reference" href="http://www.standards-schmandards.com/2005/fangs-093/">Moin-Moin Python colorizer</a>)</li> +</ul> +<ul class="simple"> +<li><a class="reference" href="http://pygments.org/">Pygments</a> a generic syntax highlighter for general use.<ul> +<li>Written completely in Python, usable as a command-line tool and as a +Python package.</li> +<li>A wide range of common <a class="reference" href="http://pygments.org/languages">languages and markup formats</a> is supported.</li> +<li>Additionally, OpenOffice's <tt class="docutils literal"><span class="pre">*.odt</span></tt> is supported by the <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">odtwriter</a>.</li> +<li>The layout is configurable by style sheets.</li> +<li>Several built-in styles and an option for line-numbering.</li> +<li>Built-in output formats include HTML, LaTeX, rtf</li> +<li>Support for new languages, formats, and styles is added easily (modular +structure, Python code, existing documentation).</li> +<li>Well documented and actively maintained.</li> +<li>The web site provides a recipe for <a class="reference" href="http://pygments.org/docs/rstdirective/">using Pygments in ReST documents</a>. +It is used in the <a class="reference" href="#pygments-enhanced-docutils-front-ends">Pygments enhanced docutils front-ends</a> below.</li> +</ul> +</li> +<li>The experimental <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">Odtwriter</a> for Docutils OpenOffice export supports syntax +colours using Pygments.</li> +</ul> +<p><a class="reference" href="http://pygments.org/">Pygments</a> seems to be the most promising docutils highlighter. For printed +output, the <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> package has its advantages too.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id10" id="pygments-enhanced-docutils-front-ends" name="pygments-enhanced-docutils-front-ends">2 Pygments enhanced docutils front-ends</a></h1> +<p>Here comes a working example for syntax highlighting in HTML and LaTeX +output with <a class="reference" href="http://pygments.org/">pygments</a>.</p> +<p>The example code in "<a class="reference" href="http://pygments.org/docs/rstdirective/">Using Pygments in ReST documents</a>" defines a new +"sourcecode" directive. The directive takes one argument <cite>language</cite> and uses +the <a class="reference" href="http://pygments.org/">Pygments</a> source highlighter to parse and render its content as a +colourful source code block.</p> +<p>Combining the <a class="reference" href="http://pygments.org/">pygments</a> example code with the standard <a class="reference" href="http://docutils.sourceforge.net/">docutils</a> front-ends, +results in front-end scripts generating output documents with syntax colour. +For consistency with the majority of existing add-ons, the directive is +renamed to "code-block".</p> +<dl class="docutils"> +<dt><a class="reference" href="../tools/rst2html-pygments">rst2html-pygments</a></dt> +<dd>enhances the standard docutils <tt class="docutils literal"><span class="pre">rst2html</span></tt> front-end to +generate a HTML rendering with syntax highlight.</dd> +<dt><a class="reference" href="../tools/rst2latex-pygments">rst2latex-pygments</a></dt> +<dd>enhances docutils' <tt class="docutils literal"><span class="pre">rst2latex</span></tt> to generate LaTeX with syntax highlight.</dd> +<dt>Advantages:</dt> +<dd><ul class="first last simple"> +<li>Easy implementation with no changes to the stock <a class="reference" href="http://docutils.sourceforge.net/">docutils</a>.</li> +<li>Separation of code blocks and ordinary literal blocks.</li> +</ul> +</dd> +<dt>Disadvantages:</dt> +<dd><ul class="first last simple"> +<li>"code-block" content is formatted by <a class="reference" href="http://pygments.org/">pygments</a> and inserted in the +document tree as a "raw" node making the approach writer-dependant.</li> +<li>documents are incompatible with the standard docutils because of the +locally defined directive.</li> +<li>more "invasive" markup distracting from content</li> +<li>no "minimal" code block marker -- three additional lines per code block</li> +</ul> +</dd> +</dl> +<p>The later disadvantages become an issue in literate programming where a code +block is the most used block markup (see the proposal for a <a class="reference" href="#configurable-literal-block-directive">configurable +literal block directive</a> below).</p> +<p>To support the <tt class="docutils literal"><span class="pre">..</span> <span class="pre">code-block::</span></tt> directive, the PyLit converter would need +a configurable "code block marker" instead of the hard coded <tt class="docutils literal"><span class="pre">::</span></tt> +presently in use. (See also the <a class="reference" href="../examples/pylit.py.html#code-block-directive">code-block directive</a> section in +pylit.py.)</p> +<div class="section"> +<h2><a class="toc-backref" href="#id11" id="example" name="example">2.1 Example</a></h2> +<dl class="docutils"> +<dt>Python script:</dt> +<dd><table class="first last docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">text source:</th><td class="field-body"><a class="reference" href="for-else-test.py.txt">for-else-test.py.txt</a></td> +</tr> +<tr class="field"><th class="field-name">HTML:</th><td class="field-body"><a class="reference" href="for-else-test.py.html">for-else-test.py.html</a></td> +</tr> +<tr class="field"><th class="field-name">LaTeX:</th><td class="field-body"><a class="reference" href="for-else-test.py.tex">for-else-test.py.tex</a></td> +</tr> +<tr class="field"><th class="field-name">PDF:</th><td class="field-body"><a class="reference" href="for-else-test.py.pdf">for-else-test.py.pdf</a></td> +</tr> +</tbody> +</table> +</dd> +<dt>Stylesheets:</dt> +<dd><table class="first last docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">CSS stylesheet:</th><td class="field-body"><a class="reference" href="../tools/pygments-default.css">pygments-default.css</a></td> +</tr> +<tr class="field"><th class="field-name">LaTeX style:</th><td class="field-body"><a class="reference" href="../tools/pygments-default.sty">pygments-default.sty</a></td> +</tr> +</tbody> +</table> +</dd> +</dl> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id12" id="proposal-for-a-code-block-directive-in-docutils" name="proposal-for-a-code-block-directive-in-docutils">3 Proposal for a code-block directive in docutils</a></h1> +<p>In a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3923">post to the docutils users list</a>, David Goodger wrote (after an all +too long discussion):</p> +<blockquote> +<p>Here are my pronouncements:</p> +<ul class="simple"> +<li>If reST is to grow a code-block (or sourcecode or syntax-highlight +or whatever) directive, it must be independent of the output format.</li> +<li>The result will be stored in a literal_block node in the document +tree. There will be no new element.</li> +<li>There will be no "unparsed" code-block. It would make no sense.</li> +<li>There will be no special pass-through support for LaTeX to do its +own syntax highlighting.</li> +</ul> +</blockquote> +<p>On 7.06.07, David Goodger wrote:</p> +<blockquote> +<p>On 6/7/07, G. Milde suggested:</p> +<ol class="arabic" start="3"> +<li><p class="first">Docutils will support optional features that are only available if +a recommended package or module is installed.</p> +<p>-> code-block directive content would be</p> +<blockquote> +<ul class="simple"> +<li>rendered with syntax highlight if <tt class="docutils literal"><span class="pre">import</span> <span class="pre">pygments</span></tt> works,</li> +<li>output as "ordinary" literal-block (preserve space, mono-coloured +fixed-width font) if <tt class="docutils literal"><span class="pre">import</span> <span class="pre">pygments</span></tt> fails.</li> +</ul> +</blockquote> +</li> +</ol> +<p>+1 on number 3.</p> +</blockquote> +<p>Implemented 2007-06-08.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id13" id="parsing" name="parsing">3.1 Parsing</a></h2> +<p>Felix Wiemann provided a <a class="reference" href="http://article.gmane.org/gmane.text.docutils.user/3689">proof of concept</a> script that utilizes the +<a class="reference" href="http://pygments.org/">pygments</a> parser to parse a source code string and store the result in +the document tree.</p> +<p>This concept is used in <a class="reference" href="pygments_code_block_directive.py.html">pygments_code_block_directive</a>, (source: +<a class="reference" href="../pygments_code_block_directive.py">pygments_code_block_directive.py</a>), to define and register a "code-block" +directive.</p> +<ul class="simple"> +<li>The <cite>DocutilsInterface</cite> class uses <a class="reference" href="http://pygments.org/">pygments</a> to parse the content of the +directive and classify the tokens using short CSS class names identical to +pygments HTML output. If pygments is not available, the unparsed code is +returned.</li> +<li>The <cite>code_block_directive</cite> function inserts the tokens in a "rich" +<literal_block> element with "classified" <inline> nodes.</li> +</ul> +<p>The XML rendering of the small example file <a class="reference" href="myfunction.py.txt">myfunction.py.txt</a> looks like +<a class="reference" href="myfunction.py.xml">myfunction.py.xml</a>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id14" id="writing" name="writing">3.2 Writing</a></h2> +<p>The writers can use the class information in the <inline> elements to render +the tokens. They should ignore the class information if they are unable to +use it or to pass it on.</p> +<dl class="docutils"> +<dt>HTML</dt> +<dd><p class="first">The "html" writer works out of the box.</p> +<ul class="simple"> +<li>The <a class="reference" href="../tools/rst2html-highlight">rst2html-highlight</a> front end registers the "code-block" directive and +converts an input file to html.</li> +<li>Styling is done with the adapted CSS style sheet <a class="reference" href="../tools/pygments-default.css">pygments-default.css</a> +based on docutils' default stylesheet and the output of +<tt class="docutils literal"><span class="pre">pygmentize</span> <span class="pre">-S</span> <span class="pre">default</span> <span class="pre">-f</span> <span class="pre">html</span></tt>.</li> +<li>The result looks like <a class="reference" href="myfunction.py.html">myfunction.py.html</a>.</li> +</ul> +<p class="last">The "s5" and "pep" writers are not tested yet.</p> +</dd> +<dt>XML</dt> +<dd>"xml" and "pseudoxml" work out of the box, too. See <a class="reference" href="myfunction.py.xml">myfunction.py.xml</a> +and <a class="reference" href="myfunction.py.pseudoxml">myfunction.py.pseudoxml</a></dd> +<dt>LaTeX</dt> +<dd><p class="first">Latex writers must be updated to handle the "rich" <literal_block> element +correct.</p> +<ul class="last"> +<li><p class="first">The "latex" writer currently fails to handle "classified" <inline> +doctree elements. The output <a class="reference" href="myfunction.py.tex">myfunction.py.tex</a> contains undefined +control sequences <tt class="docutils literal"><span class="pre">\docutilsroleNone</span></tt>.</p> +</li> +<li><p class="first">The "newlatex2e" writer produces a valid LaTeX document +(<a class="reference" href="myfunction.py.newlatex2e.tex">myfunction.py.newlatex2e.tex</a>). However the <cite>pdflatex</cite> output looks +mixed up a bit (<a class="reference" href="myfunction.py.newlatex2e.pdf">myfunction.py.newlatex2e.pdf</a>).</p> +<p>The pygments-produced style file will not currently work with +"newlatex2e" output.</p> +</li> +</ul> +</dd> +<dt>OpenOffice</dt> +<dd>The non-official "odtwriter" provides syntax highlight with +pygments but uses a different syntax.</dd> +</dl> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id15" id="todo" name="todo">3.3 TODO</a></h2> +<ul class="simple"> +<li>fix the "latex" writer.</li> +<li>think about an interface for pygments' options (like "encoding" or +"linenumbers").</li> +</ul> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id16" id="configurable-literal-block-directive" name="configurable-literal-block-directive">4 Configurable literal block directive</a></h1> +<div class="section"> +<h2><a class="toc-backref" href="#id17" id="goal" name="goal">4.1 Goal</a></h2> +<p>A clean and simple syntax for highlighted code blocks -- preserving the +space saving feature of the "minimised" literal block marker (<tt class="docutils literal"><span class="pre">::</span></tt> at the +end of a text paragraph). This is especially desirable in literate programs +with many code blocks.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id18" id="inline-analogon" name="inline-analogon">4.2 Inline analogon</a></h2> +<p>The <em>role</em> of inline <cite>interpreted text</cite> can be customised with the +"default-role" directive. This allows the use of the concise "backtick" +syntax for the most often used role, e.g. in a chemical paper, one could +use:</p> +<pre class="literal-block"> +.. default-role:: subscript + +The triple point of H`2`O is at 0°C. +</pre> +<p>This customisation is currently not possible for block markup.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id19" id="proposal-make-the-default-literal-block-role-configurable" name="proposal-make-the-default-literal-block-role-configurable">4.3 Proposal: make the default "literal block" role configurable.</a></h2> +<ul> +<li><p class="first">Define a new "literal" directive for an ordinary literal block. +This would insert the block content into the document tree as +"literal-block" element with no parsing.</p> +</li> +<li><p class="first">Define a "literal-block" setting that controls which directive is called +on a block following <tt class="docutils literal"><span class="pre">::</span></tt>. Default would be the "literal" directive.</p> +<p>Alternatively, define a new "default-literal-block" directive instead of +a settings key.</p> +</li> +<li><p class="first">From a syntax view, this would be analog to the behaviour of the <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">odtwriter</a>. +(I am not sure about the representation in the document tree, though.)</p> +</li> +</ul> +<div class="section"> +<h3><a class="toc-backref" href="#id20" id="motivation" name="motivation">4.3.1 Motivation</a></h3> +<p>Analogue to customising the default role of "interpreted text" with the +"default-role" directive, the concise <tt class="docutils literal"><span class="pre">::</span></tt> literal-block markup could be +used for e.g.</p> +<ul class="simple"> +<li>a "code-block" or "sourcecode" directive for colourful code +(analog to the one in the <a class="reference" href="#pygments-enhanced-docutils-front-ends">pygments enhanced docutils front-ends</a>)</li> +<li>the "line-block" directive for poems or addresses</li> +<li>the "parsed-literal" directive</li> +</ul> +<p>Example (using the upcoming "settings" directive):</p> +<pre class="literal-block"> +ordinary literal block:: + + some text typeset in monospace + +.. settings:: + :literal-block: code-block python + +colourful Python code:: + + def hello(): + print "hello world" +</pre> +<p>In the same line, a "default-block-quote" setting or directive could be +considered to configure the role of a block quote.</p> +</div> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id21" id="odtwriter" name="odtwriter">5 Odtwriter</a></h1> +<p>Dave Kuhlman's <a class="reference" href="http://www.rexx.com/~dkuhlman/odtwriter.html">odtwriter</a> extension can add syntax highlighting +to ordinary literal blocks.</p> +<p>The <tt class="docutils literal"><span class="pre">--add-syntax-highlighting</span></tt> command line flag activates syntax +highlighting in literal blocks. By default, the "python" lexer is used.</p> +<p>You can change this within your reST document with the <cite>sourcecode</cite> +directive:</p> +<pre class="literal-block"> +.. sourcecode:: off + +ordinary literal block:: + + content set in teletype + +.. sourcecode:: on +.. sourcecode:: python + +colourful Python code:: + + def hello(): + print "hello world" +</pre> +<p>The "sourcecode" directive defined by the odtwriter is principally +different from the "code-block" directive of <tt class="docutils literal"><span class="pre">rst2html-pygments</span></tt>:</p> +<ul> +<li><p class="first">The odtwriter directive does not have content. It is a switch.</p> +</li> +<li><p class="first">The syntax highlighting state and language/lexer set by this directive +remain in effect until the next sourcecode directive is encountered in the +reST document.</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">..</span> <span class="pre">sourcecode::</span> <span class="pre"><newstate></span></tt></dt> +<dd><p class="first last">make highlighting active or inactive. +<newstate> is either <tt class="docutils literal"><span class="pre">on</span></tt> or <tt class="docutils literal"><span class="pre">off</span></tt>.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">..</span> <span class="pre">sourcecode::</span> <span class="pre"><lexer></span></tt></dt> +<dd><p class="first last">change the lexer parsing literal code blocks. +<lexer> should be one of aliases listed at pygment's <a class="reference" href="http://pygments.org/languages">languages and +markup formats</a>.</p> +</dd> +</dl> +</li> +</ul> +<p>I.e. the odtwriter implements a <a class="reference" href="#configurable-literal-block-directive">configurable literal block directive</a> +(but with a slightly different syntax than my proposal below).</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id22" id="syntax-highlight-with-the-listings-sty-latex-package" name="syntax-highlight-with-the-listings-sty-latex-package">6 Syntax highlight with the <tt class="docutils literal"><span class="pre">listings.sty</span></tt> LaTeX package</a></h1> +<p>Using the <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> LaTeX package for syntax highlight is currently not +possible with the standard latex writer output.</p> +<p>Support for the use of <a class="reference" href="http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html">listings</a> with docutils is an issue that must be +settled separate from the <a class="reference" href="#proposal-for-a-code-block-directive-in-docutils">proposal for a code-block directive in +docutils</a>. It would need</p> +<ul class="simple"> +<li>a new, specialized docutils latex writer, or</li> +<li>a new option (and behaviour) to the existing latex writer.</li> +</ul> +<!-- External links --> +<!-- Internal links --> +</div> +</div> +<div class="footer"> +<hr class="footer" /> +<a class="reference" href="syntax-highlight.txt">View document source</a>. +Generated on: 2007-06-08. + +</div> +</body> +</html> diff --git a/sandbox/code-block-directive/docs/syntax-highlight.txt b/sandbox/code-block-directive/docs/syntax-highlight.txt new file mode 100644 index 000000000..954f10eab --- /dev/null +++ b/sandbox/code-block-directive/docs/syntax-highlight.txt @@ -0,0 +1,442 @@ +.. -*- rst-mode -*- + +Syntax Highlight +---------------- + +.. contents:: +.. sectnum:: + +Syntax highlighting significantly enhances the readability of code. +So it is almost a must for pretty-printing a literate program. + +PyLit_ uses docutils_ as pretty-printing back end. However, in the current +version, docutils does not highlight literal blocks. This may change in the +future, as in a mail on +`Questions about writing programming manuals and scientific documents`__, +docutils main developer David Goodger wrote: + + I'd be happy to include Python source colouring support, and other + languages would be welcome too. A multi-language solution would be + useful, of course. My issue is providing support for all output formats + -- HTML and LaTeX and XML and anything in the future -- simultaneously. + Just HTML isn't good enough. Until there is a generic-output solution, + this will be something users will have to put together themselves. + +__ http://sourceforge.net/mailarchive/message.php?msg_id=12921194 + + +Existing highlighting additions to docutils +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are already docutils extensions providing syntax colouring, e.g: + +* SilverCity_ is a C++ library and Python extension that can provide lexical + analysis for over 20 different programming languages. A recipe__ + for a "code-block" directive provides syntax highlight by SilverCity. + +__ http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170 + +* The `listings`_ LaTeX package provides highly customisable and advanced + syntax highlight, though only for LaTeX (and LaTeX derived PS|PDF). + A patch__ mailed by Gael Varoquaux uses the listings package for a + "code-block" directive with syntax highlight. + +__ http://article.gmane.org/gmane.text.docutils.devel/3914 + +* Trac_ has `reStructuredText support`__ and offers syntax highlighting with + a "code-block" directive using GNU Enscript_, SilverCity_, or Pygments_. + +__ http://trac.edgewall.org/wiki/WikiRestructuredText + +* The rest2web_ site builder provides the `colorize`__ macro (using the + `Moin-Moin Python colorizer`_) + +__ http://www.voidspace.org.uk/python/rest2web/macros.html#colorize + +* `Pygments`_ a generic syntax highlighter for general use. + + * Written completely in Python, usable as a command-line tool and as a + Python package. + * A wide range of common `languages and markup formats`_ is supported. + * Additionally, OpenOffice's ``*.odt`` is supported by the odtwriter_. + * The layout is configurable by style sheets. + * Several built-in styles and an option for line-numbering. + * Built-in output formats include HTML, LaTeX, rtf + * Support for new languages, formats, and styles is added easily (modular + structure, Python code, existing documentation). + * Well documented and actively maintained. + * The web site provides a recipe for `using Pygments in ReST documents`_. + It is used in the `Pygments enhanced docutils front-ends`_ below. + +* The experimental Odtwriter_ for Docutils OpenOffice export supports syntax + colours using Pygments. + +Pygments_ seems to be the most promising docutils highlighter. For printed +output, the listings_ package has its advantages too. + + +Pygments enhanced docutils front-ends +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here comes a working example for syntax highlighting in HTML and LaTeX +output with pygments_. + +The example code in "`Using Pygments in ReST documents`_" defines a new +"sourcecode" directive. The directive takes one argument `language` and uses +the `Pygments`_ source highlighter to parse and render its content as a +colourful source code block. + +Combining the pygments_ example code with the standard docutils_ front-ends, +results in front-end scripts generating output documents with syntax colour. +For consistency with the majority of existing add-ons, the directive is +renamed to "code-block". + +`rst2html-pygments`_ + enhances the standard docutils ``rst2html`` front-end to + generate a HTML rendering with syntax highlight. + +`rst2latex-pygments`_ + enhances docutils' ``rst2latex`` to generate LaTeX with syntax highlight. + +Advantages: + + Easy implementation with no changes to the stock docutils_. + + Separation of code blocks and ordinary literal blocks. + +Disadvantages: + - "code-block" content is formatted by `pygments`_ and inserted in the + document tree as a "raw" node making the approach writer-dependant. + - documents are incompatible with the standard docutils because of the + locally defined directive. + - more "invasive" markup distracting from content + - no "minimal" code block marker -- three additional lines per code block + +The later disadvantages become an issue in literate programming where a code +block is the most used block markup (see the proposal for a `configurable +literal block directive`_ below). + +To support the ``.. code-block::`` directive, the PyLit converter would need +a configurable "code block marker" instead of the hard coded ``::`` +presently in use. (See also the `code-block directive`__ section in +pylit.py.) + +__ ../examples/pylit.py.html#code-block-directive + + +Example +""""""" + +Python script: + :text source: `for-else-test.py.txt`_ + :HTML: `for-else-test.py.html`_ + :LaTeX: `for-else-test.py.tex`_ + :PDF: `for-else-test.py.pdf`_ + +Stylesheets: + :CSS stylesheet: `pygments-default.css`_ + :LaTeX style: `pygments-default.sty`_ + + + +Proposal for a code-block directive in docutils +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +In a `post to the docutils users list`__, David Goodger wrote (after an all +too long discussion): + + Here are my pronouncements: + + * 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. + + * There will be no "unparsed" code-block. It would make no sense. + + * There will be no special pass-through support for LaTeX to do its + own syntax highlighting. + +__ http://article.gmane.org/gmane.text.docutils.user/3923 + +On 7.06.07, David Goodger wrote: + + On 6/7/07, G. Milde suggested: + + 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. + + +1 on number 3. + +Implemented 2007-06-08. + + +Parsing +""""""" + +Felix Wiemann provided a `proof of concept`_ script that utilizes the +pygments_ parser to parse a source code string and store the result in +the document tree. + +This concept is used in `pygments_code_block_directive`_, (source: +`pygments_code_block_directive.py`_), to define and register a "code-block" +directive. + +* The `DocutilsInterface` class uses pygments_ to parse the content of the + directive and classify the tokens using short CSS class names identical to + pygments HTML output. If pygments is not available, the unparsed code is + returned. + +* The `code_block_directive` function inserts the tokens in a "rich" + <literal_block> element with "classified" <inline> nodes. + +The XML rendering of the small example file `myfunction.py.txt`_ looks like +`myfunction.py.xml`_. + + +Writing +""""""" + +The writers can use the class information in the <inline> elements to render +the tokens. They should ignore the class information if they are unable to +use it or to pass it on. + +HTML + The "html" writer works out of the box. + + * The rst2html-highlight_ front end registers the "code-block" directive and + converts an input file to html. + * Styling is done with the adapted CSS style sheet `pygments-default.css`_ + based on docutils' default stylesheet and the output of + ``pygmentize -S default -f html``. + * The result looks like `myfunction.py.html`_. + + The "s5" and "pep" writers are not tested yet. + +XML + "xml" and "pseudoxml" work out of the box, too. See `myfunction.py.xml`_ + and `myfunction.py.pseudoxml`_ + +LaTeX + Latex writers must be updated to handle the "rich" <literal_block> element + correct. + + * The "latex" writer currently fails to handle "classified" <inline> + doctree elements. The output `myfunction.py.tex`_ contains undefined + control sequences ``\docutilsroleNone``. + + * The "newlatex2e" writer produces a valid LaTeX document + (`myfunction.py.newlatex2e.tex`_). However the `pdflatex` output looks + mixed up a bit (`myfunction.py.newlatex2e.pdf`_). + + The pygments-produced style file will not currently work with + "newlatex2e" output. + +OpenOffice + The non-official "odtwriter" provides syntax highlight with + pygments but uses a different syntax. + + +TODO +"""" + +* fix the "latex" writer. + +* think about an interface for pygments' options (like "encoding" or + "linenumbers"). + + + +.. _proof of concept: + http://article.gmane.org/gmane.text.docutils.user/3689 +.. _pygments_code_block_directive.py: ../pygments_code_block_directive.py +.. _pygments_code_block_directive: pygments_code_block_directive.py.html +.. _pygments_docutils_interface.py: pygments_docutils_interface.py +.. _myfunction.py.txt: myfunction.py.txt +.. _myfunction.py.xml: myfunction.py.xml +.. _myfunction.py.pseudoxml: myfunction.py.pseudoxml +.. _myfunction.py.html: myfunction.py.html +.. _myfunction.py.tex: myfunction.py.tex +.. _myfunction.py.newlatex2e.tex: myfunction.py.newlatex2e.tex +.. _myfunction.py.newlatex2e.pdf: myfunction.py.newlatex2e.pdf +.. _rst2html-highlight: ../tools/rst2html-highlight +.. _pygments-long.css: ../tools/pygments-long.css + + + + +Configurable literal block directive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Goal +"""" + +A clean and simple syntax for highlighted code blocks -- preserving the +space saving feature of the "minimised" literal block marker (``::`` at the +end of a text paragraph). This is especially desirable in literate programs +with many code blocks. + +Inline analogon +""""""""""""""" + +The *role* of inline `interpreted text` can be customised with the +"default-role" directive. This allows the use of the concise "backtick" +syntax for the most often used role, e.g. in a chemical paper, one could +use:: + + .. default-role:: subscript + + The triple point of H`2`O is at 0°C. + +This customisation is currently not possible for block markup. + +Proposal: make the default "literal block" role configurable. +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +* Define a new "literal" directive for an ordinary literal block. + This would insert the block content into the document tree as + "literal-block" element with no parsing. + +* Define a "literal-block" setting that controls which directive is called + on a block following ``::``. Default would be the "literal" directive. + + Alternatively, define a new "default-literal-block" directive instead of + a settings key. + +* From a syntax view, this would be analog to the behaviour of the odtwriter_. + (I am not sure about the representation in the document tree, though.) + +Motivation +'''''''''' + +Analogue to customising the default role of "interpreted text" with the +"default-role" directive, the concise ``::`` literal-block markup could be +used for e.g. + +* a "code-block" or "sourcecode" directive for colourful code + (analog to the one in the `pygments enhanced docutils front-ends`_) + +* the "line-block" directive for poems or addresses + +* the "parsed-literal" directive + +Example (using the upcoming "settings" directive):: + + ordinary literal block:: + + some text typeset in monospace + + .. settings:: + :literal-block: code-block python + + colourful Python code:: + + def hello(): + print "hello world" + + +In the same line, a "default-block-quote" setting or directive could be +considered to configure the role of a block quote. + +Odtwriter +~~~~~~~~~ + +Dave Kuhlman's odtwriter_ extension can add syntax highlighting +to ordinary literal blocks. + +The ``--add-syntax-highlighting`` command line flag activates syntax +highlighting in literal blocks. By default, the "python" lexer is used. + +You can change this within your reST document with the `sourcecode` +directive:: + + .. sourcecode:: off + + ordinary literal block:: + + content set in teletype + + .. sourcecode:: on + .. sourcecode:: python + + colourful Python code:: + + def hello(): + print "hello world" + + +The "sourcecode" directive defined by the odtwriter is principally +different from the "code-block" directive of ``rst2html-pygments``: + +* The odtwriter directive does not have content. It is a switch. + +* The syntax highlighting state and language/lexer set by this directive + remain in effect until the next sourcecode directive is encountered in the + reST document. + + ``.. sourcecode:: <newstate>`` + make highlighting active or inactive. + <newstate> is either ``on`` or ``off``. + + ``.. sourcecode:: <lexer>`` + change the lexer parsing literal code blocks. + <lexer> should be one of aliases listed at pygment's `languages and + markup formats`_. + +I.e. the odtwriter implements a `configurable literal block directive`_ +(but with a slightly different syntax than my proposal below). + + +Syntax highlight with the ``listings.sty`` LaTeX package +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using the listings_ LaTeX package for syntax highlight is currently not +possible with the standard latex writer output. + +Support for the use of listings_ with docutils is an issue that must be +settled separate from the `proposal for a code-block directive in +docutils`_. It would need + +* a new, specialized docutils latex writer, or +* a new option (and behaviour) to the existing latex writer. + + +.. External links +.. _pylit: http://pylit.berlios.de +.. _docutils: http://docutils.sourceforge.net/ +.. _rest2web: http://www.voidspace.org.uk/python/rest2web/ +.. _Enscript: http://www.gnu.org/software/enscript/enscript.html +.. _SilverCity: http://silvercity.sourceforge.net/ +.. _Trac: http://trac.edgewall.org/ +.. _Moin-Moin Python colorizer: + http://www.standards-schmandards.com/2005/fangs-093/ +.. _odtwriter: http://www.rexx.com/~dkuhlman/odtwriter.html +.. _pygments: http://pygments.org/ +.. _listings: http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html +.. _fancyvrb: http://www.ctan.org/tex-archive/help/Catalogue/entries/fancyvrb.html +.. _alltt: http://www.ctan.org/tex-archive/help/Catalogue/entries/alltt.html +.. _moreverb: http://www.ctan.org/tex-archive/help/Catalogue/entries/moreverb.html +.. _verbatim: http://www.ctan.org/tex-archive/help/Catalogue/entries/verbatim.html +.. _languages and markup formats: http://pygments.org/languages +.. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/ +.. _`Docutils Document Tree`: + http://docutils.sf.net/docs/ref/doctree.html#classes + +.. Internal links +.. _rst2html-pygments: ../tools/rst2html-pygments +.. _rst2latex-pygments: ../tools/rst2latex-pygments +.. _for-else-test: +.. _for-else-test.py.html: for-else-test.py.html +.. _for-else-test.py.txt: for-else-test.py.txt +.. _for-else-test.py.tex: for-else-test.py.tex +.. _for-else-test.py.pdf: for-else-test.py.pdf +.. _pygments-default.css: ../tools/pygments-default.css +.. _pygments-default.sty: ../tools/pygments-default.sty + |