2. How to Use xmlformat
Prev |  | Next

## 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:

- If the environment variable `XMLFORMAT_CONF` is defined, xmlformat uses its value as the name of the configuration file.

- Otherwise, if a file named `xmlformat.conf` exists in the current directory, xmlformat uses it as the configuration file.

- Otherwise, xmlformat uses a set of built-in formatting options.

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

Prev |  | Next
1. Introduction | Home | 3. The Document Processing Model