OASIS Darwin Information Typing Architecture (DITA) TC

This was my todo from last week's mtg - sorry I'm leaving it to the wire. This describes a solution that can be implemented today - I still think there more work to be done, including: -  a general solution for key scoping (but not deliverable-based scoping since the boundaries of deliverables are mutable, as I'm trying to show here). - a standardized approach for cross-deliverable referencing - if we want to encourage this approach, for example, or propose an alternative - but we should be providing some guidance to vendors on how to implement so that the solution is cross-vendor compatible scenario: - we need to produce PDFs for each chapter of a book, as well as a single big PDF that contains all chapters - the chapters contain cross-references to content in other chapters, which needs to be resolved as a cross-deliverable link in the single-chapter PDFs but as a local link in the single big PDF case - each chapter is represented by a separate map - each topicref in the map has a uniquely addressable key (using whatever general scoping mechanism we choose to implement) - the book as a whole is represented by a master map that pulls in the others solution for individual chapter case: - for each chapter, execute a partial PDF build, which does not transform the content but does preprocess the map to turn each topicref href into a form appropriate for the deliverable being produced (ie, including the filename of the PDF being produced, with appropriate anchor syntax)         this results in a deliverable-specific set of key mappings - for each chapter, create a master map that includes the chapter being built and then resource-only inclusions of the deliverable-specific maps for all other chapters - for each chapter's master map, execute a full PDF build         this results in a chapter-level PDF with all links to other chapter resolved correctly solution for whole book case: - build normally Michael Priestley, Senior Technical Staff Member (STSM) Lead IBM DITA Architect mpriestl@ca.ibm.com http://dita.xml.org/blog/25

Unless I'm misunderstanding, this doesn't address my scenario at all. Given two root maps Map A and Map B, each to be produced as a separate standalone PDF, the question is: How does an author of Map A define a key that references a key defined in Map B's key space? E.g., I define key "key-x-in-map-B" and then author a reference to that key from some topic used in Map A, e.g.: <xref keyref="key-x-in-map-B">X in B</xref>. To process this, the processor has to know what a reference to a specific key name becomes in the rendered output so that the rendition contains a working link from the PDF for Map A to the PDF for Map B. There's lots of ways to implement this, but the most obvious is to have some deterministic processor that always produces the same result for a given key name/key space pair so that the processor of Map A can blindly generate references in Map A's PDF to the eventual corresponding anchors in Map B's PDF. This might require a run-time parameter that specifies the delivery location of the two PDFs so that if relative URLs are to be constructed, they can be constructed reliably. But the essential bit here is having the key definition *as authored* be an unambiguous reference to a key in the scope of Map B's key space. I don't see that we have a way to do that in DITA 1.2. Note that the only thing I'm concerned with is the markup in the content as authored--given an unambiguous address, the processing implementation is an exercise in engineering and is uninteresting. If there is no unambiguous address then there is no generalized processing that will work except by accident or unenforceable convention. In particular, it *cannot be correct* to author the key definition in this scenario where the URL is to the resource *as rendered*. It must be to the resource *as authored*. That is a fundamental requirement because without that, you cannot have generic content to which any processing may be applied with consistent and predictable results. As an author I want to say "I am linking to this *content* thing in this other publication" and I want links to that thing to work correctly in all possible renditions. "Work correctly" is rendition dependent, but the author's intent and their markup is rendition independent. Cheers, E. On 9/6/11 9:19 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote: > > This was my todo from last week's mtg - sorry I'm leaving it to the wire. > > This describes a solution that can be implemented today - I still think there > more work to be done, including: > > - a general solution for key scoping (but not deliverable-based scoping since > the boundaries of deliverables are mutable, as I'm trying to show here). > - a standardized approach for cross-deliverable referencing - if we want to > encourage this approach, for example, or propose an alternative - but we > should be providing some guidance to vendors on how to implement so that the > solution is cross-vendor compatible > > scenario: > - we need to produce PDFs for each chapter of a book, as well as a single big > PDF that contains all chapters > - the chapters contain cross-references to content in other chapters, which > needs to be resolved as a cross-deliverable link in the single-chapter PDFs > but as a local link in the single big PDF case > - each chapter is represented by a separate map > - each topicref in the map has a uniquely addressable key (using whatever > general scoping mechanism we choose to implement) > - the book as a whole is represented by a master map that pulls in the others > > solution for individual chapter case: > - for each chapter, execute a partial PDF build, which does not transform the > content but does preprocess the map to turn each topicref href into a form > appropriate for the deliverable being produced (ie, including the filename of > the PDF being produced, with appropriate anchor syntax) > this results in a deliverable-specific set of key mappings > - for each chapter, create a master map that includes the chapter being built > and then resource-only inclusions of the deliverable-specific maps for all > other chapters > - for each chapter's master map, execute a full PDF build > this results in a chapter-level PDF with all links to other chapter > resolved correctly > > solution for whole book case: > - build normally > > Michael Priestley, Senior Technical Staff Member (STSM) > Lead IBM DITA Architect > mpriestl@ca.ibm.com > http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com

Hi Eliot, I believed your scenario was covered in my case of multiple chapters being produced as separate PDFs. In that scenario, the author of Map A does not define a key that references a key defined in map B - they simply include map B's definition of map B's keys, after it has gone through processing to produce a deliverable-specific version of that key definition. I believe my scenario shows how cross-deliverable referencing could work without using map-specific addressing. I believe map-specific addressing is problematic because it doesn't actually tell us what the deliverable-specific address will be. You assume some automated process that will allow automatic association - but I believe that is too large an assumption to make. If I am addressing content from a deliverable produced by another team, we would all have to agree on that automatic processing rule - which requires upfront coordination even greater than that required to ensure unique keys. The only time we can know what a deliverable's addressing scheme will be (ie what the hrefs should resolve to) is when the deliverable is built. That's why I have a deliverable-specific map being built as part of the deliverable build, which can then be incorporated into the keyspace for other deliverables to enable cross-deliverable links for a given set of deliverables. Michael Priestley, Senior Technical Staff Member (STSM) Lead IBM DITA Architect mpriestl@ca.ibm.com http://dita.xml.org/blog/25 From: Eliot Kimber <ekimber@reallysi.com> To: Michael Priestley/Toronto/IBM@IBMCA, dita <dita@lists.oasis-open.org> Date: 09/06/2011 11:01 AM Subject: Re: [dita] Scenario for cross-deliverable referencing Unless I'm misunderstanding, this doesn't address my scenario at all. Given two root maps Map A and Map B, each to be produced as a separate standalone PDF, the question is: How does an author of Map A define a key that references a key defined in Map B's key space? E.g., I define key "key-x-in-map-B" and then author a reference to that key from some topic used in Map A, e.g.: <xref keyref="key-x-in-map-B">X in B</xref>. To process this, the processor has to know what a reference to a specific key name becomes in the rendered output so that the rendition contains a working link from the PDF for Map A to the PDF for Map B. There's lots of ways to implement this, but the most obvious is to have some deterministic processor that always produces the same result for a given key name/key space pair so that the processor of Map A can blindly generate references in Map A's PDF to the eventual corresponding anchors in Map B's PDF. This might require a run-time parameter that specifies the delivery location of the two PDFs so that if relative URLs are to be constructed, they can be constructed reliably. But the essential bit here is having the key definition *as authored* be an unambiguous reference to a key in the scope of Map B's key space. I don't see that we have a way to do that in DITA 1.2. Note that the only thing I'm concerned with is the markup in the content as authored--given an unambiguous address, the processing implementation is an exercise in engineering and is uninteresting. If there is no unambiguous address then there is no generalized processing that will work except by accident or unenforceable convention. In particular, it *cannot be correct* to author the key definition in this scenario where the URL is to the resource *as rendered*. It must be to the resource *as authored*. That is a fundamental requirement because without that, you cannot have generic content to which any processing may be applied with consistent and predictable results. As an author I want to say "I am linking to this *content* thing in this other publication" and I want links to that thing to work correctly in all possible renditions. "Work correctly" is rendition dependent, but the author's intent and their markup is rendition independent. Cheers, E. On 9/6/11 9:19 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote: > > This was my todo from last week's mtg - sorry I'm leaving it to the wire. > > This describes a solution that can be implemented today - I still think there > more work to be done, including: > > -  a general solution for key scoping (but not deliverable-based scoping since > the boundaries of deliverables are mutable, as I'm trying to show here). > - a standardized approach for cross-deliverable referencing - if we want to > encourage this approach, for example, or propose an alternative - but we > should be providing some guidance to vendors on how to implement so that the > solution is cross-vendor compatible > > scenario: > - we need to produce PDFs for each chapter of a book, as well as a single big > PDF that contains all chapters > - the chapters contain cross-references to content in other chapters, which > needs to be resolved as a cross-deliverable link in the single-chapter PDFs > but as a local link in the single big PDF case > - each chapter is represented by a separate map > - each topicref in the map has a uniquely addressable key (using whatever > general scoping mechanism we choose to implement) > - the book as a whole is represented by a master map that pulls in the others > > solution for individual chapter case: > - for each chapter, execute a partial PDF build, which does not transform the > content but does preprocess the map to turn each topicref href into a form > appropriate for the deliverable being produced (ie, including the filename of > the PDF being produced, with appropriate anchor syntax) >         this results in a deliverable-specific set of key mappings > - for each chapter, create a master map that includes the chapter being built > and then resource-only inclusions of the deliverable-specific maps for all > other chapters > - for each chapter's master map, execute a full PDF build >         this results in a chapter-level PDF with all links to other chapter > resolved correctly > > solution for whole book case: > - build normally > > Michael Priestley, Senior Technical Staff Member (STSM) > Lead IBM DITA Architect > mpriestl@ca.ibm.com > http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com 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

Michael, On Sep 6, 2011, at 8:11 AM, Michael Priestley wrote: > > Hi Eliot, > > I believed your scenario was covered in my case of multiple chapters being produced as separate PDFs. > > In that scenario, the author of Map A does not define a key that references a key defined in map B - they simply include map B's definition of map B's keys, after it has gone through processing to produce a deliverable-specific version of that key definition. > I'm wading in deep water here:-) and may very well have missed a critical point, but it seems like this is a markup issue that isn't resolve in the general case by simply merging the two (or more) sets of key definitions (which I think is what you're saying above). If the keys are unique across all of the maps, then yes, you could simply include map B's definitions in map A and use them directly. But, if they are not unique, then don't you still need markup that will allow you to uniquely identify the key you want? In which case, you're back to the problem Eliot stated originally (at least as I understand his original statement). Also, don't you still need a method for identifying the universe of maps that are in play? Best Regards, Richard Hamilton ------- XML Press XML for Technical Communicators http://xmlpress.net hamilton@xmlpress.net

Hi Richard, If the keys are not unique, we will need a key scoping mechanism. In my original note I called that out as a requirement.  If the keys are unique, no scoping mechanism is required. The issue of key scoping is separate from the issue of cross-deliverable references. You can have issues with duplicate keys in a single deliverable as well. Whatever solution we come up with for key scoping will have to cope with both separate deliverable and combined deliverable use cases across the same content source. That's why I provided an example that showed both. Eliot wants to have scoping by map - I have concerns with this as an approach, like the need to require source map awareness in the context of assembled map key spaces (like A+B getting built together into a single PDF); but maybe these could be figured out. We'd also want to figure out how things behave when conref'd, etc. All this could be done as part of the proposal for handling key scoping - maybe map-based scoping will turn out to be the best way to do it after all. But map-based scoping is:  1) not a requirement for cross-deliverable referencing (any more than it is a requirement for building single deliverables that include multiple maps) 2) only one of several possible ways that keys could be scoped, which I would like to leave to the other proposal to work out. My main concern is that we separate the issues: scoping by map does not solve the issue of cross-deliverable addressing, it only solves the issue of duplicate key resolution (and it creates new issues for key resolution in the context of same-deliverable addressing). Michael Priestley, Senior Technical Staff Member (STSM) Lead IBM DITA Architect mpriestl@ca.ibm.com http://dita.xml.org/blog/25 From: Richard Hamilton <hamilton@xmlpress.net> To: Michael Priestley/Toronto/IBM@IBMCA Cc: Eliot Kimber <ekimber@reallysi.com>, dita <dita@lists.oasis-open.org> Date: 09/06/2011 05:01 PM Subject: Re: [dita] Scenario for cross-deliverable referencing Michael, On Sep 6, 2011, at 8:11 AM, Michael Priestley wrote: > > Hi Eliot, > > I believed your scenario was covered in my case of multiple chapters being produced as separate PDFs. > > In that scenario, the author of Map A does not define a key that references a key defined in map B - they simply include map B's definition of map B's keys, after it has gone through processing to produce a deliverable-specific version of that key definition. > I'm wading in deep water here:-) and may very well have missed a critical point, but it seems like this is a markup issue that isn't resolve in the general case by simply merging the two (or more) sets of key definitions (which I think is what you're saying above). If the keys are unique across all of the maps, then yes, you could simply include map B's definitions in map A and use them directly. But, if they are not unique, then don't you still need markup that will allow you to uniquely identify the key you want? In which case, you're back to the problem Eliot stated originally (at least as I understand his original statement). Also, don't you still need a method for identifying the universe of maps that are in play? Best Regards, Richard Hamilton ------- XML Press XML for Technical Communicators http://xmlpress.net hamilton@xmlpress.net

