2.  How to Use xmlformat

To format the file mydoc.xml using the default formatting options, use the following command. (% represents your shell prompt here; do not type it as part of the command.)

% xmlformat mydoc.xml

(xmlformat might be installed as xmlformat.pl or xmlformat.rb, depending on implementation language. In that case, you should invoke it under the appropriate name.)

The built-in formatting options cause each element to begin a new line, with sub-element indentation of one space, and no text normalization. Suppose mydoc.xml looks like this:

<table> <row> <cell> A </cell> <cell> B </cell> </row>
<row> <cell> C </cell> <cell> D </cell> </row> </table>

xmlformat will produce this result by default:

<table>
 <row>
  <cell> A </cell>
  <cell> B </cell>
 </row>
 <row>
  <cell> C </cell>
  <cell> D </cell>
 </row>
</table>

The default style is perhaps suitable for data-oriented XML documents that contain no mixed-content elements. For more control over output, specify a configuration file.

If the formatting options are stored in a file named xf-opts.conf, you can apply them to the document by specifying a --config-file option:

% xmlformat --config-file=xf-opts.conf mydoc.xml

If you do not specify a configuration file using a --config-file (or --f) option, xmlformat uses the following rules to determine what formatting options to use:

Configuration options and configuration file syntax are described in Section 4, “ Using Configuration Files ”.

To see the command-line options that xmlformat supports, invoke it with the --help or --h option:

% xmlformat --help
Usage: xmlformat [options] xml-file

Options:
--help, -h
    Print this message
--backup suffix -b suffix
    Back up the input document, adding suffix to the input
    filename to create the backup filename.
--canonized-output
    Proceed only as far as the document canonization stage,
    printing the result.
--check-parser
    Parse the document into tokens and verify that their
    concatenation is identical to the original input document.
    This option suppresses further document processing.
--config-file file_name, -f file_name
    Specify the configuration filename. If no file is named,
    xmlformat uses the file named by the environment variable
    XMLFORMAT_CONF, if it exists, or ./xmlformat.conf, if it
    exists. Otherwise, xmlformat uses built-in formatting
    options.
--in-place, -i
    Format the document in place, replacing the contents of
    the input file with the reformatted document. (It's a
    good idea to use --backup along with this option.)
--show-config
    Show configuration options after reading configuration
    file. This option suppresses document processing.
--show-unconfigured-elements
    Show elements that are used in the document but for
    which no options were specified in the configuration
    file. This option suppresses document output.
--verbose, -v
    Be verbose about processing stages.
--version, -V
    Show version information and exit.

Warning

Do not use the --in-place or -i reformatting option until you are certain your configuration options are set up the way you want. Unpleasant consequences may occur otherwise. For example, if you have verbatim elements that you have forgotten to declare as verbatim, they will be reformatted and you will have to restore them to their original state later. Use of the --backup or -b option can help you recover from this kind of problem.

xmlformat writes the result to the standard output by default. To perform an "in-place" conversion that writes the reformatted document back to the original file, use the --in-place or -i option. This is useful when you want to format multiple documents with a single command; streaming multiple output documents to the standard output concatenates them, which is likely not what you want.

Because in-place formatting replaces the original document, it's prudent to make a backup of the original using the --backup (or -b) option. This option takes a suffix value to be added to each input filename to produce the backup filename.

To inspect the default (built-in) configuration options, use this command:

% xmlformat --config-file=/dev/null --show-config