dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: 13121 - reusing portions of structural specializations via domain mechanism
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: dita <dita@lists.oasis-open.org>
- Date: Fri, 8 Mar 2013 10:01:59 -0500
Goal:
Allow parts of structural specializations
to be reused by other structural specializations without requiring one
to be specialized from the other. For example, allow the <steps>
structure from <task> to be reused in place of an <ol> within
a <troubleshootingsteps> section of the <troubleshooting> topic
type.
Approach:
Declare the reused portion of the specialization
as a domain that is being used in the structural specialization. Cannot
be used to turn portions of a structural specialization into a general-purpose
domain - can only be used by direct reference from a reusing specialization's
content model. In other words: allows <troubleshootingsteps> to reference
<steps> in its content model; does not allow making <steps>
generally available wherever <ol> is available.
Method for DTDs:
- add a declaration to the domains attribute
for the dependency on the new domain: (topic troubleshooting+task/steps)
(note: the method for declaring
a dependency is part of DITA 1.2, but there's no clear definition of the
algorithm to use when constructing - this is my best guess)
- include the structural .mod file at
the end of the domains section of the .dtd file
- no need to touch domain .ent section
because reuse is by direct content model reference, not by domain substitution
Effect on generalizing:
- same as any other domain that is used
by direct content model reference - the domain cannot be generalized without
generalizing the structural specialization as well, so effectively it behaves
as part of the structural specialization
- we'll need to add examples for both
basic and multi-level specialization to make this more explicit
- the current documentation for generalization
with domain dependencies needs improvement in any case
Effect on conref:
- acts as a structural specialization
rather than a domain, so no on-the-fly generalization unless conreffing
from a higher-level ancestor of both
- need to add both a simple and a complex
multi-level specialization example here
- troubleshooting can conref troubleshooting
that includes steps, steps can conref steps from either troubleshooting
or task, etc.
Documentation issues encountered
during research:
conref and generalization sections:
need to at least refer to topic on conref and generalization for constraints
module
conref and generalization for constraints
section:
didn't we say that conref between doctypes
with different constraints would be allowed unless somehow specially declared?
not finding that section
https://www.oasis-open.org/committees/download.php/34659/DITA_TC_meeting_13_October_2009.txt
I think this somehow got dropped during
the push for DITA 1.2 closure. I really think we need it back in, for lots
of reasons, including conref between strict and general task.
constraints section:
we're very restrictive on naming conventions/entity
formation etc. - which is needed for eg having the -c that tells us whether
a domain is a constraint or not but may be overly restrictive for cases
where someone wants to make a universal change - like getting rid of ph,
say
I think it would be useful to relax
the constraint here, and it's probably a prereq for implementing the lightweight
DITA proposal, which has several constraints that affect general content
models.
generalization section - need to update
section that claims doctype can be auto-generated - no longer really true,
may not have been for some time
- also need to think through impact
of the advice to include structural classes in the domains list - what
will that do to conref and generalization rules?
- also if structural classes are recommended
to be included in the domains list, the examples given - and our own domains
used in DITA - should be updated
domain usage declaration section - as
mentioned earlier, the syntax used in the domain dependencies case is not
documented. In addition, the examples given in the spec differ from what
I'd expected, and from what's documented in the DITA Adoption TC whitepaper:
https://www.oasis-open.org/committees/download.php/36614/domain_and_topic_integration_v0_3.pdf
Heres the original proposal:
https://www.oasis-open.org/committees/download.php/25248/IssueDomainTopic12010.html
Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]