Michael, Thanks for the explanation. That helps me put the question in context. Best Regards, Richard On Sep 6, 2011, at 2:29 PM, Michael Priestley wrote: > > Hi Richard, > > If the keys are not unique, we will need a key scoping mechanism. In my original note I called that out as a requirement. If the keys are unique, no scoping mechanism is required. > > The issue of key scoping is separate from the issue of cross-deliverable references. You can have issues with duplicate keys in a single deliverable as well. Whatever solution we come up with for key scoping will have to cope with both separate deliverable and combined deliverable use cases across the same content source. That's why I provided an example that showed both. > > Eliot wants to have scoping by map - I have concerns with this as an approach, like the need to require source map awareness in the context of assembled map key spaces (like A+B getting built together into a single PDF); but maybe these could be figured out. We'd also want to figure out how things behave when conref'd, etc. All this could be done as part of the proposal for handling key scoping - maybe map-based scoping will turn out to be the best way to do it after all. > > But map-based scoping is: > 1) not a requirement for cross-deliverable referencing (any more than it is a requirement for building single deliverables that include multiple maps) > 2) only one of several possible ways that keys could be scoped, which I would like to leave to the other proposal to work out. > > My main concern is that we separate the issues: scoping by map does not solve the issue of cross-deliverable addressing, it only solves the issue of duplicate key resolution (and it creates new issues for key resolution in the context of same-deliverable addressing). > > Michael Priestley, Senior Technical Staff Member (STSM) > Lead IBM DITA Architect > mpriestl@ca.ibm.com > http://dita.xml.org/blog/25 > > > From: Richard Hamilton <hamilton@xmlpress.net> > To: Michael Priestley/Toronto/IBM@IBMCA > Cc: Eliot Kimber <ekimber@reallysi.com>, dita <dita@lists.oasis-open.org> > Date: 09/06/2011 05:01 PM > Subject: Re: [dita] Scenario for cross-deliverable referencing > > > > > Michael, > > On Sep 6, 2011, at 8:11 AM, Michael Priestley wrote: > > > > > Hi Eliot, > > > > I believed your scenario was covered in my case of multiple chapters being produced as separate PDFs. > > > > In that scenario, the author of Map A does not define a key that references a key defined in map B - they simply include map B's definition of map B's keys, after it has gone through processing to produce a deliverable-specific version of that key definition. > > > I'm wading in deep water here:-) and may very well have missed a critical point, but it seems like this is a markup issue that isn't resolve in the general case by simply merging the two (or more) sets of key definitions (which I think is what you're saying above). > > If the keys are unique across all of the maps, then yes, you could simply include map B's definitions in map A and use them directly. But, if they are not unique, then don't you still need markup that will allow you to uniquely identify the key you want? In which case, you're back to the problem Eliot stated originally (at least as I understand his original statement). Also, don't you still need a method for identifying the universe of maps that are in play? > > Best Regards, > Richard Hamilton > ------- > XML Press > XML for Technical Communicators > http://xmlpress.net > hamilton@xmlpress.net > > > > >

