# HG changeset patch # User Franz Glasner # Date 1779210087 -7200 # Node ID 50bd1e91b8222fa10fad77316097bc64dc66a2e8 # Parent e5ea2f9559863976ed74394404bb8255c4941c1e Doc enhancements: style, sub-headings, wording, examples, details diff -r e5ea2f955986 -r 50bd1e91b822 docs/examples/example-1.pseudocode --- a/docs/examples/example-1.pseudocode Tue May 19 18:50:24 2026 +0200 +++ b/docs/examples/example-1.pseudocode Tue May 19 19:01:27 2026 +0200 @@ -17,7 +17,8 @@ \FUNCTION{A Function with {escaped\} text} \IS (1234567890 != what) or a and b xor (c in d) \rem this is another remark - \block {foo bar} + \block {foo is not bar} + \block {2 + 6 = 1 (mod 7)} \IF a is nil \THEN \text{Set something} @@ -34,13 +35,14 @@ (* Here is a "block" of expressions. A block has a leading symbol. *) - \block {foo - bar} + \block {foo ?= bar + Bär >= Maus + and Bär != Maus} \block{a 1.2 {x in X\} c} (* Analogous there is a variant that is in text-mode by default. It has an other leading symbol. *) \tstate{We will compute next \expr{a xor b or (\text{set} X is Empty)} \rem without c! - or multiply it the other way round} + or multiply it the \ttx-ges/other/ way.} \tstate{foo bar \rem A remark within a text statement until LF! nextfoo nextbar diff -r e5ea2f955986 -r 50bd1e91b822 docs/lexer-algpseudocode.rst --- a/docs/lexer-algpseudocode.rst Tue May 19 18:50:24 2026 +0200 +++ b/docs/lexer-algpseudocode.rst Tue May 19 19:01:27 2026 +0200 @@ -19,7 +19,7 @@ They recognize all sorts of single- and multi-line comments in addition to expressions and commands that are inspired by `Algpseudocodex`_. -They may be used in `Sphinx`_ by their aliases. +They are used in `Sphinx`_ using their aliases. The code-block: .. code-block:: none @@ -63,7 +63,7 @@ - (Mathematical) operators and symbols - ``\TEXT{...}`` - To switch in a text-mode that prohibits automatic expression + Used to switch to a text-mode that prohibits automatic expression highlighting. A closing curly brace can be quoted with ``\}`` to not end the @@ -79,15 +79,15 @@ - :ref:`explicit-token-types` - In the `default`-mode it recognizes all sorts of single- and multi-line - comments in addition to expressions and commands that are inspired by - `Algpseudocodex`_. + The `default`-mode is an extension of `expression`: + in addition to `expressions` it recognizes all sorts of single- and + multi-line comments and commands that are inspired by `Algpseudocodex`_. - In `texts` it recognizes: + In `text` context it recognizes: - ``\EXPR`` or ``\EXPRESSION`` - To switch to expression-mode. + Use to switch to expression-mode. A closing curly brace can be quoted with ``\}`` to not end the expression mode prematurely. @@ -149,7 +149,9 @@ Comments ======== -- with the ``\REMARK`` or ``\REM`` keywords (this includes a leading symbol) +- with the ``\REMARK`` or ``\REM`` keywords + (until the end of the line; the output includes a leading symbol, + by default ``▷``) - multi-line comments with ``/* ... */``; they can be **nested** - multi-line comments with ``(* ... *)``; they can be **nested** - single-line comments with ``//`` or ``#`` (until the end of the line) @@ -184,12 +186,13 @@ Literals ======== -Strings and numbers as in `Python`_. String prefixes ``r``, ``f`` and ``t`` -are not supported -- ``u`` and ``b`` are. +Strings and numbers as in `Python`_. +String prefixes ``u`` and ``b`` are supported---prefixes +``r``, ``f`` and ``t`` are not supported. -To yield non-string-delimiting single- and double-quotes you have to escape them -using ``\'`` or ``\"``. This must be used to typeset something as -:algpseudocode:`f\\'(x) = 0`. +To have non-string-delimiting single- and double-quotes in the output you +have to escape them using ``\'`` or ``\"``. +This must be used to typeset something as :algpseudocode:`f\\'(x) = 0`. .. code-block:: algpseudocode @@ -254,7 +257,7 @@ - Start with a backslash character ``\`` - Case-insensitive -- Yield mostly to :py:class:`pygments.Token.Keyword` +- Yield mostly the :py:class:`pygments.token.Token.Keyword` token type - Translated if a translation is found - Depending on the command---may have required or optional parameters @@ -376,8 +379,10 @@ '''''''''''' The separator character can be empty, a run of ASCII spaces, a run of -TAB characters, a single underscore ``_`` or a single hyphen ``-`` -like: +TAB characters, a single underscore ``_`` or a single hyphen ``-``. + +All of the following examples are equally valid and result in the +same output: ``\ENDIF``, ``\END IF``, ``\END-IF``, ``\END_IF`` or ``\END IF`` @@ -411,7 +416,7 @@ \text{\END-FORALL} \END-FORALL \text{\END-LOOP} \END-LOOP -.. note:: The output of END-commands can be suppressed by setting the +.. note:: The output of these END-commands can be suppressed by setting the lexer option ``no_end`` to :py:obj:`True`. @@ -445,8 +450,8 @@ Explicit Token Types ==================== -Handle keywords and operators that are not handled by default or change -the default handling of some expressions. +They allow to handle keywords and operators that are not recognized by default. +And they allow the user to explicitely highlight some input text at low-level. `XX` represents a `value` in the :py:data:`pygments.token.STANDARD_TYPES` dict. @@ -481,8 +486,9 @@ \text{• \\tt-kc/C} \tt-kc/C \rem C as Keyword.Constant \text{• \\tt-ow/∈} \tt-ow/∈ \rem ∈ as Operator.Word - \text{• \\ttx-kc{A New Constant Keyword\}} \ttx-kc{A New Constant Keyword} \rem As a new Keyword.Constant - \text{• \\ttx-nv{A New Variable Name\}} \ttx-nv{A New Variable Name} \rem An explicit Name.Variable + \text{• \\ttx-kc{A Constant Keyword\}} \ttx-kc{A Constant Keyword} \rem An explicit Keyword.Constant + \text{• \\ttx-nv{A Variable Name\}} \ttx-nv{A Variable Name} \rem An explicit Name.Variable + \text{• \\ttx-ni{An Entity*Name\}} \ttx-ni{An Entity*Name} \rem An explicit Name.Entity \text{• \\ttx-k(∈ ∌)} \ttx-k(∈ ∌) \rem ∈ and ∌ as (ordinary) Keywords \text{• \\ttx-o<∈ ∌>} \ttx-o<∈ ∌> \rem ∈ and ∌ as (ordinary) Operators /* @@ -503,6 +509,8 @@ .. note:: Explicit token types are **case-sensitive**. +.. note:: Explicit token types work in all `expression` and `text` contexts. + .. _escaping-rules: @@ -584,7 +592,9 @@ Some Examples ============= -A synthetic example with many features. +.. rubric:: Synthetic Example + +The first example is a synthetic example with many features. .. only:: builder_html @@ -598,13 +608,15 @@ :language: algpseudocode :lines: 2- -With a customized `AlgPseudocodeLexer` and its `no_end` -option set to :py:obj:`True`. +The highlighted output with a customized `AlgPseudocodeLexer` and its `no_end` +option set to :py:obj:`True`: .. literalinclude:: examples/example-1.pseudocode :language: NoEndAlgPseudocode :lines: 2- +.. rubric:: Dinic's Algorithm + The second example is Wikipedia's description of *Dinic's Algorithm* (see https://en.wikipedia.org/wiki/Dinic%27s_algorithm). @@ -614,12 +626,14 @@ .. raw:: latex - Its source code can be found at \url{algorithm-dinic.pseudocode} + Its source code can be found at \url{algorithm-dinic.pseudocode}. .. literalinclude:: examples/algorithm-dinic.pseudocode :language: algpseudocode :lines: 2- +.. rubric:: Ford–Fulkerson Algorithm + The third example is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm* (see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm). @@ -636,6 +650,8 @@ :language: algpseudocode :lines: 2- +.. rubric:: Edmonds–Karp Algorithm + The fourth example is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm* (see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm) with a custom lexer which skips all ``ENDxxx`` keywords.