Michael wrote:
> This ground feels familiar - here's
the examples we were discussing last
> year when we left off - they are
examples of cases where it could be
> appropriate to override default
behaviors for conref, metadata
> inheritance, etc. So you'll need to explain
how my concerns don't
> apply in the context of these
examples.
>
> http://lists.oasis-open.org/archives/dita/200710/msg00013.html
JO: . . . here are some examples of
overrides that I don’t think we should allow:
JO: Allowing a reference of the form
“#elementid” to reference sub-topic content.
MP: if someone's using a CMS and assigning GUIDs to every element, they may
actually have one unique identifier per element, rather than per topic+element.
JO: Using a single
GUID to reference DITA sub-topic content should not be allowed. No exceptions.
MP: That said, I see your point - it would
be preferable for the tool to externalize the reference as properly formed
DITA, even if it is internally managed differently. I can easily see the syntax
of the href and conref attributes, along with the domains and class attributes,
as being immutable. That said, if someone wants to override what they do with
that syntax (for example, fetching the linktext for the subelement from its
parent topic), I would think that's reasonable.
JO: See my comment
below that starts out “I just think that if we make everything overrideable
…”.
JO: Allowing specializations to give new
meanings to or ignore the meanings of existing attribute/value pairs
(scope=”external”).
MP: maybe there's a difference here between "meaning" and
"behavior". For example, current behavior for
scope="external" might be to open up a new browser window - but in a
particular delivery context they might actually want to popup an intermediate
window that says "you're leaving the website and everything after this is
unwarrantied" or something. Not changing the meaning, but definitely
changing the behavior.
JO: The specific
example given here seems fine to me. But take a related example, that
uses scope=”peer”. Today scope=”peer” is used to say
that the referenced item isn’t currently available for processing, but it
is part of the same document set. I think this definition should be true
in all cases. What one does with items that are part of the “same
document set” could be customized, but not the fact that the item is
considered part of the same document set.
JO: Allowing specializations to ignore
@lockmeta.
MP: I can imagine a draft review process that pulled in "author" info
from the target topics, even though lockmeta was set, because they wanted to
use a single map for both review and for final publication, and they only
wanted the author info for review... So in this case, I am imagining a process
that would ignore lockmeta to do a particular metadata fetch based on business
need rather than specialization.
JO: Wouldn’t it
be better to honor lockmeta and always push or not push the metadata values
from the map into the topic, and then using an output appearance customization
render or not render the “author” info as appropriate for review or
for final publication?
JO: Or wouldn’t
it be better to define lockmeta as an attribute that can inherit its value and
then add lockmeta to the map root element, topicref, topichead, and topicgroup
so that someone that wants this behavior can change the value for an entire
document or portions of a document as desired?
JO: Or to define a way
to set, change, or delete attribute values using conditional processing and
ditaval?
JO: Allowing properties that normally
cascade from a map to a topic to not cascade depending on the specializations
in use.
MP: if a group was doing extensive customization in a map, and was tracking
authorship of the map at a chapter level, I can imagine overriding the normal
cascade of metadata from map to topic to stop author from cascading and
implying authorship of the actual topics rather than of the referencing map
sections. Again, a customization not based on specialization, but still
definitely an override of default behavior.
JO: Doesn’t this
indicate that author information is being used for different somewhat ambiguous
purposes (map author vs. topic author) and that to remove the ambiguity one
should really create a specialization that includes a second set of map-author
information? And because this would be a specialization, it would be OK
to define new rules for inheritance/cascading or even to allow the new element(s)
to cascade, but then later be ignored during output (appearance) processing?
And, if this is a common enough need, we could consider adding map-author
information to the standard definition for map.
MP: I can definitely see the point of
preserving the syntax and meaning of our core attributes - but not sure how
much of subsequent behavior we can really standardize beyond "don't be an
idiot". For example, we have a "<b>" element that
should be rendered as bold - but if someone has a compelling reason to override
that (like bold text has been reserved for warnings only), then I think
adopters should have the freedom to define their own output processing, even
when it deviates from what's in the spec.
JO: How one shows
something as “bold” is an output appearance issue and so I think a
customization along these lines would be fine.
> http://lists.oasis-open.org/archives/dita/200710/msg00051.html
MP: I was thinking of addressing as
"what the syntax means" - for example topicid/elementid - we wouldn't
want that to be overridden by processing, it's not even clear to me what
overriding that would mean. But I buy that processing for addresses should not
ignore or misinterpret the actual information in the address. That said, all
the processes that do something with the info at that address should be
overrideable - like shortdesc pulling, link creation, etc. etc.
JO: I just think that
if we make everything overrideable that there is nothing that users or vendors
can count on as they exchange DITA documents and specializations. Getting back
to what started this discussion long ago, I think it would be better if we can
identify behaviors for which it is important to allow for different non-appearance
customizations, that we define standard ways to request the behavior that is
desired using standard DITA syntax. This might just be a new attribute on elements
that has as a default value that could be specified by the specialization
author that is a list of the common behaviors. If the default is to pull
shrotdesc, create links, and to cascade, then we might have @defaultprocessing=”noshortdescpulling
nolinkcreation nocascade …”. This would make some of the
behaviors customizable as well as standard. It would make it much easier for
users to exchange documents and specializations without having to develop many
system dependent customizations to go with them. We could even make the list of
tokens that can be included in the list open ended. That would allow new
customizations to be implemented once for a particular system and then shared
by different specializations after that.
JO: And if we
are not willing to build something into the standard that allows specializers
to call for different non-appearance behaviors, my preference is that we define
these non-appearance behaviors to be required, so that authors and specializers
that follow the standard can exchange documents and specializations with
confidence and without having to do a lot of additional customization work to
get the non-appearance behaviors that they want. While I think this is
the right approach, the rules that I proposed fall well short of this in that
they only call for these non-appearance behaviors to be required on the base
topic or map document types.
MP: As another conref example: we say you
can generalize on the fly where necessary/appropriate - I can imagine someone
overriding the generalization to, for example, generate titles for specialized
sections that are being generalized during conref. Is that ok?
JO: I’d think it
would be fine to allow the generation of titles for specialized sections that
don’t have them (or even which do have them), but I’d think this
would be an output appearance customization and not something that was part of
conref processing.
JO: But even if you
really want this to be part of conref processing I think it might be OK as long
as the generated content is valid DITA XML for the context in which it is being
used. I am a little uneasy about this because even if this is allowed it
would not be the default behavior and so users can’t count on the
behavior being available or easily available as they move their documents from system
to system.
MP: Are there other conref overrides that
wouldn't be ok, for example overriding the process to allow conref across
specializations without generalization at all?
JO: I think there
needs to be enough validation according to the standard and with no exceptions so
that we know that the conref content either is or that it could be valid at the
point where it is being included.
> http://lists.oasis-open.org/archives/dita/200710/msg00050.html
MP: 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/"?
Answer from the
original e-mail exchange: JO: 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 the
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.
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Sunday, January 06, 2008
4:52 PM
To: Ogden, Jeff
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] How much
flexibility do specializers have to make exceptions to behaviors that are
outlined in the DITA standard?
This ground feels familiar - here's the examples we
were discussing last year when we left off - they are examples of cases where
it could be appropriate to override default behaviors for conref, metadata
inheritance, etc. So you'll need to explain how my concerns don't apply in the
context of these examples.
http://lists.oasis-open.org/archives/dita/200710/msg00013.html
http://lists.oasis-open.org/archives/dita/200710/msg00051.html
http://lists.oasis-open.org/archives/dita/200710/msg00050.html
Michael
Priestley
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
"Ogden, Jeff"
<jogden@ptc.com>
01/04/2008 06:12 PM
|
To
|
Michael Priestley/Toronto/IBM@IBMCA
|
cc
|
<dita@lists.oasis-open.org>
|
Subject
|
RE: [dita] How much flexibility do
specializers have to make exceptions to behaviors that are outlined in the
DITA standard?
|
|
Michael,
I
think you are worried about something that won’t really apply.
The
DITA specifications are mostly silent about issues related to output appearance
(as they should be). And when the specification is silent no requirement
is imposed. If there are areas where the specification does talk about
output appearance we should either remove them from the standard or make sure
there is appropriate wording accompany each one that makes it clear that they
are examples and not requirements.
But
there are other areas that aren’t primarily about output appearance. For
example: inheritance or cascading of properties, metadata, and attribute
values; the syntax and interpretation of href values; key reference processing;
or conref processing. Here I think the specification does (and should) impose
requirements. I think most of these non-appearance requirements should be
imposed on all DITA doctypes including specializations, but to make progress
because you and others don‘t agree, I backed off on this and just imposed
the non-appearance requirements on generic topics and maps.
It is
an open question if we should impose these non-appearance requirements on the
standard DITA specializations (concept, task, reference, glossary, and soon the
learning and training specializations and machine industry specializations). I
sort of think we should, but I realize I am fighting an up hill battle on this.
I think that because these are standard specializations, that if we want
to allow exceptions from the base DITA non-appearance behavior, that we should
do that explicitly in the DITA standard (and if we put the exceptions into the
standard they aren’t really exceptions anymore).
For
specializations that aren’t part of the standard we would not impose
either appearance or non-appearance requirements. Here we would only impose the
“markup/syntax” requirements.
In our
discussions we’ve been talking about “markup/syntax” and
“processing behaviors”. Perhaps we need three categories:
Markup/syntax;
Non-appearance
related processing behaviors; and
Appearance
related processing behaviors.
While
the three categories may be right, I don’t much like the specific
terminology and would welcome better suggestions.
-Jeff
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Friday, January 04, 2008 4:58 PM
To: Ogden, Jeff
Cc: dita@lists.oasis-open.org
Subject: Re: [dita] How much flexibility do specializers have to
make exceptions to behaviors that are outlined in the DITA standard?
Hi Jeff,
I'm uncomfortable with the first resolution below: "For the base
topic and map types both the “markup/syntax” and “processing
behaviors” described in the DITA specifications are required."
Specifically, I think the processing behaviors should remain explicitly
overrideable - maybe "required to be provided as default behaviors"?
I believe there are cases where processing behaviors even for generic topics
and maps could legitimately be overridden by implementors. Otherwise we are
claiming that, for example, no one can generate links from maps except in the
way we specify, or change the way something is formatted... There were a few
examples I came up with before the holidays, I'll try to find them in the
archives.
In the meantime, the architectural spec does have an explicit statement on processing
customization: http://docs.oasis-open.org/dita/v1.1/OS/archspec/customize.html
"When you just need a difference in output, you can use DITA customization
to override the default output without affecting portability or interchange,
and without involving specialization.
For
example, if your readers are mostly experienced users, you could concentrate on
creating many summary tables, and maximizing retrievability; or if you needed
to create a brand presence, you could customize the transforms to apply
appropriate fonts and indent style, and include some standard graphics and
copyright links.
Use
customization when you need new output, with no change to the underlying
semantics (you aren’t saying anything new or meaningful about the
content, only its display)."
Michael Priestley
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
"Ogden, Jeff"
<jogden@ptc.com>
01/02/2008 03:30 PM
|
To
|
<dita@lists.oasis-open.org>
|
cc
|
|
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:
1. How much flexibility do specializers
have to make exceptions to behaviors that are outlined in the DITA standard?
(MUST, SHOULD, MAY discussion)
http://lists.oasis-open.org/archives/dita/200710/msg00025.html
2. What does it mean when we say that
an implementation supports the DITA standard? Is the entire standard required
or are some parts optional?
3. Is the scope of DITA 1.2 as it is
shaping up too large? Is the DITA specification becoming too complex?
4. Is the approach outlined in the
proposed DITA 1.2 documentation TOC a good approach?
http://wiki.oasis-open.org/dita/Draft_1.2_TOC
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:
1. For the base topic and map types
both the “markup/syntax” and “processing behaviors”
described in the DITA specifications are required.
2. For specializations the
“markup/syntax" described in the DITA specifications is required
unless explicitly stated otherwise.
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.
4. For user defined specializations
specific implementations will usually require possibly substantial additional
effort on the user’s part to implement exceptions to the default output
processing behaviors as described in the DITA specifications. Such
implementations are considered fully compliant with the DITA specifications.
5. Using the general guidelines
outlined above the specification editors will review and update all of the DITA
specifications to ensure they are clear about what MUST, SHOULD, or MAY (see RFC 2119) be done
with respect to both the DITA document types that are officially part of the
standard (topic, map, concept, glossary, reference, task, bookmap,
learning/training specializations, and machine industry specializations) and
for user defined specializations that aren’t a formal part of the
standard.
6. Members of the DITA TC are
encouraged to send suggestions to the specification editors about specific
items in the specifications that should have explicitly stated exceptions to
the general rules given above. Suggested exceptions can call for either
stricter or loser requirements. Any differences of opinion about
exceptions will be resolved as part of the review and approval process for the
DITA 1.2 specifications.
-Jeff
From: Ogden, Jeff [mailto:jogden@ptc.com]
Sent: Monday, October 15, 2007 5:39 PM
To: dita@lists.oasis-open.org
Subject: [dita] How much flexibility do specializers have to make
exceptions to behaviors that are outlined in the DITA standard?
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]
Sent: Tuesday, October 16, 2007 11:56 PM
To: Ogden, Jeff
Cc: dita@lists.oasis-open.org
Subject: Re: [dita] How much flexibility do specializers have to
make exceptions to behaviors that are outlined in the DITA standard?
"Ogden, Jeff" <jogden@ptc.com> wrote on 16/10/2007 07:39:06 AM:
> 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?
I prefer for the standard to make no promises, and let specializers take as
much rope as they need.
> 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),
Interesting that you bring up URIs. Inevitably some specialization is
going to come along that wants to link to somewhere in a way that isn't covered
by existing hrefs. We don't have a standard way of making new href-like
attributes, and to cater to those specializations we need to. Or do we:
is this what data/@href is for?
And because that made me think of xlink, it reminds me that something we have
also not discussed for an awfully long time is namespaces. Are DITA
specializers allowed to add namespaced attributes?
> 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.
This is a little tangential, but depending on how we approach a solution, it
might not be.
I suppose that a common scenario is that I have a document that contains a specialization,
but for $transform I don't have any processing to handle that specialization,
so I get fallback behaviour.
Sometimes fallback behaviour is fine. The UI domain, for instance, is
hardly groundbreaking, and falling back to <ph> is not going to hurt.
Sometimes fallback behaviour is ugly. The Utilities domain's
<imagemap> element doesn't really work if rendered as a plain
<fig>: you end up seeing the coordinates as plain text. (I suppose
the real culprit here is the <shape> element rather than its ancestor
imagemap, and that if it were omitted you'd get something at least
presentable.)
How can the processor know when fallback behaviour is acceptable? Is
there some way for a <shape> to say to the processing for its base
topic/keyword, "skip me" (or "die")? (Obviously the
answer today is "no, there isn't", so really my question is "is
this something we want?".)
--
Deborah Pickett
Information Architect, Moldflow Corporation, Melbourne
Deborah_Pickett@moldflow.com
From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Thursday, October 25, 2007 3:21 PM
To: Eliot Kimber
Cc: dita
Subject: Re: [dita] How much flexibility do specializers have to
make exceptions to behaviors that are outlined in the DITA standard?
Hi Eliot,
Re:
> 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.
Couldn't the implementer choose to create hoverhelp for a link to APItopics by
summarizing the syntax, rather than always pulling the shortdesc? Agreed the
syntax should be consistent, but why limit what we do with that syntax?
> Conref. You cannot change the constraints or effective result that conref
produces.
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/"?
It seems to me that one of the advantages of having conref as an explicit
process rather than something that happens as part of parsing (as with entities
or XIncludes) is that you can, as an implementer, choose to enhance or restrict
the processing according to your local requirements.
Michael Priestley
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
-----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]
Sent: Thursday, October 25, 2007 3:41 PM
To: Michael Priestley
Cc: dita; Eliot Kimber
Subject: Re: [dita] How much flexibility do specializers have to
make exceptions to behaviors that are outlined in the DITA standard?
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.
I realized in my wording below I used the word syntax twice to mean two different
things :-)
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 standard; the expected behavior should be default.
Michael Priestley
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
> -----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]
Sent: Thursday, October 25, 2007 6:18 PM
To: Michael Priestley; Eliot Kimber
Cc: dita
Subject: RE: [dita] How much flexibility do specializers have to
make exceptions to behaviors that are outlined in the DITA standard?
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]
Sent: Thursday, October 25, 2007 6:22 PM
To: Eliot Kimber
Cc: dita
Subject: Re: [dita] How much flexibility do specializers have to
make exceptions to behaviors that are outlined in the DITA standard?
I guess I was having trouble separating out "addressing" as a
behavior from the various actual processes that use addressing. I see your
point.
I was thinking of addressing as "what the syntax means" - for example
topicid/elementid - we wouldn't want that to be overridden by processing, it's
not even clear to me what overriding that would mean. But I buy that processing
for addresses should not ignore or misinterpret the actual information in the
address. That said, all the processes that do something with the info at that
address should be overrideable - like shortdesc pulling, link creation, etc.
etc.
For conref, which goes beyond the address, where do we draw the line? Is there
a problem with my example? Or is it another case where the syntax's meaning is
preserved, so even if the exact behavior as described in the spec doesn't apply
it still is preserving the important part of the process, ie the meaning of the
address?
As another conref example: we say you can generalize on the fly where
necessary/appropriate - I can imagine someone overriding the generalization to,
for example, generate titles for specialized sections that are being
generalized during conref. Is that ok? Are there other conref overrides that
wouldn't be ok, for example overriding the process to allow conref across
specializations without generalization at all?
Michael Priestley
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
The End