From adce38b7e84199e2cef9c0a8b314e8ecd26f170c Mon Sep 17 00:00:00 2001 From: milde Date: Thu, 22 Mar 2007 16:46:35 +0000 Subject: [PATCH] Documentation update git-svn-id: http://svn.berlios.de/svnroot/repos/pylit/trunk@36 fb71aa59-6827-0410-b536-ee2229a4f8e3 --- rstdocs/features/features.txt | 84 +++++++---------- rstdocs/features/for-else-test.py.txt | 10 +- rstdocs/features/pygments-default.css | 96 +++++++++++++++++++ rstdocs/features/pygments-default.css.txt | 102 --------------------- rstdocs/features/pygments-default.sty | 86 +++++++++++++++++ rstdocs/features/rst2html-pygments | 8 +- .../{rst2html-pygments => rst2latex-pygments} | 20 ++-- rstdocs/features/syntax-highlight.txt | 90 ++++++++++-------- rstdocs/index.txt | 25 ++--- .../literate-programming/literate-programming.txt | 40 +++++++- rstdocs/tutorial/index.txt | 46 +++++----- 11 files changed, 360 insertions(+), 247 deletions(-) create mode 100644 rstdocs/features/pygments-default.css delete mode 100644 rstdocs/features/pygments-default.css.txt create mode 100644 rstdocs/features/pygments-default.sty copy rstdocs/features/{rst2html-pygments => rst2latex-pygments} (70%) diff --git a/rstdocs/features/features.txt b/rstdocs/features/features.txt index b179642..b2358d3 100644 --- a/rstdocs/features/features.txt +++ b/rstdocs/features/features.txt @@ -6,15 +6,15 @@ Features `PyLit` (Python-Literate) provides a plain but efficient tool for literate programming: a bidirectional converter between -* a *text source* (reStructuredText_ with embedded code blocks) and -* a *code source* (source code with comment blocks). +* a *text source* with embedded code blocks and +* a *code source* with the documentation in comment blocks. It is written in Python_ but should work with any programming language that provides a syntax for comment blocks. (Currently, only comments running from -a comment string to the end of line are accepted.) +a comment string to the end of line are supported.) -The following features set PyLit apart from -`existing literate programming frameworks`__ +The following features set PyLit apart from other +`literate programming frameworks`__ __ ../literate-programming/index.html#existing-frameworks @@ -26,9 +26,10 @@ Text source and code source are considered equal. Both hold the full information. The ``pylit.py`` script converts the text source to code source and vice -versa. Round-trips are possible without loss of information. (It is also -possible, to 'export' to a format by stripping code or text parts during the -conversion using the ``--strip`` option.) +versa. Round-trips are possible without loss of information. [#]_ + +.. [#] Given the ``--strip`` option, PyLit will "export" to a format by + stripping code or text parts during the conversion. Advantages ~~~~~~~~~~ @@ -46,6 +47,8 @@ Limitations * The parallel existence of code and text source might lead to confusion on which is the up to date, authoritative source. + The literate source of pylit.py has a section on `dual source handling`_. + * While by default, an output file is not overwritten if it is newer than the input file, loss of changes can occur when both formats are edited in parallel. @@ -68,51 +71,25 @@ Limitations Simplicity ---------- -`Py lit` does not introduce "named chunks". It lets the programmer -intersperse documentation and code freely but does not provide code -re-ordering or multiple expansion of definitions. Some call this -*semi-literate* style. - -This restriction was done deliberately. It reduces the complexity and seems -better suited for a programming language like Python where you would rather -use packages, modules, classes, and functions to structure the code. - - The computer science and programming pioneers, like Girth and Knuth, used - another programming style than we recommend today. One notable difference - is the use of procedure abstractions. When Mirth and Knuth wrote their - influential books and programming, procedure calls were used with care, - partly because they were relatively expensive. Consequently, they needed - an extra level of structuring within a program or procedure. - 'Programming by stepwise refinement' as well as 'literate programming' can - be seen as techniques and representations to remedy the problem. The use - of many small (procedure) abstractions goes in another direction. If you - have attempted to use 'literate programming' on a program (maybe an - object-oriented program) with lots of small abstractions, you will - probably have realized that there is a misfit between, on the one hand, - being forced to name literal program fragments (scraps) and on the other, - named program abstractions. We do not want to leave the impression that - this is a major conceptual problem, but it is the experience of the author - that we need a variation of literate programming, which is well-suited to - programs with many, small (named) abstractions. - - -- Kurt Nørmark: `Literate Programming - Issues and Problems`_ - -.. _`Literate Programming - Issues and Problems`: - http://www.cs.auc.dk/~normark/litpro/issues-and-problems.html +Pylit is a `pure Python module`__, i.e. a module written in Python and +contained in a single .py file. +PyLit converts between a "text document with embedded code" and "commented +code" but does not provide code re-ordering or multiple expansion of +definitions. Some call this `semi-literate programming`_. -reStructured Text ------------------ +Doing without "named chunks" reduces the complexity of the program and +enables a line-by-line correspondence between text source and code source. -`PyLit` uses `reStructured Text`_ from Python docutils_ for text markup. [#]_ +__ http://python.org/doc/2.2.3/dist/simple-example.html#SECTION000220000000000000000 +.. _semi-literate programming: ../literate-programming/index.html#semi-literate -Most of the time, a programmer will see the source in a "text editor". With -reStructured Text as documenting language, not only the pretty printed -documentation, but also the source (be it in "text" or "code" format) is a -"combination of documentation and source together in a fashion suited for -reading by human beings", i.e. a *literate program* according to the -"inclusive" definition in the `Literate Programming FAQ`_. +reStructured Text +----------------- + +PyLit uses `reStructured Text`_ from Python docutils_ for hyperlinks and +text markup. [#]_ * reStructured Text is an "ASCII-markup" language. Its syntax is very similar to common conventions used to structure "ASCII text" like e.g. emails. @@ -128,7 +105,15 @@ reading by human beings", i.e. a *literate program* according to the hyper-linked, browsable HTML documentation as well as to a LaTeX document (and with pdflatex further to a printer-ready PDF manual). -The tutorial_ and the examples_ show what code and text source look like. +Most of the time, a programmer will see the source in a "text editor". With +reStructured Text as documenting language, not only the pretty printed +documentation, but also the source (be it in "text" or "code" format) is a +"combination of documentation and source together in a fashion suited for +reading by human beings", i.e. a *literate program* according to the +"inclusive" definition in the `Literate Programming FAQ`_. + +The tutorial_ and the examples_ show what code and text source may look like. + .. [#] Actually, only the syntax for literal blocks is needed for PyLit to convert from text to code. If no pretty-printed or web-ready document @@ -143,6 +128,7 @@ The tutorial_ and the examples_ show what code and text source look like. .. _`Editor Support for reStructuredText`: http://docutils.sourceforge.net/tools/editors/README.html .. _Literate Programming FAQ: http://www.literateprogramming.com/lpfaq.pdf +.. _dual source handling: examples/pylit.py.html#dual-source-handling .. _rest2web: http://www.voidspace.org.uk/python/rest2web/ .. _tutorial: ../tutorial/index.html .. _examples: ../examples/index.html diff --git a/rstdocs/features/for-else-test.py.txt b/rstdocs/features/for-else-test.py.txt index 125481c..33c4281 100644 --- a/rstdocs/features/for-else-test.py.txt +++ b/rstdocs/features/for-else-test.py.txt @@ -3,10 +3,14 @@ Example for syntax highlight with Pygments ========================================== -Translate this document to html with the pygments enhanced frontend:: - - rst2html-pygments --stylesheet=pygments-default.css +Translate this document to html with a pygments enhanced frontend:: + rst2html-pygments --stylesheet=pygments-default.css + +or + + rst2latex-pygments --stylesheet=pygments-default.sty + to gain syntax highlight in the output. .. Run the doctests with ``pylit --doctest for-else-test.py``. diff --git a/rstdocs/features/pygments-default.css b/rstdocs/features/pygments-default.css new file mode 100644 index 0000000..9a931b0 --- /dev/null +++ b/rstdocs/features/pygments-default.css @@ -0,0 +1,96 @@ +/* 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/ */ diff --git a/rstdocs/features/pygments-default.css.txt b/rstdocs/features/pygments-default.css.txt deleted file mode 100644 index 2c74c17..0000000 --- a/rstdocs/features/pygments-default.css.txt +++ /dev/null @@ -1,102 +0,0 @@ -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 code blocks ------------------- - -Content copied from the `html4css1.css` rule for literal blocks. -Selector adapted to the output of Pygments_. - -TODO: why does this fail? - -.. sourcecode:: css - - 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.css`: - -.. sourcecode:: 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/ diff --git a/rstdocs/features/pygments-default.sty b/rstdocs/features/pygments-default.sty new file mode 100644 index 0000000..853ef22 --- /dev/null +++ b/rstdocs/features/pygments-default.sty @@ -0,0 +1,86 @@ +% 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. + +% Separate paragraphs by vertical space +% ------------------------------------- + +\setlength{\parindent}{0em} +\setlength{\parskip}{1ex} + +% 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`:: + +\usepackage{fancyvrb} +\usepackage{color} + +\newcommand\at{@} +\newcommand\lb{[} +\newcommand\rb{]} +\newcommand\Cba[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\Caz[1]{\textcolor[rgb]{0.00,0.25,0.82}{#1}} +\newcommand\Cay[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\Cax[1]{\textcolor[rgb]{0.00,0.63,0.00}{#1}} +\newcommand\Cbc[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\Cas[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\Car[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\Caq[1]{\textcolor[rgb]{0.73,0.27,0.27}{\textit{#1}}} +\newcommand\Cap[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\Caw[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\Cav[1]{\textcolor[rgb]{0.60,0.60,0.60}{\textbf{#1}}} +\newcommand\Cau[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\Cat[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\Cak[1]{\textbf{#1}} +\newcommand\Caj[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}} +\newcommand\Cai[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\Cah[1]{\textcolor[rgb]{0.63,0.63,0.00}{#1}} +\newcommand\Cao[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}} +\newcommand\Can[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} +\newcommand\Cam[1]{\textcolor[rgb]{0.73,0.40,0.13}{\textbf{#1}}} +\newcommand\Cal[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\Cac[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\Cab[1]{\textit{#1}} +\newcommand\Caa[1]{\textcolor[rgb]{0.50,0.50,0.50}{#1}} +\newcommand\Cag[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\Caf[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} +\newcommand\Cae[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\Cad[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\Cbb[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\CaZ[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\CaY[1]{\textcolor[rgb]{0.00,0.00,0.50}{\textbf{#1}}} +\newcommand\CaX[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} +\newcommand\Cbd[1]{\textcolor[rgb]{0.73,0.40,0.53}{\textbf{#1}}} +\newcommand\Cbe[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\CaS[1]{\textcolor[rgb]{0.82,0.25,0.23}{\textbf{#1}}} +\newcommand\CaR[1]{\textcolor[rgb]{0.50,0.00,0.50}{\textbf{#1}}} +\newcommand\CaQ[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} +\newcommand\CaP[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\CaW[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\CaV[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\CaU[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\CaT[1]{\textcolor[rgb]{0.00,0.00,1.00}{\textbf{#1}}} +\newcommand\CaK[1]{\textcolor[rgb]{0.00,0.53,0.00}{#1}} +\newcommand\CaJ[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\CaI[1]{\textcolor[rgb]{0.00,0.63,0.00}{#1}} +\newcommand\CaH[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\CaO[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand\CaN[1]{\textcolor[rgb]{0.73,0.27,0.27}{#1}} +\newcommand\CaM[1]{\textcolor[rgb]{0.00,0.00,0.50}{\textbf{#1}}} +\newcommand\CaL[1]{\textcolor[rgb]{0.00,0.00,1.00}{#1}} +\newcommand\CaC[1]{\textcolor[rgb]{0.63,0.00,0.00}{#1}} +\newcommand\CaB[1]{\textcolor[rgb]{0.00,0.53,0.00}{\textit{#1}}} +\newcommand\CaA[1]{\textcolor[rgb]{0.67,0.13,1.00}{#1}} +\newcommand\CaG[1]{\textcolor[rgb]{0.67,0.13,1.00}{\textbf{#1}}} +\newcommand\CaF[1]{\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{#1}} +\newcommand\CaE[1]{\textcolor[rgb]{0.72,0.53,0.04}{#1}} +\newcommand\CaD[1]{\textcolor[rgb]{1.00,0.00,0.00}{#1}} diff --git a/rstdocs/features/rst2html-pygments b/rstdocs/features/rst2html-pygments index fba7da6..3b01b9a 100644 --- a/rstdocs/features/rst2html-pygments +++ b/rstdocs/features/rst2html-pygments @@ -1,8 +1,8 @@ #!/usr/bin/python -# Author: David Goodger, an unknown Pygments author|contributor, Guenter Milde -# Date: $Date: $ -# Copyright: This module has been placed in the public domain. +# :Author: David Goodger, a Pygments author|contributor, Guenter Milde +# :Date: $Date: $ +# :Copyright: This module has been placed in the public domain. # This is a merge of the docutils_ `rst2html` front end with an extension # suggestion taken from the pygments_ documentation. @@ -24,7 +24,7 @@ description = ('Generates (X)HTML documents from standalone reStructuredText ' 'Needs an adapted stylesheet' + default_description) # Define a new directive `sourcecode` that uses the `pygments` source -# highligther to render code in color. +# highlighter to render code in color. # # Code from the `pygments`_ documentation for `Using Pygments in ReST # documents`_. diff --git a/rstdocs/features/rst2html-pygments b/rstdocs/features/rst2latex-pygments similarity index 70% copy from rstdocs/features/rst2html-pygments copy to rstdocs/features/rst2latex-pygments index fba7da6..12edc95 100644 --- a/rstdocs/features/rst2html-pygments +++ b/rstdocs/features/rst2latex-pygments @@ -1,14 +1,14 @@ #!/usr/bin/python -# Author: David Goodger, an unknown Pygments author|contributor, Guenter Milde +# Author: David Goodger, a Pygments author|contributor, Guenter Milde # Date: $Date: $ # Copyright: This module has been placed in the public domain. -# This is a merge of the docutils_ `rst2html` front end with an extension +# This is a merge of the docutils_ `rst2latex` front end with an extension # suggestion taken from the pygments_ documentation. """ -A front end to docutils, producing HTML with colorized code using pygments +A front end to docutils, producing LaTeX with colorized code using pygments """ try: @@ -19,12 +19,12 @@ except: from docutils.core import publish_cmdline, default_description -description = ('Generates (X)HTML documents from standalone reStructuredText ' +description = ('Generates LaTeX documents from standalone reStructuredText ' 'sources. Uses `pygments` to colorize code. ' 'Needs an adapted stylesheet' + default_description) # Define a new directive `sourcecode` that uses the `pygments` source -# highligther to render code in color. +# highlighter to render code in color. # # Code from the `pygments`_ documentation for `Using Pygments in ReST # documents`_. @@ -33,9 +33,9 @@ from docutils import nodes from docutils.parsers.rst import directives from pygments import highlight from pygments.lexers import get_lexer_by_name -from pygments.formatters import HtmlFormatter +from pygments.formatters import LatexFormatter -pygments_formatter = HtmlFormatter() +pygments_formatter = LatexFormatter() def pygments_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -45,14 +45,14 @@ def pygments_directive(name, arguments, options, content, lineno, # no lexer found - use the text one instead of an exception lexer = get_lexer_by_name('text') parsed = highlight(u'\n'.join(content), lexer, pygments_formatter) - return [nodes.raw('', parsed, format='html')] + return [nodes.raw('', parsed, format='latex')] pygments_directive.arguments = (1, 0, 1) pygments_directive.content = 1 directives.register_directive('sourcecode', pygments_directive) -# Call the docutils publisher to render the input as html:: +# Call the docutils publisher to render the input as latex:: -publish_cmdline(writer_name='html', description=description) +publish_cmdline(writer_name='latex', description=description) # .. _doctutile: http://docutils.sf.net/ # .. _pygments: http://pygments.org/ diff --git a/rstdocs/features/syntax-highlight.txt b/rstdocs/features/syntax-highlight.txt index d2bb580..c23234d 100644 --- a/rstdocs/features/syntax-highlight.txt +++ b/rstdocs/features/syntax-highlight.txt @@ -4,11 +4,12 @@ crumb: Highlights page-title: Pylit - Features - Syntax Highlight file: rst2html-pygments + file: rst2latex-pygments file: for-else-test.py.txt + file: for-else-test.py.tex + file: for-else-test.py.pdf file: for-else-test.py.html file: pygments-default.css - file: pygments-default.css.txt - file: pygments-default.css.html /restindex .. sectnum:: @@ -21,9 +22,10 @@ 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. But in a mail on +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`__, -David Goodger wrote: +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 @@ -64,58 +66,67 @@ __ http://www.voidspace.org.uk/python/rest2web/macros.html#colorize Pygments seems to be the most promising docutils highlighter. -Pygments enhanced rst2html front-end -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `rst2html-pygments`_ script combines code from "`Using Pygments in ReST -documents`_" with the standard docutils ``rst2html`` front-end producing a -html rendering with syntax highlight. (It should be not too difficult to -create an ``rst2latex-pygments`` front end as well.) +Pygments enhanced docutils front-ends +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 +literal block with syntax colour. -A new "sourcecode" directive is defined, that takes one argument `language` -and uses the `Pygments`_ source highlighter to render its content as a -literal block with syntax colour. It looks like:: +Example:: .. sourcecode:: python def hello(): print "hello world" +Combining the pygments_ example code with the standard docutils_ front-ends, +results in front-end scripts generating pretty-print with syntax highlight: -To support this way of syntax highlight, the PyLit converter would need a -configurable "code block marker" instead of the hard coded double colon -(``::``) presently in use. (See also the `sourcecode directive`__ section in -pylit.py.) - -__ ../examples/pylit.py.html#sourcecode-directive +`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 needed for the stock docutils_. -* Separation of code blocks and ordinary literal blocks. + + Easy implementation with no changes needed for the stock docutils_. + + Separation of code blocks and ordinary literal blocks. Disadvantage: - -* more "invasive" markup distracting from content -* no "minimal" code block marker -- three additional lines per code block + - more "invasive" markup distracting from content + - no "minimal" code block marker -- three additional lines per code block The disadvantages become a real issue in literate programming where a code -block is expected to be the most used block markup by far. +block is expected to be the most used block markup. Examples """""""" -`for-else-test.py.html`_ - tries out of the command flow in a Python for else construct. +example Python script: + `for-else-test`_ investigates the command flow in a Python + ``for ... else`` construct. - Source: `for-else-test.py.txt`_ - -`pygments-default.css.html`_ - is the style sheet that provides the colours in these examples - - Sources: `pygments-default.css`_, `pygments-default.css.txt`_ + :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`_ +To support this way of syntax highlight, the PyLit converter would need a +configurable "code block marker" instead of the hard coded double colon +(``::``) presently in use. (See also the `sourcecode directive`__ section in +pylit.py.) + +__ ../examples/pylit.py.html#sourcecode-directive + Odtwriter syntax ~~~~~~~~~~~~~~~~ @@ -145,7 +156,7 @@ directive:: The "sourcecode" directive defined by the odtwriter is principally -different from the "sourcecode" directive of rst2html-pygments: +different from the "sourcecode" directive of ``rst2html-pygments``: * The odtwriter directive does not have content. It is a switch. @@ -264,7 +275,7 @@ used for e.g. * the "parsed-literal" directive * a "sourcecode" directive for colourful code - (analog to the one in `rst2html-pygments`_) + (analog to the one in the `pygments enhanced docutils front-ends`_) * a "listing" directive for the `listings`_ environment in LaTeX @@ -298,8 +309,13 @@ considered to configure the role of a block quote. .. _Using Pygments in ReST documents: http://pygments.org/docs/rstdirective/ .. _rst2html-pygments: rst2html-pygments -.. _for-else-test.py.txt: for-else-test.py.txt +.. _rst2latex-pygments: 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: pygments-default.css .. _pygments-default.css.txt: pygments-default.css.txt .. _pygments-default.css.html: pygments-default.css.html +.. _pygments-default.sty: pygments-default.sty diff --git a/rstdocs/index.txt b/rstdocs/index.txt index de07b1a..e9194c5 100644 --- a/rstdocs/index.txt +++ b/rstdocs/index.txt @@ -1,7 +1,7 @@ .. -*- rst-mode -*- restindex crumb: Home - page-title: PyLit - Literate programming with reStructuredText + page-title: PyLit /restindex ============================================================ @@ -23,25 +23,27 @@ __ literate-programming/index.html .. _Charming Python interview: http://www-128.ibm.com/developerworks/library/l-pyth7.html -`Pylit Features`__ - PyLit (Python-Literate) is a Python_ module providing a bidirectional - converter between - - * a *text source* with embedded code blocks and - * a *code source* with documentation in comment blocks. +`Pylit Features`__ + *PyLit* (Python-Literate) is a `pure Python module`__ providing a + **bidirectional** converter between a text source with embedded code + blocks and a code source with documentation in comment blocks. - Documentation or code can be edited in their "native" format using + Documentation and code can be edited in their "native" format using ones favourite editor and editing mode. + + The Python docutils_ can be used to convert the text source into HTML or + LaTeX documents. -.. _pylit module: examples/pylit.py.html -.. _reStructured Text: http://docutils.sourceforge.net/rst.html __ features/index.html +__ http://python.org/doc/2.2.3/dist/simple-example.html#SECTION000220000000000000000 +.. _docutils Text: http://docutils.sourceforge.net/ Tutorial__ How to write literate programs with PyLit __ tutorial/index.html + Examples__ Use cases for literate programming with PyLit @@ -49,10 +51,8 @@ Examples__ __ examples/index.html - `Download, Installation, Usage`__ PyLit requires functioning Python_ installation and the `pylit.py`_ module. - Installation_ and usage_ are straigtforward. Not required by PyLit converter but for conversion of the text source @@ -116,4 +116,5 @@ About this site developers by the Fraunhofer-Institut für Offene Kommunikationssysteme (FOKUS) in Berlin. +.. _reStructured Text: http://docutils.sourceforge.net/rst.html .. _rest2web: http://www.voidspace.org.uk/python/rest2web/ diff --git a/rstdocs/literate-programming/literate-programming.txt b/rstdocs/literate-programming/literate-programming.txt index d9c198f..55e9795 100644 --- a/rstdocs/literate-programming/literate-programming.txt +++ b/rstdocs/literate-programming/literate-programming.txt @@ -58,20 +58,50 @@ by Mark-Jason Dominus: This is why the `Wikipedia entry on literate programming`_ classifies POD as `embedded documentation`. -PyLit also fails this narrow definition but, according to the Wikipedia, -qualifies as `semi-literate`: +PyLit also fails this narrow definition but, according to the Wikipedia_, +qualifies as _`semi-literate`: It is the fact that documentation can be written freely whereas code must be marked in a special way that makes the difference between semi-literate programming and excessive documenting, where the documentation is embedded into the code as comments. -For more discussion of the PyLit concepts see the Features_ page. +Renouncing named chunks and code re-ordering enables the `dual-source`_ +concept. It seems well suited for a programming language like Python where +you would rather use packages, modules, classes, and functions to structure +the code. Also, Pythons dynamic name resolution allows a great deal of +flexibility in the order of code. + + The computer science and programming pioneers, like Wirth and Knuth, used + another programming style than we recommend today. One notable difference + is the use of procedure abstractions. When Wirth and Knuth wrote their + influential books and programming, procedure calls were used with care, + partly because they were relatively expensive. Consequently, they needed + an extra level of structuring within a program or procedure. + 'Programming by stepwise refinement' as well as 'literate programming' can + be seen as techniques and representations to remedy the problem. The use + of many small (procedure) abstractions goes in another direction. If you + have attempted to use 'literate programming' on a program (maybe an + object-oriented program) with lots of small abstractions, you will + probably have realized that there is a misfit between, on the one hand, + being forced to name literal program fragments (scraps) and on the other, + named program abstractions. We do not want to leave the impression that + this is a major conceptual problem, but it is the experience of the author + that we need a variation of literate programming, which is well-suited to + programs with many, small (named) abstractions. + + -- Kurt Nørmark: `Literate Programming - Issues and Problems`_ + .. _POD is not Literate Programming: http://www.perl.com/pub/a/tchrist/litprog.html -.. _Wikipedia entry on literate programming: +.. _Wikipedia entry on literate programming: +.. _Wikipedia: http://en.wikipedia.org/wiki/Literate_programming#Embedded_documentation +.. _`Literate Programming - Issues and Problems`: + http://www.cs.auc.dk/~normark/litpro/issues-and-problems.html +.. _dual-source: /features/index.html#dual-source + Existing Frameworks @@ -151,7 +181,7 @@ How does PyLit differ from the web-like literate programming frameworks: text source into both, pretty-printed hardcopy (via LaTeX - PDF) and browsable electronic (HTML) form. -For a full discussion of the PyLit concepts see the Features_ page. +For a full discussion of PyLit's concepts see the Features_ page. .. _docutils: http://docutils.sourceforge.net/ .. _Features: /features/index.html diff --git a/rstdocs/tutorial/index.txt b/rstdocs/tutorial/index.txt index b190d55..03b7deb 100644 --- a/rstdocs/tutorial/index.txt +++ b/rstdocs/tutorial/index.txt @@ -14,7 +14,7 @@ How to write program documents with PyLit Hello world ----------- -We start with a classical example (in Python_) +We start with a classical example in Python_ .. include:: hello.py :literal: @@ -35,17 +35,17 @@ text document". Points to mention: -* You can start literate programming with an existing code file (and without +* One can start literate programming with an existing code file (and without knowledge of reStructured Text syntax). -* The *documentation* is uncommented (if it is separated from code by a +* *Documentation* is uncommented (if it is separated from code by a blank line and has a recognised comment string at the start of each line). * A double colon is added at the end of the text block. It is the - reStructured Text marker for the following `literal block`_. + `reStructured Text`_ marker for the following `literal block`_. (No marker is added, if the text block already ends with a double colon.) -* The *code* is indented to form a literal block. It will be printed using a +* *Code* is indented to form a literal block. It will be printed using a monospaced font and without reStructured Text substitutions. * PyLit adds ".txt" to the filename for the text version. @@ -88,11 +88,11 @@ Points to mention: Textblocks and Comments ----------------------- -Comment lines are only transformed to a text block, +Comment lines are only transformed to a text block, if they -* if they start with a matching `comment string` (Python default ``'# '``, - whitespace counts!), and -* if they are separated from non-text lines by at least one blank[#]_ line +* start with a matching `comment string` (whitespace counts!, the Python + default is ``'# '``), and +* are separated from non-text lines by at least one blank[#]_ line Otherwise, they are kept as commented code. @@ -109,7 +109,9 @@ An example will illustrate this. The code:: is mapped to text as:: - 99bottles.py -- print the famous "99 bottles of beer" song lyrics:: + 99bottles.py -- print the famous "99 bottles of beer" song lyrics + + :: # This is used as an introductory example to literate programming # in the literateprograms.org Wiki. @@ -134,7 +136,7 @@ However, :: is mapped to text as:: - 99bottles.py -- print the famous "99 bottles of beer" song lyrics:: + 99bottles.py -- print the famous "99 bottles of beer" song lyrics This is used as an introductory example to literate programming in the literateprograms.org Wiki. @@ -185,17 +187,18 @@ the source is a literate program anyway). But there are advantages also: many source files. If needed for the documentation, it is possible to repeat the header in the -the first text block, e.g. using `inline markup`_ markup in `line block`_ -nested in a `block quote`_: +the first text block, e.g. using a `parsed literal block`_: + +.. parsed-literal:: - | ``#!/usr/bin/env python`` - | ``# -*- coding: iso-8859-1 -*-`` + #!/usr/bin/env python + # -*- coding: iso-8859-1 -*- Doctests -------- -Pylit allows to run `Python doctests`_ on a literate script. +Pylit supports `Python doctests`_ in a literate script. We add a doctest to our example: @@ -276,15 +279,8 @@ looks like .. _literal block: http://docutils.sourceforge.net/docs/user/rst/quickref.html#literal-blocks -.. _inline markup: - http://docutils.sourceforge.net/docs/user/rst/quickref.html#inline-markup - -.. _line block: - http://docutils.sourceforge.net/docs/user/rst/quickref.html#line-blocks - -.. _block quote: - http://docutils.sourceforge.net/docs/user/rst/quickref.html#block-quotes - +.. _parsed literal block: + http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block .. _noweb: http://www.eecs.harvard.edu/~nr/noweb/ .. _include directive: -- 2.11.4.GIT