References to non-existent/removed clauses

[zrgt]

As some clauses were removed in V3.1 ,there are currently references in .adoc files in branch IDTA-01002-3-1_preparation on removed clauses. We need to adapt texts there.

Example of reference to non-existing clause 12 in interfaces-payload.adoc:

see Clause 12.12.3 for further details on service specifications and profiles

We need to adjust texts before release

[sebbader-sap]

@zrgt what's the best practice for references in ASCIIDOC? Especially to keep it in the same way as for Part 1.

[zrgt]

@sebbader-sap sorry I didn't understand the question, could you explain it in more detail?

[sebbader-sap]

It's about two different topics, it just came to my mind when I read your initial finding:

1. The example you mention is wrong, it needs to be corrected.
2. In the previous PDF, statements like "... Clause 12.12.3 ... " had a link behind so the reader could immediately jump there. I expect to have a hyperlink available now that we are in the ASCIIDOC/website world. And I am just asking myself how this shall be done, how would we (the writers) know what the hyperlink to a certain paragraph was etc. I thought there were some ideas already, maybe in some Part 1 rounds but not sure anymore.

[zrgt]

@sebbader-sap I've already fixed all links/references/bib-refs/figure-refs/table-refs in Part 5 and Part 2. Please check the result e.g. Preamble of Part 5 and also see the raw code by clicking on "Edit this page".

In short:

• First thing you should do is to define an id for the figure/table/section etc. you want to reference. If you want to reference a document, you need its name.
  • You can define it with [[ELEMENT_ID]] or with [#ELEMENT_ID]
• Then you can reference this id in the text with:
  • xref:DOCUMENT.adoc[Link name] if you reference a Document in other .adoc file but in the same repo
  • xref:DOCUMENT.adoc[Link name]#ELEMENT_ID if you reference smth (e.g. Section/Figure) in other .adoc file but in the same repo
  • <<ELEMENT_ID>> if you reference smth in the same .adoc file

Example:

xref:aasx.adoc[] is an example of a reference for a document. 

xref:aasx.adoc#general[General] is an example of a reference for a section with ELEMENT_ID="general" in a document. 

<<general>> is an example of a reference for a section with ELEMENT_ID="general" in the same document. 

[[general]]
== General

Here we reference a figure: The following process in <<aasx-package-gen-and-use>> is defined for creating and consuming AASX packages.

.Process for Generating and Consuming AASX Packages
[[aasx-package-gen-and-use]]
image::aasx-package-gen-and-use.jpeg[]

For more info refer to antora documentation: https://docs.antora.org/antora/latest/page/xref/