Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

ID handling for conrefered structures

Open
  • Is something wrong?
#5 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Bug
Clarity
Needs clarification
Activity status
Stale
Tech stack
xml
Domain
documentation, tooling

Research direction

Start with the attached ID-handling-normalizeDITA.zip and reproduce the duplicate-ID cases described for repeated and nested conrefs. Compare the generated output IDs across each cascade; done means the intended ID-selection behavior is defined and duplicate IDs no longer occur within a topic.

Written by the indexing model from the issue text.

Description

How this plugin handles IDs in conrefered contend depends on the nesting context and can result in output files with duplicate IDs:

  • If a conrefered element contains an ID the plugin ignores this for the output element.
    Source: <conref> --> <ph id=”ABC”>
    Output: <ph>

  • If a conrefered element contains other elements with IDs the plugin generates new IDs for these elements in the corresponding output elements.
    Source: <conref> --> <ph id=”ABC”><ph id=”DEF”>
    Output: <ph><ph id=”djpigfv”>
    But it generates for each conref target only one publication wide ID.
    If a conref is used several times within a topic (e. g. product name variables) we get duplicate IDs in the output.

  • If an element with conkeyref attribute on top level contains a ID there are two possible outputs:

  1. If the conrefered element contains another conkeyref the ID of this target will be set as output ID all other IDs (top-level and all lower conreference levels) are ignored.
    Source: <conref1 id=”ABC”> --> <conref2 id=”DEF”> --> <conref3 id=”GHI”>
    Output: Output ID from conref 2 id=“DEF”
  2. If the conrefered element is not a conreference element by itself the top-level ID is set as output ID
    Source: <conref1 id=”ABC”> --> <ph id="DEF"><conref2 id=”GHI”> --> <conref3 id=”JKL”>
    Output: Output ID from conref 1 id=“ABC”

("top-level" means the conreference cascade chain starting point)
("low-level" means the last conrefered target in chain finaly rendered)

I am not shure about the intended handling but first of all it would be good to prevent duplicate ID generation within a topic. Is it possible to generate new IDs for each use case of a conref target or to set a suffix?
Otherwise maybe it would be possible to controll ID generation of nested elements using something like -dita-use-conref-target.

Additionally I would like to get the original id values rendered to the output files instead of new generated.

In my opinion the described cases 1. and 2. should grab IDs from the same level: "ABC" (top level) or "DEF" (second level).

Testing Files:
ID-handling-normalizeDITA.zip

Dominant language
XSLT
Stars
6
Forks
3
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from dita-ot/org.dita.normalize

All issues in dita-ot/org.dita.normalize

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.