Re: [dita] Issue: Map element IDs and references to them

[Michael Priestley <mpriestl@ca.ibm.com>]

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 
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

Rob Frankland <robf@sockmonkeyconsult.com>

08/18/2009 06:33 PM

To	"Grosso, Paul" <pgrosso@ptc.com>
cc	dita <dita@lists.oasis-open.org>
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:robander@us.ibm.com]
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"
             <pgrosso@ptc.com>

    
To
  
             08/18/2009
05:34          "dita"
    
<dita@lists.oasis-open.org>
  
             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:robander@us.ibm.com]
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    
     <mpriestl@ca.ibm.com>
             PM
      
cc
    
               
                     
 dita
      
<dita@lists.oasis-open.org>
    
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
      mpriestl@ca.ibm.com
      http://dita.xml.org/blog/25


 Eliot Kimber
 <ekimber@reallysi.com>


      
To
    
 07/06/2009 09:27 AM        
                 dita

      
<dita@lists.oasis-open.org>
    
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:  ekimber@reallysi.com
<mailto:ekimber@reallysi.com>
      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