OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
  • 1.  Question from keys review: addressing non-topicref elements in a map

    Posted 05-07-2015 16:00
    DITAWeb URL: http://ditaweb.com/oasis-dita/#/Collaborate/00160583-FA_1/DB00074180/Using%20keys%20to%20address%20DITA%20elements Topic (title as it appears in the review): "Using keys to address DITA elements" Text in question, about the syntax for using keyref: For references to non-topic elements within topics and non-topicref elements within maps , the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element (for example, keyref="topic-key/some-element-id" .) Original comment thread: [Chris Nitchie] Non-topicrefs in maps? Whenever I need to conkeyref something into I do it by putting it in the of a topic bound to a key and conkeyref it from the topic. Does the OT permit referencing elements in a map via key? And what about topicref elements? Why wouldn't you need an element ID to reference those? A reference to a key is a reference to the content referenced by the effective key definition, not the topic ref itself. All of this is a long-winded way of saying I think we need to remove the phrase, "and non-topicref elements within maps". [Robert Anderson] This is word-for-word what appeared in DITA 1.2, apart from changing "solidus" to "slash", and adding "for example" to the example: http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_address_dita_elements.html But - I think I agree with Chris's comment. I don't know how it would be used for non-topicref element within a map. This needs to go to the TC. [Eliot Kimber] It is possible (if not particularly useful or recommend) to address any element in any map by ID (because all the elements take IDs). So the spec has to account for the case. That's why it was in 1.2 and needs to remain. My own additional commentary: For elements within topics, we always have the #topic/element syntax for linking with @href. So it's clear to me that when a key name resolves to a topic, "key/element" means the XML element with id="element" inside that topic. It maps easily to the @href syntax of #[variable-topic]/element. When referencing any element in a map (a topicref, a navtitle, a phrase inside link text), the syntax is file.ditamap#element or just #element. If we do in fact allow a key syntax of keyref="key/mapelement", I don't know how it resolves. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )


  • 2.  Re: [dita] Question from keys review: addressing non-topicref elements in a map

    Posted 05-07-2015 16:33
    I'd settle for removing the word 'non-topicref' so that it reads, "and elements within maps." If you bind a map to a key <mapref href= keys="mapKey"/> Then to reference any element in that map via key, keyref="mapKey/elementId". For example: <topicref conkeyref="mapKey/topicrefId"/> -or- <navtitle conkeyref="mapKey/someTitle"/> You'd use conkeyref instead of keyref on the former to pull in the whole branch, as opposed to referencing whatever content is referenced by that topicref. I don't think you could use conkeyref="someRandomKey" to effectively conref the key-defining topicref. Chris P.S. I'm on vacation this week and only checking e-mail occasionally, but I wanted to contribute my $0.02 while my thoughts were fresh. From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Robert D Anderson <robander@us.ibm.com> Sent: Thursday, May 7, 2015 11:58 AM To: DITA TC Subject: [dita] Question from keys review: addressing non-topicref elements in a map   DITAWeb URL: http://ditaweb.com/oasis-dita/#/Collaborate/00160583-FA_1/DB00074180/Using%20keys%20to%20address%20DITA%20elements Topic (title as it appears in the review): "Using keys to address DITA elements" Text in question, about the syntax for using keyref: For references to non-topic elements within topics and non-topicref elements within maps , the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element (for example, keyref="topic-key/some-element-id" .) Original comment thread: [Chris Nitchie] Non-topicrefs in maps? Whenever I need to conkeyref something into I do it by putting it in the of a topic bound to a key and conkeyref it from the topic. Does the OT permit referencing elements in a map via key? And what about topicref elements? Why wouldn't you need an element ID to reference those? A reference to a key is a reference to the content referenced by the effective key definition, not the topic ref itself. All of this is a long-winded way of saying I think we need to remove the phrase, "and non-topicref elements within maps". [Robert Anderson] This is word-for-word what appeared in DITA 1.2, apart from changing "solidus" to "slash", and adding "for example" to the example: http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_address_dita_elements.html But - I think I agree with Chris's comment. I don't know how it would be used for non-topicref element within a map. This needs to go to the TC. [Eliot Kimber] It is possible (if not particularly useful or recommend) to address any element in any map by ID (because all the elements take IDs). So the spec has to account for the case. That's why it was in 1.2 and needs to remain. My own additional commentary: For elements within topics, we always have the #topic/element syntax for linking with @href. So it's clear to me that when a key name resolves to a topic, "key/element" means the XML element with id="element" inside that topic. It maps easily to the @href syntax of #[variable-topic]/element. When referencing any element in a map (a topicref, a navtitle, a phrase inside link text), the syntax is file.ditamap#element or just #element. If we do in fact allow a key syntax of keyref="key/mapelement", I don't know how it resolves. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )


  • 3.  Re: [dita] Question from keys review: addressing non-topicref elements in a map

    Posted 05-07-2015 16:56
    That makes sense for cases where the key resolves to a map, but what if it resolves to a topicref? <topicref keys="chapter1" id="confused">...it's a point in the TOC...</topicref> Currently you can reference that with: keyref="chapter1" href= > If we remove the "non-topicref" elements, it would then state that 'for references to elements within maps, the value of @keyref is a key name plus slash plus element ID', which I think is incorrect here -- because you just use the key name to reference this topicref. Also, what would it mean if I encountered this, where chapter1 resolves to a topicref? keyref="chapter1/otherID" It makes me think that if we do allow the key/ID syntax for maps, then we have to explicitly say "for keys that resolve to a map document" or whatever wording best conveys that idea. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) Chris Nitchie ---05/07/2015 11:33:18---I'd settle for removing the word 'non-topicref' so that it reads, "and elements within maps." If you From: Chris Nitchie <chris.nitchie@oberontech.com> To: Robert D Anderson/Rochester/IBM@IBMUS, DITA TC <dita@lists.oasis-open.org> Date: 05/07/2015 11:33 Subject: Re: [dita] Question from keys review: addressing non-topicref elements in a map Sent by: <dita@lists.oasis-open.org> I'd settle for removing the word 'non-topicref' so that it reads, "and elements within maps." If you bind a map to a key <mapref href= keys="mapKey"/> Then to reference any element in that map via key, keyref="mapKey/elementId". For example: <topicref conkeyref="mapKey/topicrefId"/> -or- <navtitle conkeyref="mapKey/someTitle"/> You'd use conkeyref instead of keyref on the former to pull in the whole branch, as opposed to referencing whatever content is referenced by that topicref. I don't think you could use conkeyref="someRandomKey" to effectively conref the key-defining topicref. Chris P.S. I'm on vacation this week and only checking e-mail occasionally, but I wanted to contribute my $0.02 while my thoughts were fresh. From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Robert D Anderson <robander@us.ibm.com> Sent: Thursday, May 7, 2015 11:58 AM To: DITA TC Subject: [dita] Question from keys review: addressing non-topicref elements in a map DITAWeb URL: http://ditaweb.com/oasis-dita/#/Collaborate/00160583-FA_1/DB00074180/Using%20keys%20to%20address%20DITA%20elements Topic (title as it appears in the review): "Using keys to address DITA elements" Text in question, about the syntax for using keyref: For references to non-topic elements within topics and non-topicref elements within maps , the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element (for example, keyref="topic-key/some-element-id".) Original comment thread: [Chris Nitchie] Non-topicrefs in maps? Whenever I need to conkeyref something into I do it by putting it in the of a topic bound to a key and conkeyref it from the topic. Does the OT permit referencing elements in a map via key? And what about topicref elements? Why wouldn't you need an element ID to reference those? A reference to a key is a reference to the content referenced by the effective key definition, not the topic ref itself. All of this is a long-winded way of saying I think we need to remove the phrase, "and non-topicref elements within maps". [Robert Anderson] This is word-for-word what appeared in DITA 1.2, apart from changing "solidus" to "slash", and adding "for example" to the example: http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_address_dita_elements.html But - I think I agree with Chris's comment. I don't know how it would be used for non-topicref element within a map. This needs to go to the TC. [Eliot Kimber] It is possible (if not particularly useful or recommend) to address any element in any map by ID (because all the elements take IDs). So the spec has to account for the case. That's why it was in 1.2 and needs to remain. My own additional commentary: For elements within topics, we always have the #topic/element syntax for linking with @href. So it's clear to me that when a key name resolves to a topic, "key/element" means the XML element with id="element" inside that topic. It maps easily to the @href syntax of #[variable-topic]/element. When referencing any element in a map (a topicref, a navtitle, a phrase inside link text), the syntax is file.ditamap#element or just #element. If we do in fact allow a key syntax of keyref="key/mapelement", I don't know how it resolves. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ )