Formatting and indenting documents (pretty print)

In structured markup languages, the whitespace between elements that is created by use of the Space bar, Tab or multiple line breaks insertion from use of the Enter, is not recognized by the parsing tools. Often this means that when structured markup documents are opened, they are arranged as one long, unbroken line, what seems to be a single paragraph.

While this is perfectly acceptable practice, it makes editing difficult and increases the likelihood of errors being introduced. It also makes the identification of exact error positions difficult. Formatting and Indenting, also called Pretty Print, enables such documents to be neatly arranged, in a manner that is consistent and promotes easier reading on screen and in print output.

Pretty print is in no way associated with the layout or formatting that will be used in the transformed document. This layout and formatting is supplied by the XSL style sheet specified at time of transformation.

 

Procedure 4.9. To format and indent a document:

  1. Open or focus on the document that is to be formatted and indented.

  2. Select menu DocumentXML DocumentFormat and Indent (Ctrl+Shift+P) or click the toolbar button Format and indent . While in progress the Status Panel will indicate Pretty print in progress. On completion, this will change to Pretty print successful and the document will be arranged.

[Note]Note

Pretty Print can format empty elements as an auto-closing markup tag (ex. <a/>) or as a regular tag (ex. <a></a> ). It can preserve the order or attributes or order them alphabetically. Also the user may specify a list of elements for which white spaces are preserved exactly as before Pretty print and a one with elements for which white space is stripped. These can be configured from OptionsPreferences+Editor / Format.

Pretty Print requires that the structured document is well formed. If the document is not well formed an error message is displayed. The message will usually indicate that a problem has been found in the form and will hint to the problem type. It will not highlight the general position of the error, to do this run the well formed action by selecting DocumentCheck document form (Ctrl+Shift+W).

To change the formatting of just one XML element see the action Pretty print element . To change the indenting of the current selected text see the action Indent selection .

For user preferences related to formatting and indenting like Detect indent on open and Indent on paste see the corresponding Preferences panel.

XML elements can be excepted from the reformatting performed by the pretty-print operation by including them in the Preserve space elements (XPath) list. That means that when the Format and Indent (pretty-print) action encounters in the document an element with the name contained in this list the whitespace is preserved inside that element. This is useful when most of the elements must be reformatted with the exception of a few ones which are listed here.

For the situation when whitespace should be preserved in most elements with the exception of a few elements, the names of these elements must be added to the Strip space elements (XPath) list.

In addition to simple element names both the Preserve space elements (XPath) list and the Strip space elements (XPath) one accept a restricted set of XPath expressions for covering a pattern of XML elements with only one expression. The allowed types of expressions are:

//xs:documentation
the XPath descendant axis can be used only at the beginning of the expression; the namespace prefix can be attached to any namespace, no namespace binding check is performed when aplying the pretty-print operation
/chapter/abstract/title
note the use of the XPath child axis
//section/title
the descendant axis can be followed by the child axis

The value of an xml:space attribute present in the XML document on which the pretty-print operation is applied always takes precedence over the Preserve space elements (XPath) and the Strip space elements (XPath) lists.