Filenames

Use the file element to mark up the name of a file or directory. You may also use it to mark up collections or portions of filenames, such as search paths and file extensions.

Notes

The file element can contain a mixture of text and any general inline elements.
The file element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The file element can link to other pages or documents. See Ubiquitous Linking for more information.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The file element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use file to specify a filename:

XML catalogs are stored in <file>/etc/xml/catalog</file>.

XML catalogs are stored in /etc/xml/catalog.

Use file to specify a path:

<sys>$XDG_DATA_DIRS</sys> defaults to <file>/usr/local/share:/usr/share</file>.

$XDG_DATA_DIRS defaults to /usr/local/share:/usr/share.

Processing Expectations

Filenames should be displayed in a fixed-width or wide font. Fixed-width fonts tend to have more distinction between visually similar characters. This is particularly important in filenames, since letters often appear without the context of a known word that helps make them discernible in normal prose.

Comparison to Other Formats

The file element is similar to the filename element in DocBook.

The file element is similar to the filepath element in DITA.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the file element. The namespace declarations for this definition are on the page Pages.

mal_inline_file = element file {
  mal_inline_file_attr,
  mal_inline_file_inline
}
mal_inline_file_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_file_inline = mal_inline