It can apply raw text attributes in addition to styles.
It can apply both raw text attributes and styles through more than just the Start Tag and End Tag. It is this extension of where the attributes and styles are applied that gives the function its name.
It allows attributes and styles to be applied from Start Tag up to End Tag without including End Tag.
The ability to apply raw text attributes is a very important designation. <&extend:()> and its relative <&bygraph:()> are the only custom functions that can apply raw text attributes. If you need to change the paragraph alignment on a specific paragraph but you don’t have a Paragraph Style defined to do this, <&extend:()> and <&bygraph:()> are the only functions that can fulfil your need.
<&extend:()> can still be very useful even when just applying styles as specified in Paragraph and Character Style fields of the rule. If specified, the Paragraph and Character Style will be used by <&extend:()> to determine which styles to apply. All other text attributes come from the function parameters p2 through pn.
extend’s 5 modes
The function has 5 modes enumerated 0, 1, 2, 3, and 4. The modes are specified by the first function parameter p1. If that parameter isn’t specified, then mode 0 is chosen as the default.
<&extend:(0)> and <&extend:(1)>
In modes 0 and 1 the function determines the text attributes of the text containing the Start Tag. It then finds other text with these same attributes and applies the indicated styles or attributes.
While both modes 0 and 1 only work with text that matches the style and attributes of the text where the tag was found. Mode 0 only looks down. If it finds another tag, in text with a different style, it will then start looking down from that point trying to find other matches for that style. Mode 1, however is a ‘do it all at once’ function. The first time it finds the tag, it will then record the tag’s style and then apply the new styles and attributes to all text both before and after the tag to any text whose styles and attributes matches that of the tag.
Because mode 1 processes the entire contents of the active text frame at one time, mode 1 can be considerably faster to run than mode 0 which investigates each and every text style range (each different blob of text with a different set of text attributes from the prior blob text). The difference is moot at the beginning of processing because there might be only 1 text style range.
Currently in Modes 0 & 1 the function only matches text that matches the Paragraph Style, Character Style, font and style, pointSize, paragraph alignment, and leading values of the specified Start Tag. Please file a support ticket at support.townnews.com if you need additional access.
<&extend:(2)> and <&extend:(3)>
Modes 2 and 3 are very similar to each other, but quite different from modes 0 and 1. Modes 2 and 3 do not look at the existing formats of the text, instead they behave more like the normal functionality of the Start Tag, Start Tag Replace, End Tag, and End Tag Replace fields in the Translate Ruleset.
However, mode 2 doesn’t apply any text attributes or styles to the End Tag. The applied text attributes stop before End Tag. This makes it ideal for extending a format until another tag is reached. And mode 2 is very useful when you don’t want to override similar text elsewhere within the story you are translating. Mode 2 does not swap End Tag with End Tag Replacement, but Mode 3 does.
Mode 3 is very similar to the normal behavior of the application except <&extend:(3)> provides a method to use text attributes other than predefined Styles.
<&extend:(4)> and <&bygraph:()>
Mode 4, the 5th <&extend:()> mode, works on a paragraph by paragraph basis rather than by text style ranges or pure tag to tag translations. This paragraph by paragraph checking makes it particularly well suited to styling sports agate which contains many single paragraph tags.
Mode 4 can also be invoked with <&bygraph:()>. <&bygraph:()> has the ability to use and/or swap a different closing tag but it is not greedy in its application of text attributes and styles the way that <&extend:(4)> is.
End Tag and End Tag Replacement
With <&extend:()> modes 0, 1, & 2 the only purpose of the End Tag is to cause <&extend:()> to look beyond the first occurrence of the Start Tag until occurrences have been found.
However, in these first three modes, the End Tag is not replaced with the End Tag Replacement.
The remaining modes 3 & 4 will swap End Tag for End Tag Replacement.
Note: Modes 3 & 4 of <&extend:()> are the only custom functions that perform End Tag to End Tag Replacement.
Text Attributes. See separate documentation page on how to apply the text attributes.
extend Modes
There are 5 modes for the <&extend:()> function. The mode is specified as the first parameter. If no mode is specified then mode 0 (zero) is assumed. The <&bygraph:()> function is essentially the same as <&extend:(4)>.
Value
Description
0
Locate all text with the styles and text attributes matching the Start Tag and apply the new styles and text attributes from the tag downward in the active text frame.
1
Locate all text with the styles and text attributes matching the Start Tag but apply the new styles and text attributes both above and below in the active text frame.
2
In this mode, the function does not worry about the existing styles and text attributes of the Start Tag, but it applies the new styles and text attributes up to, but NOT through the End Tag in the active text frame.
3
As mode 2 above, but apply the new styles and text attributes through the End Tag. Very similar to the normal functions of translator, except that text attributes can be applied in addition to the Paragraph Style and Character Style fields of the rule.
4
Limits all activity to a paragraph by paragraph basis. The active frame is searched from the bottom paragraph to the top of the story.
Specifying text attributes for <&extend:()>
For details on specifying formats for <&extend:()>, see “Specifying Text Attributes for <&extend:()> and <&bygraph:()>”.
Trivia
<&extend:()> and <&bygraph:()> have the distinction of having the option to use more parameters than any other custom function, but unlike most other parameter-heavy functions, <&extend:()> is quite useful without any supplied parameters.
<&extend:(3)> and <&extend:(4)> are the only stand-alone functions that will honor the purpose of Start Tag Replacement and End Tag Replacement.
