RE: [dita] Rethinking the DITA Reference Docs

["Ogden, Jeff" <jogden@ptc.com>]

Eliot,

Michael, Robert, and I will be working on the reorganization and
updating of the DITA specification documents for DITA 1.2.  Robert has
already proposed some changes to the way the documents are organized to
make them a bit easier to maintain.

    -Jeff

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> Sent: Wednesday, February 06, 2008 6:32 PM
> To: dita@lists.oasis-open.org
> Subject: [dita] Rethinking the DITA Reference Docs
> 
> I've been thinking a good bit about the DITA reference docs lately,
both
> in the context of the modularization we're planning for the spec
itself
> as well as in the context of integrating the reference docs with the
> documentation for specializations.
> 
> The main challenge I ran into was that the docs as currently written
use
> xrefs to link from the "contains" and "contained by" sections to the
> related element types.
> 
> This makes it essentially impossible to refactor the docs to reflect a
> subset of modules (e.g., specializations that only use the base
> highlight and indexing domains) or use in new specializations just by
> including the docs into your own map: you would have to copy and
modify
> every entry. Definitely not realizing the promise of DITA to enable
> mix-and-match interchange.
> 
> I can think of two possible solutions:
> 
> 1. Use metadata attributes on each xref to bind references to modules.
> 
> 2. Replace the explicit lists of element types with either references
to
>   more generic placeholders (e.g., "ph and its specializations" or
> "paragraph content") or only to base types, with the explicit
> implication that the base types may be extended on a per-shell basis
by
> specific modules.
> 
> 3. Use relationship tables to link types to their containers and
contents.
> 
> The first option would work and would make things configurable. It
would
> be relatively easy to either update the existing source with search
and
> replace or update the code that generates those bits to include the
> defining module.
> 
> The second option would require an awful lot of rewriting and would
> probably be unsatisfying in the end.
> 
> The third option is more complete but would require either custom
coding
> to implement processing the reltables to synthesize the contains and
> contained-by sections or refinement of the Toolkit to make display of
> reltable links more flexible than it is today (that is, be able to get
> something other than "Related reference" as the header for a set of
> generated related links).
> 
> The third option would also allow for props= attributes that take the
> names of the different modules to enable run-time inclusion or
exclusion
> of links for specific modules, making it easy to tailor a master
> all-inclusive map.
> 
> There's no difficulty in generating the reltables themselves--there's
> plenty of tooling that can process the declarations as XML, so I'm not
> worried about that.
> 
> I'm not sure who is currently responsible for managing the DITA
> reference source, I suppose this most affects them in the short term.
> I'm willing to do what I can to code the required processing, either
for
> generation of source data or rendering into HTML and/or PDF as my time
> allows. Since I would like a general solution for my client work I've
> got a bit of motivation to help find a better solution than the
current
> source provides.
> 
> Cheers,
> 
> Eliot
> --
> Eliot Kimber
> Senior Solutions Architect
> "Bringing Strategy, Content, and Technology Together"
> Main: 610.631.6770
> www.reallysi.com
> www.rsuitecms.com
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  You may a link to this group and all your TCs in
> OASIS
> at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php