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


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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

Subject: RE: [dita] Rethinking the DITA Reference Docs


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.


> -----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,
> in the context of the modularization we're planning for the spec
> 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
> 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
> 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
>   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
> specific modules.
> 3. Use relationship tables to link types to their containers and
> The first option would work and would make things configurable. It
> be relatively easy to either update the existing source with search
> 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
> 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
> 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
> 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
> 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
> at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

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