Draft

1.2 (2019-02-09)

System Items

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the sys element to mark up any type of system item that isn't covered by other elements such as file, cmd, or code.

Notes

  • The sys element can contain a mixture of text and any general inline elements.

  • The sys element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.

  • The sys 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 sys element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Use sys to mark up a domain name:

The Linux kernel is hosted on <sys>git.kernel.org</sys>.

The Linux kernel is hosted on git.kernel.org.

Processing Expectations

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

Comparison to Other Formats

The sys element is similar to the systemitem element in DocBook. DocBook has gained numerous elements which were once marked using the class attribute on the systemitem element. Since Mallard does not provide the level of markup specificity that DocBook does, the sys element should be used in place of these and various other elements.

The sys element is similar to the keyword element in DITA. The keyword element serves as a base element for many specializations, including for the cmdname element, which is similar to the cmd element in Mallard. Unless a more specific Mallard element is available, the sys element should be used in place of specializations of the keyword element.

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 sys element. The namespace declarations for this definition are on the page Pages.

mal_inline_sys = element sys {
  mal_inline_sys_attr,
  mal_inline_sys_inline
}
mal_inline_sys_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_sys_inline = mal_inline
© 2008-2011 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard