Next in thread →
Next in month →
RE: [dita] Issue: Map element IDs and references to them
This discussion started out about the uniqueness of ids in maps, but what we’ve been talking about is really more about uniqueness of IDs in topics or I guess about uniqueness of IDs in both topics and maps. Does this matter? I’m guessing not. And the recent discussion has been about non-unique id values added by using conref. Is conref the only way to create non-unique ids? What about Key References? Does whatever wording we come up with for the DITA 1.2 spec. need to limit the non-unique ID processing issue to IDs created by conref or keyref or can we make this a more general discussion without any limitation? I’m thinking that more general is the way to go for DITA 1.2 at least. Michael wrote: > So: we are accepting that a processor may solve this in any way they wish for 1.2, and we recommend no particular course of action. I think this is right. But we are going to add something that says something along these lines: Because some DITA id attributes are true XML IDs and others are not, the uniqueness of id attribute values within DITA documents is not enforced by validating XML parsers. Never-the-less ID values within maps and topics should be unique. Aren’t we? Or perhaps something longer that says: Because some DITA id attributes are true XML IDs and others are not, the uniqueness of id attribute values within DITA documents is not enforced by validating XML parsers. Never-the-less ID values within maps and topics should be unique. If an id value is not unique, processors should recover from the error, continue processing, and should produce a warning message. And is “should” want we want to say about warning messages or do we want to make this, “may, but are not required to, produce a warning message”. I don’t feel strongly about this point. -Jeff From: Michael Priestley [mailto:] Sent: Wednesday, August 19, 2009 9:53 AM To: Grosso, Paul Cc: dita Subject: RE: [dita] Issue: Map element IDs and references to them Fair enough. 1.3 it is. I'll add that in the 2b case, you'd also want to know whether the reference should point to the original, or to the original as reused. Just because something's conref'd in place A doesn't mean it's not also directly included in place B. My assumption was that the format of the reference (which includes the id of the containing topic) would remove all ambiguity, but that brings up questions of processing order, and leaves unsolved the edge case of conrefs that pull in whole branches of topics. So: we are accepting that a processor may solve this in any way they wish for 1.2, and we recommend no particular course of action (though I personally would freak out if they solved it by changing the local id). Michael Priestley, Senior Technical Staff Member (STSM) Lead IBM DITA Architect http://dita.xml.org/blog/25 "Grosso, Paul" <> 08/19/2009 09:40 AM To "dita" <> cc Subject RE: [dita] Issue: Map element IDs and references to them I don't know how common certain things are with conrefs at this point. But assuming dita's conrefs are generally supposed to replace the need for XML's parsed entity references, I've certainly seen referenced entities that contain id/idref pairs. You're missing a 2b case below: that id in the content being conreffed in is referenced from a different topic that you are also pulling into your map from somewhere else. Once you do fixup on that pulled in id, the from-other-topic reference to it is broken. So, to answer your question, we don't stop worrying, but we put off trying to come up with any solution until post-DITA 1.2. It's too complex an issue to try to solve in a big hurry (and 1.2 is already late enough that we shouldn't take the time that would be necessary to fix it now). paul From: Michael Priestley [mailto:] Sent: Tuesday, 2009 August 18 17:51 To: Rob Frankland Cc: dita; Grosso, Paul Subject: Re: [dita] Issue: Map element IDs and references to them Just to check - how common is it for a conref'd element to contain internal elements that reference each other? It seems like we're dealing with an edge case of an edge case. I'm guessing it could happen - maybe in a large table with multiple footnote definitions, and the whole table gets conref'd - but I wouldn't think it was common. Also, Rob just to clarify - any fix would be applied at processing time, and not to the original source. We're not talking about touching or editing the source. This is the way I'm thinking of it: 1- main case: you conref in something, it doesn't contain elements with ids, or the ids are unique in the new context - no problem 2- exception: the thing you conref'd in contains an id that's already in use by the conreffing topic or map - adjust the id of the thing being pulled in, since we know it's not being referenced, and the other (local) id might be - eg by another topic or map 3- extra exception: the thing you conref'd in contains both an id, and a reference to the id - so adjust them both (you'd need to adjust the reference anyway) - again, preserving the id of the local element since it could be referenced by some other topic we're not aware of. As Paul points out, there's a proposal for 1.3 that would take care of case 3. Does that mean we stop worrying about case 2? The proposal for 1.3 doesn't address case 2. I'll back off the SHOULD if that makes people uncomfortable - but let's at least put a MAY in. Some kind of hint that the norm is changing the id of the thing being pulled in, rather than the local id it conflicts with (assuming I can convince Rob that that's preferable). Michael Priestley, Senior Technical Staff Member (STSM) Lead IBM DITA Architect http://dita.xml.org/blog/25 Rob Frankland <> 08/18/2009 06:33 PM To "Grosso, Paul" <> cc dita <> Subject Re: [dita] Issue: Map element IDs and references to them Paul got my point exactly. This is really difficult, you cannot assure that an ID is unique and any fix will almost assuredly make a bad reference now or in the future. The crux of the matter is that currently DITA encourages reuse of this type without any way to check validity before processing - correct? Rob Grosso, Paul wrote: -----Original Message----- From: Robert D Anderson [mailto:] Sent: Tuesday, 2009 August 18 17:00 To: Grosso, Paul Cc: dita Subject: RE: [dita] Issue: Map element IDs and references to them Possibly - but to get the inside-section link to work, additional work would still be required. Unless your topic IDs are all identical -- you'll have this section: <section id="thing"> <title>This is a silly section</title> <note id="test">note that IDs can be a problem</note> <p>Look at that note: <xref href=""#other/test"/> </section> If that is pulled unchanged into another topic with no modification, you will end up with a reference to "#other/test" ... meaning you will most likely have a broken link, because the new topic doesn't have id="other". Right, but that's a problem we already know we need to fix (and we know how to fix it); see DITA 1.3 proposal 13001 at http://wiki.oasis-open.org/dita/DITA_1.3_Proposals If the referencing topic, as in the sample below, has id="something", and the target topic has id="other", then for the link to remain valid as a link, you'll have to do one of these: 1) Change the value to #other/test -- but if "test" is now duplicated, you have the problem we've been trying to resolve. 2) Change the value to point to the original target - othertopic.dita#other/test - but this takes you out of the file, which I'd guess is never the desired or expected result 3) Change the note to "test-gen1" and change the reference to "#something/test-gen1" - this is what my code does now, because (to me) it seemed closest to the author's and reader's intent. That is, within that block, the link stays valid and it stays local to that block. Once we've implemented proposal 13001, you won't have to do anything if the referencing topic doesn't have id="test" anywhere--and having to do nothing to make this work is as it should be. If the referencing topic does have id="test", that's the problem we're discussing where Rob suggests having some kind of "fixup" of the ids in the referencing document instead of in the referenced document. Not that that's necessarily the best solution either. Which is why it isn't clear we should be defining a particular solution for DITA 1.2. Whether Michael's "shoulds" are optional enough to be acceptable is open for question. RFC 2119 says SHOULD means "that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course." I'm not sure we, ourselves, understand the full implications yet. My view on that is - if one of my other topics links to "test" within topic "something", then I have created that link because I want to go to the element I've defined in there with id="test". Likewise, if somebody else has linked to "test" within my topic, then they're linking to the element that actually exists there with id="test". I also want that link to be reliable, regardless of what other IDs people add within section I'm reusing. If we go the other way, we also run in to the equivalent problem over in topic "other". What happens when we have this, and the conref pulls in a phrase with id="test": <section id="thing"> <title>This is a silly section</title> <note id="test">note that IDs can be a problem</note> <p>Look at that note: <xref href=""#other/test"/> <p conref="a.dita#nother/thing"/> </section> If we have to modify the original, then the local xref is broken because it now goes to a phrase instead of the note. Right, id fixup--regardless of where you do it--always implies fixing up both ids and idrefs. This is not an easy issue--which is why I don't think we should be defining specific processing for DITA 1.2. This will take a lot more thought; we should tackle this much more deliberately in DITA 1.3. paul Thoughts? Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit "Grosso, Paul" <> To 08/18/2009 05:34 "dita" <> PM cc Subject RE: [dita] Issue: Map element IDs and references to them But Rob's point (I believe) is what if the silly section had an xref to the note with the id="test"? After conreffing it into your topic, that xref will now link to something completely different than the author of the silly section intended. paul -----Original Message----- From: Robert D Anderson [mailto:] Sent: Tuesday, 2009 August 18 16:30 To: Rob Frankland Cc: dita Subject: Re: [dita] Issue: Map element IDs and references to them Hi Rob, More specifically, the issue is this one - say I have this topic: <topic id="something"> <title>Sample topic</title> <body> <p id="test">This is a sample</p> <section conref="othertopic.dita#other/thing"/> </body> </topic> Now - what happens when the referenced section brings in an element that has id="test"? If the owner of that other topic randomly adds id="test" to a note within that section, I should not have to change the ID on my paragraph in order to make my conref valid - I should be able to reuse without fear of breaking my own topic. So, the second bullet in Michael's note is specifically talking about how the processors work when that id="test" value gets pulled into the section in this topic. The suggestion is that, if "test" already exists in this topic, the ID somehow be mangled so that the original can still work. So, the result after conref would be something like: <topic id="something"> <title>Sample topic</title> <body> <p id="test">This is a sample</p> <section> <title>This is a silly section</title> <note id="test-gen1">note that IDs can be a problem</note> </section> </body> </topic> Anybody already linking or conref'ing to the id "test" within this topic will still be safe, and still get the item they expected. Does that make sense? Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit Rob Frankland <robf@sockmonkeyc onsult.com> To Michael Priestley 08/18/2009 05:19 <> PM cc dita <> Subject Re: [dita] Issue: Map element IDs and references to them In the second bullet shouldn't it be the local ID that gets changed. If the ID of the one being brought is changed, will cause problems in the original use of the ID. Local author has the much safe ability to change value of the ID. Rob -- Rob Frankland Sock Monkey Consulting, LLC 12408 Kallgren RD NE Bainbridge Island, WA 98110 Landline: 206-780-8850 Cell: 206-963-5541 Michael Priestley wrote: OK, Robert talked some sense into me off-line. I now get Eliot's point during the call today that a link into the substructures of a conref'd section (for example) is not reliable, if only because it requires that link resolution be done as a second pass, after conref resolution, where many processes may be resolving both conrefs and links at the same time as part of a resolve-references pass. I also get Jeff's point about the closest target being preferable to the first target: for example, if I have an xref to a list item, both in the same document, then I'd want it to continue working even after I conref in something between them that introduces a duplicate id. So in this case, same document=closer. That said, I still want our behaviors to be predictable, ie the same across processors. But I don't want to make a backwards-incompatible change either, if I can avoid it. So how about: - map documents, and individual topics, SHOULD NOT contain duplicate ids on their elements (note should not, rather than must not) - conrefs that bring in an element with an id that already exists in the conreffing context SHOULD change the id of the element being brought in, to avoid creating a collision (again note should not rather than must not) That should give a rule similar to what Jeff described in the call today, and makes it recommended but not required. Michael Priestley, Senior Technical Staff Member (STSM) Lead IBM DITA Architect http://dita.xml.org/blog/25 Eliot Kimber <> To 07/06/2009 09:27 AM dita <> cc Subject [dita] Issue: Map element IDs and references to them There appears to be serious inconsistency between what at least I understand our decisions about addressing elements within maps to be and what the arch spec says. In addition, the arch spec as currently drafted is inconsistent on this matter. In particular, we have established that the fragment identifier for elements within maps is simply the @id attribute value, e.g. "#sometopicref". However, the draft arch spec says this under "Map IDs and element IDs within a map": "The id attributes for other elements in map are not of type ID and are not required to be unique." If this statement is true then a fragment identifier consisting of just the element ID is not sufficient to enable reliable addressing of elements within maps. So something has to give. I see the following possible solutions: A. Define a rule for resolving ambiguous references, e.g. "first occurrence in document order". This probably reflects current behavior of most implementations. B. Require element IDs to be unique within map documents. Note that because of shared elements between topics and maps, it's not possible to declare the ID attribute for most elements to be of type ID, so this requirement has to be validated by processors. C. Make topicref IDs XML IDs and scope all other element IDs to the nearest ancestor with a specified @id attribute (or the map element, whichever is nearer). Allow two-part fragment identifiers. Single-part fragment identifiers address the first occurrence in document order. Option (A) is the simplest to implement but the least complete. Option C is the most complete but changes current processing and address resolution behavior. As for use cases, references to topicrefs is the primary use case for pointing to elements within maps, but certainly the current spec doesn't disallow other references and there could be reasons to, e.g., data-about, conref from "resource" maps, etc. Cheers, Eliot ---- Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc. email: <mailto:> office: 610.631.6770 | cell: 512.554.9368 2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403 www.reallysi.com <http://www.reallysi.com> | http://blog.reallysi.com <http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com> --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php -- Rob Frankland Sock Monkey Consulting, LLC 12408 Kallgren RD NE Bainbridge Island, WA 98110 Landline: 206-780-8850 Cell: 206-963-5541
Next in thread →
Next in month →