I think we are talking at cross purposes. You are proposing a process that requires an *author* to explicitly include the intermediate process of a particular rendition process. That is simply not an acceptable solution because it mixes the domain of authoring (what's in the content I have and reasonably know about) and the domain of processing, which is, in the general case, unknowable to authors. I cannot accept any such solution. My requirement is that the content *as authored* convey all the information required to express authorial intent and to enable any processor to do the right thing given access to the content involved, without recourse to any particular implementation approach. Your solution does not do that in any way that I can see. That is, saying "the map author includes an map generated by a rendition process" is simply not going to work in the general case because not all processors would generate a map that couple be so included, even if it was sensible to define the authoring in that way. Doing so would be to mandate a particular implementation approach. In my scenario I am creating a map for a specific publication, which represents an invariant unit of publishing *to one or more rendition types*. That is, the map is be published to PDF or HTML or EPUB or something as yet uninvented but each of those renditions will reflect the same content (ignoring conditional processing). The author *of a topic* references some target by key. At the time they author the reference to the key they can't know or care where the ultimate target of the key might be in the content as authored or in the content as rendered, for the simple reason that it is unknowable at authoring time. If they are authoring in the context of a specific map then of course they can know where the key resolves in the context of that map, but if they are authoring the topic outside of a map context then they are simply stating the requirement that there needs to be something at the end of the key in whatever contexts that topic is used. But they cannot know all the possible maps the topic might be used by in the future. The author *of a map* that uses the topic has the responsibility of binding the key to a resource. If the resource is in the same map, then no problem, they just create a normal key reference and they're done. But if the resource is *not* in the same map, *there is nothing they can do today to indicate their intent to reference a resource in a different map*. They *do not want* to directly address a thing in a non-DITA rendition of the publication, for the simple reason that they want the link to work in all possible renditions and because they, as the author of the map, can't know the details of the renditions that might come later. Including the map for a particular rendition of the target map doesn't solve the problem precisely because it is rendition specific, but the intent is not rendition specific, it is publication-as-authored specific. That is, the map author is saying "the target topic is in this other publication, represented by this other map, regardless of where that map is rendered." That is my whole point: neither the author of the topic nor the author of the map can know anything about any potential renditions of the two publications (root maps) involved. They can only know about the maps *as authored*. A production system *can* know about the maps as rendered, *because it's rendering them*. It can know what rendition-specific addresses a thing as authored gets as rendered for a specific rendition. It can know that either because it did the rendition and remembered the result, however it remembers it, or because it has a deterministic algorithm for mapping input locations to result addresses, meaning it can predict what the address as rendered will be. It knows where the rendered results will be published relative to each other, so it can construct appropriate relative URIs if necessary. The DITA standard already defines unambiguous key scopes, namely the root maps that define key spaces. There is no ambiguity about that. That means that addressing a root map *as a root map* allows you to address keys in that key space without having to coordinate key names across key spaces. The *only thing* we lack is the fragment identifier syntax to distinguish a normal element ID reference from a key reference. Cheers, E. On 9/6/11 10:11 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote: > > Hi Eliot, > > I believed your scenario was covered in my case of multiple chapters being > produced as separate PDFs. > > In that scenario, the author of Map A does not define a key that references a > key defined in map B - they simply include map B's definition of map B's keys, > after it has gone through processing to produce a deliverable-specific version > of that key definition. > > I believe my scenario shows how cross-deliverable referencing could work > without using map-specific addressing. I believe map-specific addressing is > problematic because it doesn't actually tell us what the deliverable-specific > address will be. You assume some automated process that will allow automatic > association - but I believe that is too large an assumption to make. If I am > addressing content from a deliverable produced by another team, we would all > have to agree on that automatic processing rule - which requires upfront > coordination even greater than that required to ensure unique keys. > > The only time we can know what a deliverable's addressing scheme will be (ie > what the hrefs should resolve to) is when the deliverable is built. That's why > I have a deliverable-specific map being built as part of the deliverable > build, which can then be incorporated into the keyspace for other deliverables > to enable cross-deliverable links for a given set of deliverables. > > Michael Priestley, Senior Technical Staff Member (STSM) > Lead IBM DITA Architect > mpriestl@ca.ibm.com > http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > > > > From: Eliot Kimber <ekimber@reallysi.com> > To: Michael Priestley/Toronto/IBM@IBMCA, dita <dita@lists.oasis-open.org> > Date: 09/06/2011 11:01 AM > Subject: Re: [dita] Scenario for cross-deliverable referencing > > > > > Unless I'm misunderstanding, this doesn't address my scenario at all. > > Given two root maps Map A and Map B, each to be produced as a separate > standalone PDF, the question is: > > How does an author of Map A define a key that references a key defined in > Map B's key space? E.g., I define key "key-x-in-map-B" and then author a > reference to that key from some topic used in Map A, e.g.: <xref > keyref="key-x-in-map-B">X in B</xref>. > > To process this, the processor has to know what a reference to a specific > key name becomes in the rendered output so that the rendition contains a > working link from the PDF for Map A to the PDF for Map B. There's lots of > ways to implement this, but the most obvious is to have some deterministic > processor that always produces the same result for a given key name/key > space pair so that the processor of Map A can blindly generate references in > Map A's PDF to the eventual corresponding anchors in Map B's PDF. > > This might require a run-time parameter that specifies the delivery location > of the two PDFs so that if relative URLs are to be constructed, they can be > constructed reliably. > > But the essential bit here is having the key definition *as authored* be an > unambiguous reference to a key in the scope of Map B's key space. I don't > see that we have a way to do that in DITA 1.2. > > Note that the only thing I'm concerned with is the markup in the content as > authored--given an unambiguous address, the processing implementation is an > exercise in engineering and is uninteresting. If there is no unambiguous > address then there is no generalized processing that will work except by > accident or unenforceable convention. > > In particular, it *cannot be correct* to author the key definition in this > scenario where the URL is to the resource *as rendered*. It must be to the > resource *as authored*. That is a fundamental requirement because without > that, you cannot have generic content to which any processing may be applied > with consistent and predictable results. > > As an author I want to say "I am linking to this *content* thing in this > other publication" and I want links to that thing to work correctly in all > possible renditions. "Work correctly" is rendition dependent, but the > author's intent and their markup is rendition independent. > > Cheers, > > E. > > > On 9/6/11 9:19 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote: > >> >> This was my todo from last week's mtg - sorry I'm leaving it to the wire. >> >> This describes a solution that can be implemented today - I still think there >> more work to be done, including: >> >> - a general solution for key scoping (but not deliverable-based scoping >> since >> the boundaries of deliverables are mutable, as I'm trying to show here). >> - a standardized approach for cross-deliverable referencing - if we want to >> encourage this approach, for example, or propose an alternative - but we >> should be providing some guidance to vendors on how to implement so that the >> solution is cross-vendor compatible >> >> scenario: >> - we need to produce PDFs for each chapter of a book, as well as a single big >> PDF that contains all chapters >> - the chapters contain cross-references to content in other chapters, which >> needs to be resolved as a cross-deliverable link in the single-chapter PDFs >> but as a local link in the single big PDF case >> - each chapter is represented by a separate map >> - each topicref in the map has a uniquely addressable key (using whatever >> general scoping mechanism we choose to implement) >> - the book as a whole is represented by a master map that pulls in the others >> >> solution for individual chapter case: >> - for each chapter, execute a partial PDF build, which does not transform the >> content but does preprocess the map to turn each topicref href into a form >> appropriate for the deliverable being produced (ie, including the filename of >> the PDF being produced, with appropriate anchor syntax) >> this results in a deliverable-specific set of key mappings >> - for each chapter, create a master map that includes the chapter being built >> and then resource-only inclusions of the deliverable-specific maps for all >> other chapters >> - for each chapter's master map, execute a full PDF build >> this results in a chapter-level PDF with all links to other chapter >> resolved correctly >> >> solution for whole book case: >> - build normally >> >> Michael Priestley, Senior Technical Staff Member (STSM) >> Lead IBM DITA Architect >> mpriestl@ca.ibm.com >> http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > >> < http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com

