xml: changes requested by marchersimon,

which undo the "the" changes previously made for sbrl.
The `select`, `edit`, and `transform` subcommands are not yet ready.

pages/common/xml-canonic.md

@@ -3,15 +3,15 @@
 > Make XML documents canonical.
 > More information: <http://xmlstar.sourceforge.net/docs.php>.
 
-- Make an XML document canonical, preserving comments (default behavior):
+- Make an XML document canonical, preserving comments:
 
-`xml canonic --with-comments {{path/to/input.xml|URI}} >{{path/to/output.xml}}`
+`xml canonic {{path/to/input.xml|URI}} > {{path/to/output.xml}}`
 
 - Make an XML document canonical, removing comments:
 
-`xml canonic --without-comments {{path/to/input.xml|URI}} >{{path/to/output.xml}}`
+`xml canonic --without-comments {{path/to/input.xml|URI}} > {{path/to/output.xml}}`
 
-- Exclusive XML canonicalization, using an XPATH from a file, preserving comments:
+- Make XML exclusively canonical, using an XPATH from a file, preserving comments:
 
 `xml canonic --exc-with-comments {{path/to/input.xml|URI}} {{path/to/c14n.xpath}}`
 

pages/common/xml-depyx.md

@@ -5,11 +5,11 @@
 
 - Convert a PYX (ESIS - ISO 8879) document to XML format:
 
-`xml depyx {{path/to/input.pyx|URI}} >{{path/to/output.xml}}`
+`xml depyx {{path/to/input.pyx|URI}} > {{path/to/output.xml}}`
 
-- Convert a PYX document from the standard input to XML format:
+- Convert a PYX document from stdin to XML format:
 
-`cat {{path/to/input.pyx}} | xml depyx >{{path/to/output.xml}}`
+`cat {{path/to/input.pyx}} | xml depyx > {{path/to/output.xml}}`
 
 - Display help for the `depyx` subcommand:
 

pages/common/xml-elements.md

@@ -5,21 +5,21 @@
 
 - Extract elements from an XML document (producing XPATH expressions):
 
-`xml elements {{path/to/input.xml|URI}} >{{path/to/elements}}`
+`xml elements {{path/to/input.xml|URI}} > {{path/to/elements}}`
 
-- Extract elements and attributes from an XML document:
+- Extract elements and their attributes from an XML document:
 
-`xml elements -a {{path/to/input.xml|URI}} >{{path/to/elements}}`
+`xml elements -a {{path/to/input.xml|URI}} > {{path/to/elements}}`
 
-- Extract elements, attributes, and their values from an XML doc:
+- Extract elements and their attributes and values from an XML document:
 
-`xml elements -v {{path/to/input.xml|URI}} >{{path/to/elements}}`
+`xml elements -v {{path/to/input.xml|URI}} > {{path/to/elements}}`
 
-- Print sorted unique elements from an XML document (to see structure):
+- Print sorted unique elements from an XML document to see its structure:
 
 `xml elements -u {{path/to/input.xml|URI}}`
 
-- Print sorted unique elements up to a depth of 3:
+- Print sorted unique elements from an XML document up to a depth of 3:
 
 `xml elements -d{{3}} {{path/to/input.xml|URI}}`
 

pages/common/xml-escape.md

@@ -1,13 +1,13 @@
 # xml escape
 
-> Escape special XML characters.
+> Escape special XML characters, e.g. `<a1>` -> `&lt;a1&gt;`.
 > More information: <http://xmlstar.sourceforge.net/doc/xmlstarlet.pdf>.
 
 - Escape special XML characters in a string:
 
 `xml escape "{{<a1>}}"`
 
-- Escape special XML characters from the standard input:
+- Escape special XML characters from stdin:
 
 `echo  "{{<a1>}}" | xml escape`
 

pages/common/xml-format.md

@@ -5,23 +5,23 @@
 
 - Format an XML document, indenting with tabs:
 
-`xml format --indent-tab {{path/to/input.xml|URI}} >{{path/to/output.xml}}`
+`xml format --indent-tab {{path/to/input.xml|URI}} > {{path/to/output.xml}}`
 
 - Format an HTML document, indenting with 4 spaces:
 
-`xml format --html --indent-spaces {{4}} {{path/to/input.html|URI}} >{{path/to/output.html}}`
+`xml format --html --indent-spaces {{4}} {{path/to/input.html|URI}} > {{path/to/output.html}}`
 
 - Recover parsable parts of a malformed XML document, without indenting:
 
-`xml format --recover --noindent {{path/to/malformed.xml|URI}} >{{path/to/recovered.xml}}`
+`xml format --recover --noindent {{path/to/malformed.xml|URI}} > {{path/to/recovered.xml}}`
 
