RE: [dita] Conditional processing with the @rev attribute

Hi Su-Laine,

I agree the arch spec topic needs to
be updated, and I'll agree on the language entry being more specific. It
doesn't say "no filtering" today, although it doesn't say "yes
filtering" either (and the other ones do).

I also agree the new language added
to the attribute description in 1.2 is confusing. I don't know what the
author meant. 

I can imagine wanting to make the point
that rev is not meant to be a rev or version of the product, but a rev
or version of the text. And I can imagine wanting to make the point that
rev is not a mechanism that replaces a version control system; it is not
meant to support automated undo to previous versions, for example. It's
just meant to support the generation of change bars. But I don't think
the current text makes those points.

Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect 



http://dita.xml.org/blog/25

From:
"Su-Laine Yeo" <>

To:
Michael Priestley/Toronto/IBM@IBMCA,
"Kristen James Eberlein" <>

Cc:
<>

Date:
07/16/2010 03:33 PM

Subject:
RE: [dita] Conditional processing with
the @rev attribute

Thanks Michael for the prompt
clarification. The about-ditaval topic for both DITA 1.1 and DITA 1.2 is
clear about no filtering for @rev, however I think that both the archspec
and the language reference should say that there is no filtering for @rev,
in addition to the language reference linking prominently to the about-ditaval
topic.  The language reference for @rev is not clear to me:

 

For DITA 1.1 it says: “Indicates
revision level of an element. It is useful for flagging outputs based on
revision. If no value is specified, but the attribute is specified on an
ancestor within a map or within the related-links section, the value will
inherit from the closest ancestor.” ( http://docs.oasis-open.org/dita/v1.1/CD02/langspec/common/select-atts.html
)

 

For DITA 1.2 it says: “Indicates
a revision level of an element that identifies when the element was added
or modified. It may be used to flag outputs when it matches a run-time
parameter. It is not sufficient to be used for full version control, such
as single-sourcing multiple product variants based on version level, as
it only represents one aspect of the revision level. If no value is specified,
but the attribute is specified on an ancestor within a map or within the
related-links section, the value will cascade from the closest ancestor.”
( http://docs.oasis-open.org/dita/v1.2/cd03/spec/common/select-atts.html#select-atts
)

 

Neither of these currently
says to me “no filtering”. Also I don’t understand this sentence: “It
is not sufficient to be used for full version control, such as single-sourcing
multiple product variants based on version level, as it only represents
one aspect of the revision level.” Where are the other aspects of the
revision level stored? Is revision level the same as version level? What
does the term “sufficient to be used for full version control” mean in
terms of how processors are expected to treat  an attribute? 

 

Cheers,

Su-Laine

 

 

Su-Laine Yeo

Solutions Consultant 

JustSystems Canada, Inc.

Office: 778-327-6356 



www.justsystems.com

XMetaL Community Forums:
http://forums.xmetal.com/

 

 

 

From: Michael Priestley [mailto:]

Sent: Thursday, July 15, 2010 7:25 PM

To: Kristen James Eberlein

Cc: 

Subject: Re: [dita] Conditional processing with the @rev attribute

 

The description of the attribute in the language reference is clear, and
the description of flagging behavior for the ditaval elements is clear:

http://docs.oasis-open.org/dita/v1.2/cd03/spec/common/select-atts.html#select-atts

http://docs.oasis-open.org/dita/v1.2/cd03/spec/common/about-ditaval.html#ditaval

The architectural spec topic does not make the distinction adequately,
but the distinction has always been there, and the expected behavior is
described in the language spec.

I think this is an area where we need to clear up the language in the arch
spec, and also add links to the relevant portions of the lang spec.

Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect 



http://dita.xml.org/blog/25

From:

Kristen James Eberlein <>

To:



Date:

07/15/2010 09:56 PM

Subject:

Re: [dita] Conditional processing with the
@rev attribute

 

Su-Laine, my understanding is that the @rev attribute is used for flagging
but not filtering. Both filtering and flagging fall under the rubric of
"conditional processing." Can others confirm this?

Obviously, we need to clarify the spec around this point.

Best,

Kris

Kristen James Eberlein

Principal consultant, Eberlein Consulting

Secretary, OASIS DITA Technical Committee

Charter member, OASIS DITA Adoption Committee

www.eberleinconsulting.com

+1 919 682-2290; kriseberlein (skype)

On 7/15/2010 9:30 PM, Su-Laine Yeo wrote: 

Hi everyone,

As far as I know, the @rev attribute has
always been included in the list of conditional processing attributes (http://docs.oasis-open.org/dita/v1.1/CD02/archspec/condproc.html).
I don’t know of anything in the DITA 1.1 spec that says that
it
should be processed differently
from the other conditional processing
attributes. 

However, AFAIK the Open Toolkit
ignores DITAVAL statements to exclude
content based on @rev, and a
recent statement from Michael was that
“rev cannot be used for filtering”:
http://tech.groups.yahoo.com/group/dita-users/message/17821
.
It’s not clear to me whether Michael’s
statement is a statement of how the OT currently behaves or if it’s a
statement of how the OT should
behave. 

The draft DITA 1.2 spec deepens my confusion.
It says, “DITA
defines five attributes that are specifically intended to enable filtering
or flagging of individual elements.
Those attributes are @audience, @platform,
@product, @otherprops, and @props.” But then a few paragraphs later under
a section titled
“Conditional
processing
attributes” it lists six attributes
including @rev. 

So is @rev a conditional processing attribute
or not? What
is our expectation from processors?

a) Processors
should
filter based on @rev if
instructed to do so by the DITAVAL file

b)
Processors
may choose to
filter based on @rev if
instructed to do so by
the DITAVAL file

c) Processors must never filter
based on @rev regardless of what the
DITAVAL file says 

In my opinion, the wording of the DITA 1.1
spec indicates option A or B, so we can’t change the expected behaviour
to C without
breaking backwards-compatibility.

Su-Laine

Su-Laine Yeo

Solutions Consultant 

JustSystems Canada, Inc.

Office: 778-327-6356



www.justsystems.com

XMetaL Community Forums:
http://forums.xmetal.com/