References

@bookmark

• first parameter: the name of the bookmark (which — according to MS Word’s specifications — should not contain any spaces or punctuation, and must not start with a number)

• second parameter: any parameter that can be converted into text. Note that bookmarks are not intended to cover multiple paragraphs.

• see also: @bookmark-link

This function inserts an MS Word “bookmark” around the text specified in the parameter. Afterwards, you can then establish a clickable hyperlink to this area of text through the @bookmark-link function.

As suggested by the name, “bookmarks” act as reference locations inside MS Word, spanning the text you specified as the first parameter. Once inserted at some location in the document, you can then elsewhere refer to them, either with the text of the bookmark, or with the number of the paragraph in which the bookmark is located. Note that bookmarks leave no visual traces within the document: you can only detect their presence by showing the “Insert Cross-References” dialog box and asking for the list of bookmarks.

For example, @bookmark("alpha", "some random text") will insert the plain text “some random text” in the document, and attach a bookmark named “alpha” to that piece of text.

If you want to insert more rich text as the second parameter, you are advised to refer to an internal snippet. For example, @bookmark("alpha", @BETA) will insert whatever text is associated with internal snippet BETA into the document, and associate a bookmark called “alpha” to it.

@bookmark-link

• sole parameter: the name of the bookmark to refer to

• see also: @bookmark and @bookmark-pagelink

This function inserts a (clickable) hyperlink to the specified bookmark. The text that will get inserted is equal to the text covered by the targeted bookmark.

For example, when you would use @bookmark("alpha", "some text beta") in some clause, you can refer to that text elsewhere with @bookmark-link("alpha"). The latter special function call will result in the text “some text beta” being inserted in the document, as a clickable hyperlink.

@bookmark-pagelink

• sole parameter: the name of the bookmark to refer to

• see also: @bookmark and @bookmark-link

This function inserts a (clickable) hyperlink to the specified bookmark. The text that will get inserted is equal to the page number the targeted bookmark.

For example, when you would use @bookmark("alpha", "some text beta") in some clause, you can refer to that text elsewhere with @bookmark-pagelink("alpha"). The latter special function call will result in the number of the page (e.g., 34) being inserted in the document, as a clickable hyperlink.

@clause-title

• parameter: a #concept or a §cross-tag

• returns the title of the clause that implements the concept/cross-tag (or empty text if the concept is not implemented, or is implemented but the implementing clause has no title)

• see also: @ref-title

Returns, as a text value, the title of the first clause that implements the concept/cross-tag.

