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

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-techcomm message

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


Subject: FW: [dita] 13121 - reusing portions of structural specializations via domain mechanism


Please review Michael's proposal as it related to the Troubleshooting Topic.
JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
Joann.hackos@comtech-serv.com
303-232-7586



From: Michael Priestley <mpriestl@ca.ibm.com>
Date: Friday, March 8, 2013 11:01 PM
To: DITA TC <dita@lists.oasis-open.org>
Subject: [dita] 13121 - reusing portions of structural specializations via domain mechanism

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]