Text structure

@asterisks

• single parameter: the number of asterisks to insert

Inserts a centered paragraph that contains the specified number of asterisks, separated by 10 spaces. The paragraph contains 25pt spacing above.

This special function’s typical use case is before a signatures block — example:

@bullets

(including @bullets-and / @bullets-or / @bullets-andor / @bullets-skipfinal / @bullets-and-skipfinal / @bullets-or-skipfinal / @bullets-andor-skipfinal)

• parameters: either a list, or one or more values (which may themselves be lists, from which the elements will then be extracted)

• returns a bulleted list if at least one item results in output (no result if an empty list or item without output is passed)

• see also: @enumerate

Converts the parameter(s) into an enumeration that will always be displayed as a bullet-set.

For example:

• inserting @bullets(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {LIST! | alpha | beta | gamma}

• inserting @bullets-and(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {AND! | alpha | beta | gamma}

Use @enumerate instead if you do not necessarily want to force the use of bullets, but instead want to rely on the applicable styling to determine how an enumeration should be shown.

The functions that include ….-skipfinal can be used if you want to avoid that the final item receives a suffix.For example, @bullets(‘alpha’, ‘beta’, gamma’) results in a list of three bullets, for which the last bullet (containing “gamma”) will probably end at the suffix “.” (or any other suffix that happens to be selected in the layout settings). To prevent such suffix from being inserted, used @bullets-skipfinal.

@enumerate

(Including @enumerate-and / @enumerate-or / @enumerate-andor / @enumerate-numbered / @enumerate-numbered-and / @enumerate-numbered-or / @enumerate-numbered-andor. All of them also include an alternative version with suffix -skipfinal, that skips the suffix for the final item.)

• parameters: either a list, or one or more values (which may themselves be lists, from which the elements will then be extracted)

• returns an enumerated list (or nothing, if the list is empty)

• see also: @bullets

Converts the parameter into an enumeration, as if {AND | … | … } was typed in. Depending on the applicable styling, such enumeration may get displayed in an “inline” list, or instead as a bulleted list.

For example:

• inserting @enumerate(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {LIST | alpha | beta | gamma}

• inserting @enumerate-or(‘alpha’, ‘beta’, ‘gamma’) is identical to typing {OR | alpha | beta | gamma}

The function versions that include -…numbered…- in their name, will be forced to show numbers when formatted as an inline list. For example, @enumerate(‘alpha’, ‘beta’, ‘gamma’) can — depending on the layout settings — result in “alpha, beta and gamma”. If instead you use @enumerate-numbered(‘alpha’, ‘beta’, ‘gamma’), then numbers will be inserted in between — in many layout settings this will for example look like “(i) alpha, (ii) beta and (iii) gamma”. This is similar to typing {AND | 1. alpha | 2. beta | 3. gamma}.If, in accordance with the layout settings, the @enumerate-numbered-… happens to result in a bulleted list, then the …-numbered-… part would make no difference.

@float

• parameter:

  • a text, number or currency value

• results in a floating-point number, or nothing if the conversion is unsuccessful

• see also: @int

This special function is primarily intended to convert a text that represents a number into an actual number. (Technically, in other programming languages, this would be called a conversion from string to float / double.)

Background: when a user would type in "5" in a text box where all kinds of text can be entered, then this content may look like a number, but cannot actually be used as a number (e.g., to perform mathematical operations with it). Theoretically software could try to anticipate these situations, but in practice there are many reasons (particularly performance and consistency) why this is traditionally not done. The @float special function can however be used to this text into an actual number.

For example, if the number "5.3" would be stored in a text-datafield #alpha^text then {35 + #alpha^text} would result in a "Value is not a number" error. However, {35 + @float(#alpha^text)} would result in 40.3, because @float converts the text-based storage of #alpha^text into an actual number.

For ease of use, @float can also be passed:

• a floating-point number, which would then simply be returned

• a plain number, in which that number is converted into a floating-point number (so 35 would become 35.0)

• a currency value, in which the accompanying number is simply extracted — e.g. @float(35.5 EUR) would result in the floating-point number 35.5.

If the conversion is unsuccessful, then nothing is returned. For example, @int("dog") would result in nothing, because "dog" cannot be converted into a number.

In order to allow for multiple numbering notations in an international context, ClauseBuddy allows to use both a period and a comma as the fractional point. For example, both @int("35.3") and @int("35,3") would result in the floating-point number 35.3.

@for and @for-calc

• parameters:

  • a placeholder

  • a list of elements (e.g., @list, list of texts datafield, or a repeating datafield)

  • a snippet that can optionally contain the specified placeholder, as well as the implicitly present placeholders ?INDEX and ?MAX-INDEX

• results in a list of snippets (@for) or values (@for-calc)

This function results in a list of snippets or values, equal to the number of elements specified in the second parameter. At each iteration, the snippet will be changed so that the specified placeholder will be replaced by element of the current iteration. In addition, the implicitly present placeholders ?INDEX (= one-based index of the current iteration) and ?TOTAL (= total number of elements) will also be replaced in the snippet.

For an in-depth discussion, see For-loops.

@int

• parameter:

  • a text, number or currency value

• results in a plain number, or nothing if the conversion is unsuccessful

• see also: @float

This special function is primarily intended to convert a text that represents a number into an actual number. (Technically, in other programming languages, this would be called a conversion from string to integer.)

Background: when a user would type in "5" in a text box where all kinds of text can be entered, then this content may look like a number, but cannot actually be used as a number (e.g., to perform mathematical operations with it). Theoretically software could try to anticipate these situations, but in practice there are many reasons (particularly performance and consistency) why this is traditionally not done. The @int special function can however be used to this text into an actual number.

For example, if the number "5" would be stored in a text-datafield #alpha^text then {35 + #alpha^text} would result in a "Value is not a number" error. However, {35 + @int(#alpha^text)} would result in 40, because @int converts the text-based storage of #alpha^text into an actual number.

For ease of use, @int can also be passed:

• a floating-point number (in which case the number is rounded to the closest plain number — e.g., @int(#alpha^nr) would result in 36 if #alpha^nr contains the floating-point number 35.5)

• a plain number, in which that number is simply returned as-is

• a currency value, in which the accompanying number is rounded to the closest plain number — e.g. @int(35.5 EUR) would result in the plain number 36.

If the conversion is unsuccessful, then nothing is returned. For example, @int("dog") would result in nothing, because "dog" cannot be converted into a number.

In order to allow for multiple numbering notations in an international context, ClauseBuddy allows to use both a period and a comma as the fractional point. For example, both @int("35.3") and @int("35,3") would result in the number 35.

@in-binder

• no parameters

• returns true or false

Returns true if inside a Binder (i.e., if there are one or more subdocuments part of a Binder). Returns false in a standalone document.

Tip: you can easily invert the behaviour of this special function: not(@in-binder) will return true when working in a regular document.

@pagecount

• no parameters

• inserts a special Word-field that contains the total number of pages in the entire Word-document

For example, @pagecount — no parameters or parentheses necessary — would return “15” if that happens to be the total number of pages.

Note that the @pagecount cannot be calculated in the browser (i.e., will only export in Word or PDF). Within MS Word, the number of pages is inserted as a so-called “field”, so it can automatically update when the actual number of pages would change. (You may have to update the fields by selecting the text and pressing F9.)

@str

• parameters: anything convertible to text

Returns a text parameter that converts all of the parameters into text, and concatenates them together into a single text.

For example, @str(5, " ", 3 days, #employee) may — depending on the current concept-label for #employee — convert to “5 3 days the Employee”.

This can be especially useful when you want to deviate from Clause9's default spacing system. For example, in the following text:

alpha " #beta " gamma

the spaces around the #beta will disappear in the final result, because this is typically what you want. If for some specific reason you intend to keep this spacing, you can use @str('alpha "', #beta, ' " gamma'). The conversion to @str will cause all parameters to be concatenated into a single text, that will not be further space-processed by Clause9.

@text-part

• parameter: a clause-part (e.g., “@ALPHA”)

• converts the clause-part into a text

Converts the entire clause-part into a static text parameter. Please note that all newlines are thereby converted into spaces.

For example,

See @text(@ALPHA)

ALPHA = this is a test

and this also

would cause the text “this is a test and this also” (notice the space between the two parts) to be converted into a text-parameter. This text-parameter could then be used in other calculations.Only use this special-function when strictly necessary, because it slows down the recalculations.

@terms-toc

• no parameters

• see also: @terms-toc

This function inserts an index of references to defined terms that are used in the document. Such list can be used as an alternative or complement to a typical definition list.

This list consists of all the terms that are used somewhere in the document, to which either an explicit (autonomous) definiton was assigned, or for which some paragraph with an integrated definition (“shall have the meaning as set forth…”) is visible in the document.

Note that the list of included terms is not calculated in the same way as the definition lists, because references to integrated definitions are included irrespective of whether those are included in the definition list.

@toc

• required parameter: the number of levels for the table of contents (1, 2, 3 or 4)

• optional parameters:

  • insert a page-break before? (true/false, default value is false)

  • insert a page-break after? (true/false, default value is false)

  • insert the default title? (true/false default value is true)

• see also: @toc-o1 @terms-toc

This function inserts a table of contents (including or without the title) with the specified number of levels at the position where the special function is invoked. The typical use case of this function is when the predefined options offered by the Clause9 interface are not enough (e.g., because you want to insert the TOC at a particular location), or when you want the insertion of the TOC to be dynamically configurable by the end-user. Examples:

• @toc(4) inserts the title “Table Of Contents” (translated into the current language) with four levels of paragraph references, without a break before or after.

• @toc(3, true, true) inserts the default title, three levels of paragraph references, preceded and followed by a break.

• @toc(1, false, false, false) does not insert the default title, and inserts one level of paragraph references, without a break before or after.

If your users encounter issues when updating a TOC in Word, then you may want to have a look at @toc-o1.

@toc-o1

• required parameters:

  • insert a page-break before? (true/false, default value is false)

  • insert a page-break after? (true/false, default value is false)

  • insert the default title? (true/false default value is true)

• see also: @toc @terms-toc

This function inserts a table of contents (including or without the title) of one level at the position where the special function is invoked. Similar to @toc, the typical use case of @toc-o1 is when the predefined options offered by the Clause9 interface are not enough (e.g., because you want to insert the TOC at a particular location), or when you want the insertion.

What differentiates @toc-o1 from @toc is that it creates a TOC of one single level, on the basis of the “outline level” of the paragraphs within the document. This requires some background explanation on how MS Word works internally.

Essentially, MS Word compiles a TOC by running through the entire document and collecting relevant paragraphs. Relevant paragraphs can either be determined on the basis of their MS Word style, or on the basis of the “outline level” of each paragraph (which is a property of every paragraph in MS Word).

The first option — looking for paragraphs with specific MS Word styles — is the more flexible option, and is therefore the default option used by Clause9. More specifically, Clause9 instructs MS Word to look for the styles for the “Document Title”, “Heading 1 Title”, “Heading 2 Title”, “Heading 3 Title”, and so on. However, as specified in Microsoft’s documentation, this breaks down for users who happen to have the locale settings of their computer set to use a semicolon instead of a comma as a list separator, which is on Windows the case for some versions of MS Word in non-Anglosaxon countries, and on a Mac often when the display language of MS Word is set to something other than English. When these users try to update the TOC, they will see an empty TOC and/or get a message that no relevant entries could be found in the document. Microsoft therefore recommends to not generate TOCs through the styles option when a document is being used in an international setting.

The second option — looking for paragraphs with a certain outline level — can be used as a fallback, but has its own share of problems. The documents generated by Clause9 can contain both headings (style “Heading 1”, “Heading 2”, etc.) and titles (“Heading 1 title”, “Heading 2 title”, etc.), and both have the same outline level, as illustrated by the levels of the paragraphs 2.1 and 3.1 in the following screenshot:

Using the outline-level based TOC beyond level 1 is therefore not a good idea in a legal text — and even when you use it through @toc-o1, you should be careful to avoid having non-title paragraphs at level 1, as they may end up in the TOC.

In summary, @toc-o1 should be used as a fallback to cope with the technical limitations of MS Word, for when @toc breaks down for your end-users. This is a very unfortunate situation that hopefully gets resolved in some future version of MS Word.

@underscores

• parameter: the number of desired underscores

• returns the specified number of underscores, printed next to each other

In Clause9, an underscore is a special character (used, for example, to hard-code numbers). Simply inserting a set of underscores, by way of placeholder, will therefore result in an error message from the software.

Instead of writing @str("___") or {"___"}, you can write @underscores(3) to insert three underscores.