Please enable JavaScript to view this site.


Navigation: Saras

Editing Individual Saras

Scroll Prev Up Next More

A Sara is essentially a "search and replace" command, that is saved in SaraSets for re-use.


At the top of the Sara definition, is a field where you can enter your own 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.





Each Sara is then composed of:


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.


regex to take text in quotes and remove the quotes

regex to take text in quotes and remove the quotes


Partial Replacement


Additionally, when using QuarkXPress 2018-2024 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.


applying the replacement to a specific capture group only

applying the replacement to a specific capture group only


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

For DiaryGridlines Saras

For DiaryGridlines Saras

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.


For Global or Standalone Saras

For Global or Standalone Saras

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 Attributes


The Find and Change sets of attributes are in turn made up of 4 elements, which appear in the Sara Editor:



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.


The name of a font.


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


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


Simple Style Attributes


The Style family of attributes is by far the most extensive.


These attributes follow the naming conventions generally used in QuarkXPress and InDesign.


The first 12 attributes are typographical and well known, the only exception being Plain, which is a particularity of QuarkXPress.


The reset un-checked boxes button should be used in response to the warning message 181985.


Valued Style Attributes


The remaining attributes are more complex, often but not always, measured with 2 decimals:




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.


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.


Additionally, if you are using InDesign, then you can also specify one of the 2 types of automated kerning available in InDesign, namely Metrics kerning (based on the design of the font maker) or Optical (where InDesign tries to find the optimal kerning for each character pair visually).


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


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.


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.


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.


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


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-2024 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-2024 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-2024 and is supported by all 64-bit versions of InDesign.


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 Options


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-2024 or InDesign 2020-2024.


Multiline Text


multi-line text option locating dates when there is not enough room to display all information, such as the week number

multi-line text option locating dates when there is not enough room to display all information, such as the week number

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).



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, ...).





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

SARAs Paragraph Options

SARAs Paragraph Options

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-2024 or InDesign 2020-2024 and, for obvious reasons, the importation of INDD files into a text frame is limited to the use of InDesign.

SARAs Picture Box Options

SARAs Picture Box Options

SARAs Frame/Background Options

SARAs Frame/Background Options

Saras Box-wide Text Options

Saras Box-wide Text Options

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-2024 or InDesign 2020-2024.

Change Z-Order

within the same layer

within the same layer

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.





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


See also: applying styles with macros.



Topic 104265, last updated on 28-Nov-2023