Hi, In addition to what Eliot said, for the Oxygen user's guide we also have this rule of the topic ID equal to the file name. We impose it with a Schematron check along with a quick fix to change the ID if necessary, search for "Topic ID must be equal to file name": https://github.com/oxygenxml/userguide/blob/master/DITA/rules/rulesAdvanced.... Regards, Radu Radu Coravu Oxygen XML Editor On 4/2/23 18:42, ekimber@contrext.com wrote:

As Radu points out, the DITA specification does not require that topic IDs be unique beyond the scope of the XML document that contains them. In general, especially when using keys and with the addition of the “same topic” fragment identifier (‘#./some-element-id’), topic IDs are of little practical value because you almost never need to refer to them unless you nest topics within a single XML document. If you are using keys for all references to things outside of topics and you only have a single topic in each DITA source file, there is never a reason to refer to topic IDs in your DITA source.

I used to go out of my way to make the ID of every topic that is the root of its XML document “topicid” just to make the point that they don’t need to be unique.

However, as Radu also points out, many tools assume that DITA topic IDs are useful (they are not) and therefore make assumptions or impose requirements on them. These assumptions are unfounded and the requirements are misguided. Nevertheless, it is the case that many tools do this and it’s just not worth the effort to fight it.

At ServiceNow we use the practice of making the topic ID the same as the topic filename, because we also impose a filename uniqueness requirement on our content. Filename uniqueness is also not required by the DITA standard but it turns out to be really useful in practice, especially if you are using the “keyname == filename” practice for assigning keys to topics and images when you add them to maps, something Oxygen makes very easy to do.

One reason to make the topic ID the same as (or reflect, as you show in your template) the topic filename is that it makes correlating error messages that reflect the topic ID to the source topic easier—many DITA processes involve combining or modifying topics in a way that might change their organization into files, meaning that the original filename may be lost even though the original ID is retained (i.e., chunking as implemented in newer Open Toolkit versions, which only changes topic IDs when necessary to make the chunked result have unique topic IDs).

So as much as it pains me to say so, the practical implication for most of users of DITA content is that topic IDs should be unique across your content set.

Note, however, that this is still not sufficient for determining the anchors used in generated outputs—as long as there is reuse the output processor may need to generate new unique anchor values (i.e., HTML file names, PDF anchors, contextual help context IDs, etc.), in which case the original topic filename or ID cannot be preserved—at best it becomes the basis for the generated value (i.e., the way Open Toolkit adds “-1” to topic filenames when a topic is used as both a resource-only topic and a normal-role topic in the same root map context).

When you are using keys, those become a natural basis for generating output anchors and may be completely different from the topic’s filename or ID. Keys are necessarily unique within a root map and therefore serve as a reliable basis for output anchors when uniqueness of anchors within the deliverable is needed (which it usually is).

Another option is to use the <resourceid> element to provide hints for deliverable anchors. For DITA 2.0 we’ve extended the semantics of <resourceid> to make this explicit and you can anticipate that in a DITA 1.3 context by implementing your own handling of <resourceid> to determine output anchors.

And of course the ditavalref facility, with the ability to define key and filename prefix and suffix values, makes it possible to re-use topics in different parts of a map and ensure unique keys and filenames in the effective input to an output process.

Cheers,

E.

*From: *oXygen-user <oxygen-user-bounces@oxygenxml.com> on behalf of Frank Dissinger <frank.dissinger@cgs-oris.com> *Date: *Monday, March 27, 2023 at 3:44 AM *To: *Oxygen User Mailing List <oxygen-user@oxygenxml.com> *Subject: *[oXygen-user] IDs for new DITA topics

Hi all,

I understand that a topic ID must be unique within the scope of the root ditamap used for publishing the content.

FrameMaker, which I used previously, creates IDs of the type

id172OC0C03J7

So there is an arbitrary combination of 11 digits and letters.

In oXygen I have set the "DITA > ID Option" as follows:

${localName}_${id}

Which creates IDs of the following type:

task_rf2_vcg_ywb

So there is an arbitrary combination of only 9 characters, mostly letters. But perhaps sufficient for ensuring uniqueness...

However, when I use the "DITA > Insert > Insert New DITA Resource" command, oXygen does not honor the "ID Option" setting, but creates IDs which are identical to the file name.

This is not what I want and surely not suitable for ensuring uniqueness.

How can I get oXygen to honor the "ID Option" setting or make it otherwise generate IDs with arbitrary characters which are likely to be unique?

Regards,

Frank

--

*Frank Dissinger*

Documentation Manager

....................................................................

*CGS Publishing Technologies International GmbH*

*Email *frank.dissinger@cgs-oris.com | *Web* www.cgs-oris.com <http://www.cgs-oris.com/>

*Address*Kettelerstr. 24 | D-63512 Hainburg | Germany

*Phone*+49 6182 9626-27 | *Fax* +49 6182 9626-99

*Commercial register*Offenbach, HRB no. 21495

*Managing directors*Bernd Rückert, Christoph Thommessen

<https://www.cgs-oris.com/signatur>

_______________________________________________ oXygen-user mailing list oXygen-user@oxygenxml.com https://www.oxygenxml.com/mailman/listinfo/oxygen-user