[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Rethinking the DITA Reference Docs
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]