forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [Proposal] Rules for Forrest Use of class-Attributes
Date Thu, 05 Jan 2006 12:23:12 GMT
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

Mime
View raw message