-- Format an XML document from the standard input, removing the DOCTYPE declaration:
+- Format an XML document from stdin, removing the DOCTYPE declaration:
 
-`cat {{path\to\input.xml}} | xml format --dropdtd >{{path/to/output.xml}}`
+`cat {{path\to\input.xml}} | xml format --dropdtd > {{path/to/output.xml}}`
 
 - Format an XML document, omitting the XML declaration:
 
-`xml format --omit-decl {{path\to\input.xml|URI}} >{{path/to/output.xml}}`
+`xml format --omit-decl {{path\to\input.xml|URI}} > {{path/to/output.xml}}`
 
 - Display help for the `format` subcommand:
 

pages/common/xml-list.md

@@ -1,15 +1,15 @@
 # xml list
 
-> List a directory's contents in XML format.
+> List a directory's contents (like 'ls') in XML format.
 > More information: <http://xmlstar.sourceforge.net/docs.php>.
 
 - List the current directory's contents to an XML document:
 
-`xml list >{{path/to/dir_list.xml}}`
+`xml list > {{path/to/dir_list.xml}}`
 
 - List the specified directory's contents to an XML document:
 
-`xml list {{path/to/directory}} >{{path/to/dir_list.xml}}`
+`xml list {{path/to/directory}} > {{path/to/dir_list.xml}}`
 
 - Display help for the `list` subcommand:
 

pages/common/xml-pyx.md

@@ -5,11 +5,11 @@
 
 - Convert an XML document to PYX format:
 
-`xml pyx {{path/to/input.xml|URI}} >{{path/to/output.pyx}}`
+`xml pyx {{path/to/input.xml|URI}} > {{path/to/output.pyx}}`
 
-- Convert an XML document from the standard input to PYX format:
+- Convert an XML document from stdin to PYX format:
 
-`cat {{path/to/input.xml}} | xml pyx >{{path/to/output.pyx}}`
+`cat {{path/to/input.xml}} | xml pyx > {{path/to/output.pyx}}`
 
 - Display help for the `pyx` subcommand:
 

pages/common/xml-unescape.md

@@ -1,13 +1,13 @@
 # xml unescape
 
-> Unescape special XML characters.
+> Unescape special XML characters, e.g. `&lt;a1&gt;` -> `<a1>`.
 > More information: <http://xmlstar.sourceforge.net/docs.php>.
 
 - Unescape special XML characters from a string:
 
 `xml unescape "{{&lt;a1&gt;}}"`
 
-- Unescape special XML characters from the standard input:
+- Unescape special XML characters from stdin:
 
 `echo  "{{&lt;a1&gt;}}" | xml unescape`
 

pages/common/xml-validate.md

@@ -3,9 +3,9 @@
 > Validate XML documents.
 > More information: <http://xmlstar.sourceforge.net/docs.php>.
 
-- Validate XML document(s) for well-formedness only (default behavior):
+- Validate XML document(s) for well-formedness only:
 
-`xml validate --well-formed {{path/to/input1.xml|URI}} {{input2.xml ...}}`
+`xml validate {{path/to/input1.xml|URI}} {{input2.xml ...}}`
 
 - Validate XML document(s) against a Document Type Definition (DTD):
 

pages/common/xml.md

@@ -1,20 +1,21 @@
 # xml
 
 > XMLStarlet Toolkit: Query, edit, check, convert and transform XML documents.
+> This command also has documentation about its subcommands, e.g. `xml validate`.
 > Subcommands: `canonic`, `edit`, `elements`, `escape`, `unescape`, `format`, `list`, `pyx`, `depyx`, `select`, `transform`, or `validate`.
 > More information: <http://xmlstar.sourceforge.net/docs.php>.
 
-- Execute a subcommand with input from a file or URI and using standard output:
+- Execute a subcommand with input from a file or URI, printing to stdout:
 
 `xml {{subcommand}} {{options}} {{path/to/input.xml|URI}}`
 
-- Execute a subcommand using the standard input and standard output:
+- Execute a subcommand using stdin and stdout:
 
 `xml {{subcommand}} {{options}}`
 
 - Execute a subcommand with input from a file or URI and output to a file:
 
-`xml {{subcommand}} {{options}} {{path/to/input.xml|URI}} >{{path/to/output}}`
+`xml {{subcommand}} {{options}} {{path/to/input.xml|URI}} > {{path/to/output}}`
 
 - Display help for a subcommand:
 
@@ -24,6 +25,6 @@
 
 `xml --help`
 
-- Display version:
+- Display the version of the XMLStarlet Toolkit:
 
 `xml --version`