Hi Eliot, You are misunderstanding my case. Hopefully the examples I provided in a followon email will help. The authors would be working with a key definition file that mapped to the source files they need to link to. At build time, a new map would be created to pull in the deliverable-specific mappings, overriding the source-time mappings. My approach does assume that a key mapping file can be produced by the build for a specific deliverable. I don't see any way to avoid this assumption, since at no other time does a system know what the key mappings should be for that deliverable - taking into account things like build parameters, like ditavals to be used. Your approach also makes some assumptions:  - You are assuming a single production system for all deliverables. Mine does not.  - You are also assuming a single scope for all deliverables from a given map. You do not allow for map nesting or conreffing to allow for larger or smaller scopes, and you explicitly ignore ditaval. My approach allows for any combination of output conditions. Michael Priestley, Senior Technical Staff Member (STSM) Lead IBM DITA Architect mpriestl@ca.ibm.com http://dita.xml.org/blog/25 From: Eliot Kimber <ekimber@reallysi.com> To: Michael Priestley/Toronto/IBM@IBMCA Cc: dita <dita@lists.oasis-open.org> Date: 09/13/2011 11:00 AM Subject: Re: [dita] Scenario for cross-deliverable referencing I think we are talking at cross purposes. You are proposing a process that requires an *author* to explicitly include the intermediate process of a particular rendition process. That is simply not an acceptable solution because it mixes the domain of authoring (what's in the content I have and reasonably know about) and the domain of processing, which is, in the general case, unknowable to authors. I cannot accept any such solution. My requirement is that the content *as authored* convey all the information required to express authorial intent and to enable any processor to do the right thing given access to the content involved, without recourse to any particular implementation approach. Your solution does not do that in any way that I can see. That is, saying "the map author includes an map generated by a rendition process" is simply not going to work in the general case because not all processors would generate a map that couple be so included, even if it was sensible to define the authoring in that way. Doing so would be to mandate a particular implementation approach. In my scenario I am creating a map for a specific publication, which represents an invariant unit of publishing *to one or more rendition types*. That is, the map is be published to PDF or HTML or EPUB or something as yet uninvented but each of those renditions will reflect the same content (ignoring conditional processing). The author *of a topic* references some target by key. At the time they author the reference to the key they can't know or care where the ultimate target of the key might be in the content as authored or in the content as rendered, for the simple reason that it is unknowable at authoring time. If they are authoring in the context of a specific map then of course they can know where the key resolves in the context of that map, but if they are authoring the topic outside of a map context then they are simply stating the requirement that there needs to be something at the end of the key in whatever contexts that topic is used. But they cannot know all the possible maps the topic might be used by in the future. The author *of a map* that uses the topic has the responsibility of binding the key to a resource. If the resource is in the same map, then no problem, they just create a normal key reference and they're done. But if the resource is *not* in the same map, *there is nothing they can do today to indicate their intent to reference a resource in a different map*. They *do not want* to directly address a thing in a non-DITA rendition of the publication, for the simple reason that they want the link to work in all possible renditions and because they, as the author of the map, can't know the details of the renditions that might come later. Including the map for a particular rendition of the target map doesn't solve the problem precisely because it is rendition specific, but the intent is not rendition specific, it is publication-as-authored specific. That is, the map author is saying "the target topic is in this other publication, represented by this other map, regardless of where that map is rendered." That is my whole point: neither the author of the topic nor the author of the map can know anything about any potential renditions of the two publications (root maps) involved. They can only know about the maps *as authored*. A production system *can* know about the maps as rendered, *because it's rendering them*. It can know what rendition-specific addresses a thing as authored gets as rendered for a specific rendition. It can know that either because it did the rendition and remembered the result, however it remembers it, or because it has a deterministic algorithm for mapping input locations to result addresses, meaning it can predict what the address as rendered will be. It knows where the rendered results will be published relative to each other, so it can construct appropriate relative URIs if necessary. The DITA standard already defines unambiguous key scopes, namely the root maps that define key spaces. There is no ambiguity about that. That means that addressing a root map *as a root map* allows you to address keys in that key space without having to coordinate key names across key spaces. The *only thing* we lack is the fragment identifier syntax to distinguish a normal element ID reference from a key reference. Cheers, E. On 9/6/11 10:11 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote: > > Hi Eliot, > > I believed your scenario was covered in my case of multiple chapters being > produced as separate PDFs. > > In that scenario, the author of Map A does not define a key that references a > key defined in map B - they simply include map B's definition of map B's keys, > after it has gone through processing to produce a deliverable-specific version > of that key definition. > > I believe my scenario shows how cross-deliverable referencing could work > without using map-specific addressing. I believe map-specific addressing is > problematic because it doesn't actually tell us what the deliverable-specific > address will be. You assume some automated process that will allow automatic > association - but I believe that is too large an assumption to make. If I am > addressing content from a deliverable produced by another team, we would all > have to agree on that automatic processing rule - which requires upfront > coordination even greater than that required to ensure unique keys. > > The only time we can know what a deliverable's addressing scheme will be (ie > what the hrefs should resolve to) is when the deliverable is built. That's why > I have a deliverable-specific map being built as part of the deliverable > build, which can then be incorporated into the keyspace for other deliverables > to enable cross-deliverable links for a given set of deliverables. > > Michael Priestley, Senior Technical Staff Member (STSM) > Lead IBM DITA Architect > mpriestl@ca.ibm.com > http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > > > > From: Eliot Kimber <ekimber@reallysi.com> > To: Michael Priestley/Toronto/IBM@IBMCA, dita <dita@lists.oasis-open.org> > Date: 09/06/2011 11:01 AM > Subject: Re: [dita] Scenario for cross-deliverable referencing > > > > > Unless I'm misunderstanding, this doesn't address my scenario at all. > > Given two root maps Map A and Map B, each to be produced as a separate > standalone PDF, the question is: > > How does an author of Map A define a key that references a key defined in > Map B's key space? E.g., I define key "key-x-in-map-B" and then author a > reference to that key from some topic used in Map A, e.g.: <xref > keyref="key-x-in-map-B">X in B</xref>. > > To process this, the processor has to know what a reference to a specific > key name becomes in the rendered output so that the rendition contains a > working link from the PDF for Map A to the PDF for Map B. There's lots of > ways to implement this, but the most obvious is to have some deterministic > processor that always produces the same result for a given key name/key > space pair so that the processor of Map A can blindly generate references in > Map A's PDF to the eventual corresponding anchors in Map B's PDF. > > This might require a run-time parameter that specifies the delivery location > of the two PDFs so that if relative URLs are to be constructed, they can be > constructed reliably. > > But the essential bit here is having the key definition *as authored* be an > unambiguous reference to a key in the scope of Map B's key space. I don't > see that we have a way to do that in DITA 1.2. > > Note that the only thing I'm concerned with is the markup in the content as > authored--given an unambiguous address, the processing implementation is an > exercise in engineering and is uninteresting. If there is no unambiguous > address then there is no generalized processing that will work except by > accident or unenforceable convention. > > In particular, it *cannot be correct* to author the key definition in this > scenario where the URL is to the resource *as rendered*. It must be to the > resource *as authored*. That is a fundamental requirement because without > that, you cannot have generic content to which any processing may be applied > with consistent and predictable results. > > As an author I want to say "I am linking to this *content* thing in this > other publication" and I want links to that thing to work correctly in all > possible renditions. "Work correctly" is rendition dependent, but the > author's intent and their markup is rendition independent. > > Cheers, > > E. > > > On 9/6/11 9:19 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote: > >> >> This was my todo from last week's mtg - sorry I'm leaving it to the wire. >> >> This describes a solution that can be implemented today - I still think there >> more work to be done, including: >> >> -  a general solution for key scoping (but not deliverable-based scoping >> since >> the boundaries of deliverables are mutable, as I'm trying to show here). >> - a standardized approach for cross-deliverable referencing - if we want to >> encourage this approach, for example, or propose an alternative - but we >> should be providing some guidance to vendors on how to implement so that the >> solution is cross-vendor compatible >> >> scenario: >> - we need to produce PDFs for each chapter of a book, as well as a single big >> PDF that contains all chapters >> - the chapters contain cross-references to content in other chapters, which >> needs to be resolved as a cross-deliverable link in the single-chapter PDFs >> but as a local link in the single big PDF case >> - each chapter is represented by a separate map >> - each topicref in the map has a uniquely addressable key (using whatever >> general scoping mechanism we choose to implement) >> - the book as a whole is represented by a master map that pulls in the others >> >> solution for individual chapter case: >> - for each chapter, execute a partial PDF build, which does not transform the >> content but does preprocess the map to turn each topicref href into a form >> appropriate for the deliverable being produced (ie, including the filename of >> the PDF being produced, with appropriate anchor syntax) >>         this results in a deliverable-specific set of key mappings >> - for each chapter, create a master map that includes the chapter being built >> and then resource-only inclusions of the deliverable-specific maps for all >> other chapters >> - for each chapter's master map, execute a full PDF build >>         this results in a chapter-level PDF with all links to other chapter >> resolved correctly >> >> solution for whole book case: >> - build normally >> >> Michael Priestley, Senior Technical Staff Member (STSM) >> Lead IBM DITA Architect >> mpriestl@ca.ibm.com >> http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > >> < http://dita.xml.org/blog/25 < http://dita.xml.org/blog/25 > > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com

Minutes of the OASIS DITA TC Tuesday, 13 Sept 2011 Recorded by Richard Hamilton [ Note: This is my first shot at minutes in a while, so please expect, and feel free to report, any anomalies ] Quorum present Regrets: Thilo Buchholz, Tom Magliery Don Day moved to accept last week's minutes, Kris Eberlein seconded, and the minutes were accepted. Subcommittee reports: none today Business: 1) Vote on charter for DITA for Programmers subcommittee Lisa Dyer presented charter to the group. Goal: provide specializations for 1.3 specs for common apis, including: javascript, java, c, c++, and REST Su-Laine Yeo: suggested the subcommittee name should be "DITA for Programming Content," rather than DITA for Programmers Michael Priestley: Concern that scope is too narrow. What about architectural designs? Some work is going on in that area at IBM. Action Item: Lisa will discuss possibilities with Aaron Labella of IBM. Chris Nitchie from PTC has a method for working with a generalized markup that can be used with multiple object oriented languages, and which might be applicable in this work. Adrian Warman: How would this contrast with, for example, javadoc? Michael Priestley: Javadoc ontent in java source would stay the same, applet would change to one that generates DITA, rather than html. Lisa will take comments under consideration and come back next week to continue the discussion, which will be first on the agenda. 2) Continuation of triage of DITA 1.3 Proposals: 13041: Scenario for cross-deliverable referencing - Discussion centered on Eliot Kimber's and Michael Priestley's approaches to this question, which center on the question of whether/how map scope can be tied to deliverable scope when resolving cross-map referencing. - Michael asked Eliot to explain how he would markup Michael's example (multiple chapters processed as separate chapters and as a single book) - Michael notes this is a real-world example, since the scenario is how the DITA spec could be built. - Action Item for Eliot: create a markup example for his approach. Michael summarized the issue and the two approaches under discussion: - The issue is referencing keys in other maps and how they get resolved. - Eliot: keys get resolved to target keys based on processing rules that are external to the markup. - Michael: does not assume a single processing system. Instead, the map creator would create key re-definitions for different deliverables that would be used to resolve key references from other maps. He said it would be nice to use Eliot's model, but his, admittedly messier, model would be more independent of processing software. Don: suggests continuing the discussion after Michael, Eliot, and other interested parties can work off-line to bring up a unified approach that can be discussed by the TC. [ meeting adjourned ]