dita message
[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 tobehaviors that are outlined in the DITA standard?
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "Ogden, Jeff" <jogden@ptc.com>
- Date: Fri, 4 Jan 2008 16:58:22 -0500
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]