[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] How much flexibility do specializers have to make exceptions to behaviors that are outlined in the DITA standard?
|
There are four long standing items toward the end of the DITA TC agenda:
We had some good e-mail exchanges on the first item back in late October. The e-mail discussion is included below. I don’t think that that discussion lead to a consensus or any action items.
I’d like to finish up the discussion on the first item, so we can start to work our way through the next three items. I propose that anyone who wishes send any last thoughts on this topic to the DITA TC e-mail list between now and next Monday, that we have a brief discussion during next week’s DITA TC call to see where we stand, and as part of that discussion see if we agree to the following as a resolution of this issue:
3. For specializations the "processing behaviors" described in the DITA specifications are not required, but are strongly encouraged default behaviors unless explicitly stated otherwise. Here “strongly encouraged” means that there may be valid reasons in particular circumstances to implement exceptions to the described default behavior, but the full implications of such exceptions must be understood and carefully weighed before choosing to implement behaviors that differ from the default behaviors described in the DITA specifications.
-Jeff
From: Ogden, Jeff
[mailto:jogden@ptc.com]
We’ve had some e-mail discussions about “How much flexibility specializers have to make exceptions to behaviors that are outlined in the DITA standard”. But those discussions have been fairly quiet for 10 days or so. We had some good discussion of this during the last DITA TC meeting. During that discussion we agreed to move the discussion back to the DITA TC e-mail list.
So this note is my attempt to get the e-mail discussion restarted.
I don’t think we want to talk about this issue during tomorrow’s DITA TC call, but if we can get some good discussion going on the e-mail list we may be ready to talk about it during next week’s call.
I think Gershon’s draft meeting minutes provide a pretty good summary of the discussion, so far. From the draft 9 October 2007 meeting minutes:
> 4) How much flexibility do specializers have to make exceptions to > behaviors that are outlined in the DITA standard? > > JO: We had good discussions. MP has a more liberal approach, > whereas I feel we should not permit as much flexibility. > > MP: I'm drawing the line between syntax and behavior. Syntax > must be preserved. Everything beyond there is pretty contextual. > > JE: There are edge cases where we've had to deviate from the > standard in order to achieve the specialization we needed. > Though these are minor deviations that could be easily > transformed back into standard DITA. > > Discussion... > > MP: If someone wants to override the stated default behavior > (for some good reason), I don't think we should call that going > against the DITA spec. > > Discussion... > > Don requested we move this discussion to the email list. > > Yet further discussion... > > Don asked us to take items 3 and 4 off into 2 discussions next > week. In the meantime, continue discussions on-list.
Much of the discussion so far has been between Michael and me. I’d like to see if we can get some others to express their views on this issue. If most people don’t care or if most people agree with Michael that specializers can do pretty much anything they want, we may not need a lot more discussion. If this position makes some people uneasy, then we need to find that out and we will need to continue the discussion to figure out how and where to draw some lines.
I believe that there is agreement that specializers have a lot of control and can change many things related to output processing behaviors of their specializations. I think there is also agreement that we need to review the DITA specifications to make sure they are clear about what MUST, SHOULD, or MAY be done with respect to both the basic DITA document types that are officially part of the standard (topic, map, concept, glossary, reference, task, and bookmap) and for user defined specializations that aren’t a formal part of the standard. I am a little less sure, but I think there is agreement that we want to add some sort of conformance statement to the DITA specifications.
The question that is up for discussion is, are specializers free to do anything they want or are there some things that the DITA Standard makes out of bounds even for user defined specializations that aren’t part of the official DITA standard?
From my point of view, I’d like to see some limits on what specializers can do in terms of referencing behaviors (what legal DITA URI’s can look like and what they mean), and when there are interactions such as property cascading behavior between one document and another (from a map to a topic or from a map to a map to a topic). I want to increase the likelihood that DITA users can share their documents, including specialized documents, with others or move the documents into new processing environments and still get good results. I want to reduce the amount of reimplementation users have to do when they share their documents or move into new processing environments.
Paul Grosso described this in terms of the distinction that is made in XSLT between transformations and styling. Styling would be very open and specializers could do pretty much whatever they want. Transformations (explicit or implied) would be more tightly defined by the DITA Standard and specializers would have less flexibility (but still some flexibility). Paul, feel free to restate this if what I wrote here isn’t quite right.
I’ll shut up now. Please let us know what you think.
-Jeff
From:
Deborah_Pickett@moldflow.com [mailto:Deborah_Pickett@moldflow.com]
From: Michael Priestley
[mailto:mpriestl@ca.ibm.com]
-----Original Message----- From: Eliot Kimber [mailto:ekimber@reallysi.com] Sent: Thursday, October 25, 2007 3:10 PM To: dita Subject: Re: [dita] How much flexibility do specializers have to make exceptions to behaviors that are outlined in the DITA standard?
On 10/15/07 4:39 PM, "Ogden, Jeff" <jogden@ptc.com wrote: > The question that is up for discussion is, are specializers free to do > anything they want or are there some things that the DITA Standard makes > out of bounds even for user defined specializations that aren't part of > the official DITA standard?
> From my point of view, I'd like to see some limits on what specializers > can do in terms of referencing behaviors (what legal DITA URI's can look > like and what they mean), and when there are interactions such as > property cascading behavior between one document and another (from a map > to a topic or from a map to a map to a topic). I want to increase the > likelihood that DITA users can share their documents, including > specialized documents, with others or move the documents into new > processing environments and still get good results. I want to reduce > the amount of reimplementation users have to do when they share their > documents or move into new processing environments.
The DITA specification defines a number of core processing semantics that constitute the core processing infrastructure that makes DITA both work functionally (that is, when implemented, those features produce the result that you presumably want because you're using DITA) and allows documents and document processing to be reasonably interchangeable.
I think that this infrastructure includes the following:
- All addressing of DITA-governed content by DITA-governed content. That is, you cannot, within a specialization, change the rules for resolving hrefs (or any other DITA-defined addressing mechanism)) to DITA-based content.
- Conref. You cannot change the constraints or effective result that conref produces.
Where things start to get a little cloudier, and where I think this discussion started, is in the area of the implications for topic references and in particular how do topic references affect the effective properties of the topics they reference?
The issue here is that while this area can be viewed as concrete in the way that addressing and conref are, it can also be seen as a matter of presentation style. For example, for some specializations of metadata used within topicref I want their values to propagate and replace values on referenced topics and for other values I do not. A blanket DITA-defined rule of "metadata always propagates" or "metadata never propagates" would be wrong some of the time so we can't define it. That leads to Paul's original question of how can specializations express their intent in a case like this that allows a tool like Arbortext Editor to do the expected thing automatically? Clearly in this specific case there's a need for some sort of schema-level way to indicate the processing intent.
Simple enough to design for this case, but how many cases are there? Probably lots. That suggests you need a more general mechanism for this sort of thing. That will be, necessarily, complex. Easier to just punt and say "DITA has no opinion". But that doesn't help Paul. Seems like, for the moment, there's no easy answer to this question.
At a minimum DITA has to define clear default behaviors for those areas where processors can legitimately do different things.
I guess I would need to see some specific cases where a specialization wants to deviate from either the defined or suggested behavior to evaluate whether or not the deviation is processing or style, there's a way to usefully parameterize the behavior choices or whether the requirement can be satisfied in a different way. Or where, as above, DITA either says nothing or isn't clear and there are multiple useful ways that a processor could behave.
It's also worth saying that while DITA should "just work" that's always in terms of the default behavior, whatever it is, as defined by the DITA spec. Specializations that want something other than the default are on their own and there should be no expectation on anyone's part that specialization-specific stuff will magically happen without some implementation effort.
In that respect, DITA-based applications are no different from any other purpose-built XML application in that you may have to do a bit of local customization of your generic tools to get what you want. However, with DITA it should always be less (or no greater than) it would have otherwise been because DITA gives you so much out of the box.
For example, for demonstration purposes I've defined a specialization of reference for capturing animal field guide entries, including specializations of <data for capturing the Linnaean classification of the animals described. No DITA-aware processor is going to give me any special support for authoring these classifications but I'd probably want to build a little classification editor for these values since they need to be validated and could be gathered from external data sources and whatnot. I would not fault any DITA-supporting editor for not providing that but I would expect a way to add it without too much difficulty.
Cheers,
Eliot
-- W. Eliot Kimber Senior Solutions Architect Really Strategies, Inc.
From: Michael Priestley
[mailto:mpriestl@ca.ibm.com]
> -----Original Message----- From: Eliot Kimber [mailto:ekimber@reallysi.com] Sent: Thursday, October 25, 2007 4:04 PM To: Michael Priestley Cc: dita Subject: Re: [dita] How much flexibility do specializers have to make exceptions to behaviors that are outlined in the DITA standard?
On 10/25/07 2:41 PM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote: > Clarification: > > in the href overriding example, a processor might choose to create a > preview by summarizing specialized elements in a target's <refsyn> or > equivalent, rather than using the <shortdesc>. This wouldn't affect the > syntax of the href, but does change the expected processing from the > default.
What you've described is rendition, not address resolution.
That is, when I say "addressing" I mean "the object that is addressed by the href value" which is different with what you do with that thing once you have it.
That is, how or if you produce tooltips in some rendition is entirely a matter of style. What those tooltips apply to (or at least what the initial source of their ultimate value is) is a function of invariant address processing.
That is, you can choose to produce or not produce tooltips, you can't change what "mytopic.dita#topicid/elementid" means from an address resolution standpoint.
[Note that this is one problem with DITA not using standard addressing mechanisms: it provides no built in mechanism for choice in how you do addressing at the fragment identifier level, which means you either have non-DITA stuff or you use URIs that have to be interpreted by a specific URI resolver. This is a fundamental problem with DITA 1.x that must be corrected in DITA 2.]
> Main point remains the same: I think everything in "expected behavior" is > expected default behavior; everything in "expected markup/syntax" is > required unless otherwise stated. The syntax for href and conref should be > default.
But the point is that that there are some things in DITA that are not "expected behavior" but "required behavior", which includes, I assert, all addressing and conref.
Cheers,
E.
-- W. Eliot Kimber Senior Solutions Architect Really Strategies, Inc.
From: Ogden, Jeff
[mailto:jogden@ptc.com]
Eliot, thanks for your comments and for getting this conversation started again.
In response to Michael’s comment/question: > Couldn't an implementer decide that they want to limit reuse in their organization > to content coming from specific directories? For example, check the conref path > to ensure that it starts with "/reuse/"?
I don’t see a problem with this as long as the implementer is being more restrictive than what is required by the standard. The standard says that conref values are URIs that reference DITA content with a number of checks to make sure they content being referenced is legal or is likely to be legal in the new context. Limiting the references to a particular path isn’t violating that. The conref values that start with /reuse/ will always be valid URI and with a bit of luck the thing being referenced will be DITA content that is legal in the current content. An implementation will not have to do anything special to make the required checks. You can’t expect other implementations to impose the same limitations automatically, but that is OK.
-Jeff
From: Michael Priestley
[mailto:mpriestl@ca.ibm.com]
The End |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]