Laying Out Descriptions

How a description layout is interpreted by processing tools (such as the Report Tool, e.g. when generating an HTML report) is affected by whitespace pre-processing rules and by MediaWiki- like markup present within the description element.

6.9.3.1 Whitespace Pre-processing

A description’s leading whitespace (up to and including the first line break) and trailing whitespace (including line breaks) is not significant. Processing tools need to discard non- significant whitespace. This will allow for a variety of layout styles while still retaining predictable behavior. Pre-processing rules are detailed in Section I.2.1.

The following example illustrates several single-line description fragments that would be rendered equivalent by the whitespace pre-processing rules. The first style shown is preferred when writing XML.

<description>The top-level object for a Device</description> <description> The top-level object for a Device </description> <description>The top-level object for a Device

</description>

<description>The top-level object for a Device </description>

Non-significant whitespace also includes the longest common whitespace prefix that occurs at the start of every line. For example, if every line in a description is indented by three whitespace characters then these characters are not part of the description layout. However, if one of these lines had no whitespace indent, then the three whitespace characters at the beginning of each of the other lines would be significant.

Note that this common-prefix calculation is based on the number of whitespace characters, not the type of whitespace character (i.e. the space character and the tab character are not differentiated). For this reason, a description should not contain tab characters; otherwise the rendered layout will not be consistent.

The following example illustrates some additional single-line description fragments that would be rendered equivalent by the whitespace pre-processing rules. Each of the styles shown is reasonable, but the first one might be slightly preferred when writing XML (especially for short descriptions).

<description>The top-level object for a Device</description> <description>

The top-level object for a Device </description>

<description>

The top-level object for a Device </description>

The following example illustrates some multi-line description fragments that would be rendered equivalent by the whitespace pre-processing rules. The first or second style shown is preferred when writing XML.

<description>Numeric value indicating the supported revision for UPnP IGD. A value of 0 indicates no support.</description>

<description>

Numeric value indicating the supported revision for UPnP IGD. A value of 0 indicates no support.

</description> <description>

Numeric value indicating the supported revision for UPnP IGD. A value of 0 indicates no support.

</description> <description>

Numeric value indicating the supported revision for UPnP IGD. A value of 0 indicates no support.

</description>

<description>Numeric value indicating the supported revision for UPnP IGD. A value of 0 indicates no support.

</description>

6.9.3.2 Markup

A description can contain a limited amount of markup that is similar in fashion to MediaWiki markup. Processing tools are expected to interpret this markup when processing descriptions (e.g. the Report Tool interprets the markup when generating its HTML Data Model reports).

There are two types of markup available: formatting markup (I.2.2) which indicates how the marked text should be formatted, and Template references (I.2.3) which are meant to be replaced with template-dependent text.

Formatting markup is indicated in a description using certain reserved character sequences. For example, two apostrophes on each side of some text indicate that the contained text is to be emphasized in italics (e.g. ''This is to be italicized''). Possible formatting includes: italics, bold, bold italics, bulleted list, numbered list, indented list, verbatim. See Section I.2.2 for a full list of the standard markup and how it is invoked.

A Template reference is indicated in a description as text enclosed in double curly braces ({}). The template text consists of a template name that can be followed by arguments separated by vertical pipe (|) characters. For example, {{bibref|TR-106a6|A.2.2.4}} is a bibref

Template, and would be replaced with something like [Section A.2.2.4/TR-106a6]. See Section

I.2.3 for a full list of the standard Templates and how they are invoked.

The following example illustrates a description with four lines containing various markup items. A processing tool should interpret the markup as follows: {{bibref|RFC3986}} is a Template reference to an item defined in the bibliography; the line starting with a colon indicates an indented line; the ''host'' text is to be italicized; the URL literal is to be a hyperlink; and each line is a separate paragraph. Also note that whitespace pre-processing is applied before any markup is interpreted.

<description>

HTTP URL, as defined in {{bibref|RFC3986}}. In the form:

: http://host:port/path

The ''host'' portion of the URL MAY be the IP address for the management interface of the CPE in lieu of a host name.

</description>

The resulting layout will look something like the following:

HTTP URL, as defined in [RFC3986]. In the form:

http://host:port/path

The host portion of the URL MAY be the IP address for the management interface of the CPE in lieu of a host name.