lhtml-markup 2.2.0__tar.gz → 2.3.0__tar.gz

{lhtml_markup-2.2.0 → lhtml_markup-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lhtml-markup
-Version: 2.2.0
+Version: 2.3.0
 Summary: Lightweight HTML markup language — simplifies HTML authoring with shorthand syntax
 License: MIT
 Project-URL: Homepage, https://github.com/drohmer/lhtml
@@ -59,9 +59,14 @@ Dependencies (`lark`, `pygments`, `pyyaml`) are installed automatically.
 lhtml input.l.html                    # Convert to stdout
 lhtml input.l.html -o output.html     # Convert to file
 lhtml input.l.html -w                 # Wrap in full HTML document
+lhtml input.l.html -b                 # Render source line breaks as <br>
+lhtml a.l.html b.l.html               # Several files: a.html, b.html next to sources
+lhtml a.l.html b.l.html -o build/     # Several files into a directory
 python -m lhtml input.l.html          # Alternative invocation
 ```
 
+Files are read and written as UTF-8 (a BOM is accepted). Errors and warnings are reported on stderr with the file name, the remaining files are still processed, and the exit code is non-zero if any file failed. An input file is never overwritten (e.g. `lhtml page.html` without `-o`). Includes are looked up in the input file's directory first, then in the current directory.
+
 ### Python API
 
 ```python
@@ -133,6 +138,8 @@ This is <em>italic</em> text.
 This is <code class="code-inline">inline code</code> text.
 ```
 
+Inside inline code, `<` and `>` are escaped (so `` `std::vector<float>` `` displays correctly), and `**`, `__`, `$`, `include::`, `code::` and `::#` are not interpreted. Existing entities such as `&lt;` are kept. Named tags such as `link::` remain active, but a bare `::` is C++ (`` `::glfwInit()` ``), not a closing tag.
+
 
 ### Tag Elements (the `::` system)
 
@@ -144,6 +151,12 @@ tagName::(.classes #id)[cssStyle]{htmlAttributes} content ::
 
 All bracket groups are optional. If `tagName` is omitted, defaults to `div`.
 
+Tag names start with a letter and may contain letters, digits, `_` and `-` (useful for custom tags). A tag is only recognized when it is not glued to a preceding word: `std::chrono::seconds`, `obj.link::x` or the Python slice `a[::2]` are left untouched.
+
+A closing `::` may be directly followed by punctuation or HTML (`**span::[c] x ::**`, `important ::,`). In a run of colons, `::` markers are the pairs ending the run: `::::[...]` is a closing `::` followed by `::[...]`, and `x:::nl` is `x:` followed by `::nl`. A `::` between two HTML tags (as in pre-highlighted code `<span>::</span>`) is left untouched.
+
+A tag that is opened but never closed, or a `::` without matching opening tag, produces an `LHTMLWarning` quoting the beginning of the tag.
+
 #### Div / Span with Styles
 
 ```
@@ -209,6 +222,8 @@ Output:
 
 ### Links
 
+The URL of `link::`, `img::`, `video::` and `videoplay::` is never modified (`__`, `**`, `$` are kept). Parentheses that are part of the URL are kept (`Mercury_(planet)`, `fig(1).png`), while a group starting with `.` or `#` is a class/id group.
+
 ```
 link::https://example.com[Click here]
 link::page.html(.nav)[Back to home]
@@ -252,7 +267,7 @@ def hello():
 code::[-]
 ````
 
-Syntax highlighting is powered by Pygments. Any language supported by Pygments can be used.
+`include::file` directives inside a code block insert the file as raw code. Syntax highlighting is powered by Pygments. Any language supported by Pygments can be used. An empty language (`code::[]`) renders plain text; an unknown language renders plain text with a warning.
 
 
 ### Spacer
@@ -280,12 +295,28 @@ verbatim::[-]
 ```
 
 
+### Line breaks
+
+By default, line breaks of the source have no visual effect (as in HTML). With the option `-b` / `--line-breaks` (or `line-breaks: true` in the YAML front matter, or `{'line-breaks': True}` in the `meta` passed to `lhtml.run()`), each line break of the text is rendered with `<br>`, blank lines included:
+
+```
+Line 1            Line 1<br>
+Line 2     =>     Line 2<br>
+                  <br>
+Other paragraph   Other paragraph
+```
+
+Images and videos are inline: images written one per line are stacked (write them on the same line to keep them side by side). Lines that start or end with a block element (headings, lists, `div::`, block-level HTML tags such as `<div>`, `<p>`, `<li>`, code and verbatim blocks, `<script>`, display math, ...) are structure: they never get a `<br>` and blank lines next to them are ignored. The content of code blocks, verbatim blocks, scripts, comments and math is never modified.
+
+
 ### Comments
 
 ```
 Some text ::# This comment will be removed
 ```
 
+A comment starts a line or follows whitespace, so `link::#intro[...]` (link to an anchor) is not a comment.
+
 
 ### File Inclusion
 
@@ -294,11 +325,13 @@ include::header.html
 include::components/nav.html
 ```
 
-Included files are recursively processed (up to 20 levels).
+Included files are recursively processed (up to 20 levels); their own YAML front matter is ignored. An included file looks for its own includes first in its own directory, then in `directory_include`. A circular include raises `LHTMLIncludeLoopError`.
 
 
 ### YAML Front Matter
 
+The front matter must be at the very beginning of the file (`---` separators elsewhere are kept as text). Input text is normalized first: a leading BOM is removed and CRLF line endings become LF.
+
 ```
 ---
 title: "My Page"
@@ -318,6 +351,7 @@ Supported metadata keys:
 | `css` | string or list | CSS files to include |
 | `js` | string or list | JavaScript files to include |
 | `wrap-auto` | boolean | Wrap output in full HTML document |
+| `line-breaks` | boolean | Render source line breaks as `<br>` |
 | `directory_include` | list | Directories to search for includes |
 
 
@@ -331,9 +365,10 @@ Register handlers for new `::` tag types:
 from lhtml.pipeline import tag_registry
 
 def handle_alert(element, tag_to_close, current_directory):
+    """Open <div class="alert">; the following :: closes it."""
     style = element.get('[]', '')
-    text = element.get('text', '')
-    return f'<div class="alert" style="{style}">{text}</div>', True
+    tag_to_close.append('div')
+    return f'<div class="alert" style="{style}">', True
 
 tag_registry.register('alert', handle_alert)
 ```
@@ -343,6 +378,12 @@ Then use in LHTML:
 alert::[background:yellow; padding:10px;] Warning message ::
 ```
 
+A handler receives the parsed element (`'[]'`, `'()'`, `'{}'`, `'text'`: the
+word glued after the brackets) and returns `(html, is_real_tag)`. To wrap the
+content that follows, push the HTML tag name on `tag_to_close`: the next `::`
+(or `::name[-]`) closes it. Returning `is_real_tag=False` leaves the source
+text unchanged.
+
 ### Custom Code Lexers
 
 Register custom Pygments lexers for syntax highlighting:
@@ -376,6 +417,7 @@ All keys for the `meta` dict passed to `lhtml.run()`:
 ```python
 {
     'wrap-auto': False,        # Wrap in HTML document
+    'line-breaks': False,      # Render source line breaks as <br>
     'title': 'Webpage',        # Document title
     'css': [],                 # CSS files (string or list)
     'js': [],                  # JS files (string or list)
@@ -387,7 +429,7 @@ All keys for the `meta` dict passed to `lhtml.run()`:
 
 ## Design Principles
 
-- **HTML-first**: Raw HTML is never modified. Only LHTML syntax triggers conversions.
+- **HTML-first**: Raw HTML is never modified. Only LHTML syntax triggers conversions. In particular, the following are never transformed (not even by `include::` or `::#`): HTML tags and their attributes (URLs containing `__`, quoted values containing `>`, ...), `<script>` and `<style>` blocks (CSS `::before`, ...), HTML comments, and math (`$...$`, `$$...$$`, `\(...\)`, `\[...\]`, so that `$x**2$` reaches MathJax/KaTeX intact). Text between HTML tags is still processed.
 - **Island grammar**: LHTML syntax "islands" float in a sea of opaque content (HTML, Jinja2 templates, LaTeX, etc.) that passes through untouched.
 - **Minimal**: A few symbols (`::`, `=`, `*`, `**`, `__`, `` ` ``) cover most needs. No complex configuration required.
 - **Composable**: LHTML works seamlessly with Jinja2 templates, making it suitable for static site generators.
@@ -408,7 +450,6 @@ src/lhtml/
   listing.py           # List processing
   code.py              # Code syntax highlighting (Pygments)
   wrap_html.py         # HTML document wrapping
-  ast_nodes.py         # AST node dataclasses
   errors.py            # Structured error types
 ```
 

{lhtml_markup-2.2.0 → lhtml_markup-2.3.0}/README.md

@@ -40,9 +40,14 @@ Dependencies (`lark`, `pygments`, `pyyaml`) are installed automatically.
 lhtml input.l.html                    # Convert to stdout
 lhtml input.l.html -o output.html     # Convert to file
 lhtml input.l.html -w                 # Wrap in full HTML document
+lhtml input.l.html -b                 # Render source line breaks as <br>
+lhtml a.l.html b.l.html               # Several files: a.html, b.html next to sources
+lhtml a.l.html b.l.html -o build/     # Several files into a directory
 python -m lhtml input.l.html          # Alternative invocation
 ```
 
+Files are read and written as UTF-8 (a BOM is accepted). Errors and warnings are reported on stderr with the file name, the remaining files are still processed, and the exit code is non-zero if any file failed. An input file is never overwritten (e.g. `lhtml page.html` without `-o`). Includes are looked up in the input file's directory first, then in the current directory.
+
 ### Python API
 
 ```python
@@ -114,6 +119,8 @@ This is <em>italic</em> text.
 This is <code class="code-inline">inline code</code> text.
 ```
 
+Inside inline code, `<` and `>` are escaped (so `` `std::vector<float>` `` displays correctly), and `**`, `__`, `$`, `include::`, `code::` and `::#` are not interpreted. Existing entities such as `&lt;` are kept. Named tags such as `link::` remain active, but a bare `::` is C++ (`` `::glfwInit()` ``), not a closing tag.
+
 
 ### Tag Elements (the `::` system)
 
@@ -125,6 +132,12 @@ tagName::(.classes #id)[cssStyle]{htmlAttributes} content ::
 
 All bracket groups are optional. If `tagName` is omitted, defaults to `div`.
 
+Tag names start with a letter and may contain letters, digits, `_` and `-` (useful for custom tags). A tag is only recognized when it is not glued to a preceding word: `std::chrono::seconds`, `obj.link::x` or the Python slice `a[::2]` are left untouched.
+
+A closing `::` may be directly followed by punctuation or HTML (`**span::[c] x ::**`, `important ::,`). In a run of colons, `::` markers are the pairs ending the run: `::::[...]` is a closing `::` followed by `::[...]`, and `x:::nl` is `x:` followed by `::nl`. A `::` between two HTML tags (as in pre-highlighted code `<span>::</span>`) is left untouched.
+
+A tag that is opened but never closed, or a `::` without matching opening tag, produces an `LHTMLWarning` quoting the beginning of the tag.
+
 #### Div / Span with Styles
 
 ```
@@ -190,6 +203,8 @@ Output:
 
 ### Links
 
+The URL of `link::`, `img::`, `video::` and `videoplay::` is never modified (`__`, `**`, `$` are kept). Parentheses that are part of the URL are kept (`Mercury_(planet)`, `fig(1).png`), while a group starting with `.` or `#` is a class/id group.
+
 ```
 link::https://example.com[Click here]
 link::page.html(.nav)[Back to home]
@@ -233,7 +248,7 @@ def hello():
 code::[-]
 ````
 
-Syntax highlighting is powered by Pygments. Any language supported by Pygments can be used.
+`include::file` directives inside a code block insert the file as raw code. Syntax highlighting is powered by Pygments. Any language supported by Pygments can be used. An empty language (`code::[]`) renders plain text; an unknown language renders plain text with a warning.
 
 
 ### Spacer
@@ -261,12 +276,28 @@ verbatim::[-]
 ```
 
 
+### Line breaks
+
+By default, line breaks of the source have no visual effect (as in HTML). With the option `-b` / `--line-breaks` (or `line-breaks: true` in the YAML front matter, or `{'line-breaks': True}` in the `meta` passed to `lhtml.run()`), each line break of the text is rendered with `<br>`, blank lines included:
+
+```
+Line 1            Line 1<br>
+Line 2     =>     Line 2<br>
+                  <br>
+Other paragraph   Other paragraph
+```
+
+Images and videos are inline: images written one per line are stacked (write them on the same line to keep them side by side). Lines that start or end with a block element (headings, lists, `div::`, block-level HTML tags such as `<div>`, `<p>`, `<li>`, code and verbatim blocks, `<script>`, display math, ...) are structure: they never get a `<br>` and blank lines next to them are ignored. The content of code blocks, verbatim blocks, scripts, comments and math is never modified.
+
+
 ### Comments
 
 ```
 Some text ::# This comment will be removed
 ```
 
+A comment starts a line or follows whitespace, so `link::#intro[...]` (link to an anchor) is not a comment.
+
 
 ### File Inclusion
 
@@ -275,11 +306,13 @@ include::header.html
 include::components/nav.html
 ```
 
-Included files are recursively processed (up to 20 levels).
+Included files are recursively processed (up to 20 levels); their own YAML front matter is ignored. An included file looks for its own includes first in its own directory, then in `directory_include`. A circular include raises `LHTMLIncludeLoopError`.
 
 
 ### YAML Front Matter
 
+The front matter must be at the very beginning of the file (`---` separators elsewhere are kept as text). Input text is normalized first: a leading BOM is removed and CRLF line endings become LF.
+
 ```
 ---
 title: "My Page"
@@ -299,6 +332,7 @@ Supported metadata keys:
 | `css` | string or list | CSS files to include |
 | `js` | string or list | JavaScript files to include |
 | `wrap-auto` | boolean | Wrap output in full HTML document |
+| `line-breaks` | boolean | Render source line breaks as `<br>` |
 | `directory_include` | list | Directories to search for includes |
 
 
@@ -312,9 +346,10 @@ Register handlers for new `::` tag types:
 from lhtml.pipeline import tag_registry
 
 def handle_alert(element, tag_to_close, current_directory):
+    """Open <div class="alert">; the following :: closes it."""
     style = element.get('[]', '')
-    text = element.get('text', '')
-    return f'<div class="alert" style="{style}">{text}</div>', True
+    tag_to_close.append('div')
+    return f'<div class="alert" style="{style}">', True
 
 tag_registry.register('alert', handle_alert)
 ```
@@ -324,6 +359,12 @@ Then use in LHTML:
 alert::[background:yellow; padding:10px;] Warning message ::
 ```
 
+A handler receives the parsed element (`'[]'`, `'()'`, `'{}'`, `'text'`: the
+word glued after the brackets) and returns `(html, is_real_tag)`. To wrap the
+content that follows, push the HTML tag name on `tag_to_close`: the next `::`
+(or `::name[-]`) closes it. Returning `is_real_tag=False` leaves the source
+text unchanged.
+
 ### Custom Code Lexers
 
 Register custom Pygments lexers for syntax highlighting:
@@ -357,6 +398,7 @@ All keys for the `meta` dict passed to `lhtml.run()`:
 ```python
 {
     'wrap-auto': False,        # Wrap in HTML document
+    'line-breaks': False,      # Render source line breaks as <br>
     'title': 'Webpage',        # Document title
     'css': [],                 # CSS files (string or list)
     'js': [],                  # JS files (string or list)
@@ -368,7 +410,7 @@ All keys for the `meta` dict passed to `lhtml.run()`:
 
 ## Design Principles
 
-- **HTML-first**: Raw HTML is never modified. Only LHTML syntax triggers conversions.
+- **HTML-first**: Raw HTML is never modified. Only LHTML syntax triggers conversions. In particular, the following are never transformed (not even by `include::` or `::#`): HTML tags and their attributes (URLs containing `__`, quoted values containing `>`, ...), `<script>` and `<style>` blocks (CSS `::before`, ...), HTML comments, and math (`$...$`, `$$...$$`, `\(...\)`, `\[...\]`, so that `$x**2$` reaches MathJax/KaTeX intact). Text between HTML tags is still processed.
 - **Island grammar**: LHTML syntax "islands" float in a sea of opaque content (HTML, Jinja2 templates, LaTeX, etc.) that passes through untouched.
 - **Minimal**: A few symbols (`::`, `=`, `*`, `**`, `__`, `` ` ``) cover most needs. No complex configuration required.
 - **Composable**: LHTML works seamlessly with Jinja2 templates, making it suitable for static site generators.
@@ -389,7 +431,6 @@ src/lhtml/
   listing.py           # List processing
   code.py              # Code syntax highlighting (Pygments)
   wrap_html.py         # HTML document wrapping
-  ast_nodes.py         # AST node dataclasses
   errors.py            # Structured error types
 ```
 

{lhtml_markup-2.2.0 → lhtml_markup-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lhtml-markup"
-version = "2.2.0"
+version = "2.3.0"
 description = "Lightweight HTML markup language — simplifies HTML authoring with shorthand syntax"
 readme = "README.md"
 license = {text = "MIT"}

{lhtml_markup-2.2.0 → lhtml_markup-2.3.0}/src/lhtml/__init__.py

@@ -15,7 +15,8 @@ from .wrap_html import wrap_auto
 
 from .process import (
     process_yaml, process_verbatim_to_index, process_verbatim_back_from_index,
-    process_remove_comment, process_include, find_file,
+    process_remove_comment, process_include, process_include_recursive, find_file,
+    process_protect, process_unprotect, process_line_breaks,
     process_bold, process_italic, process_code_inline,
     process_title, process_tag, process_code,
     process_listing,
@@ -23,13 +24,7 @@ from .process import (
 
 from .errors import (
     LHTMLError, LHTMLParseError, LHTMLFileNotFound,
-    LHTMLTagStackError, LHTMLIncludeLoopError,
-)
-
-from .ast_nodes import (
-    LHTMLDocument, TextNode, TagElement, HeadingNode,
-    ListNode, ListItem, InlineFormat, CodeBlock,
-    VerbatimBlock, IncludeDirective, Comment, SpacerNode, ClosingTag,
+    LHTMLTagStackError, LHTMLIncludeLoopError, LHTMLWarning,
 )
 
 from .pipeline import ProcessingPipeline, tag_registry, lexer_registry
@@ -79,7 +74,8 @@ __all__ = [
     # Processing functions
     'extract_bracket_elements',
     'process_yaml', 'process_verbatim_to_index', 'process_verbatim_back_from_index',
-    'process_remove_comment', 'process_include', 'find_file',
+    'process_remove_comment', 'process_include', 'process_include_recursive', 'find_file',
+    'process_protect', 'process_unprotect', 'process_line_breaks',
     'process_bold', 'process_italic', 'process_code_inline',
     'process_title', 'process_tag', 'process_code',
     'process_listing',
@@ -87,11 +83,7 @@ __all__ = [
     'wrap_auto',
     # Pipeline & plugins
     'ProcessingPipeline', 'tag_registry', 'lexer_registry',
-    # AST
-    'LHTMLDocument', 'TextNode', 'TagElement', 'HeadingNode',
-    'ListNode', 'ListItem', 'InlineFormat', 'CodeBlock',
-    'VerbatimBlock', 'IncludeDirective', 'Comment', 'SpacerNode', 'ClosingTag',
     # Errors
     'LHTMLError', 'LHTMLParseError', 'LHTMLFileNotFound',
-    'LHTMLTagStackError', 'LHTMLIncludeLoopError',
+    'LHTMLTagStackError', 'LHTMLIncludeLoopError', 'LHTMLWarning',
 ]

{lhtml_markup-2.2.0 → lhtml_markup-2.3.0}/src/lhtml/cli.py

@@ -5,13 +5,18 @@ Usage:
     lhtml [-w] file.l.html -o output.html         # Single file → output file
     lhtml [-w] a.l.html b.l.html                  # Multiple files → .html next to sources
     lhtml [-w] a.l.html b.l.html -o build/        # Multiple files → output directory
+    lhtml -b file.l.html                          # Source line breaks rendered as <br>
     python -m lhtml [same options]
 """
 
 import os
+import sys
 import argparse
+import warnings
 
+from .errors import LHTMLError
 from .pipeline import ProcessingPipeline
+from .process import read_source
 
 
 _pipeline = ProcessingPipeline()
@@ -49,16 +54,22 @@ def _output_path_for(input_path, output_arg):
 
 
 def _process_file(f_in, meta_base):
-    """Process a single LHTML file and return the HTML output."""
-    meta = dict(meta_base)
-    dir_to_include = os.path.dirname(os.path.abspath(f_in))
-    if dir_to_include:
-        meta['directory_include'] = meta.get('directory_include', []) + [dir_to_include + '/']
+    """Process a single LHTML file and return (html, warning_messages).
 
-    with open(f_in) as fid:
-        txt = _ensure_trailing_newline(fid.read())
+    Includes are looked up first in the file's directory, then in the
+    current directory.
+    """
+    meta = dict(meta_base)
+    dir_of_file = os.path.dirname(os.path.abspath(f_in)) + '/'
+    meta['directory_include'] = [dir_of_file] + [
+        d for d in meta.get('directory_include', []) if d != dir_of_file]
+    meta['current_directory'] = dir_of_file
 
-    return _ensure_trailing_newline(_pipeline.run(txt, meta))
+    txt = _ensure_trailing_newline(read_source(f_in))
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter('always')
+        html = _ensure_trailing_newline(_pipeline.run(txt, meta))
+    return html, [str(w.message) for w in caught]
 
 
 def main():
@@ -68,6 +79,9 @@ def main():
     parser.add_argument('-w', '--wrapAuto',
                         help='Wrap content in basic HTML template',
                         action='store_true')
+    parser.add_argument('-b', '--line-breaks',
+                        help='Render the line breaks of the source text as <br>',
+                        action='store_true')
     parser.add_argument('-o', '--output',
                         help='Output file (single input) or directory (multiple inputs)')
     args = parser.parse_args()
@@ -75,23 +89,48 @@ def main():
     meta = {'directory_include': [os.getcwd() + '/']}
     if args.wrapAuto:
         meta['wrap-auto'] = True
+    if args.line_breaks:
+        meta['line-breaks'] = True
 
     single_file = len(args.inputFiles) == 1
     single_to_stdout = single_file and args.output is None
 
+    if (not single_file and args.output is not None
+            and not os.path.isdir(args.output) and not args.output.endswith('/')):
+        parser.error(f'-o must be a directory when several input files are given '
+                     f'(got {args.output!r}; add a trailing / to create it)')
+
+    errors = 0
     for f_in in args.inputFiles:
         if not os.path.isfile(f_in):
-            print(f'Error: file not found [{f_in}]')
+            print(f'lhtml: error: file not found [{f_in}]', file=sys.stderr)
+            errors += 1
             continue
 
-        html = _process_file(f_in, meta)
+        try:
+            html, messages = _process_file(f_in, meta)
+            for message in messages:
+                print(f'lhtml: warning in {f_in}: {message}', file=sys.stderr)
+
+            if single_to_stdout:
+                sys.stdout.buffer.write(html.encode('utf-8'))
+                sys.stdout.flush()
+                continue
 
-        if single_to_stdout:
-            print(html)
-        else:
             out_path = _output_path_for(f_in, args.output)
-            with open(out_path, 'w') as f_out:
+            if os.path.abspath(out_path) == os.path.abspath(f_in):
+                raise ValueError(f'output file would overwrite the input file [{out_path}]')
+            out_dir = os.path.dirname(out_path)
+            if out_dir:
+                os.makedirs(out_dir, exist_ok=True)
+            with open(out_path, 'w', encoding='utf-8') as f_out:
                 f_out.write(html)
+        except (LHTMLError, OSError, UnicodeError, ValueError) as e:
+            print(f'lhtml: error in {f_in}: {e}', file=sys.stderr)
+            errors += 1
+
+    if errors:
+        sys.exit(1)
 
 
 if __name__ == '__main__':

{lhtml_markup-2.2.0 → lhtml_markup-2.3.0}/src/lhtml/code.py

@@ -4,8 +4,11 @@ Uses Pygments for highlighting. Custom lexers can be registered
 via the lexer_registry in pipeline.py.
 """
 
+import warnings
+
 from pygments import highlight
-from pygments.lexers import get_lexer_by_name
+from pygments.lexers import get_lexer_by_name, TextLexer
+from pygments.util import ClassNotFound
 from pygments.formatters import HtmlFormatter
 from pygments.lexer import words, inherit
 import pygments.lexers
@@ -51,24 +54,33 @@ _BUILTIN_LEXERS = {
 
 def export_html_code(text, language, cssclass='code'):
     """Highlight a code block and return HTML."""
-    # Check plugin registry first, then built-in lexers
+    language = (language or '').strip()
+
+    # Check plugin registry first, then built-in lexers (case-insensitive)
     lexer_class = None
     try:
         from .pipeline import lexer_registry
-        lexer_class = lexer_registry.get(language)
+        lexer_class = lexer_registry.get(language) or lexer_registry.get(language.lower())
     except ImportError:
         pass
 
     if lexer_class is None:
-        lexer_class = _BUILTIN_LEXERS.get(language)
+        lexer_class = _BUILTIN_LEXERS.get(language.lower())
 
+    lexer_options = dict(stripall=False, stripnl=True, ensurenl=True,
+                         tabsize=2, encoding='utf-8')
     if lexer_class is not None:
         lexer = lexer_class()
+    elif not language:
+        lexer = TextLexer(**lexer_options)
     else:
-        lexer = get_lexer_by_name(
-            language, stripall=False, stripnl=True,
-            ensurenl='True', tabsize=2, encoding='utf-8',
-        )
+        try:
+            lexer = get_lexer_by_name(language, **lexer_options)
+        except ClassNotFound:
+            from .errors import LHTMLWarning
+            warnings.warn(f'Unknown language {language!r} for code::[...] block, '
+                          'rendered as plain text', LHTMLWarning, stacklevel=2)
+            lexer = TextLexer(**lexer_options)
 
     formatter = HtmlFormatter(linenos=False, cssclass=cssclass)
     return highlight(text, lexer, formatter)

{lhtml_markup-2.2.0 → lhtml_markup-2.3.0}/src/lhtml/errors.py

@@ -20,6 +20,10 @@ class LHTMLError(Exception):
         super().__init__(full_message)
 
 
+class LHTMLWarning(UserWarning):
+    """Category of the warnings emitted while processing LHTML markup."""
+
+
 class LHTMLParseError(LHTMLError):
     """Error during parsing of LHTML markup (unclosed brackets, etc.)."""
     pass
@@ -36,18 +40,34 @@ class LHTMLFileNotFound(LHTMLError):
 
 
 class LHTMLTagStackError(LHTMLError):
-    """A closing :: tag has no matching opening tag."""
-
-    def __init__(self, source_pos: int = -1, source_line: int = -1):
-        message = 'Closing tag :: has no matching opening tag'
+    """A closing :: tag has no matching opening tag, or a tag is never closed."""
+
+    def __init__(self, context: str | int = '', unclosed: str | None = None,
+                 source_pos: int = -1, source_line: int = -1):
+        if isinstance(context, int):
+            # LHTML 2.2 signature: LHTMLTagStackError(source_pos, source_line)
+            if isinstance(unclosed, int):
+                source_line, unclosed = unclosed, None
+            source_pos, context = context, ''
+        self.context = context
+        self.unclosed = unclosed
+        if unclosed:
+            message = f'Tag <{unclosed}> is never closed'
+        else:
+            message = 'Closing tag :: has no matching opening tag'
+        if context:
+            message += f' (near {context!r})'
         super().__init__(message, source_pos, source_line)
 
 
 class LHTMLIncludeLoopError(LHTMLError):
     """Too many include iterations — likely a circular include."""
 
-    def __init__(self, max_iterations: int = 20):
-        message = f'Too many include iterations (>{max_iterations}), possible circular include'
+    def __init__(self, max_iterations: int = 20, chain: list[str] | None = None):
+        self.chain = chain or []
+        message = f'Circular or too deep include (max depth {max_iterations})'
+        if self.chain:
+            message += ': ' + ' -> '.join(self.chain)
         super().__init__(message)