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.
§#conceptor§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.
§#conceptor§tag)returns the specified parameter, flagged with a preference for never showing the document’s title
see also
@drop-clause-title,@short-ref,@long-refand@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
single parameter: a reference (e.g.
§#conceptor§tag)returns the specified parameter, flagged to only show the last level in a numbering-set
see also
@drop-doc-ref,@short-refand@long-ref
Drops the “context” and prefix (“clause”, “section”, “article”, etc.) of a cross-reference, so that only the last level of numbering is shown.
For example, if §liability would be a reference to cross-tagged clause, printed as clause 1.2.3.(b), then @last-level(§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.
The “last level” will coincide with the number printed at the left side of a clause by MS Word. So, depending on how the numbering styling is defined, the “last level” is not necessarily the “last number” for MS Word. For example:
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
@last-levelfor 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,
@last-levelrequires a bullet as the last level in order to have a meaningful effect.Conversely, if you would define a numbering system such as “I.” for the first level, “A.” for the second level and “(i)” for the third level, the “last level” for a clause at level 3 will consist of “(i)”.
Accordingly, this special function is most relevant for two situations:
You are referring to a specific bullet (i.e., a paragraph started with an asterisk * in the Clause9 editor) — such as
1.2.3.(b)in the example above — and you do not want to include the preceding levels.You are using a numbering styling other than a typical “legal numbering”, e.g. with a style such as “I.A.(i)” in the example above.
@long-ref
single parameter: a reference (e.g.
§#conceptor§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-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.
§#conceptor§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.
Last updated
