transform: pretty printing and improved writing; removed --xsl-output…

…, added --no-syntax.

README.rst

@@ -26,6 +26,9 @@ Xul -- XML Utilities
    :target: https://github.com/peteradrichem/Xul/actions/workflows/code-checks.yml
    :alt: Code checks
 
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+
 Xul is a set of XML scripts written in Python.
 Documentation can be found on `Read The Docs`_.
 

docs/changelog.rst

@@ -3,16 +3,19 @@ Changelog
 
 This document records all notable changes to `Xul <https://xul.readthedocs.io/>`_.
 
-`Unreleased <https://github.com/peteradrichem/Xul/compare/2.5.1...py3k>`_ (2025-01-13)
+`Unreleased <https://github.com/peteradrichem/Xul/compare/2.5.1...py3k>`_ (2025-01-17)
 --------------------------------------------------------------------------------------
 * Drop support for Python < 3.9.
 * :doc:`xp <xp>`: fix boolean result (Python >= 3.12).
 * :doc:`xp <xp>`: fix string result representation (Python 3).
 * :doc:`xp <xp>`: improved printing of namespaces.
-* Better error messages.
-* Code checks: ruff, black, isort, mypy.
+* :doc:`transform <transform>`: syntax highlighting for terminal output
+* :doc:`transform <transform>`: added ``--no-syntax`` option for terminal output
+* :doc:`transform <transform>`: removed ``--xsl-output`` option (always for ``--file``).
+* Fixed encoding issues.
+* Clearer error messages.
+* Code checks: ruff, black, isort, mypy (GitHub Action).
 * Test script for local testing with Docker Compose.
-* GitHub Action: code checks.
 * Typing.
 * Updated Sphinx configuration.
 * Output formatting (f-strings).

docs/index.rst

@@ -29,6 +29,9 @@ Current version: |release|
    :target: https://github.com/peteradrichem/Xul/actions/workflows/code-checks.yml
    :alt: Code checks
 
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+
 .. index::
    single: scripts
 

docs/ppx.rst

@@ -17,6 +17,8 @@ Use ``ppx`` to pretty print an :ref:`xml_source` in human readable form.
 .. index::
    single: white space
 
+``ppx`` will try to use the character encoding of your terminal and defaults to UTF-8.
+
 White Space
 -----------
 For greater readability ``ppx`` removes and adds *white space*.
@@ -33,14 +35,14 @@ Options
 
    $ ppx --help
 
