|
| 1 | +<?xml version="1.0" encoding="UTF-8"?> |
| 2 | +<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd"> |
| 3 | +<topic id="topic_s4k_q5r_vj"> |
| 4 | + <title>Questions/Issues/Observations on 13004 Scoped Keys</title> |
| 5 | + <body> |
| 6 | + <p>Questions/concerns rising from my attempt to apply scoped keys to a |
| 7 | + real-world example.</p> |
| 8 | + <ol |
| 9 | + id="ol_qh2_t5r_vj"> |
| 10 | + <li>Should it be possible for the same scope to have multiple keyscope |
| 11 | + names? That would make it possible to have the same physical scope |
| 12 | + referenced by different qualified names. This would be parallel with |
| 13 | + @keys.<p>Without this I don't see a way to alias a scope with a |
| 14 | + different key scope, unless you can do something |
| 15 | + like:<codeblock><topicref keyscope="scope-y" keyref="scope-x-root"/> |
| 16 | +<topicref keyscope="scope-x" keys="scope-x-root"> |
| 17 | + ... keys defined in scope-x ... |
| 18 | +</topicref></codeblock></p><p>Would |
| 19 | + the above be taken to mean that references to "scope-y.foo" resolve to |
| 20 | + keys defined in scope "scope-x"? I don't think that behavior is |
| 21 | + necessary from the current proposal.</p></li> |
| 22 | + <li>When there are scopes, topics intended for use within a scope have to |
| 23 | + know when to use unscoped keys and scoped keys. That is, authors of |
| 24 | + topics will need to know which references are to keys that are expected |
| 25 | + to be local to whatever scope the topic is used in and which are not |
| 26 | + local. I think this is reasonable but it bears repeating. I think this |
| 27 | + case is the same as for cross-publication links. You either know your |
| 28 | + link is *always* cross-scope or cross-publication or you don't. If you |
| 29 | + don't you assume it is local to the current scope or publication. I |
| 30 | + suppose for keys for which authors are unsure they could use a third |
| 31 | + qualifier like "possibly-scoped" and let the using map author sort it |
| 32 | + out.<p>I think this ends up being a question of how topic authors come |
| 33 | + to know about the keys they should use when creating references. One |
| 34 | + would expect that there are normally business rules in effect, possibly |
| 35 | + enforced or guided by authoring or content management systems.</p></li> |
| 36 | + <li>If I have a map that specifies @keyscope and then include that map via |
| 37 | + mapref, I really want to be able to specify the key scope name on the |
| 38 | + mapref so that I know, given only the declarations in the local map, |
| 39 | + what the keyspace name used for peer map is--meaning I don't have to |
| 40 | + dereference the peer map and examine it in order to discover that it |
| 41 | + defines a scope (which I need to know in order to process key references |
| 42 | + in the context of the local map).<p>I think this means that when a |
| 43 | + <mapref> element specifies @keyscope it establishes a name for the |
| 44 | + scope defined by the referenced map. If the referenced map also |
| 45 | + specifies @keyscope, it establishes a single-level key scope, not a two |
| 46 | + level keyscope. </p><p>That is, the effect |
| 47 | + of:<codeblock>Map A: |
| 48 | +<map><title>Map A</title> |
| 49 | + <mapref keyscope="map-b" href="map-b.ditamap"/> |
| 50 | + ... |
| 51 | +</map> |
| 52 | + |
| 53 | + |
| 54 | +Map B: |
| 55 | +<map keyscope="map-b"> |
| 56 | + <topicref id="ref-in-map-b"> |
| 57 | + ... |
| 58 | + </topicref> |
| 59 | + ... |
| 60 | +</map></codeblock></p><p>is |
| 61 | + equivalent |
| 62 | + to:<codeblock><map><title>Map A</title> |
| 63 | + <topicgroup keyscope="map-b"> |
| 64 | + <topicref id="ref-in-map-b"> |
| 65 | + ... |
| 66 | + </topicref> |
| 67 | + </topicgroup> |
| 68 | + ... |
| 69 | +</map></codeblock></p><p>and |
| 70 | + not:</p><codeblock><map><title>Map A</title> |
| 71 | + <topicgroup keyscope="map-b"> |
| 72 | + <topicgroup keyscope="map-b"> |
| 73 | + <topicref id="ref-in-map-b"> |
| 74 | + ... |
| 75 | + </topicref> |
| 76 | + </topicgroup> |
| 77 | + </topicgroup> |
| 78 | + ... |
| 79 | +</map></codeblock><p>This |
| 80 | + also implies that scopes defined in peer maps are <b>not</b> usable from |
| 81 | + local maps, avoiding any requirement to do full key space construction |
| 82 | + of peer maps in order to resolve keyrefs from the local map.</p><p>Given |
| 83 | + this rule I think it gives you same addressing facility I was trying to |
| 84 | + define in my cross-publication proposal, that is, a single identifier |
| 85 | + for the peer key space and no more.</p></li> |
| 86 | + <li>The practical implications for scopes defined in standalone |
| 87 | + keydef-containing maps could be non-obvious and tricky. There's a lot of |
| 88 | + indirection involved and it could get quite confusing an non-obvious |
| 89 | + with regard to what it means, for example, to have a <keydef> element |
| 90 | + define a scope.<p>I think in that case it means that the resource |
| 91 | + defined by that key can only be referenced by a scope-qualified |
| 92 | + reference. That may not be obvious to all users.</p></li> |
| 93 | + <li>In the case where you have a map that defines a key scope and that map |
| 94 | + references a peer map and assigns it a scope (per item 3 above), then |
| 95 | + references to that scope still only need to be qualified with the |
| 96 | + peer-map's scope name, because all topics referenced from within the |
| 97 | + local map will be in the same (or descendant) scope context as the peer |
| 98 | + map reference.<p>This means that if you always include your peer maps |
| 99 | + within your using map's root scope, then references to keys on those |
| 100 | + peers will always only require a single scope qualification term (e.g., |
| 101 | + "peer-map.foo", <b>not</b> "my-local-map-scope.peer-map.foo").</p></li> |
| 102 | + <li>For Open Toolkit, with generate-outer of "2", the peer deliverable |
| 103 | + as-delivered maps need to be in the same directory tree as the root map, |
| 104 | + otherwise, the Toolkit can't find them. This means that these maps need |
| 105 | + to have either absolute URLs or URLs relative to the location of the |
| 106 | + using root map, not relative to the peer root map. When the files are |
| 107 | + organized in this way, the cross-deliverable links are correctly |
| 108 | + generated by normal toolkit processing.<p>When generate-outer is "3", |
| 109 | + then the as-delivered maps can live with the maps they reflected, but |
| 110 | + the output directory will be below where it might otherwise be expected |
| 111 | + to be.</p></li> |
| 112 | + <li>When the target of the xref is a complete topic, then if there is a |
| 113 | + navtitle for the keydef (which the Toolkit claims is required, which it |
| 114 | + probably is), then the link text used is the navtitle.<p>However, if the |
| 115 | + target of the xref is an element within the topic (e.g., a figure), then |
| 116 | + the link text is the URL of the target. Not clear how to provide the |
| 117 | + link text in that case without modifying the xref itself, since there is |
| 118 | + no indirection element for the target element, only the topic. This |
| 119 | + supports the argument that we need an indirection facility for |
| 120 | + references to elements within topics as well as to topics as we have |
| 121 | + with keys. On the other hand, if we have to generate intermediate copies |
| 122 | + of all the topics then that process can also set the xref text, although |
| 123 | + this requires processing the peer documents in order to get the |
| 124 | + appropriate link texts for each target element.</p><p>One solution might |
| 125 | + be to add metadata to the keydef used by the xref-to-element-with-topic |
| 126 | + to provide a mapping of element IDs to link text. This would be done as |
| 127 | + part of the process of generating the as-delivered key definitions for |
| 128 | + each publication. Essentially, for each element within a topic with an |
| 129 | + ID you'd need to generate an ID-to-link text mapping in the generated |
| 130 | + keydef. Hmm. You have to do all IDed elements because you can't know |
| 131 | + what elements might be linked to from other deliverables.</p></li> |
| 132 | + </ol> |
| 133 | + </body> |
| 134 | +</topic> |
0 commit comments