RE: [dita-adoption] List of elements requiring styling

["Grosso, Paul" <pgrosso@ptc.com>]

> -----Original Message-----
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
> Sent: Thursday, 2011 February 10 19:39
> To: dita-adoption@lists.oasis-open.org
> Subject: [dita-adoption] List of elements requiring styling
> 
> Hi everyone,
> I've done some thinking about how to move forward on this perpetual
> item:
> 
> ITEM: DITA 1.2 elements needing styling and translatable strings (Yeo)
> *       http://www.oasis-open.org/apps/org/workgroup/dita-
> adoption/email/archives/201008/msg00016.html
> 
> There are a few challenges in getting out an official document that
> lists all the elements needing styling:
> 
> 1) There is a need for a list like this for the 1.1  elements, as well
> as for the new elements.
> 
> 2) Most elements that are visible in output should be styled
> distinctively from other types of elements, or we wouldn't have
> invented them.

I'm not sure what it means for an element to be "visible in
output", but there could certainly be elements we invented
for its semantic meaning that don't necessarily need 
distinctive styling.

But more importantly, whether they get distinctive styling
and what that styling is should be a decision for the user
or document type designer, not us.  Styling is not something
we should be determining.

My understanding (though I'm still not sure I have a clear
one) of this issue is that some people think there are some
aspects of the presentation of some elements that need to be
explained to users rather then letting users decide how they
want to style things themselves.  Su-Laine's example in her
above quoted email is that <note="warning"> implies the need
for a new string which needs to be translated.  But I don't
see that.  Maybe I want warnings to be in red, or maybe I
want to collect all note="warning" elements into a sort of
appendix of warnings [probably not a smart move in the case
of warnings, but the point is that it's not up to us to say
how to style things].

So I remain unclear on what we're really trying to do and why,
and insofar as I understand it, I'm not sure I agree.

> 
> 3) Reviewers would need a thorough knowledge of all parts of the DITA
> vocabulary in order to properly review a full list of which elements
> should be styled distinctively.
> 
> I did some work on the draft page here:
> http://wiki.oasis-open.org/dita-
> adoption/DITA%201.2%20Elements%20which%20Need%20Styling#preview

I have a problem with all the "must be styled..." statements.
I didn't think DITA was a formatting standard, and I believe
that styling of DITA content is the purview of the application 
writers or end users, not OASIS.

I understand that some people want to make clear whether a user
should author a particular string (e.g., title) or not, but it's
the decision of the document type creator (the person tasked with
developing the stylesheet) what should be authored and what should
be generated, and it's their job to make clear to their users what
should be authored or not.  That's not something for us to decide
beyond what we've decided by virtue of what the DTD allows for a
given element.

> It occurred to me when writing it that the main issue that needs inter-
> organization consensus is the question of whether authors should write
> something to indicate the element semantic, or whether the stylesheet
> should make the semantic obvious enough that the author doesn't have to
> write anything to convey the semantic. E.g. if stylesheets don't style
> task <prereq> sections distinctively, then authors feels they must
> write "Prerequisites: " at the beginning of the element.
> 
> Question 1:
> 
> I think it would be reasonable for the Adoption TC to publish a short
> document covering this question as a general guideline for stylesheet
> developers. DITA TC subcommittees that deal with domain specific
> vocabulary sets could then, if and when they choose, create their own
> documents interpreting the guidelines for their own vocabulary sets.
> Does this sound reasonable?

If we could come up with guidelines of the form "the value of xxx
for the yyy attribute on element zzz is generally meant to be an 
indication that mmmmmmm" where mmmmmm is a semantic/operational
statement, not a statement about styling, then I think that would
be fine and useful.  (And as far as I can tell, that's exactly
what the DITA spec already says in the "Using type in a note element"
section at
http://docs.oasis-open.org/dita/v1.2/os/spec/common/thetypeattribute.html
so at least in this case, I don't see the need for anything.)

But insofar as we start making statements about styling, I have
problems.

By way of example, if we want to say that note/@type="warning" 
indicates that the note in question is a warning, fine, but if 
we want to say that such an element must be styled so that it 
generates the word "Warning" or even that it must be styled 
differently than note/@type="caution", then I don't agree.

> 
> Question 2:
> 
> As a proposal to get the discussion going, I suggest that our
> guidelines say that all elements should be styled distinctively-enough
> that the author does not have to write anything to convey the semantic.
> E.g. for the <prereq> element, stylesheets could insert generated text
> such as "Prerequisites." A set of stylesheets that styles <prereq>
> elements as if they are ordinary sections would not be in conformance
> with this guideline.

I don't think I can agree to that.

paul