RE: [dita] Rethinking the DITA Reference Docs

["Mary McRae" <mary.mcrae@oasis-open.org>]

Hi everyone,

  Not to weigh in on Eliot's proposal, but as OASIS TC Administrator I would certainly like to be able to point to the DITA specifications and say not only that they were valid DITA documents themselves, but that they could serve as a reference implementation - that best practices would be put to use in the actual specifications.

  Then again, I was a consultant in a past life, and anything that creates work creates revenue :-)

... now back to your regularly-scheduled programming.

Mary

> -----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