-   usage: ppx [-h] [-V] [-n] [-o] [xml_source [xml_source ...]]
+   usage: ppx [-h] [-V] [-n] [-o] [xml_source ...]
 
    Pretty Print XML source in human readable form.
 
    positional arguments:
      xml_source            XML source (file, <stdin>, http://...)
 
-   optional arguments:
+   options:
      -h, --help            show this help message and exit
      -V, --version         show program's version number and exit
      -n, --no-syntax       no syntax highlighting
@@ -50,7 +52,7 @@ Options
 
 .. index::
    single: ppx script; syntax highlighting
-   single: syntax highlighting
+   single: syntax highlighting; ppx
 
 Syntax Highlighting
 -------------------
@@ -70,7 +72,6 @@ You can disable syntax highlighting with the ``--no-syntax`` option.
 
 .. index::
    single: ppx script; XML declaration
-   single: XML declaration
    single: XML declaration; ppx
 
 XML declaration

docs/transform.rst

@@ -11,17 +11,23 @@ an :ref:`xml_source`.
 If you need a command-line XSLT processor with more options have a look at
 `xsltproc <https://gnome.pages.gitlab.gnome.org/libxslt/xsltproc.html>`_
 
-Transform an XML file:
+Output a transformed XML file with syntax highlighting like :doc:`ppx <ppx>`:
 
 .. code-block:: bash
 
    transform stylesheet.xsl file.xml
 
-Transform an XML file and :doc:`pretty print <ppx>` the result:
+Transform an URL:
 
 .. code-block:: bash
 
-   transform --xsl-output stylesheet.xsl file.xml | ppx
+   curl -s https://example.com/path/file.xml | transform stylesheet.xsl
+
+Save transformed XML to a file:
+
+.. code-block:: bash
+
+   transform stylesheet.xsl source.xml --file new.xml
 
 Options
 -------
@@ -31,37 +37,60 @@ Options
 
    $ transform --help
 
-   usage: transform [-h] [-V] [-x | -o] [-f FILE] xslt_source xml_source
+   usage: transform [-h] [-V] [-f FILE | -s] [-o] xslt_source [xml_source]
 
-   Transform XML source with XSLT.
+   Transform an XML source with XSLT.
 
    positional arguments:
      xslt_source           XSLT source (file, http://...)
      xml_source            XML source (file, <stdin>, http://...)
 
-   optional arguments:
+   options:
      -h, --help            show this help message and exit
      -V, --version         show program's version number and exit
-     -x, --xsl-output      honor xsl:output
+     -f FILE, --file FILE  save result to file
+
+   terminal output options:
+     -n, --no-syntax       no syntax highlighting
      -o, --omit-declaration
                            omit the XML declaration
-     -f FILE, --file FILE  save result to file
+
+
+.. index::
+   single: transform script; syntax highlighting
+   single: syntax highlighting; transform
+
+Syntax highlighting
+-------------------
+
+.. program:: transform
+.. option:: -n, --no-syntax
+
+``transform`` will syntax highlight the XML result if you have Pygments_ installed.
+Output the transformed XML without syntax highlighting:
+
+.. code-block:: bash
+
+   transform --no-syntax stylesheet.xsl file.xml
+
 
 .. index::
    single: transform script; XML declaration
    single: XML declaration; transform
 
-XSL output
-----------
+XML declaration
+---------------
+XML documents should begin with an XML declaration which specifies the version of XML being used [#]_.
 
 .. program:: transform
-.. option:: -x, --xsl-output
+.. option:: -o, --omit-declaration
 
-You can honor the ``xsl:output`` element [#]_ with the ``--xsl-output`` option.
+You can omit the XML declaration with the ``--omit-declaration`` option.
 
 .. code-block:: bash
 
-   transform --xsl-output stylesheet.xsl file.xml
+   transform --omit-declaration stylesheet.xsl file.xml
+
 
 Save transformation result to file
 ----------------------------------
@@ -86,31 +115,21 @@ Example stylesheet that converts an XML document to UTF-16 encoding:
 
    </xsl:stylesheet>
 
-Save the transformation result to a little-endian UTF-16 Unicode text file.
+Save the transformation result to a little-endian UTF-16 text file.
 
 .. code-block:: bash
 
-   transform --xsl-output to_utf16.xsl utf8.xml --file utf16.xml
+   transform to_utf16.xsl utf8.xml --file utf16.xml
 
-When saving to file use the ``--xsl-output`` option to preserve the character encoding of the transformation.
+Save to file will honor the ``xsl:output`` element [#]_.
 
-XML declaration
----------------
-XML documents should begin with an XML declaration which specifies the version of XML being used [#]_.
 
-.. program:: transform
-.. option:: -o, --omit-declaration
-
-You can omit the XML declaration with the ``--omit-declaration`` option.
-
-.. code-block:: bash
-
-   transform --omit-declaration stylesheet.xsl file.xml
+.. _Pygments: https://pygments.org/
 
 
 .. rubric:: Footnotes
 
 .. [#] `XSL Transformations (XSLT) 1.0 <https://www.w3.org/TR/xslt-10/>`_
-.. [#] `XSL Transformations: 16 Output <https://www.w3.org/TR/xslt-10/#output>`_
 .. [#] Extensible Markup Language §2.8
    `Prolog and Document Type Declaration <https://www.w3.org/TR/xml/#sec-prolog-dtd>`_
+.. [#] `XSL Transformations: 16 Output <https://www.w3.org/TR/xslt-10/#output>`_

docs/xp.rst

@@ -45,24 +45,24 @@ Options
    Select nodes in an XML source with an XPath expression.
 
    positional arguments:
-   xpath_expr            XPath expression
-   xml_source            XML source (file, <stdin>, http://...)
+     xpath_expr            XPath expression
+     xml_source            XML source (file, <stdin>, http://...)
 
    options:
-   -h, --help            show this help message and exit
-   -V, --version         show program's version number and exit
-   -e, --exslt           add EXSLT XML namespaces
-   -d DEFAULT_NS_PREFIX, --default-prefix DEFAULT_NS_PREFIX
-                         set the prefix for the default namespace in XPath [default: 'd']
-   -q, --quiet           don't print XML source namespaces
-   -p, --pretty-element  pretty print the result element
-   -r, --result-xpath    print the XPath expression of the result element (or its parent)
-   -f, -l, --files-with-hits
-                         only the names of files with a non-false and non-NaN result are written to standard output
-   -F, -L, --files-without-hits
-                         only the names of files with a false or NaN result, or without any results are written to
-                         standard output
-   -m, --method          use ElementTree.xpath method instead of XPath class
+     -h, --help            show this help message and exit
+     -V, --version         show program's version number and exit
+     -e, --exslt           add EXSLT XML namespaces
+     -d DEFAULT_NS_PREFIX, --default-prefix DEFAULT_NS_PREFIX
+                           set the prefix for the default namespace in XPath [default: 'd']
+     -q, --quiet           don't print XML source namespaces
+     -p, --pretty-element  pretty print the result element
+     -r, --result-xpath    print the XPath expression of the result element (or its parent)
+     -f, -l, --files-with-hits
+                           only the names of files with a non-false and non-NaN result are written to standard output
+     -F, -L, --files-without-hits
+                           only the names of files with a false or NaN result, or without any results are written to
+                           standard output
+     -m, --method          use ElementTree.xpath method instead of XPath class
 
 
 .. index::

pyproject.toml

@@ -37,7 +37,7 @@ test = [
     "isort~=5.13.2",
     "lxml-stubs~=0.5.1",
     "mypy~=1.14.1",
-    "ruff~=0.9.1",
+    "ruff~=0.9.2",
     "types-Pygments~=2.19",
 ]
 syntax = [