Python/libs/pygments-lexer-pseudocode2: docs/lexer-algpseudocode.rst comparison

comparison docs/lexer-algpseudocode.rst @ 169:3c517c22df9c

Much more details and refinements in the docs

author	Franz Glasner <fzglas.hg@dom66.de>
date	Mon, 11 May 2026 10:39:39 +0200
parents	bff8b900713a
children	ad80fcbf7b47

comparison

equal deleted inserted replaced

-:bff8b900713a
+:3c517c22df9c
 .. code-block:: algpseudocode-de
 \PROGRAM {The Pseudoprogram} \IS
 \END PROGRAM {The Pseudoprogram}
+States
+======
 The AlgPseudocode lexer and its language variants AlgPseudocodeDE and
 AlgPseudocodeFR basically work in three states: `default`,
 `expression` and `text`.
 - ``\REM`` and ``\REMARK`` for remarks (aka comments)
 - :ref:`explicit-token-types`
-.. rubric:: Some Examples
-A synthetic example with many features:
-.. literalinclude:: examples/example-1.pseudocode
-:language: algpseudocode
-:lines: 2-
-With a customized `AlgPseudocodeLexer` and its `no_end`
-option set to ``True``.
-.. literalinclude:: examples/example-1.pseudocode
-:language: NoEndAlgPseudocode
-:lines: 2-
-This is Wikipedia's description of *Dinic's Algorithm*
-(see https://en.wikipedia.org/wiki/Dinic%27s_algorithm):
-.. literalinclude:: examples/algorithm-dinic.description
-:language: algpseudocode
-:lines: 2-
-This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm*
-(see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm):
-.. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode
-:language: algpseudocode
-:lines: 2-
-This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm*
-(see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm)
-with a custom lexer that skip all ``ENDxxx`` keywords:
-.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
-:language: NoEndAlgPseudocode
-:lines: 2-
-And now the *Edmonds–Karp Algorithm* with french keywords:
-.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
-:language: algpseudocode-fr
-:lines: 2-
-And again the *Edmonds–Karp Algorithm* with german keywords:
-.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
-:language: algpseudocode-de
-:lines: 2-
-More details you will find :ref:`here <details-algpseudocode>`.
-.. _details-algpseudocode:
 Lexer Options
 =============
 .. describe:: prohibit_raiseonerror_filter
 **Type:** :py:class:`bool`
 **Default:** `False`
 If ``True`` all the ``\ENDxxx`` commands will be skipped and yield
-nothing.
+no output.
 .. describe:: gets
 **Type:** :py:class:`str` or :py:obj:`None`
 Runs of dots ``.``, ``..``, ``...``, ``....``, ... are handled
 properly in expressions and yield a punctuation token.
 They are not replaced by corresponding Unicode symbols.
-Keywords
+Commands
 ========
-Explicit Keywords
------------------
 - Start with a backslash character ``\``
 - Case-insensitive
+- Yield mostly to :py:class:`pygments.Token.Keyword`
 - Translated if a translation is found
+- Depending on the command---may have required or optional parameters
-Parameter handling is as follows:
+Parameter handling is as follows:
-- Parameters are enclosed in curly braces ``{`` and ``}``
-- Escaping within the braces is possible using the backslash ``\``
+* Parameters are enclosed in curly braces ``{`` and ``}``
-- Parameters are separated from the keyword/command by a (possibly empty) run
+* Escaping within the braces is possible using the backslash ``\`` as
-of space or TAB characters.
+escape character
-This is true for required and optional parameters.
+* Parameters are separated from the keyword/command by a (possibly empty) run
+of space or TAB characters.
-.. todo:: Escaping
+This is true for required and optional parameters.
-A single backslash is a Generic.Error token
+.. todo:: Escaping
+A single backslash yields a Generic.Error token when in
-With Required Parameters
+`default` and `expression` states.
-~~~~~~~~~~~~~~~~~~~~~~~~
+Commands With Required Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. code-block:: algpseudocode
 \TEXT{\PROGRAM {A Program\}  or  \PROG {A Program\}}                                    \PROGRAM {A Program}
 \TEXT{\ALGORITHM{An Algorithm\}  or  \ALGO{An Algorithm\}}                              \ALGORITHM{An Algorithm}
 \TEXT{\CALL{a function\}(p1, p2)}                  \CALL{a function}(p1, p2)
 \TEXT{\NAME{an entity name\}}                      \NAME{an entity name}
-With Optional Parameters
+Commands With Optional Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Some ``END``-keywords have optional parameters:
+Some ``END``-commands have optional parameters:
 .. code-block:: algpseudocode
 \TEXT{\ENDPROGRAM  \ENDPROG}              \ENDPROGRAM
 \TEXT{\ENDALGORITHM  \ENDALGO}            \ENDALGORITHM
 .. code-block:: algpseudocode
 \TEXT{\CLASS{Foo Bar Class\} ... \END CLASS {Foo Bar Class\}}   \TEXT{yields}   \CLASS{Foo Bar Class} ... \END CLASS {Foo Bar Class}
-.. seealso:: Syntax variants: `END-Keywords`_
+\TEXT{\CLASS{Foo Bar Class\} ... \END CLASS}                   \TEXT{yields}   \CLASS{Foo Bar Class} ... \END CLASS
+.. seealso:: For other syntax variants concerning `END` see also section
-Without Parameters
+`END-Commands`_.
-~~~~~~~~~~~~~~~~~~
-"Normal" Keywords
+Commands Without Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Normal" Commands
 '''''''''''''''''
 .. code-block:: algpseudocode
 \TEXT{\IF}                                \IF
 ``\REMARK`` or ``\REM`` is special: all characters to the end of the
 line are taken as comment; curly braces are not needed---in fact:
 they are interpreted to be part of the comment.
-END-Keywords
+END-Commands
 ''''''''''''
-The separator character can be empty, a run of ASCII spaces, a run of TAB characters,
+The separator character can be empty, a run of ASCII spaces, a run of
-a single underscore ``_`` or a single hyphen ``-`` like:
+TAB characters, a single underscore ``_`` or a single hyphen ``-``
+like:
 ``\ENDIF``, ``\END IF``, ``\END-IF``, ``\END_IF`` or ``\END IF``
 .. code-block:: algpseudocode
 \text{\END_IF}            \END_IF     \rem a single underscore
 \text{\END   IF}          \END       IF     \rem a single TAB character
-The list of END-keywords (here always just with ``-`` as separator):
+The list of END-commands (here always just with ``-`` as separator):
 .. code-block:: algpseudocode
 \text{\END-PROGRAM  \END-PROG}              \END-PROGRAM
 \text{\END-ALGORITHM  \END-ALGO}            \END-ALGORITHM
 \text{\END-WHILE}                           \END-WHILE
 \text{\END-FOR}                             \END-FOR
 \text{\END-FORALL}                          \END-FORALL
 \text{\END-LOOP}                            \END-LOOP
+.. note:: The output of END-commands can be suppressed by setting the
+lexer option ``no_end`` to ``True``.
 Names and Entities
 ==================
 In an expression context all other words are interpreted as entity
 \TEXT{\NAME{entity-name 3\}}   \NAME{entity-name 3}
 \TEXT{München}                München
 \TEXT{Genève}                 Genève
 .. _explicit-token-types:
 Explicit Token Types
 ====================
 Lexer *instances* that are added to
 :py:data:`sphinx.highlighting.lexers` somehow are taken as is by
 Sphinx and are not augmented with any default filters.
 For older Sphinx versions your mileage may vary.
+Some Examples
+=============
+A synthetic example with many features:
+.. literalinclude:: examples/example-1.pseudocode
+:language: algpseudocode
+:lines: 2-
+With a customized `AlgPseudocodeLexer` and its `no_end`
+option set to ``True``.
+.. literalinclude:: examples/example-1.pseudocode
+:language: NoEndAlgPseudocode
+:lines: 2-
+This is Wikipedia's description of *Dinic's Algorithm*
+(see https://en.wikipedia.org/wiki/Dinic%27s_algorithm):
+.. literalinclude:: examples/algorithm-dinic.description
+:language: algpseudocode
+:lines: 2-
+This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm*
+(see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm):
+.. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode
+:language: algpseudocode
+:lines: 2-
+This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm*
+(see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm)
+with a custom lexer that skip all ``ENDxxx`` keywords:
+.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
+:language: NoEndAlgPseudocode
+:lines: 2-
+And now the *Edmonds–Karp Algorithm* with french keywords:
+.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
+:language: algpseudocode-fr
+:lines: 2-
+And again the *Edmonds–Karp Algorithm* with german keywords:
+.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
+:language: algpseudocode-de
+:lines: 2-

Mercurial > hgrepos > Python > libs > pygments-lexer-pseudocode2

comparison docs/lexer-algpseudocode.rst @ 169:3c517c22df9c