For example @clause-title(#liability) could result in Liability limitations agreed between the Parties.

@crosstag

• sole parameter: the name of the crosstag

• returns text

Creates a crosstag with the specified name.

So instead of writing §alpha-beta, you can also write @crosstag("alpha-beta"). The latter has the advantage that the parameter can of course be dynamically implemented.

@doctitle

• no parameters

• returns text

For example, @doctitle — no parameters or parentheses necessary — would insert the title of the current document. (When called insider a binder, the title of the document that contains the function-call will be returned.)

@drop-clause-title

• single parameter: a reference (e.g. §#concept or §tag)

• returns the specified parameter, flagged with a preference for never showing the target clause's title

• see also @drop-doc-ref

Force the clause title to not be shown between parentheses, even if the styling would dictate this.

@drop-doc-ref

• single parameter: a reference (e.g. §#concept or §tag)

• returns the specified parameter, flagged with a preference for never showing the document’s title

• see also @drop-clause-title, @short-ref, @long-ref and @last-level

When referencing a clause outside of the current subdocument, Clause9 will append the other subdocument’s title (e.g., “article 3.2 of Schedule 2”. Usually this is exactly what you want, but there are situations where you want to avoid this.

When wrapping a reference in @drop-doc-ref, the software will drop the reference to the subdocument’s title, when a clause is actually part of a Binder. (Outside of a Binder, this special function has no effect.)

@last-level

Deprecated - please do not use anymore. Replaced by @ref-relevant-context and @ref-no-context.

@long-ref

• single parameter: a reference (e.g. §#concept or §tag)

• returns the specified parameter, flagged with a preference for the long version of the reference

• see also @short-ref

When wrapping a reference in @long-ref, the software will prefer the long version of a reference (currently this is only relevant for document-references, which have both a long and short version). For example, even when the user’s styling is set to use the short version of a document’s title, @long-ref(§document) will return the long version, if available.

See the in-depth explanations in Binder settings page.

@ref-if

• parameter: #concept

• returns a reference, or nothing

• see also: @implemented @refs-if-and @refs-if-or

Returns a reference if the concept is implemented, otherwise results in nothing. Calling @ref-if(#concept) is largely similar to calling {@implemented(#concept): §#concept}, but will not result in an error message if the concept would happen to not be implemented.

@ref-no-context

• single parameter: a reference (e.g. §#concept or §tag)

• returns the specified parameter, flagged to only show the last level in a numbering-set

• see also @drop-doc-ref, @short-ref and @long-ref

Inserts a cross-reference that works like the 'Paragraph number (no context)' cross-reference in MS Word: only the number of the actual level is shown.

More information on cross-references in MS Word, including an explanation on the differences between 'Paragraph number (no context)' and the other types of cross-references, can be found in this article on our website.

For example, if a separate clause-file is paragraph (b) in clause 1.2.3. and it has cross-tag liability :

• a reference to §liability would be printed as clause 1.2.3.(b), but

• a reference to @ref-relevant-context(§liability) would result in merely (b).

Note that also the prefix-word (in the example “clause”, but this will change depending on the language and reference styling) gets dropped.

In a typical “legal numbering” styling (which also happens to be the default in Clause9), the level numbering will consist of “1.” for the first level, “1.1.” for the second level, “1.1.1.” for the third level, etc. In such situation, the result of @ref-no-context for a clause at level 3 will be the full set “1.1.1.” (= the number printed by MS Word on the left side of the clause), so not simply the last digit “1”.

In other words, @ref-no-context requires that the number of the clause being referred to does not contain 'all' numbering levels in order to have a meaningful effect.

Accordingly, this special function is most relevant for if you are referring to a specific bullet or paragraph the numbering of which does not contain all numbering levels and you do not want to include all of the preceding levels.

@ref-relevant-context

• single parameter: a reference (e.g. §#concept or §tag)

• returns the specified parameter, flagged to only show the relevant level(s) in a numbering-set

• see also @drop-doc-ref, @short-ref and @long-ref

Inserts a cross-reference that works like the 'Paragraph number' cross-reference in MS Word. What gets inserted as a number will depend on the position of the cross-reference. When you would for example insert a cross-reference to clause 3.A.a from within clause 3.A.d, then MS Word will insert just the d. Conversely, if you would insert a cross-reference to that very same clause 3.A.a from within, say, clause 4., then MS Word will insert a full reference, so 3.A.a, as this would disambiguate the cross-reference.

More information on cross-references in MS Word, including an explanation on the differences between 'Paragraph number' and the other types of cross-references, can be found in this article on our website.

Note that also the prefix-word (in the example “clause”, but this will change depending on the language and reference styling) gets dropped.

(N.B.: any references to the old @last-level special function work exactly as if they were references to @ref-relevant-context)

@ref-title

• parameter: #concept

• returns a reference, followed by the title of the referenced clause between parentheses

• see also: @clause-title

Returns a reference if the concept is implemented, followed by the title of the referenced clause between parentheses. (If the concept is not implemented, it results in nothing).

For example, @ref-title(#liability) may result in article 2 (Liability)

@refs-and

• parameters: cross-references — either tag-based or concept-based (intra-clause references such as §1 will not work)

• see also: @refs-or, @refs-if-or and @refs-if-and

This special function allow you to insert multiple cross-references at once. The software will take care that:

• all references are ordered in accordance with their appearance in the document/binder

• all references are grouped per subdocument

• duplicate words are avoided

For example, assume you have to insert tag-based cross-references to the clause on liability (art. 12.2 of the main body), confidentiality (art. 4 of the main body), pricing (article 3 of Annex A), documentation (article 4 of Annex A) and contacts (article 5 of Annex A).

• If you simply insert “§liability, §confidentiality, §pricing, §documentation and §contacts”, then you end up with “clause 12.2, clause 4, clause 3 of Annex A, clause 4 of Annex A and clause 5 of Annex A”. Clause9 treats all those cross-references separately, without regard to one another. Notice that (1) the words “clause” and “Annex A” get repeated needlessly, (2) the ordering of the first two clauses is wrong, because it just happens that liability is printed before confidentiality, and (3) there is no reference to the main document in the first two clauses.

• Instead, you can use @refs-and(§liability, §confidentiality, §pricing, §documentation, §contacts), which results in a much cleaner “clauses 4 and 12.2 of the main document and clauses 3, 4 and 5 of Annex A”. (Notice the plural “clauses” instead of the singular “clause”).

@refs-or

• parameters: cross-references — either tag-based or concept-based (intra-clause references such as §1 will not work)

• see also: @refs-and, @refs-if-or and @refs-if-and

This special function allow you to insert multiple cross-references at once. The software will take care that:

• all references are ordered in accordance with their appearance in the document/binder

• all references are grouped per subdocument

• duplicate words are avoided

For example, assume you have to insert tag-based cross-references to the clause on liability (art. 12.2 of the main body), confidentiality (art. 4 of the main body), pricing (article 3 of Annex A), documentation (article 4 of Annex A) or contacts (article 5 of Annex A).

• If you simply insert “§liability, §confidentiality, §pricing, §documentation or §contacts”, then you end up with “clause 12.2, clause 4, clause 3 of Annex A, clause 4 of Annex A or clause 5 of Annex A”. Clause9 treats all those cross-references separately, without regard to one another. Notice that (1) the words “clause” and “Annex A” get repeated needlessly, (2) the ordering of the first two clauses is wrong, because it just happens that liability is printed before confidentiality, and (3) there is no reference to the main document in the first two clauses.

• Instead, you can use @refs-or(§liability, §confidentiality, §pricing, §documentation, §contacts), which results in a much cleaner “clause 4 or 12.2 of the main document or clauses 3, 4 or 5 of Annex A”. (Notice that, unlike @refs-and, the word “clause” remains in singular)

@refs-if-and

This function is identical to @refs-and, but drops invalid references (i.e., references that do not currently have a valid target).

@refs-if-or

This function is identical to @refs-or, but drops invalid references (i.e., references that do not currently have a valid target).

@ref-subclauses

• parameter: a #defined term, §cross-tag, §this or §nr reference

• returns either a single reference, or a range of references

• see also: @ref-siblings-before, @ref-siblings-after

Returns a reference to a range of references: the first subclause up to the last subclause (or only the first subclause, if there is only a single subclause). Returns an error if no subclauses can be found.

Example:

@ref-siblings-after

• parameter: a #defined term, §cross-tag, §this or §nr reference

• returns either a single reference, or a range of references

• see also: @ref-subclauses, @ref-siblings-before

Returns a reference to a range of references: the first sibling after the target clause, up to the last subclause of the target clause’s parent clause (or only the first sibling, if there is only one clause before the target clause). Returns an error if no siblings can be found after the target clause.

Example:

@ref-siblings-before

• parameter: a #defined term, §cross-tag, §this or §nr reference

• returns either a single reference, or a range of references

• see also: @ref-subclauses, @ref-siblings-after

Returns a reference to a range of references: the first subclause of the target clause’s parent clause, up to the subclause before the target clause (or only the first subclause of the target clause’s parent clause, if there is only one clause before the target clause). Returns an error if no siblings can be found before the target clause.

Example:

@remove-this

• Parameters: some reference, e.g. §this or §#concept

• The effect is that the reference will be listed without the (translation of the) word “this” or “these”

References such as §this, but also other references that happen to refer to the current article, result in output such as “this article 5”. When you wrap the reference in a @remove-this call — e.g. @remove-this(§this) — then the word “this” or “these” will get dropped from the output.

This is particularly relevant for languages with grammatical cases, where the word “this” may need to be inflected according to complex grammatical rules. By using this special function, you will then be able to insert the relevant word manually.

@short-ref

• single parameter: a reference (e.g. §#concept or §tag)

• returns the specified parameter, flagged with a preference for the short version of the reference

• see also @long-ref

When wrapping a reference in @short-ref, the software will prefer the short version of a reference (currently this is only relevant for document-references, which have both a long and short version). For example, even when the user’s styling is set to use the long version of a document’s title, @short-ref(§document) will return the short version, if available.

See the in-depth explanations in Binder settings page.

@subdoc-crosstags

• first optional parameter: whether to include the mainbody's crosstags as well

• second optional parameter: whether to include all crosstags of a subdocument, instead of only the first

• returns a list of texts with the crosstags of all the (non-disabled) subdocuments

This special function returns a list of all the cross-tags of all enabled subdocuments in a Binder. These crosstags can then be used for other purposes, e.g. for compiling an inventory of subdocuments.

If the first optional parameter is set to true, then the crosstag(s) of the subdocument that acts as the main-body (as specified in the Binder-settings) will also be included, assuming that subdocument is not disabled by its conditions.

If the second optional parameter is set to true, then all the crosstags of enabled subdocuments will be included. In the default behaviour, where the second optional parameter is implicitly false, only the first crosstag of each subdocument is included.

@subdoc-title

• no parameters

• returns the title of the current subdocument, without the numbering prefix (if any)

This special function returns the full title (or, failing that, the short title) that was assigned to the current subdocument, i.e. the subdocument in which the clause is situated that mentions this special function.

When used inside a binder for which the Use automatically numbered Word-styles for subdocument titles is enabled, all text up to (including) the closing brace of the subdocument will be dropped. For example, when the full title would be set to Annex {1} Pricing, then the result of this special function would be Pricing.

The most interesting use case for this special function is to insert the title inside a custom clause (formatted as a document title) of a subdocument without an automatically printed title. See the in-depth explanations in Binder settings page.