Re: [oXygen-user] IDs for new DITA topics
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.sch
Regards,
Radu
Radu Coravu
Oxygen XML Editor
On 4/2/23 18:42, ekim...@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 element to provide hints for
deliverable anchors. For DITA 2.0 we’ve extended the semantics of
to make this explicit and you can anticipate that in a
DITA 1.3 context by implementing your own handling of 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 on behalf of
Frank Dissinger
*Date: *Monday, March 27, 2023 at 3:44 AM
*To: *Oxygen User Mailing List
*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
Re: [oXygen-user] IDs for new DITA topics
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 element to provide hints for deliverable anchors. For DITA 2.0 we’ve extended the semantics of to make this explicit and you can anticipate that in a DITA 1.3 context by implementing your own handling of 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 on behalf of Frank Dissinger Date: Monday, March 27, 2023 at 3:44 AMTo: Oxygen User Mailing List Subject: [oXygen-user] IDs for new DITA topicsHi 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 DissingerDocumentation ManagerCGS Publishing Technologies International GmbHEmail frank.dissin...@cgs-oris.com | Web www.cgs-oris.comAddress Kettelerstr.
