4. indent options

Usage:

xmltool indent indent_options validate_options common_options [ xml_file ]*

Save, possibly indenting and/or flattening[1], specified XML files.

[Important]Do not forget to use option -s when needed too

Unless the document to be indented contains a specification of which schema to use (e.g. <!DOCTYPE>, xsi:noNamespaceSchemaLocation, xsi:schemaLocation or <?xml-model?>), using the -s option to explicitly specify this schema is required. See example below.

Failing to do so will cause xmltool to incorrectly indent the document after reporting the following warning: WARNING: Cannot determine which schema to use for validating "DOCUMENT_PATH".

-o save_file_or_dir

Specifies where to save all specified documents.

If a single document is to be saved, save_file_or_dir may specify a file or an existing directory.

If multiple documents are to be saved, save_file_or_dir must specify a directory. Such directory is automatically created if it does not already exist.

Default: reuse the original filename of each specified document after renaming this document using a ".BAK" filename.

-flat

Do not preserve inclusions. Instead ``flatten'' the document.

This option automatically generates xml:base attribute when needed to. Note that xml:base attributes are added even when this attribute is not allowed by the schema of the document being indented.

Default: preserve inclusions.

-indent integer

Specifies the number of space characters used to indent a child element relatively to its parent element.

  • A positive or null value means: indent always.

  • Value "-1" means: never indent.

  • Any other negative value means indent, but only if the document to be saved has an actual document type. In such case, the number of space characters is: (-2 - integer).

Default: -4.

-maxlinelength positive_integer

Specifies the maximum line length for elements containing text interspersed with child elements.

Default: 78.

-noopenlines

Do not add open lines between the child elements of elements having an ``element-only'' content model.

Default: add open lines.

-xhtml

Favor the interoperability with HTML as recommended in the XHTML spec.

In practice, if this option has been specified:

  • Empty elements having a non empty content are saved as "<tag></tag>".

  • Empty elements having an empty content are saved as "<tag />" (with a space after the tag).

Note that specifying this option for document types other than XHTML does not really make sense

Default: do not favor the interoperability with HTML.

-nocharentities

Do not save characters not supported by the encoding as entity references. Instead, save them as numeric references.

Default: when possible and when needed to, save characters as entity references.

-specialchars list_of_chars_or_char_ranges

Always save specified characters as entity references.

Example: -specialchars "reg 174 0x00ae 0256 pound:yen 163:165 0xA3:0xA5 0243:0245".

No default.

-cdatasections list_of_simple_XPaths

Save the textual contents of specified elements as CDATA sections.

XHTML example: -cdatasections "htm:script htm:style".

No default.

-prefix prefix namespace

Associates a prefix to a namespace.

Multiple "-prefix" options are allowed.

This may be needed to allow parsing the XPaths argument of the above "-cdatasections" option. Options "-prefix" must precede the "-cdatasections" option.

XHTML example: -prefix htm http://www.w3.org/1999/xhtml.

No default.

-nooriginalprefixes

Do not use the namespace prefixes originally specified in the document. Instead, generate prefixes.

Default: Reuse the original prefixes as much as possible.

-nodefaultnamespace

Do not use the default namespace originally specified in the document.

Default: Reuse the default namespace if any.

-xmlversion 1.0|1.1|original

Specifies the "version" pseudo-attribute of the XML declaration. "original" means: reuse the XML version originally specified in the document.

Default: original.

-encoding java_supported_encoding|original

Specifies which encoding to use when saving a document. "original" means: reuse the encoding originally specified in the "encoding" pseudo-attribute of the XML declaration of the document.

Default: original.

-standalone yes|no|original

Specifies the "standalone" pseudo-attribute of the XML declaration. "original" means: reuse the "standalone" pseudo-attribute originally specified in the document.

No default: do not add a "standalone" pseudo-attribute to the XML declaration.

-noinvalid

Do not save specified documents if any of them is found to have validity errors (even harmless cross-reference errors).

Default: save documents even if some of them are found to be invalid.

-script URL_or_filename

Run specified .xed script in order to modify the document before saving it to disk. Note that it's possible to specify the -script option several times in order to use several scripts in turn.

Example: Indent docbook-table.xml using the default settings. The original docbook-table.xml is saved to docbook-table.xml.BAK.

/opt/xxe/demo$ xmltool indent docbook-table.xml
/opt/xxe/demo$ ls docbook-table.xml*
docbook-table.xml
docbook-table.xml.BAK

Example: Indent docbook-table.xml using specified settings. Save indented file to out.xml.

/opt/xxe/demo$ xmltool indent -indent 1 -noopenlines -nolegacy -o out.xml docbook-table.xml

Example: Indent docbook5-mathml.xml, a DocBook 5.0 document conforming to RELAX NG schema XXE_INSTALL_DIR/addon/config/docbook5/rng/V5.0/docbook.rng, using specified settings. Save indented file to out.xml.

/opt/xxe/demo$ xmltool indent \
  -s /opt/xxe/addon/config/docbook5/rng/V5.0/docbook.rng \
  -indent 2 -maxlinelength 78 \
  -o out.xml docbook5-mathml.xml

Example: Force the indentation of schema-less file xhtml_strict.xxe.

/opt/xxe/addon/config/xhtml$ xmltool indent -indent 2 -o indented.xxe xhtml_strict.xxe 
WARNING: Cannot determine which schema to use for validating "xhtml_strict.xxe".

Example: Indent all .xhtml files contained in current directory. Create save files in directory /tmp/out/.

/opt/xxe/demo$ xmltool indent -v -encoding Windows-1252 -o /tmp/out *.xhtml

Example: Transclude all XInclude elements contained docbook-modular-book.xml (-f is needed otherwise out.xml would contain a number of duplicate ID errors).

/opt/xxe/demo$ xmltool indent -xi -f -flat -o out.xml docbook-modular-book.xml

Example: Modify doc.xml using edit.xed before saving it, indented, to /tmp/out.xml.

/opt/xxe/demo$ xmltool indent -script edit.xed -o /tmp/out.xml doc.xml


[1] That is, transclude references.