From 2ffb8c96a3938fc0a3d0e0b9ff3ea8eb136cfbe5 Mon Sep 17 00:00:00 2001 From: Nick Wellnhofer Date: Sun, 8 Jun 2025 14:58:29 +0200 Subject: [PATCH] doc: Improve xmllint documentation Group more options. Clarify effect of some parser options. Mention streaming validation with `--sax`. Remove references to libxml(3). --- doc/xmllint.xml | 396 ++++++++++++++++++++++++++---------------------- 1 file changed, 212 insertions(+), 184 deletions(-) diff --git a/doc/xmllint.xml b/doc/xmllint.xml index b6fcae90b..bd3606152 100644 --- a/doc/xmllint.xml +++ b/doc/xmllint.xml @@ -11,7 +11,7 @@ xmllint Manual - libxml2 + xmllint 2001 2004 @@ -147,57 +147,17 @@ errors both in XML code and in the XML parser itself. - &xmllint; is included in - libxml - 3 - . + &xmllint; is part of the libxml2 library. - - OPTIONS + + VALIDATION OPTIONS - &xmllint; accepts the following options (in alphabetical order): + Options enabling validation. - - - - - Use the SGML catalog(s) from SGML_CATALOG_FILES. - Otherwise XML catalogs starting - from /etc/xml/catalog or, more specifically, - ${sysconfdir}/xml/catalog are used by default. - - - - - - - - - Turn on - gzip - 1 - compression of output. - - - - - - - - - - - Use the W3C XML Canonicalisation (C14N) to - serialize the result of parsing to stdout. - It keeps comments in the result. - - - - @@ -220,51 +180,70 @@ - + - Remove DTD from output. + + Use RelaxNG file named SCHEMA + for validation. + + + + + + Use a W3C XML Schema file + named SCHEMA for validation. + + + + + + + + + Use a Schematron file + named SCHEMA for validation. + + + + + + + + + Determine if the document is a valid instance of the included + Document Type Definition (DTD). + A DTD to be validated against also can be + specified at the command line using the + option. By default, &xmllint; also checks to determine if the + document is well-formed. + + + + + + + + + PARSER OPTIONS + + The following options set the respective parser options. + + + + Fetch external DTD and populate the tree with - inherited attributes. + inherited attributes. Implies . - - - - Output in the given encoding. Note that this works for full document not fragments or result from XPath queries. - - - - - - - - Reformat and reindent the output. The XMLLINT_INDENT - environment variable controls the indentation. The default value is two - spaces " "). - - - Especially in the absence of a DTD, this feature has never worked reliably - and is fundamentally broken. - - - - - - - - Use the HTML parser. - - - @@ -275,7 +254,10 @@ - Fetch an external DTD. + + Fetch an external DTD and external + parameter entities. + @@ -294,7 +276,10 @@ - Drop ignorable blank spaces. + + Drop "ignorable" blank spaces. This option is unreliable + and shouldn't be used. + @@ -337,7 +322,8 @@ Substitute entity values for entity references. By default, &xmllint; - leaves entity references in place. + leaves entity references in place. This enables loading of + external DTDs and entities. @@ -356,16 +342,7 @@ - Do not use the Internet to fetch DTDs or entities. - - - - - - - - - Suppress output. By default, &xmllint; outputs the result tree. + Do not use the Internet to fetch DTDs or entities. Has no effect with libxml2 2.15 or later. @@ -395,17 +372,65 @@ - + + + Enable additional warnings. + + + + + - Define a file path where &xmllint; will save the result of parsing. - Usually the programs build a tree and save it - on stdout, with this option - the result XML instance will be saved onto a file. + Output any parsable portions of an invalid document. + Exact behavior is unspecified. Use of this option + is discouraged. + + + + Do XInclude processing. + + + + + + + + MISCELLANEOUS OPTIONS + + Options that don't fall in another category. + + + + + + + + + Use the SGML catalog(s) from SGML_CATALOG_FILES. + XML catalogs are loaded by default. + + + + + + + + Remove DTD after parsing. + + + + + + + Use the HTML parser. + + + @@ -417,23 +442,6 @@ - - - - Enable additional warnings. - - - - - - - - Value 0 means no formatting, 1 means XML_SAVE_FORMAT - (same as --format), 2 means XML_SAVE_WSNONSIG. - - - - @@ -442,38 +450,12 @@ - - - Output any parsable portions of an invalid document. - - - - - + - Use RelaxNG file named SCHEMA - for validation. - - - - - - - - - Use a W3C XML Schema file - named SCHEMA for validation. - - - - - - - - - Use a Schematron file - named SCHEMA for validation. + Print SAX callbacks for debugging. Can be used + for streaming DTD and Schema validation when used + with . @@ -499,36 +481,102 @@ - - - - - Determine if the document is a valid instance of the included - Document Type Definition (DTD). - A DTD to be validated against also can be - specified at the command line using the - option. By default, &xmllint; also checks to determine if the - document is well-formed. - - - - - Display the version of - libxml - 3 - used. + Display the version of libxml2 used. + + + + + + + + + OUTPUT OPTIONS + + Options controlling output. Except for + these have no effect in SAX or stream mode. + + + + + + + + + Turn on + gzip + 1 + compression of output. - + + + - Do XInclude processing. + + Use the W3C XML Canonicalisation (C14N) to + serialize the result of parsing to stdout. + It keeps comments in the result. + + + + + + + + Output in the given encoding. Note that this works for full document not fragments or result from XPath queries. + + + + + + + + Reformat and reindent the output. The XMLLINT_INDENT + environment variable controls the indentation. The default value is two + spaces " "). + + + Especially in the absence of a DTD, this feature has never worked reliably + and is fundamentally broken. + + + + + + + + + Suppress output. By default, &xmllint; outputs the result tree. + + + + + + + + + Define a file path where &xmllint; will save the result of parsing. + Usually the programs build a tree and save it + on stdout, with this option + the result XML instance will be saved onto a file. + + + + + + + + + Value 0 means no formatting, 1 means XML_SAVE_FORMAT + (same as --format), 2 means XML_SAVE_WSNONSIG. + @@ -684,13 +732,6 @@ - - - - Print SAX callbacks (only for debugging). - - - @@ -1006,22 +1047,9 @@ SEE ALSO - - libxml - 3 - - - More information can be found at - - - - libxml - 3 - web page - - - + More information can be found in the libxml2 repo at +