OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Fw: Modular Documents and Links to Publications


Eliot Kimber asked me to forward this mail to the DocBook TC.  We can 
discuss this at our next meeting as part of the modular doc discussion.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "ekimber" <ekimber@reallysi.com>
To: "Bob Stayton" <bobs@sagehill.net>
Sent: Monday, October 12, 2009 3:57 PM
Subject: FW: Modular Documents and Links to Publications


> Bob,
>
> I guess I'm not a full member of the DocBook TC--can you forward the mail
> below to the list for me?
>
> Thanks,
>
> E.
> ----
> 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>
>
> ------ Forwarded Message
>> From: ekimber <ekimber@reallysi.com>
>> Date: Mon, 12 Oct 2009 17:53:29 -0500
>> To: DocBook Technical Committee <docbook-tc@lists.oasis-open.org>
>> Conversation: Modular Documents and Links to Publications
>> Subject: Modular Documents and Links to Publications
>>
>> I haven't been paying close attention to the discussion of modularity in
>> DocBook but I have recently come to better appreciate a weakness in the
>> current DITA addressing feature set and I thought it would be useful to 
>> point
>> it out so that DocBook need not make the same mistake, or at least omit 
>> the
>> feature knowingly.
>>
>> The basic problem is this:
>>
>> There is a general requirement to be able to author links from one 
>> publication
>> to another. In DocBook today there is a one-to-one mapping from DocBook
>> documents to publications.
>>
>> This means that in DocBook today you can unambiguously author links to 
>> other
>> publications *as authored* because those links are always to the document
>> instance that represents the publication as a whole.
>>
>> However, when you enable a DITA-style modularity mechanism, where a given
>> module may be included by hyperlink into a publication structure and may 
>> occur
>> in any number of such structures, you immediately create the problem that 
>> a
>> direct pointer to a module does not, by itself, indicate any particular
>> publication context.
>>
>> The most you can know is whether or not the target of a reference is part 
>> of
>> the same publication (DITA's scope="local") or not (scope="peer" and
>> scope="external"). But knowing that the target is not part of the current
>> publication is not enough. In addition, whether a target is or is not 
>> part of
>> the "current" publication is not actually knowable from a given module at
>> authoring time in the general case, because the module cannot know what
>> contexts it might be used in.
>>
>> DITA 1.2 partly solves this problem through the keyref mechanism, which 
>> allows
>> you to have indirect, late-bound addresses. This allows a module to point 
>> to
>> an abstract target and have the details of what the target is be map 
>> specific.
>> So far so good. Without this feature, reuse is not possible in the 
>> general
>> case if you also want to have cross references or content references. (I 
>> am
>> assuming that DocBook's modularity feature includes a similar late-bound
>> indirection. If it does not you need to add one or stop now.)
>>
>> With the keyref feature each unique root map establishes a distinct "key
>> space" within which keys have bindings to resources. This means that in 
>> order
>> to resolve a key you must first establish the root map within which you 
>> are
>> resolving it. The map that you start processing with is the implicit key 
>> space
>> for all key references within the scope of that map.
>>
>> This means that in order to bind a key to a resource in another 
>> publication
>> you must specify, as part of the overall address, both the root map as 
>> well as
>> the key to be resolved within the scope of that target map. DITA 1.2 does 
>> not
>> provide this bit of addressing (it will in DITA 1.3 if I have anything to 
>> say
>> about it).
>>
>> Note that it is not acceptable to author the link to the publication *as
>> published* (e.g., the PDF, the HTML) because you can't predict or know at
>> authoring time where or how the target publication will be authored. The 
>> only
>> thing you know is the source location of the publication. It is then up 
>> to a
>> given publishing infrastructure (e.g., CMS, publication manager, set of 
>> Ant
>> scripts, whatever) to translate pointers to publications as authored to
>> publications as published for a given publishing instance.
>>
>> 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>
>
> ------ End of Forwarded Message
>
>
> 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]