.. -*- rst-mode -*-

Features
==============

`PyLit` (Python-Literate) provides a plain but efficient tool for literate
programming: a bidirectional converter between

* 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.

The following features set PyLit apart from other
`literate programming frameworks`__

__ literate-programming.html#existing-frameworks


Dual Source
-----------

The program source can be either in "text" or "code" format:

* The "code" source can be debugged, compiled or executed with standard
  tools.

* The "text" source can be converted to HTML or LaTeX documents, e.g. with
  the Python Docutils_ or Sphinx_.

The ``pylit`` module script converts the source between "text" and "code"
formats.

Both formats hold the full information. Round-trips are possible without
loss.  [#]_

.. [#] Given the ``--strip`` option, PyLit will "export" to a format by
       stripping code or text parts during the conversion.

Advantages
~~~~~~~~~~

* Work on code or documentation parts can be done in adapted editor modes or
  environments providing formatting tools, syntax highlight, outlining, and
  other conveniences.

* Debugging is straightforward (using the "code" format). Fixes are easily
  passed to the "text" format (just calling ``pylit.py`` on the "code"
  source).

Limitations
~~~~~~~~~~~

* The parallel existence of code and text formats might lead to confusion on
  which is the up to date, authoritative source.

  The ``pylit`` module has some provisions for `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.

* PyLit does not allow the specification of a separate output file for
  individual code blocks like e.g. noweb_. The "dual source" concept limits
  the choice to one output file per input file. However, this can be
  compensated by the use of the `include directive`_.
  See the tutorial_ for an example.

* Only one comment string (including whitespace) can be specified as
  "text block marker".

  It would be possible to specify a list of matching comment strings (or
  a regular expression), however as the comment string is not stored in
  the text source, all text blocks will get one common comment string if
  (re)converted to code source -- possibly loosing vital information.


Simplicity
----------

Pylit is a `pure Python module`__, i.e.  a module written in Python and
contained in a single file (``pylit.py``).

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`_.

Doing without "named chunks" reduces the complexity of the program and
enables a line-by-line correspondence between text source and code source.

__ http://python.org/doc/2.2.3/dist/simple-example.html#SECTION000220000000000000000
.. _semi-literate programming: literate-programming/index.html#semi-literate


Markup with reStructuredText
------------------------------------------

PyLit uses `reStructuredText`_ from the Python Docutils_ for documentation
text markup. [#]_

* reStructuredText is an "ASCII-markup" language. Its syntax is very similar
  to common conventions used to structure "ASCII text" like e.g. emails.
  Thus it is more easy to read and to edit in a text editor than e.g. TeX,
  HTML, or XML.

* reStructuredText is well documented, and actively maintained.

* Special editor modes for editing reStructuredText already exist (see
  `Editor Support for reStructuredText`_.)

* With Docutils_, the text source can be converted to a nice looking,
  hyper-linked, browsable HTML documentation as well as to a LaTeX document
  (and with pdflatex further to a printer-ready PDF manual).

  The Python Documentation Generator Sphinx_, adds support for more complex
  projects including extensive cross-references, automatic indices and
  automatic highlighting of source code.

Most of the time, a programmer will see the source in a "text editor". With
reStructuredText 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.


Syntax Highlight
~~~~~~~~~~~~~~~~

While not available in standard Docutils, syntax highlight is an add-on in
many reStructuredText based applications like the Sphinx_ Python
Documentation Generator.

There is documentation and experimental code in the Docutils Sandbox_
project `code-block directive`_ to implement
`syntax highlight in core Docutils`_.



.. [#] 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
       is desired, the programmer does not need to know anything else about
       reStructuredText.


Python Doctest Support
----------------------

Pylit supports `Python doctests`_ in documentation blocks. For details see
the `tutorial section`_ and the `literate doctests example`_.

.. References:

.. _Docutils: https://docutils.sourceforge.io/rst.html
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Python: http://www.python.org
.. _`Editor Support for reStructuredText`:
      https://docutils.sourceforge.io/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
.. _noweb: https://www.cs.tufts.edu/~nr/noweb/
.. _include directive:
     https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment

.. _Python doctests: http://docs.python.org/library/doctest.html
.. _literate doctests example: examples/literate-doctests.html

.. _syntax highlight in core Docutils:
   https://docutils.sourceforge.io/sandbox/code-block-directive/docs/syntax-highlight.html
.. _sandbox: https://docutils.sourceforge.io/sandbox/
.. _code-block directive:
   https://docutils.sourceforge.io/sandbox/code-block-directive
.. _Sphinx: https://www.sphinx-doc.org/
.. _tutorial section: tutorial/index.html#doctests
