Extensions for varying link style application

asam-ev / asam-project-guide

(WIP!) Project Guide for ASAM OpenX standards

Mozilla Public License 2.0

2 stars 0 forks source link

Extensions for varying link style application #153

Closed philipwindecker closed 2 years ago

philipwindecker commented 2 years ago

Source: @christian

Links to Figures, Tables, Examples, and in continuous text

Different xrefstyles for links to Figures, Tables, Examples, and in contentious text are required:

Figures, tables, and examples shall be displayed using :xrefstyle: short, for example, Figure 1, Table 1, Example 1 and so on.
Links in continuous text shall be displayed using :xrefstyle: full, for example, Section 1.2.3, "Sausages are so delicious"
Links to Figures, Tables, and Examples have to be tagged using AsciiDoc syntax, for example, <<fig-d8700b83-c9e9-4205-9df4-b9fc0ada3700>>
Links within continuous text have to be tagged using Antora xref syntax, for example, xref:domain-model:road_abstractions.adoc#top-roads-class-route[]

The extension shall identify the type of link and its occurrence and generate links on the logic mentioned above.

philipwindecker commented 2 years ago

Note: Content analysis is required for osc2 as anchors are not used consistently. I.e. "sec-" and "top-" may not point towards a page top or section. Since most content will be :xrefstyle: short, this is assumed to be the default. Idea: Make it configurable through site.yml whether replacement will be "short" or "full". However, only section links will be updated for now.

TODO for later: Check if all figures and tables are referenced locally or globally.

christiangoedert commented 2 years ago

There is one exception for not using :xrefstyle: full for links in continuous text. If a specific link text exists, just the link text shall be displayed. For example, xref:domain-model:dm_actions_and_modifiers.adoc#sec-dm-actions-specialized-action[Specialized actions] shall be displayed "Specialized actions".

philipwindecker commented 2 years ago

There is one exception for not using :xrefstyle: full for links in continuous text. If a specific link text exists, just the link text shall be displayed. For example, xref:domain-model:dm_actions_and_modifiers.adoc#sec-dm-actions-specialized-action[Specialized actions] shall be displayed "Specialized actions".

Already taken under consideration in my current developments :)

philipwindecker commented 2 years ago

List of tasks:

[x] Add xrefstyle=full to all xref macros without options (i.e. alt texts)
[x] Make xrefstyle configurable for extension
[x] Add automatic reftext attributes to all pages (to simluate "full" behavior for page references in Antora)
[x] For references to anchors on external pages, determine title of content of anchor and simulate xref link text

philipwindecker commented 2 years ago

Implemented and tested with osc2. After some bugfixes, all seems to be okay right now. Closing issue.