1 Syntax Highlight
- Author:
Günter Milde
- Contact:
- Date:
$Date: 2020-09-04 18:52:11 +0200 (Fr, 04. Sep 2020) $
- Copyright:
© 2007, 2009, 2012 G. Milde,
- License:
Released under the terms of the 2-Clause BSD license, in short:
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
- Abstract:
Proposal to add syntax highlight of code blocks to the capabilities of Docutils.
Syntax highlighting significantly enhances the readability of code. Since version 0.9, docutils supports this with a code directive and role as well as a code option to the include directive using the Pygments syntax highlighter.
- Example::
The content of the following directive
.. code:: python def my_function(): "just a test" print 8/2
is parsed and marked up as Python source code. The actual rendering depends on the style-sheet.
2 TODO
TODO: Pygments provides filters like VisibleWhitespaceFilter add options to use them?
Use syntax-highlight=long as default and add basic highlight rules (keyword, comment, string?) to the default CSS stylesheet to get syntax highlight out-of-the-box?
Let the latex2e writer write basic rules in the document preamble if "code" is used in the document?
The latex writer should pass the original content and options to a lstlistings environment. with --literal-block-env=lstlistings.
Check the odtwriter, use common syntax and implementation.
Provide more sample stylesheets in an official stylesheet library.
2.1 Configurable literal block directive
2.1.1 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 documents with many code blocks like tutorials or literate programs.
2.1.2 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.
to produce
The triple point of H2O is at 0°C.
This customisation is currently not possible for block markup.
2.1.3 Proposal
Define a new "literal-block" directive syntax for an ordinary literal block. This would simply insert the block content into the document tree as "literal-block" element.
Define a "default-literal-block" setting that controls which directive is called on a block following ::. Default would be the "literal-block" directive (backwards compatible).
2.1.4 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" directive for syntax highight
the "line-block" directive for poems or addresses
the "parsed-literal" directive
Example:
ordinary literal block:: some text typeset in monospace .. default-literal-block:: code-block python this is 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.