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

annotate docs/intro.rst @ 160:b4028838e0c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Implement lexer option "prohibit_raiseonerror_filter". Sphinx raises by default when an Error token is seen (by means of the "raiseonerror" filter that is applied by default to lexers in Sphinx). This option skips this and allows error locations to be seen and highlighted properly. While there convert most Generic.Error tokens to Error tokens because now they can be handled by a lexer with "prohibit_raiseonerror_filter=True".
author Franz Glasner <fzglas.hg@dom66.de>
date Fri, 08 May 2026 17:46:28 +0200
parents 4ee0b1536ea6
children 315cfe0a836f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
86
0c05dc09c9e2 Customize documentation index and prepare for a "Details" documentation page.
Franz Glasner <fzglas.hg@dom66.de>
parents: 45
diff changeset
1 .. -*- coding: utf-8; indent-tabs-mode: nil; -*-
0c05dc09c9e2 Customize documentation index and prepare for a "Details" documentation page.
Franz Glasner <fzglas.hg@dom66.de>
parents: 45
diff changeset
2
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
3
152
66d49e49b06b FIX: Normalize reST for chapter in intro.rst
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
4 **************
66d49e49b06b FIX: Normalize reST for chapter in intro.rst
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
5 Introduction
66d49e49b06b FIX: Normalize reST for chapter in intro.rst
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
6 **************
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
7
141
acd9073cbbe3 Make a lexerlist.rst that contains the table of the lexers because it is used at least twice
Franz Glasner <fzglas.hg@dom66.de>
parents: 140
diff changeset
8 The package contains the following lexers:
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
9
141
acd9073cbbe3 Make a lexerlist.rst that contains the table of the lexers because it is used at least twice
Franz Glasner <fzglas.hg@dom66.de>
parents: 140
diff changeset
10 .. include:: lexerlist.rst
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
11
144
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 141
diff changeset
12 They may be used in `Sphinx`_ by their aliases:
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
13
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
14 .. code-block:: none
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
15
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
16 .. code-block:: algpseudocode
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
17
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
18 \PROGRAM {The Pseudoprogram} \IS
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
19
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
20 \END PROGRAM {The Pseudoprogram}
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
21
140
e424fcdd472f REFACTOR: Change the structure of the documentation: make the README the first page.
Franz Glasner <fzglas.hg@dom66.de>
parents: 138
diff changeset
22 It will be rendered as:
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
23
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
24 .. code-block:: algpseudocode
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
25
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
26 \PROGRAM {The Pseudoprogram} \IS
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
27
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
28 \END PROGRAM {The Pseudoprogram}
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
29
150
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
30 And the same with the german variant
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
31 (using ``.. code-block:: algpseudocode-de`` as language alias):
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
32
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
33 .. code-block:: algpseudocode-de
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
34
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
35 \PROGRAM {The Pseudoprogram} \IS
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
36
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
37 \END PROGRAM {The Pseudoprogram}
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
38
150
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
39 A basic documentation for FrPseudocode you find on its
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
40 :ref:`detail page <fr-pseudocode>`.
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
41
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
42 The AlgPseudocode lexer and its friends AlgPseudocodeDE and AlgPseudocodeFR
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
43 basically work in three states: `default`, `expression` and `text`.
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
44
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
45 In expressions it automatically recognizes:
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
46
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
47 - Strings (single-quote, double-quote, triple-single-quote,
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
48 triple-double-quote, `Python`_ style)
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
49 - Numbers (also `Python`_ style)
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
50 - (Mathematical) operators and symbols
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
51 - ``\TEXT{...}``
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
52
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
53 To switch in a text-mode that prohibits automatic expression
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
54 highlighting.
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
55
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
56 A closing curly brace can be quoted with ``\}`` to not end the
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
57 text mode prematurely.
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
58
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
59 - ``\NAME``, ``\CALL`` and ``\GETS``
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
60
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
61 - ``\REM`` and ``\REMARK`` for remarks (aka comments)
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
62
150
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
63 - Names (`Name.Entity`)
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
64
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
65 - :ref:`explicit-token-types`
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
66
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
67 In the default-mode it recogzizes expressions and additionally all
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
68 sorts of comments and commands that are inspired by CTAN's
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
69 `Algpseudocodex`_.
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
70
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
71 In texts it recogzizes:
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
72
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
73 - ``\EXPR`` or ``\EXPRESSION``
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
74
150
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
75 To switch to expression-mode.
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
76
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
77 A closing curly brace can be quoted with ``\}`` to not end the expression
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
78 mode prematurely.
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
79
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
80 - ``\REM`` and ``\REMARK`` for remarks (aka comments)
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
81
150
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
82 - :ref:`explicit-token-types`
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
83
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
84
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
85 .. rubric:: Some Examples
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
86
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 147
diff changeset
87 A synthetic example with most features:
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
88
151
4a8c122725b0 Move all the example files to "examples/"
Franz Glasner <fzglas.hg@dom66.de>
parents: 150
diff changeset
89 .. literalinclude:: examples/example-1.pseudocode
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
90 :language: algpseudocode
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
91 :lines: 2-
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
92
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
93 With a customized `AlgPseudocodeLexer` and its `no_end`
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
94 option set to ``True``.
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
95
151
4a8c122725b0 Move all the example files to "examples/"
Franz Glasner <fzglas.hg@dom66.de>
parents: 150
diff changeset
96 .. literalinclude:: examples/example-1.pseudocode
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
97 :language: NoEndAlgPseudocode
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
98 :lines: 2-
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
99
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
100 This is Wikipedia's description of *Dinic's Algorithm*
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
101 (see https://en.wikipedia.org/wiki/Dinic%27s_algorithm):
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
102
151
4a8c122725b0 Move all the example files to "examples/"
Franz Glasner <fzglas.hg@dom66.de>
parents: 150
diff changeset
103 .. literalinclude:: examples/algorithm-dinic.description
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
104 :language: algpseudocode
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
105 :lines: 2-
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
106
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
107 This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm*
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
108 (see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm):
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
109
151
4a8c122725b0 Move all the example files to "examples/"
Franz Glasner <fzglas.hg@dom66.de>
parents: 150
diff changeset
110 .. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
111 :language: algpseudocode
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
112 :lines: 2-
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
113
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
114 This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm*
159
4ee0b1536ea6 Handle runs of dots in expressions (., .., ..., ...., ...)
Franz Glasner <fzglas.hg@dom66.de>
parents: 154
diff changeset
115 (see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm)
4ee0b1536ea6 Handle runs of dots in expressions (., .., ..., ...., ...)
Franz Glasner <fzglas.hg@dom66.de>
parents: 154
diff changeset
116 with a custom lexer that skip all ``ENDxxx`` keywords:
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
117
151
4a8c122725b0 Move all the example files to "examples/"
Franz Glasner <fzglas.hg@dom66.de>
parents: 150
diff changeset
118 .. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
119 :language: NoEndAlgPseudocode
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
120 :lines: 2-
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
121
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
122 And now the *Edmonds–Karp Algorithm* with french keywords:
107
1c1985532139 A couple of real pseudocode examples.
Franz Glasner <fzglas.hg@dom66.de>
parents: 86
diff changeset
123
151
4a8c122725b0 Move all the example files to "examples/"
Franz Glasner <fzglas.hg@dom66.de>
parents: 150
diff changeset
124 .. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
125
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
125 :language: algpseudocode-fr
3629bf09b30d Much more documentation including most details of the AlgPseudocodeLexer
Franz Glasner <fzglas.hg@dom66.de>
parents: 107
diff changeset
126 :lines: 2-
154
b38d10ab914a Link to the details page for AlgPseudocode
Franz Glasner <fzglas.hg@dom66.de>
parents: 152
diff changeset
127
b38d10ab914a Link to the details page for AlgPseudocode
Franz Glasner <fzglas.hg@dom66.de>
parents: 152
diff changeset
128 More details you will find :ref:`here <details-algpseudocode>`.