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

comparison docs/lexer-algpseudocode.rst @ 266:50bd1e91b822

Doc enhancements: style, sub-headings, wording, examples, details

author	Franz Glasner <fzglas.hg@dom66.de>
date	Tue, 19 May 2026 19:01:27 +0200
parents	e5ea2f955986
children	ea19b621081d

comparison

equal deleted inserted replaced

-:e5ea2f955986
+:50bd1e91b822
 These lexers are heavily inspired by CTAN’s `Algpseudocodex`_.
 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
 .. code-block:: algpseudocode
 triple-double-quote, `Python`_ style)
 - Numbers (also `Python`_ style)
 - (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
 text mode prematurely.
 - Names (`Name.Entity`)
 - :ref:`explicit-token-types`
-In the `default`-mode it recognizes all sorts of single- and multi-line
+The `default`-mode is an extension of `expression`:
-comments in addition to expressions and commands that are inspired by
+in addition to `expressions` it recognizes all sorts of single- and
-`Algpseudocodex`_.
+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.
 - ``\TEXT`` as nested construct
 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)
 .. code-block:: algpseudocode
 Literals
 ========
-Strings and numbers as in `Python`_. String prefixes ``r``, ``f`` and ``t``
+Strings and numbers as in `Python`_.
-are not supported -- ``u`` and ``b`` are.
+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
+To have non-string-delimiting single- and double-quotes in the output you
-:algpseudocode:`f\\'(x) = 0`.
+have to escape them using ``\'`` or ``\"``.
+This must be used to typeset something as :algpseudocode:`f\\'(x) = 0`.
 .. code-block:: algpseudocode
 0  1234567890 0xdead 0b100001 0o720  2.7 2.7e-54
 Commands
 ========
 - 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
 Parameter handling is as follows:
 END-Commands
 ''''''''''''
 The separator character can be empty, a run of ASCII spaces, a run of
-TAB characters, a single underscore ``_`` or a single hyphen ``-``
+TAB characters, a single underscore ``_`` or a single hyphen ``-``.
-like:
+All of the following examples are equally valid and result in the
+same output:
 ``\ENDIF``, ``\END IF``, ``\END-IF``, ``\END_IF`` or ``\END IF``
 .. code-block:: algpseudocode
 \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
+.. note:: The output of these END-commands can be suppressed by setting the
 lexer option ``no_end`` to :py:obj:`True`.
 Names and Entities
 ==================
 .. _explicit-token-types:
 Explicit Token Types
 ====================
-Handle keywords and operators that are not handled by default or change
+They allow to handle keywords and operators that are not recognized by default.
-the default handling of some expressions.
+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.
 Its corresponding token type (the associated `key` in this `dict`) is
 used as token type.
 .. code-block:: algpseudocode
 \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-kc{A Constant Keyword\}}    \ttx-kc{A Constant Keyword}  \rem An explicit Keyword.Constant
-\text{• \\ttx-nv{A New Variable Name\}}       \ttx-nv{A New Variable Name}     \rem An explicit Name.Variable
+\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
 /*
 * The line below has ∈_∌ as (peculiar) function name.
 * Their params are automatic (i.e. a normal expression).
 */
 \text{• \\ttx-NON-EXISTING[∈_∌](p1, p2)}      \ttx-NON_EXISTING[∈_∌](p1, p2)
 .. note:: Explicit token types are **case-sensitive**.
+.. note:: Explicit token types work in all `expression` and `text` contexts.
 .. _escaping-rules:
 Escaping Rules
 ==============
 Some Examples
 =============
-A synthetic example with many features.
+.. rubric:: Synthetic Example
+The first example is a synthetic example with many features.
 .. only:: builder_html
 Its source code is in :download:`examples/example-1.pseudocode`.
 .. literalinclude:: examples/example-1.pseudocode
 :language: algpseudocode
 :lines: 2-
-With a customized `AlgPseudocodeLexer` and its `no_end`
+The highlighted output with a customized `AlgPseudocodeLexer` and its `no_end`
-option set to :py:obj:`True`.
+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).
 .. only:: builder_html
 Its source code is in :download:`examples/algorithm-dinic.pseudocode`.
 .. 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).
 .. only:: builder_html
 .. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode
 :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.
 .. only:: builder_html

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

comparison docs/lexer-algpseudocode.rst @ 266:50bd1e91b822