Inline markup

Last Updated : Apr 08, 2024 |

Elements that can be intermixed with text are called inline elements; text of this sort is said to contain inline markup.

Utility

inline markup, such as uicontrol or wintitle, identifies low-level types of information. Tagging information in this way provides production software cues that it needs to apply special formatting, and it identifies information type for users of the raw files such as translators or technical writers. While this information is quite useful, providing too much such information, especially in contexts where identifying the low-level information types does is not useful.

When not to use inline markup

In some contexts it does not make sense to tag everything that you can with inline markup. Use the semantics of the context to determine whether to apply tagging. The following table provides some examples:

Case

Wrong

Right

1

<userinput><option>132</option></userinput>

<userinput>132</userinput>

2

<userinput><cmdname>cd</cmdname> <filepath>/usr/bin</filepath></userinput>

<userinput>cd /usr/bin</userinput>

3

<title>How to use the <cmdname>grep</cmdname> command</title>

<title>How to use the grep command</title>

Case 1The semantics of userinput override the semantics of option. The fact that 132 is an option is irrelevant to the purpose of the instruction; namely, that the user is to type 132 into some field.

Case 2The semantics of userinput override the semantics of cmdname and filepath. The fact that cd is the name of a command and that /usr/bin is a filepath doesn't matter because all we want to do is to tell the user to type cd /usr/bin into some field.

Case 3A purpose of a title is to help readers find content. Involved semantic tagging of title content does nothing to help readers find content faster. inline tags that make sense within title include sup for superscript, sub for subscript, or inline elements that have content provided through conref.

White-space

Placing space characters in the correct place can help you avoid formatting errors in the output.

Case

Wrong

Right

1

See<cite> Using Avaya's Wonderful Products, 555–555–555 </cite>for more information

See <cite>Using Avaya's Wonderful Products, 555–555–555</cite> for more information

2

Click<uicontrol>OK</uicontrol>to continue.

Click <uicontrol>OK</uicontrol> to continue.

3

<indexterm> Some index entry <indexterm>some sub-entry </indexterm> </indexterm>

<indexterm>Some index entry<indexterm>some sub-entry</indexterm></indexterm>

Case 1The space characters should go outside of the cite open tag (<cite>) and the cite close tag (</cite>).

Case 2Space characters are missing before the uicontrol start tag and after the uicontrol close tag. The output would look like this: ClickOKto continue.

Case 3This example has several problems. It was fixed by 1) removing the space after the first indexterm start tag. 2) removing the space immediately before the second indexterm start tag, 3) removing the spaces before each indexterm close tag.