110. toggleTextStyle

110. toggleTextStyle
	Chapter 6. Commands written in the Java™ programming language

Parameter syntax:

name [ '[' attr_specs ']' ]?

attr_specs -> attr_spec [ S 'and' S attr_spec ]*

attr_spec -> 'not(' attr_simple_spec ')'

attr_simple_spec -> '@' attr_name [ '=' quoted_attr_value ]?

This command emulates the behavior of the Bold, Italic, Underline, etc, toggles found in the tool bars of almost all word-processors. Such toggles add a given text style to text spans not having this text style and remove a given text style to text spans already having this text style. Hence the name “text style” toggle.

Note that such toggles do not require some text to be explicitly selected. If the caret is in the middle of a word, then the toggle acts on this word. If the caret is before or after a word, the toggle acts on this text location by inserting an empty text span having or on the contrary, not having, the corresponding text style.

This command supports the node selection in addition to the text selection. For example, if you want to apply a “text style” to an element in its entirety, suffice to explicitly select it. This is more handy that selecting all the text this element contains.

name

Name of an element which behaves like a text style. Such elements must have a mixed content and may contain text as well as other text styles in arbitrary order and number of occurrences.

DocBook 4 example, literal text style:

literal

Equivalent DocBook 5 example:

{http://docbook.org/ns/docbook}literal

Notice in the above example that XML names belonging to a namespace are specified using the Clark's notation.

attr_name

An element which behaves like a text style may have at most one required attribute. When this is the case, this attribute must be specified in the parameter of the toggleTextStyle command.

DocBook 4 example, external link text style:

ulink[@url]

Equivalent DocBook 5 example:

{http://docbook.org/ns/docbook}link[@{http://www.w3.org/1999/xlink}href]

quoted_attr_value

In some cases, an element which behaves like a text style has an attribute which specifies a given style. When this is the case, this attribute and its specific value must be specified in the parameter of the toggleTextStyle command.

DocBook 4 example, bold text style:

emphasis[@role='bold']

Equivalent DocBook 5 example:

{http://docbook.org/ns/docbook}emphasis[@role='bold']

This attribute value may contain a variable. Currently the only supported variable is %{url}.

DocBook 4 example, external link text style:

ulink[@url='%{url}']

or equivalently (|fallback_value, where by default fallback_value is "???", is implicit):

ulink[@url='%{url|???}']

The above specification means: convert the selection to an ulink element having an url attribute. If the text contained in the selection can be parsed as an absolute URL (e.g. "https://www.xml.com/") then use this text as the value of the url attribute, otherwise use "???" as the value of the url attribute.

attr_spec and attr_spec ... and attr_spec

Operator and means: this text style corresponds to specified element if this element has attributes matching all attribute specifications.

DITA example 1, external link style:

xref[@href and @scope='external' and @format='html']

DITA example 2, internal link text style:

xref[@href and not(@scope='external')]

not(attr_simple_spec)

Function not() means: this text style does not correspond to specified element if this element has specified attribute (whatever its value; see DocBook example below) or if this element has specified attribute value (see DITA example below).

DocBook example, emphasis text style:

emphasis[not(@role)]

DITA example, internal link text style:

xref[@href and not(@scope='external')]


109. toggleCollapsed		111. undo