Comments

Comments are useful to remember the original situation that made the use of a SARA necessary, and any assumption made about font and font size, as well as links to online resources, such a in the example below:

Comments can be used to explain the purpose of the regular expression (something that is not always obvious at first glance) and to include a link to the saved online version of that regular expression, as well as the reason for the repeat values list (if any).

Textual Value

Below the Comments field are 2 read-only fields which show a textual representation of the sara as it will be sent to QuarkXPress or InDesign.

If you place your cursor over either of these fields, a hint will appear if the text is too long to be fully displayed in the control.

Find and Change

Text, with or without attributes, to be searched for and used as replacement.

Regular Expressions

The Find field can contain regular expressions and the Change field can contain capture groups from the Find field's regular expression.

Partial Replacement

Additionally, when using QuarkXPress 2018-2025 or InDesign, you can specify that the replacement should only affect one of the capture groups, rather than the entire found text, using the syntax @gX: where X refers to the capture groups 1-9, at the beginning of the replacement string.

The advantage of the use of replacements specific to a capture group, is that it allows to look for things that are not possible using look-behind syntax, such as searching for 11 or more characters, as in the example above, while only replacing the text of a capture group (23, in the above example). This option is invaluable if the formatting (font, color, size, ...) of the 11 characters before the found 23 varies and/or is different from the formatting of the text to be replaced, namely "23" in the example above.

Repeated List of Values

In addition, if you have the need to use the same Sara but for a series of different find and/or change texts, then you can use repeated Sara markers to have the current Sara repeated for as many times as there are entries in the Repeat List, with the repeat marker(s) being replaced each time.

In the above example, instead of specifying that we want to search for Anzac Day followed by a parenthesis containing uppercase letters and/or * and/or -, we specify that we want to look for some text (represented by the <1> repeat marker) whose value will come from the repeat list, such as the one in the example to the right.

In the above example there is only one repeat marker, <1>, but you can have as many as you wish, <2>, <3>, <4>, ... In such cases, each line should contain the values for all these markers separated by a caret sign ^.

You need to ensure that all values for the same repetition are on the same line and, therefore, if you wish the values to be multiline and contain soft or hard returns, these must be replaced by the special character markers &s and &c respectively.

Page Range

Located at the bottom right, the Page Selection section allows you to specify, for each individual Sara in the list, the range of pages to which this particular Sara applies.

The appearance of the page range editor differs depending on the use made of the SaraSet; whether it applies to a diarygridline, or it applies to the entire output file or if the Sara is used in standalone mode. The page range can be defined in terms of the pages of the GridTemplate or the pages of the output file.

If your script contains page deletion, using delete page zap tokens, for example, then the page numbers that you select in the page selection field, should be based on page numbers before any pages are deleted. During diary generation, the range of pages of the page selection field will be updated, automatically, in memory, to take into account the pages that are to be deleted

Because Saras belong to SaraSets which can either be applied to DiaryGridLines or output files, internally, Q++Studio saves both types of page range information, and displays the appropriate one depending on the context

Advanced Options

A set of advanced search and replace options which let you narrow down the search based on the position of the text or the textbox in which it is, and expand the replacement by acting on attributes of the paragraph and/or textbox containing the found text..

Text

Depending on the context, this is either the text that the Sara searches for, or the text it uses to replace found text. Note that the search and replace text can include regular expressions.

Font

The name of a font.

Size

The font size. Allowed values range from 2 to 512.

Style

All the possible attributes which can modify either the Find or Change text.

H.Scale

V.Scale

Represent horizontal and vertical scale; how "squished" or "squashed" each letter is. Their values are expressed in percentage and are limited to the range of 25 to 300 for QuarkXPress and 1 to 1000 for InDesign.

Kern

Relates to the separation between pair of characters. Zero kerning means that 2 characters are spaced by the normal amount as defined by the current font. Negative kerning means letters are brought closer together, positive kerning means they are further apart. The allowed range is –326 to +326 for QuarkXPress and -1000 to +10000 for InDesign.

Note that selecting a value for kerning is equivalent to specifying the tracking in the InDesign user interface.

Track

Similar to kerning, but applies to an entire font rather than to pairs of letters. Tracking values are limited to the range of –326 to +326 for QuarkXPress and -1000 to +10000 for InDesign.

Baseline Shift

Determines by how much the baseline of each character is moved up or down from the norm. The baseline is the "bottom" of any letter that has no "tail" (such as "a,b,c" as opposed to letters that have a tail such as "p,j,y,g"). Baseline shift is measured in points, and is limited to the range –24 to +24 (+/- 2 picas) in older versions of QuarkXPress, and -27 to +27 since QuarkXPress 2015. The allowed range for InDesign is -5000 to +5000.

Shade

Determines the intensity with which the current character's color will be displayed. It is measured in percentage and ranges from 0.01 to 100.

Opacity

Determines the opacity with which the current character's color will be displayed. It is measured in percentage and ranges from 0.01 to 100. Not available when using InDesign.

Skew

Adds skew to the selected text. Not available when using QuarkXPress.

Leading

Adds text leading to the selected text. Not available when using QuarkXPress.

Text Background Shading

Text Background Shading is similar to the effect obtained using the rule above/rule below paragraph attributes but have the added advantage that this is a text property meaning that this background shade can be applied to dis-contiguous text ranges, and even with different attributes for different text on the same line.

