Write new CLI reference

docs/source/advanced-usage.rst

@@ -134,63 +134,3 @@ after the conversion:
 .. code:: shell
 
     xhtml2pdf -s test.html
-
-Advanced CLI usage
-^^^^^^^^^^^^^^^^^^
-
-Use ``xhtml2pdf --help`` to get started.
-
-
-Converting HTML data
-""""""""""""""""""""
-
-To generate a PDF from an HTML file called ``test.html`` call:
-
-.. code:: shell
-
-    xhtml2pdf -s test.html
-
-The resulting PDF will be called ``test.pdf`` (if this file is locked
-e.g. by the Adobe Reader, it will be called ``test-0.pdf`` and so on).
-The ``-s`` option takes care that the PDF will be opened directly in the
-Operating Systems default viewer.
-
-To convert more than one file you may use wildcard patterns like ``*``
-and ``?``:
-
-.. code:: shell
-
-    xhtml2pdf "test/test-*.html"
-
-You may also directly access pages from the internet:
-
-.. code:: shell
-
-    xhtml2pdf -s http://www.xhtml2pdf.com/
-
-Using special properties
-""""""""""""""""""""""""
-
-If the conversion doesn't work as expected some more information may be
-usefull. You may turn on the output of warnings by adding ``-w`` or even
-the debugging output by using ``-d``.
-
-Another reason could be, that the parsing failed. Consider trying the
-``-xhtml`` and ``-html`` options. ``xhtml2pdf`` uses the HTMLT5lib parser
-that offers two internal parsing modes: one for HTML and one for XHTML.
-
-When generating the HTML output ``xhtml2pdf`` uses an internal default CSS
-definition (otherwise all tags would appear with no differences). To get
-an impression of how this one looks like start ``xhtml2pdf`` like this:
-
-.. code:: shell
-
-    xhtml2pdf --css-dump > xhtml2pdf-default.css
-
-The CSS will be dumped into the file ``xhtml2pdf-default.css``. You may
-modify this or even take a totally self-defined one and hand it in by
-using the ``-css`` option, e.g.:
-
-.. code:: shell
-
-    xhtml2pdf --css=xhtml2pdf-default.css test.html

docs/source/index.rst

@@ -40,6 +40,7 @@ Contents
    :maxdepth: 2
 
    reference
+   reference/cli
 
 .. toctree::
    :caption: Contributing

docs/source/quickstart.rst

@@ -70,3 +70,5 @@ You can convert HTML files to PDF documents from the command line:
 .. code:: shell
 
     xhtml2pdf source.html output.pdf
+
+Read more in the :doc:`CLI reference <reference/cli>`.

docs/source/reference/cli.rst

@@ -0,0 +1,117 @@
+======================
+Command-line interface
+======================
+
+.. hint:: At any time, run ``xhtml2pdf --help`` to get help.
+
+
+Basic usage
+-----------
+
+To generate a PDF document from an HTML file called ``source.html`` call:
+
+.. code:: shell
+
+    xhtml2pdf source.html # will create source.pdf
+
+
+Source
+^^^^^^
+
+The first positional argument to the CLI should be the source HTML file.
+If you want to read it from stdin, you can use ``-``:
+
+.. code:: shell
+
+    some-script-that-outputs-html | xhtml2pdf - output.pdf
+
+You may also supply a webpage using its URL. Don't forget to quote it, when
+needed:
+
+.. code:: shell
+
+    xhtml2pdf "https://en.wikipedia.org/w/index.php?title=PDF&oldid=1183757701" output.pdf
+
+
+Destination
+^^^^^^^^^^^
+
+The second positional argument is the name of the destination PDF document. If
+omitted, xhtml2pdf will pick a name for it. Just like with the source, you can
+use ``-`` to redirect the PDF file to stdout. This is particularly useful
+together with ``curl`` or GhostScript.
+
+.. important:: Take care that the destination file is not already opened by
+               another application (like Acrobat Reader)
+
+
+Options
+-------
+
+Input
+^^^^^
+
+``--base``/``-b``
+   Specify a base path. You should set this when the source HTML is supplied via
+   stdin, as there is no other way to resolve relative hyperlinks.
+
+``--encoding``
+   The character encoding of the source HTML file. If left empty, this will be
+   inferred from the HTML ``<meta charset>`` value.
+
+``--html``
+   Parse the source document as HTML (default).
+
+``--xml``/``--xhtml``/``-x``
+   Parse the source document as XHTML. This is set automatically if the source file
+   name ends with ".xml"
+
+HTTP Options
+""""""""""""
+
+These are used when the source is a webpage.
+
+``--http_nosslcheck``
+   Do not check the website's SSL certificate.
+
+``--http_timeout``
+   equivalent to ``timeout`` in :py:class:`http.client.HTTPSConnection`
+
+``--http_source_address``
+   equivalent to ``source_address`` in :py:class:`http.client.HTTPSConnection`
+
+``--http_key_file`` and ``--http_cert_file`` were removed in Python 3.12 and are
+not used anymore.
+
+Styling
+^^^^^^^
+
+``--css``/``-c``
+   Path to default CSS file. It will be applied to the generated document. If
+   omitted, a reasonable default will be used.
+
+``--css-dump``
+   Output default CSS file.
+
+   When generating the HTML output, ``xhtml2pdf`` uses an internal default CSS
+   definition (otherwise all tags would look the same). To get an impression of
+   what it looks like, run:
+
+   .. code:: shell
+
+       xhtml2pdf --css-dump > xhtml2pdf-default.css
+
+Output
+^^^^^^
+
+``--start-viewer``/``-s``
+   Start the default PDF viewer after conversion.
+
+``--quiet``/``-q``
+   Show no messages.
+
+``--warn``/``-w``
+   Show warnings.
+
+``--debug``/``-d``
+   Show debugging information.