diff --git a/_layouts/author-docs.html b/_layouts/author-docs.html index c3f518e1..cea0c191 100644 --- a/_layouts/author-docs.html +++ b/_layouts/author-docs.html @@ -129,6 +129,8 @@ path: /topics/inline_markup/index_terms/ - title: Links and Cross-references path: /topics/inline_markup/links/ + - title: Citations and Localities + path: /topics/inline_markup/citations/ - title: Semantic elements path: /topics/inline_markup/semantic-elements/ - title: Text formatting diff --git a/author/basics/entering-bib.adoc b/author/basics/entering-bib.adoc index d062da2c..d1140efd 100644 --- a/author/basics/entering-bib.adoc +++ b/author/basics/entering-bib.adoc @@ -42,7 +42,7 @@ To cite an entry from your bibliography:app-name: . Enter the anchor name like this: `\<>`. . To specify a location within the cited document, you can add -link:/author/topics/document-format/bibliography/#localities[localities] in the +link:/author/topics/document-format/inline_markup/citations/#localities[localities] in the brackets like so: `\<>`. == Bibliography example diff --git a/author/basics/xrefs.adoc b/author/basics/xrefs.adoc index 05ccf304..2e8e1355 100644 --- a/author/basics/xrefs.adoc +++ b/author/basics/xrefs.adoc @@ -92,6 +92,6 @@ EXAMPLE: "`ISO 7301, Clause 2, Table 1a, pp. 7-9`" would be expressed as: -- ==== -Read more about link:/author/topics/sections/bibliography#localities[localities and locality values] in the Bibliography documentation. +Read more about link:/author/topics/sections/inline_markup/citations#localities[localities and locality values] in the Bibliography documentation. //Write a short summary of the article? diff --git a/author/ieee/authoring-guide/bibliographic-references.adoc b/author/ieee/authoring-guide/bibliographic-references.adoc index 73661735..01ac2dc7 100644 --- a/author/ieee/authoring-guide/bibliographic-references.adoc +++ b/author/ieee/authoring-guide/bibliographic-references.adoc @@ -96,7 +96,7 @@ sections. . Cite the whole document, by cross-referencing the anchor name like this: `\<>`. -. Cite a particular locality of the document, by cross-referencing the anchor name but additionally specify a link:/author/topics/document-format/bibliography/#localities[locality] as the second argument, like this: `\<>`. +. Cite a particular locality of the document, by cross-referencing the anchor name but additionally specify a link:/author/topics/document-format/inline_markup/citations/#localities[locality] as the second argument, like this: `\<>`. == Bibliography example diff --git a/author/iho/authoring-guide/bibliographic-references.adoc b/author/iho/authoring-guide/bibliographic-references.adoc index 53a35b7a..92471dd5 100644 --- a/author/iho/authoring-guide/bibliographic-references.adoc +++ b/author/iho/authoring-guide/bibliographic-references.adoc @@ -96,7 +96,7 @@ sections. . Cite the whole document, by cross-referencing the anchor name like this: `\<>`. -. Cite a particular locality of the document, by cross-referencing the anchor name but additionally specify a link:/author/topics/document-format/bibliography/#localities[locality] as the second argument, like this: `\<>`. +. Cite a particular locality of the document, by cross-referencing the anchor name but additionally specify a link:/author/topics/document-format/inline_markup/citations/#localities[locality] as the second argument, like this: `\<>`. == Bibliography example diff --git a/author/ogc/authoring-guide/bibliographic-references.adoc b/author/ogc/authoring-guide/bibliographic-references.adoc index 6e8c0af9..cee21c0d 100644 --- a/author/ogc/authoring-guide/bibliographic-references.adoc +++ b/author/ogc/authoring-guide/bibliographic-references.adoc @@ -101,7 +101,7 @@ sections. . Cite the whole document, by cross-referencing the anchor name like this: `\<>`. -. Cite a particular locality of the document, by cross-referencing the anchor name but additionally specify a link:/author/topics/document-format/bibliography/#localities[locality] as the second argument, like this: `\<>`. +. Cite a particular locality of the document, by cross-referencing the anchor name but additionally specify a link:/author/topics/document-format/inline_markup/citations/#localities[locality] as the second argument, like this: `\<>`. == Bibliography example diff --git a/author/topics/document-format/xrefs.adoc b/author/topics/document-format/xrefs.adoc index d5488f9d..ead926e5 100644 --- a/author/topics/document-format/xrefs.adoc +++ b/author/topics/document-format/xrefs.adoc @@ -371,7 +371,7 @@ NOTE: This differs from the normal AsciiDoc treatment of custom text. -- ==== -See link:/author/topics/document-format/bibliography#localities[localities and locality values]. +See link:/author/topics/document-format/inline_markup/citations#localities[localities and locality values]. == List items @@ -430,7 +430,7 @@ http://www.example2.com[text to go into the hyperlink,style=brackets] == External references -In link:/author/topics/document-format/bibliography#localities[localities and locality values], +In link:/author/topics/document-format/inline_markup/citations#localities[localities and locality values], anchor can be integrated in citations of documents via references. [example] diff --git a/author/topics/inline_markup/changes.adoc b/author/topics/inline_markup/changes.adoc index 24de928a..e89eca86 100644 --- a/author/topics/inline_markup/changes.adoc +++ b/author/topics/inline_markup/changes.adoc @@ -27,7 +27,7 @@ The following attributes can be expressed on changes: * `locality` gives the location in the reference document to be modified, as a collection of locality key/values, following the convention in - link:/author/topics/document-format/bibliography#localities[localities and locality values]. + link:/author/topics/document-format/inline_markup/citations#localities[localities and locality values]. * `path` gives an XPath within the identified locality, indicating the specific element to be changed. * `path_end` is used in diff --git a/author/topics/inline_markup/citations.adoc b/author/topics/inline_markup/citations.adoc new file mode 100644 index 00000000..437d4dc6 --- /dev/null +++ b/author/topics/inline_markup/citations.adoc @@ -0,0 +1,532 @@ +--- +layout: author-docs +title: Citations and localities +--- + +[[citations_localities]] +== Citations and localities + +=== General + +Citations of references in Metanorma are formulated as cross-references. + +The anchor cross-referenced is the internal identifier given for the +bibliographic entry. + +[example] +.Example of specifying a reference anchor (`ref1` is the anchor) +==== +[source,adoc] +---- +<> +---- +==== + +Metanorma AsciiDoc works in a similar way to typical AsciiDoc: any text in a +cross-reference that follows a comma constitutes custom text for the +cross-reference. + +A cross-reference `\<>` will be rendered as +"`the foregoing reference`", and hyperlinked to the `ISO7301` reference. + +[[localities]] +=== Localities + +==== General + +Citations can include details of where in the document the citation is located. + +These localities are entered by suffixing the lowercase type of locality, then +an equals sign, then the locality value or range of values. + +Multiple instances of locality and reference can be provided, delimited by comma +or colon. + +The references cannot contain spaces. Any text following the sequence of +localities will be displayed instead of the localities. + +[[locality-types]] +==== Locality types + +The following locality types are recognised in Metanorma: + +`section`:: +a general section + +`clause`:: +a clause + + +`part`:: +a document part + +`paragraph`:: +a paragraph + +`chapter`:: +a chapter + +`page`:: +a page + +`line`:: +a line identified by the line number + +`table`:: +a table + +`annex`:: +an annex + +`figure`:: +a figure + +`example`:: +an example + +`note`:: +a note + +`formula`:: +a mathematical formula + +`list`:: +a list + +`time`:: +a particular time + +`anchor`:: +an anchor + +`whole`:: +whole + +`title`:: +the title + +Except for the locality types of `whole` and `title`, all locality types require +explicit specification of an identifier to make sense. + +.Example locality types that are used on their own +[example] +==== +* `whole` +* `title` +==== + +.Example locality types that need to be used with identifiers +[example] +==== +* `note 1` (or `note=1`) +* `page 77-99` (or `page="77-79"`) +* `annex A` (or `annex=A`) +* `line 399` (or `line=399`) +==== + +Locality types not listed here shall be entered using the mechanism described at +<>. + +==== Simple locality + +A simple locality is specified with a unique location identifier or free text. + +[example] +.Example of referencing locality in Metanorma citations +==== +[source,asciidoc] +---- +<> + +NOTE: This table is based on <>. + +Sampling shall be carried out in accordance with <> +---- +==== + +[example] +.Example that renders a reference as free text +==== +[source,asciidoc] +---- +// renders as: "the foregoing reference" +<> +---- +==== + +To refer to the "`whole`" item, or the title within a block, the corresponding keyword is used +(`whole`, `title`), without an argument. + +[example] +.Example of referencing with a "whole" locality +==== +[source,asciidoc] +---- +// renders as: "ISO 712, Whole of text" +<> +---- +==== + + +==== Hierarchical locality + +A hierarchical location is specified through consecutive narrower localities. + +[example] +.Example of referencing a hierarchical locality +==== +[source,asciidoc] +---- +// renders as "`Part IV, Chapter 3, paragraph 12`" +<> +---- +==== + +[example] +.Example that renders the reference with (multiple) hierarchical localities +==== +[source,asciidoc] +---- +// renders as: "ISO 712, Section 5, Page 8-10" +<> +---- +==== + +[example] +.Example of referencing locality with additional text +==== +[source,asciidoc] +---- +// renders as "ISO 712, 5:8-10" +// ("5:8-10" treated as replacement text for all the foregoing) +<> +---- +==== + +==== Discontinuous locality + +Discontinuous localities can be named by repeating the same locality type. + +[example] +.Example of referencing a discontinuous locality +==== +[source,asciidoc] +---- +// renders as "`page 4, page 7`" +<> +---- +==== + +Discontinuous localities can also be specified by delimiting sequences of +localities with semicolon [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.24] + + +[example] +.Example of referencing discontinuous hierarchical localities +==== +[source,asciidoc] +---- +// renders as "`Part IV, Chapter 3; Part VI, Chapter 9`" +<> +---- +==== + +==== Complex locality + +Complex relations between discontinuous references can be specified by +prefixing conjoining verbs to sequences of localities separated +by semicolon [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. + +This will result in overt connectives between the references, which will be +internationalised. + +Conjoining verbs include: + +* `and!` +* `or!` +* `from!` +* `to!` + +[example] +.Example of referencing a complex locality +==== +[source,asciidoc] +---- +// renders as: "`Chapters 3 and 7`" +<> +---- +==== + +[example] +.Example of referencing a complex locality that contains a hierarchical locality +==== +[source,asciidoc] +---- +// renders as: "Part IV, Chapter 3 or Part VI, Chapter 9" +<> +---- +==== + +NOTE: This is similar to the behavior in +link:/author/topics/document-format/xrefs/#combined-xrefs[Combination of cross-references]. + +As with cross-references, more than two references combined by "`and`" should be +marked up with semicolons. Internationalisation during rendering will take care +of separating the references by colon, and inserting any necessary conjunction +wording ("`and`"). + +[example] +.Example of referencing multiple references that are complex localities +==== +[source,asciidoc] +---- +<> +// or +<> +---- +==== + +NOTE: If references are joined with semicolons and connectives, but the locality is not supplied +for a cross-reference, it is filled in by referring to the preceding conjoined +cross-reference [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.0]. +For example, `<>` is +corrected internally to the more explicit `<>`. + +Trailing text after the sequence of `locality=reference` (or +`locality{space}reference`) is treated as custom text for the cross-reference, +as would occur normally in a typical cross-reference. + +The locality can appear in quotations if it contains special characters (like +dashes or commas). + +[[custom-locality]] +==== Custom locality + +Locality types not listed in <> are entered using the +"custom locality" functionality. + +Metanorma accepts a fixed list of locality types in cross-references (see +<>), which is not meant to be exhaustive of all possible +locality types. + +[example] +`annex` is recognized as a generic reference to annexes in documents, but it +does not recognize appendixes (instead of annexes), or as distinct from annexes +(as is the case in ISO deliverables). + +A custom locality is entered by prefixing the locality type with `locality:`. + +A custom locality has the following properties: + +* The locality type will be rendered as text preceding the equal sign. + +* The locality type shall not contain commas, colons, or space. + +* The locality type is meant to be valid for all languages. ++ +NOTE: The custom locality `locality:appendix` would be used for both English +and French texts. + +* Localization of custom locality types is managed through inclusion in the +internationalization YAML file for that language, which has to be customized +as part of the Metanorma flavor implementation. ++ +NOTE: The custom locality `locality:appendix` is realized as French _Appendice_ +through configuration in the Metanorma flavor implementation. + + +[example] +.Example of referencing a custom locality the `locality:` prefix +==== +This encoding: + +[source,asciidoc] +---- +<> +---- + +Renders as: + +____ +"ISO/IEC DIR 2, Annex SL, Appendix 2, Clause 3.2" +____ +==== + + +==== Locality plus custom text + +Any text after the bibliographic localities is still treated as custom +cross-reference text. + +As with references without localities, the custom cross-reference text is the +only text that is displayed in the document; but the cross-reference still +captures the specific locality of the reference, e.g. for cross-reference +generation. + +[example] +.Example of referencing with bibliographic localities with additional custom text +==== +[source,asciidoc] +---- +<> +---- + +rendered as: + +____ +the foregoing reference +____ +==== + +==== Anchor locality + +Exceptionally, the `anchor` locality is only used in HTML, to generate +anchor links to other HTML pages [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1]. + +It is intended for use with bibliographic anchors linking to URLs (`repo:()`, `path:()`): +see <> and <>. + + +[example] +.Example of using the `anchor` locality for rendering in HTML output +==== +The following input: + +[source,asciidoc] +-- +<> + +... + +* [[[ISO7301,path:(./iso7301.html,ISO 7301)]]] +-- + +will render in HTML as: + +[source,html] +-- +ISO 7301, Clause 2, Table 1a, page 7-9 +-- +==== + +==== Case and dropped locality labels + +The `capital%`, `lowercase%` and `droploc%` options used for internal +cross-references can also be used as prefixes to localities, modifying how those +localities are +rendered [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.9]. + + +[example] +.Example of using `droploc` in a citation locality +==== +[source,asciidoc] +-- +// renders as "ISO 7301, 2" +<> +-- +==== + +[example] +.Example of using `lowercase` in a citation locality +==== +[source,asciidoc] +-- +// renders as "ISO 7301, clause 2" +<> +-- +==== + +==== Styled cross-references + +As with link:/author/topics/document-format/xrefs#xref-styles[internal cross-references], cross-referenced +citations can have a `style` attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4]. +As of this writing, the only values allowed are the types of docidentifier value that can be substituted +for the primary identifier of the reference, for standards documents; those values will need to be looked up in +Relaton (and the Semantic XML of the document). For example, given the citation + +[source,xml] +---- + +... +ISO/FDIS 17664-1 +urn:iso:std:iso-fdis:17664:-1:ed-1:fr +... + +---- + +A crossreference `<>` will be populated by default with the primary or else the first +`docidentifier` value found, `ISO/FDIS 17664-1`. However, given `<>`, the +first `docidentifier` value of type `URN` will be sought instead, and the cross-reference +will be populated by default as `URN urn:iso:std:iso-fdis:17664:-1:ed-1:fr`. + + +=== Link-only references + +A standards document can be cross-referenced in Metanorma without that document +appearing in the document references. + +Such cross-reference is treated as equivalent to a cross-reference +to a hidden citation, as documented in <>. + +Link-only references can be added to Metanorma AsciiDoc using the following +command: + +[source,adoc] +---- +++std-link:[...]++ +---- + +Where the `std-link` command contains the same text as a normal cross-reference +to a standard, including localities and other directives. +There is no need for an explicit bibliographic entry. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. + +The following two examples are equivalent: + +[example] +.Link-only reference of ISO 123 using `std-link` +==== +[source,asciidoc] +---- +std-link:[ISO 123,droploc%clause=3] +---- +==== + +[example] +.Link-only reference of ISO 123 using a hidden citation +==== +[source,asciidoc] +---- +<> + +[bibliography] +== Bibliography + +* [[[ref1,hidden(ISO 123)]]] +---- +==== + +=== Combination of citations + +Simple citations can be combined with connectives, in a similar fashion to cross-references +(link:/author/topics/building/xrefs/#combined-xrefs[Combination of cross-references]), +and which will be internationalised as +appropriate [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. + +[example] +.Example of rendering a range of citations +==== +The following citation range: + +[source,adoc] +---- +<> +---- + +is rendered as: + +____ +From [3] to [7] +____ +==== + + diff --git a/author/topics/sections/bibliography.adoc b/author/topics/sections/bibliography.adoc index eab543c6..4d564177 100644 --- a/author/topics/sections/bibliography.adoc +++ b/author/topics/sections/bibliography.adoc @@ -1171,533 +1171,6 @@ Of course, any Relaton XML BibItem entries need to be valid, and using correct ==== -[[citations_localities]] -== Citations and localities - -=== General - -Citations of references in Metanorma are formulated as cross-references. - -The anchor cross-referenced is the internal identifier given for the -bibliographic entry. - -[example] -.Example of specifying a reference anchor (`ref1` is the anchor) -==== -[source,adoc] ----- -<> ----- -==== - -Metanorma AsciiDoc works in a similar way to typical AsciiDoc: any text in a -cross-reference that follows a comma constitutes custom text for the -cross-reference. - -A cross-reference `\<>` will be rendered as -"`the foregoing reference`", and hyperlinked to the `ISO7301` reference. - -[[localities]] -=== Localities - -==== General - -Citations can include details of where in the document the citation is located. - -These localities are entered by suffixing the lowercase type of locality, then -an equals sign, then the locality value or range of values. - -Multiple instances of locality and reference can be provided, delimited by comma -or colon. - -The references cannot contain spaces. Any text following the sequence of -localities will be displayed instead of the localities. - -[[locality-types]] -==== Locality types - -The following locality types are recognised in Metanorma: - -`section`:: -a general section - -`clause`:: -a clause - - -`part`:: -a document part - -`paragraph`:: -a paragraph - -`chapter`:: -a chapter - -`page`:: -a page - -`line`:: -a line identified by the line number - -`table`:: -a table - -`annex`:: -an annex - -`figure`:: -a figure - -`example`:: -an example - -`note`:: -a note - -`formula`:: -a mathematical formula - -`list`:: -a list - -`time`:: -a particular time - -`anchor`:: -an anchor - -`whole`:: -whole - -`title`:: -the title - -Except for the locality types of `whole` and `title`, all locality types require -explicit specification of an identifier to make sense. - -.Example locality types that are used on their own -[example] -==== -* `whole` -* `title` -==== - -.Example locality types that need to be used with identifiers -[example] -==== -* `note 1` (or `note=1`) -* `page 77-99` (or `page="77-79"`) -* `annex A` (or `annex=A`) -* `line 399` (or `line=399`) -==== - -Locality types not listed here shall be entered using the mechanism described at -<>. - -==== Simple locality - -A simple locality is specified with a unique location identifier or free text. - -[example] -.Example of referencing locality in Metanorma citations -==== -[source,asciidoc] ----- -<> - -NOTE: This table is based on <>. - -Sampling shall be carried out in accordance with <> ----- -==== - -[example] -.Example that renders a reference as free text -==== -[source,asciidoc] ----- -// renders as: "the foregoing reference" -<> ----- -==== - -To refer to the "`whole`" item, or the title within a block, the corresponding keyword is used -(`whole`, `title`), without an argument. - -[example] -.Example of referencing with a "whole" locality -==== -[source,asciidoc] ----- -// renders as: "ISO 712, Whole of text" -<> ----- -==== - - -==== Hierarchical locality - -A hierarchical location is specified through consecutive narrower localities. - -[example] -.Example of referencing a hierarchical locality -==== -[source,asciidoc] ----- -// renders as "`Part IV, Chapter 3, paragraph 12`" -<> ----- -==== - -[example] -.Example that renders the reference with (multiple) hierarchical localities -==== -[source,asciidoc] ----- -// renders as: "ISO 712, Section 5, Page 8-10" -<> ----- -==== - -[example] -.Example of referencing locality with additional text -==== -[source,asciidoc] ----- -// renders as "ISO 712, 5:8-10" -// ("5:8-10" treated as replacement text for all the foregoing) -<> ----- -==== - -==== Discontinuous locality - -Discontinuous localities can be named by repeating the same locality type. - -[example] -.Example of referencing a discontinuous locality -==== -[source,asciidoc] ----- -// renders as "`page 4, page 7`" -<> ----- -==== - -Discontinuous localities can also be specified by delimiting sequences of -localities with semicolon [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.24] + - -[example] -.Example of referencing discontinuous hierarchical localities -==== -[source,asciidoc] ----- -// renders as "`Part IV, Chapter 3; Part VI, Chapter 9`" -<> ----- -==== - -==== Complex locality - -Complex relations between discontinuous references can be specified by -prefixing conjoining verbs to sequences of localities separated -by semicolon [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. - -This will result in overt connectives between the references, which will be -internationalised. - -Conjoining verbs include: - -* `and!` -* `or!` -* `from!` -* `to!` - -[example] -.Example of referencing a complex locality -==== -[source,asciidoc] ----- -// renders as: "`Chapters 3 and 7`" -<> ----- -==== - -[example] -.Example of referencing a complex locality that contains a hierarchical locality -==== -[source,asciidoc] ----- -// renders as: "Part IV, Chapter 3 or Part VI, Chapter 9" -<> ----- -==== - -NOTE: This is similar to the behavior in -link:/author/topics/document-format/xrefs/#combined-xrefs[Combination of cross-references]. - -As with cross-references, more than two references combined by "`and`" should be -marked up with semicolons. Internationalisation during rendering will take care -of separating the references by colon, and inserting any necessary conjunction -wording ("`and`"). - -[example] -.Example of referencing multiple references that are complex localities -==== -[source,asciidoc] ----- -<> -// or -<> ----- -==== - -NOTE: If references are joined with semicolons and connectives, but the locality is not supplied -for a cross-reference, it is filled in by referring to the preceding conjoined -cross-reference [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.0]. -For example, `<>` is -corrected internally to the more explicit `<>`. - -Trailing text after the sequence of `locality=reference` (or -`locality{space}reference`) is treated as custom text for the cross-reference, -as would occur normally in a typical cross-reference. - -The locality can appear in quotations if it contains special characters (like -dashes or commas). - -[[custom-locality]] -==== Custom locality - -Locality types not listed in <> are entered using the -"custom locality" functionality. - -Metanorma accepts a fixed list of locality types in cross-references (see -<>), which is not meant to be exhaustive of all possible -locality types. - -[example] -`annex` is recognized as a generic reference to annexes in documents, but it -does not recognize appendixes (instead of annexes), or as distinct from annexes -(as is the case in ISO deliverables). - -A custom locality is entered by prefixing the locality type with `locality:`. - -A custom locality has the following properties: - -* The locality type will be rendered as text preceding the equal sign. - -* The locality type shall not contain commas, colons, or space. - -* The locality type is meant to be valid for all languages. -+ -NOTE: The custom locality `locality:appendix` would be used for both English -and French texts. - -* Localization of custom locality types is managed through inclusion in the -internationalization YAML file for that language, which has to be customized -as part of the Metanorma flavor implementation. -+ -NOTE: The custom locality `locality:appendix` is realized as French _Appendice_ -through configuration in the Metanorma flavor implementation. - - -[example] -.Example of referencing a custom locality the `locality:` prefix -==== -This encoding: - -[source,asciidoc] ----- -<> ----- - -Renders as: - -____ -"ISO/IEC DIR 2, Annex SL, Appendix 2, Clause 3.2" -____ -==== - - -==== Locality plus custom text - -Any text after the bibliographic localities is still treated as custom -cross-reference text. - -As with references without localities, the custom cross-reference text is the -only text that is displayed in the document; but the cross-reference still -captures the specific locality of the reference, e.g. for cross-reference -generation. - -[example] -.Example of referencing with bibliographic localities with additional custom text -==== -[source,asciidoc] ----- -<> ----- - -rendered as: - -____ -the foregoing reference -____ -==== - -==== Anchor locality - -Exceptionally, the `anchor` locality is only used in HTML, to generate -anchor links to other HTML pages [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1]. - -It is intended for use with bibliographic anchors linking to URLs (`repo:()`, `path:()`): -see <> and <>. - - -[example] -.Example of using the `anchor` locality for rendering in HTML output -==== -The following input: - -[source,asciidoc] --- -<> - -... - -* [[[ISO7301,path:(./iso7301.html,ISO 7301)]]] --- - -will render in HTML as: - -[source,html] --- -ISO 7301, Clause 2, Table 1a, page 7-9 --- -==== - -==== Case and dropped locality labels - -The `capital%`, `lowercase%` and `droploc%` options used for internal -cross-references can also be used as prefixes to localities, modifying how those -localities are -rendered [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.9]. - - -[example] -.Example of using `droploc` in a citation locality -==== -[source,asciidoc] --- -// renders as "ISO 7301, 2" -<> --- -==== - -[example] -.Example of using `lowercase` in a citation locality -==== -[source,asciidoc] --- -// renders as "ISO 7301, clause 2" -<> --- -==== - -==== Styled cross-references - -As with link:/author/topics/document-format/xrefs#xref-styles[internal cross-references], cross-referenced -citations can have a `style` attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4]. -As of this writing, the only values allowed are the types of docidentifier value that can be substituted -for the primary identifier of the reference, for standards documents; those values will need to be looked up in -Relaton (and the Semantic XML of the document). For example, given the citation - -[source,xml] ----- - -... -ISO/FDIS 17664-1 -urn:iso:std:iso-fdis:17664:-1:ed-1:fr -... - ----- - -A crossreference `<>` will be populated by default with the primary or else the first -`docidentifier` value found, `ISO/FDIS 17664-1`. However, given `<>`, the -first `docidentifier` value of type `URN` will be sought instead, and the cross-reference -will be populated by default as `URN urn:iso:std:iso-fdis:17664:-1:ed-1:fr`. - - -=== Link-only references - -A standards document can be cross-referenced in Metanorma without that document -appearing in the document references. - -Such cross-reference is treated as equivalent to a cross-reference -to a hidden citation, as documented in <>. - -Link-only references can be added to Metanorma AsciiDoc using the following -command: - -[source,adoc] ----- -++std-link:[...]++ ----- - -Where the `std-link` command contains the same text as a normal cross-reference -to a standard, including localities and other directives. -There is no need for an explicit bibliographic entry. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. - -The following two examples are equivalent: - -[example] -.Link-only reference of ISO 123 using `std-link` -==== -[source,asciidoc] ----- -std-link:[ISO 123,droploc%clause=3] ----- -==== - -[example] -.Link-only reference of ISO 123 using a hidden citation -==== -[source,asciidoc] ----- -<> - -[bibliography] -== Bibliography - -* [[[ref1,hidden(ISO 123)]]] ----- -==== - -=== Combination of citations - -Simple citations can be combined with connectives, in a similar fashion to cross-references -(link:/author/topics/building/xrefs/#combined-xrefs[Combination of cross-references]), -and which will be internationalised as -appropriate [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. - -[example] -.Example of rendering a range of citations -==== -The following citation range: - -[source,adoc] ----- -<> ----- - -is rendered as: - -____ -From [3] to [7] -____ -==== - - == Reference processing flags === General diff --git a/author/topics/sections/concepts.adoc b/author/topics/sections/concepts.adoc index 5f5f5726..bba0af61 100644 --- a/author/topics/sections/concepts.adoc +++ b/author/topics/sections/concepts.adoc @@ -1992,7 +1992,7 @@ default, only the display text is rendered. To supplement the concept reference with a locality, the `bibliographic-anchor` element can be supplemented by a comma-delimited list of -link:/author/topics/document-format/bibliography#localities[localities and locality values], +link:/author/topics/document-format/inline_markup/citations#localities[localities and locality values], as is normal for a reference to a locality in an external document. [source,adoc]