Text background shading requires QuarkXPress 2017-2025 and is a paragraph attribute in InDesign, though character-wise shading is possible in InDesign, using underline options.

Text Framing

Text Framing is a text property which allows framing to be applied to dis-contiguous text ranges, while remaining a single frame for the full extent of the text that has the same frame attributes.

Text framing requires QuarkXPress 2017-2025 and is a paragraph attribute in InDesign.

Text Stroking

Text Stroking is similar to the Outline face attribute of QuarkXPress, but it has the advantage that the color, shade, thickness and opacity of the outline can be controlled and, additionally, by setting the option NoFill to false, then the inside remains, allowing for the creating of 2-color text (as the result of stroking remains text and can be treated as text, not as vector shapes).

Text stroking requires QuarkXPress 2017-2025 or InDesign.

Color

The Color style attribute lets you specify to color of the text to find, or to change to. The colors available come either from a list of all the colors from all the scanned templates (if applying Saras to an entire output file), or from the colors defined and used in the current GridTemplate (if applying the Sara to a DiaryGridLine).

Advanced Search Options

The Advanced Search Options allows you to specify, for each individual SARA, if it should only be performed on textboxes that have text overflow (or do not), and if they should be performed after the Boxfit or Boxgrow tokens (by default, SARAs are performed before Boxfit/Boxgrow tokens).

Advanced Search Options require QuarkXPress 2016-2025 or InDesign 2020-2025.

Multiline Text

The multi-line text option allows you to search for text that has broken into two or more lines (or text that has not).

In the example above right, we wish to locate individual "day lines" that are too long, and apply a further SARA to them, but only those "day lines" that span more than 1 line (to do this we use a regular expression to locate individual line, from return to return, before using the multi-line text option to determine if that "text" line is on one or more "visual" lines).

When Using QuarkXPress

One important remark about the multi-line text option, QuarkXPress determines that text is over more than one line by using its LOS (Lines On Screen) structures which look at the displayed lines. So any text that is not visible, will be ignored, as is the case in the example below left, where the textbox is too small to display the 2-line text we are searching for. The solution is to extend the textbox as shown below right, so that the searched text over multiple lines is visible.

Include/Exclude Matches

The Include/Exclude Matches setting, lets you specify, for each individual SARA, whether all found matches should be replaced (the default), or if the replacements should be limited to the first match (or not the first match) of each paragraph, or textbox, or page, or entire document.

Paragraph Sara Change Options

Paragraph: You can apply paragraph attributes to the resulting text of a SARA (left, right, first indents, leading, space before, space after, horizontal alignment, ...).

Restrictions

Paragraph attributes saras require QuarkXPress 2016-2025 or InDesign 2020-2025.

Box Sara Change Options

Textbox: As part of the changes specified for each SARA, you can also specify that some of the attributes of the textbox containing the found text be changed:

•background color and shade*

•frame color, thickness and style*

•box-wide text elements (text in box settings):

othe number of columns

othe gutter width

othe vertical alignment

othe first baseline alignment

othe text inset.

•replacing the textbox by an image (which can be a PDF, an AI, or an INDD document)

owhich can be set as transparent (for black & white and vector images)

owhose X/Y position offset can be specified

owhose X/Y scale change can also be specified

•specifying the PDF box to use to crop the imported PDF page (and which page to use, in the case of multi-page PDF documents).

* This group of options, as shown below, also appears in the macros resulting actions, the current month and current week minicalendar options.

Textbox Attributes Saras require QuarkXPress 2016-2025 or InDesign 2020-2025 and, for obvious reasons, the importation of INDD files into a text frame is limited to the use of InDesign.

Box Deletion Sara Options

The textbox, by itself or along with all objects that are part of the same group, can be deleted, as well as all objects on the same page and layer.

If the text found by a sara is located inside an InDesign table, then:

•The Delete Box option deletes the entire table object in which the macro token is located.

•The Delete Group option deletes the parent textbox of the table in which that macro token is located.

Alternatively, the page containing the current textbox can be deleted (this deletes the actual document page, not only the objects on it).

For testing testing/debugging purposes, you can use the keep pages diary generation option to delete all objects on the page, and leave a marker that the page is to be deleted, instead of deleting the actual page.

Deletion Saras require QuarkXPress 2016-2025 or InDesign 2020-2025.

Change Z-Order

Using the Change Z-Order option allows you to specify that the result of the current sara, if it is triggered, should be to change the z-Order of the textbox containing the found text (ie. make the textbox appear if front of, or behind, other objects of the same layer).

➢The available z-order changes are shown on the right.

As specified above, and as is the case for macros box resulting actions, the z-order change only occurs within the same layer, as the position of each layer in the list of layers determines the relative z-position of objects on each layer (that is to say the objects of a given layer are either all in front of, or all behind, all the objects of any other layer).

Apply Style Sara Change Options

Styles: You can apply styles attributes to the resulting text of a SARA and/or its containing textbox, table or cell.

Important

If you are trying to apply a box, table or cell style to a template that is not the main grid of the script (or if your script is not using the use main grid as seed generation option) then you should make sure that that template contains at least one object that uses the style you plan to use (you can then set that object to be automatically deleted by the use of a zap token such as [1Zd>0] for example). Failing to do this will most often cause message 187330 to be generated

Restrictions

Currently (November 2024), style attributes saras require InDesign and are not available when using QuarkXPress.

See also: applying styles with macros.