doc/features.txt

   1 .. -*- rst-mode -*-
   2
   3 Features
   4 ==============
   5
   6 `PyLit` (Python-Literate) provides a plain but efficient tool for literate
   7 programming: a bidirectional converter between
   8
   9 * a "text" source with embedded code blocks and
  10 * a "code" source with the documentation in comment blocks.
  11
  12 It is written in Python_ but should work with any programming language that
  13 provides a syntax for comment blocks.
  14
  15 The following features set PyLit apart from other
  16 `literate programming frameworks`__
  17
  18 __ literate-programming.html#existing-frameworks
  19
  20
  21 Dual Source
  22 -----------
  23
  24 The program source can be either in "text" or "code" format:
  25
  26 * The "code" source can be debugged, compiled or executed with standard
  27   tools.
  28
  29 * The "text" source can be converted to HTML or LaTeX documents, e.g. with
  30   the Python Docutils_ or Sphinx_.
  31
  32 The ``pylit`` module script converts the source between "text" and "code"
  33 formats.
  34
  35 Both formats hold the full information. Round-trips are possible without
  36 loss.  [#]_
  37
  38 .. [#] Given the ``--strip`` option, PyLit will "export" to a format by
  39        stripping code or text parts during the conversion.
  40
  41 Advantages
  42 ~~~~~~~~~~
  43
  44 * Work on code or documentation parts can be done in adapted editor modes or
  45   environments providing formatting tools, syntax highlight, outlining, and
  46   other conveniences.
  47
  48 * Debugging is straightforward (using the "code" format). Fixes are easily
  49   passed to the "text" format (just calling ``pylit.py`` on the "code"
  50   source).
  51
  52 Limitations
  53 ~~~~~~~~~~~
  54
  55 * The parallel existence of code and text formats might lead to confusion on
  56   which is the up to date, authoritative source.
  57
  58   The ``pylit`` module has some provisions for `dual source handling`_.
  59
  60 * While by default, an output file is not overwritten if it is newer than
  61   the input file, loss of changes can occur when both formats are edited in
  62   parallel.
  63
  64 * PyLit does not allow the specification of a separate output file for
  65   individual code blocks like e.g. noweb_. The "dual source" concept limits
  66   the choice to one output file per input file. However, this can be
  67   compensated by the use of the `include directive`_.
  68   See the tutorial_ for an example.
  69
  70 * Only one comment string (including whitespace) can be specified as
  71   "text block marker".
  72
  73   It would be possible to specify a list of matching comment strings (or
  74   a regular expression), however as the comment string is not stored in
  75   the text source, all text blocks will get one common comment string if
  76   (re)converted to code source -- possibly loosing vital information.
  77
  78
  79 Simplicity
  80 ----------
  81
  82 Pylit is a `pure Python module`__, i.e.  a module written in Python and
  83 contained in a single file (``pylit.py``).
  84
  85 PyLit converts between a "text document with embedded code" and "commented
  86 code" but does not provide code re-ordering or multiple expansion of
  87 definitions. Some call this `semi-literate programming`_.
  88
  89 Doing without "named chunks" reduces the complexity of the program and
  90 enables a line-by-line correspondence between text source and code source.
  91
  92 __ http://python.org/doc/2.2.3/dist/simple-example.html#SECTION000220000000000000000
  93 .. _semi-literate programming: literate-programming/index.html#semi-literate
  94
  95
  96 Markup with reStructuredText
  97 ------------------------------------------
  98
  99 PyLit uses `reStructuredText`_ from the Python Docutils_ for documentation
 100 text markup. [#]_
 101
 102 * reStructuredText is an "ASCII-markup" language. Its syntax is very similar
 103   to common conventions used to structure "ASCII text" like e.g. emails.
 104   Thus it is more easy to read and to edit in a text editor than e.g. TeX,
 105   HTML, or XML.
 106
 107 * reStructuredText is well documented, and actively maintained.
 108
 109 * Special editor modes for editing reStructuredText already exist (see
 110   `Editor Support for reStructuredText`_.)
 111
 112 * With Docutils_, the text source can be converted to a nice looking,
 113   hyper-linked, browsable HTML documentation as well as to a LaTeX document
 114   (and with pdflatex further to a printer-ready PDF manual).
 115
 116   The Python Documentation Generator Sphinx_, adds support for more complex
 117   projects including extensive cross-references, automatic indices and
 118   automatic highlighting of source code.
 119
 120 Most of the time, a programmer will see the source in a "text editor". With
 121 reStructuredText as documenting language, not only the pretty printed
 122 documentation, but also the source (be it in "text" or "code" format) is a
 123 *"combination of documentation and source together in a fashion suited for
 124 reading by human beings"*, i.e. a *literate program* according to the
 125 "inclusive" definition in the `Literate Programming FAQ`_.
 126
 127 The tutorial_ and the examples_ show what code and text source may look like.
 128
 129
 130 Syntax Highlight
 131 ~~~~~~~~~~~~~~~~
 132
 133 While not available in standard Docutils, syntax highlight is an add-on in
 134 many reStructuredText based applications like the Sphinx_ Python
 135 Documentation Generator.
 136
 137 There is documentation and experimental code in the Docutils Sandbox_
 138 project `code-block directive`_ to implement
 139 `syntax highlight in core Docutils`_.
 140
 141
 142
 143 .. [#] Actually, only the syntax for literal blocks is needed for PyLit to
 144        convert from text to code. If no pretty-printed or web-ready document
 145        is desired, the programmer does not need to know anything else about
 146        reStructuredText.
 147
 148 .. _Sphinx: http://sphinx.pocoo.org/
 149
 150
 151 Python Doctest Support
 152 ----------------------
 153
 154 Pylit supports `Python doctests`_ in documentation blocks. For details see
 155 the `tutorial section`_ and the `literate doctests example`_.
 156
 157 .. References:
 158
 159 .. _Docutils: http://docutils.sourceforge.net/rst.html
 160 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 161 .. _Python: http://www.python.org
 162 .. _`Editor Support for reStructuredText`:
 163       http://docutils.sourceforge.net/tools/editors/README.html
 164 .. _Literate Programming FAQ: http://www.literateprogramming.com/lpfaq.pdf
 165 .. _dual source handling: examples/pylit.py.html#dual-source-handling
 166 .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
 167 .. _tutorial: tutorial/index.html
 168 .. _examples: examples/index.html
 169 .. _noweb: http://www.cs.tufts.edu/~nr/noweb/
 170 .. _include directive:
 171      http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment
 172
 173 .. _Python doctests: http://docs.python.org/library/doctest.html
 174 .. _literate doctests example: examples/literate-doctests.html
 175
 176 .. _syntax highlight in core Docutils:
 177    http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html
 178 .. _sandbox: http://docutils.sourceforge.net/sandbox/
 179 .. _code-block directive:
 180    http://docutils.sourceforge.net/sandbox/code-block-directive
 181 .. _Sphinx: http://sphinx.pocoo.org/
 182 .. _tutorial section: tutorial/index.html#doctests