Ferdinand Soethe wrote:
Some recent discussion on this list made me think a bit more about our
concepts with regard to the use of class attributes ...
I'd appreciate your comments.
Near with me on this one, the first part may seem I'm about to disagree
with your proposal, but you'll see otherwise about half way down ;-)
Ferdinand Soethe
Function of class-Attributes
----------------------------
Forrest components (and users) use "class"-attributes in 4 different
ways:
1. Forrest uses class-attributes to preserve special meanings when
transforming custom grammer (such as xdocs) to html.
Example: In the following clipping (from document2html.xsl) you can
see that the xdocs-elements 'warning', 'note' and 'fixme'
(that have no equivalent in html) are transformed to
div-elements and assigned a class-attribute to preserve
meaning and allow for special formatting treatment.
<xsl:template match="note | warning | fixme">
<xsl:apply-templates select="@id"/>
<div>
<xsl:call-template name="add.class">
<xsl:with-param name="class"><xsl:value-of
select="local-name()"/></xsl:with-param>
</xsl:call-template>
My interpretation of our use of class attributes in this context is
different. We are not preserving "special meaning" we are conveying
hints about how the output should be styled. The meaning at this point
is completely irrelevant.
If a user needs to maintain the contextual information then they should
use the original source XML.
2. Skinning uses class-attributes to identify, format and place skin specific
(often generated) components such as menus and tabs.
If you are referring to the *rendering* of the output then this
statement is correct. If you are referring to the XDoc structure this is
not true since there is not necessarily a direct correlation between
XDoc structure and page structure (this is especially true in the
Dispatcher work).
3. Users add class-attributes to elements to create new meanings or
add 'submeanings' to existing elements and facilitate formatting of
those with the Extra-CSS-mechnism.
Example: By adding a class 'instructions' to a simple bulleted list
I can format these lists differently with extra-css.
Same comment as for 1 - the class attribute is a hint for styling not an
indication of meaning.
I accept that in both case (1 and 3) it can be misused to convey meaning
but that is just plain wrong. Users wishing to convey *meaning* should
use an appropriate source format.
4. Plugins (often) need to use class-attributes (just like Forrest in
2) to carry meaning over to html.
I can think of no example of this that is any different from the above
cases, do you have something in mind?
---
So, my own interpretation of what the class attribute (in XDoc) does is
the same in all of your four use cases. It is used as a hint to the
rendering engine about how to actually display the content. Remember
XDoc is our intermediate format, it is not intended for human consumption.
Of course, the reality of usage is that it is often easier to "misuse"
the class attribute when really one should take the time to create a new
input schema. So your interpretation of what the class attribute is used
for is, in real life, a valid one.
<snipped what="problems I agree with"/>
Avoiding these problems
-----------------------
Since we are in the process of reqriting most of our pipelines for the
transition to xhtml, I'd like us to discuss a couple of binding rules
for the handling of class in Forrest.
Good idea!
Some of these could be (please add and correct)
- all transformations (including those in skinning and plugins)
must preserve foreign class attributes. That is: Any class attributes
attached to an element going into the transformation must be carried
over into the resulting element.
+1 - ion fact, as far as I am aware this has already been agreed, it's
just that nobody has sat down and fixed each transformation by hand.
Instead we have been adding them as we find they are a problem.
This work will become much easier with the dispatcher since the XSL
snippets are small and manageable.
- When adding classes to elements that already have a class attribute,
each new class it added to a space separated list. All
transformations and css-formatting must be written to properly handle such
class-lists.
+1
- To avoid conflicts between class names created by different modules,
a module-specific prefix is added to the class name. For Forrest core
modules and extra-css-classes this prefix can be static while each new
plugin should be automatically assigned a unique prefix to use with
all their class names.
Yes. Many moons ago we agreed to make all Forrest defined class
attributes conform to a naming convention, i.e. have a "forrest-"
prefix. We should actually do this, and Ferdinand is right, this is the
time to do it.
I'm not at all sure of the benefits of using the expanded name prefixes
you define below. It just seems complex. Particularly when we remember
that classes in, for example, the tabs may be reused in the body.
I think the naming thing needs exploring with some example snippets of
output. That way we should be able to see if there is a benefit or not.
Example Class Naming
function prefix
Forrest core fo..
menus fomu-
tabs fota-
body fobo-
footer fofo-
etc.
extra-css ecss-
plugin pi..
skills-plugin piskill-
docbook-plugin pidb-
etc.
- Facilitate indirect transport
To facilitate indirect transport (such as the class from body of
xdocs to body of html) we should create and clearly document
class-channels in our transformation. In other words, make sure that
there is a channel class or id attributes into all major elements of
a page and document it ("if you want id in the html-body, attach it
to xdocs document-element").
Actually *all* elements in XDoc allow a class, so we this is already
covered by your desire to carry over all classes.
Open Issues
-----------
I have no idea how all this will be effected by structurer. Can one of
the insiders please comment.
I don't think it is affected. The problem is greatly reduced in the
Dispatcher, and it will also be easier to implement your guidelines, but
the overall observations still stand since most of the contracts have
been extracted from existing skins.
I think w should focus on sorting this out in the Dispatcher. There's
little point in doing it in skins, unless someone has a pressing
*urgent* need for it in skins.
Ross
