Rules for Forrest Use of class-Attributes

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.

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>

2. Skinning uses class-attributes to identify, format and
place skin specific
   (often generated) components such as menus and tabs.

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.   
   
4. Plugins (often) need to use class-attributes (just like
Forrest in
   2) to carry meaning over to html.


(My) Problems with the Current Approach
---------------------------------------

In customizing Forrest and attempting a plugin I found that
our
current system will generally take care of functions 1 and
2, supports
3 to a limited extend and has few or no provisions for
handling
funtion 4.

The problem I have identified so far are:

1. Class-transparency
   Most of our transformations are not class-transparent. A
   class-attribute fed into that transformation is often
ignored,
   or overwritten.

2. No Conflict-Handling
   There is not concept to avoid or handle conflicts, when
more than one
   function tries to add class to an element.

3. No rules for indirect transport of classes
   For example: Even though xdoc has a body-element,
attaching a class
                or id to it will not carry it over into the
body
                element of the final html because there is
no direct
                tranformation.

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.

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.

  Transformations that significantly change the structure of
elements
  or create multiple elements in the result tree (see the
example of 'warning')
  should try to preserve class-attributes true to their
meaning. For
  example transfer the warning-class to the surrounding
div-element
  rather than its child element.
  
  Exception: Class-attributes created as internal markers
within a
             chain of transformations may or even must be
removed.

- 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.

- 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.

  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").
  
       
Open Issues
-----------

I have no idea how all this will be effected by structurer.
Can one of
the insiders please comment.





























--
Ferdinand Soethe

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

Ross Gardler wrote:

>> 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.


> 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.

Hmmm. Maybe I need to be more precise.

Let's say we get to the point where xhtml will be our common
internal
format and all input must be transformed to xhtml before
being transformed
into the different output formats.

- btw. this ties into our debate about the
smartslides-plugin -

How will I be able to supply meaning like "this is a
chapter of
slides" other then using class?

Perhaps this is not needed to created Webpages or pdfs, but
what about
output plugins like slidy that need to know the meaning.

Or - looking from a different angle - how can that one and
only class
serve as a hint for so different outputs as pdf, html,
voice?

> If a user needs to maintain the contextual information
then they should
> use the original source XML.

Which was exactly what I had intended to do with Smartlides
when you
argued that all data had to go through the common format.

I'm confused. Am I missing something?

>> 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).

Well skinning does the job of rendering it.
To be more precise: I'm referring to the process of creating
the part
of a page that contains the menu items and tabs and uses a
standard
set of classes to allow all the skins to format it.

>> 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 disagree. The instruction class that I added to howto's
some time
ago is meaning that is deliberately carried all the way to
the final
html so that different skins can interpret that meaning
whichever way
they see fit.

But perhaps I'm still missing your point. Can you help?

> 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.

Again: why misuse? I'm missing something here.

>> 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?

No, it is the same issue. Plugins just make it more
problematic
because each one may add they own set of new meanings.

> Remember
> XDoc is our intermediate format, it is not intended for
human consumption.

I understand that. But I think that software like
out-plugins might
have even more need to know meaning than humans.
For example: The slidy transformations need to know where
the chapters
of a presentation are in order to process them correctly. A
formatting
hint like ("make this a big heading") would be
useless.


>> - 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.

Sure. I was just trying to summarize all the rules in one
document.

>> - 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

This is one important part. I might have missed the outcome
of the
debate on having more that one class-name in a
class-attribute.

>> - 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.

One reason to come up with the prefix-scheme was to avoid
long
prefixed like "forrest-" in the future. While I'm
usually much in
favour of speaking names, here I would strongly object
because we
would really increase the overhead of each page when we
carry long
class-names in every generated element.

> 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.

Seems to me like one more reason to have prefixes. Why would
you have
the same class name for two very differnt parts of a page?

> 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.

Sure. It was really just an example to illustrate that I'd
like to
have short prefixes to keep overhead small and keep things
separate
with prefixes to avoid conflicts.

> Actually *all* elements in XDoc allow a class, so we
this is already
> covered by your desire to carry over all classes.

Well, not really. Because in these indirect translations
there are a
number of different ways to make a class go into the body
class in the
end. And to keep things kompatible (especially with plugins)
it would
really help to document the way we want it to be.

For example: If our transformations support a direct
translation form
xdoc-body to html-body, we should make that clear because
the
transformations inbetween will be rather hard to follow.

>> 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.

That's what I was hoping for.

> 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.

+1
This will also give us enough time to discuss this.
Thanks for your comments.

--
Ferdinand Soethe

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 

...

> How will I be able to supply meaning like "this is
a chapter of
> slides" other then using class?

There is no need to describe the *meaning* you are only
describing 
rendering hints. Forrest is an XML publishing engine,
nothing more, all 
it does is render stuff, it does not manipulate it any
further than 
adding decoration and stripping unwanted information,
therefore there is 
no need for context in the intermediate format, only for 
rendering/publishing hints.

The confusion lies in the fact that we, as humans, think of
it as 
meaning because it has meaning to us, and we naturally pick
class names 
that are meaningful to a human. However, they could just as
easily be 
"A1", "A2", "A3" etc. Forrest
would still do its job correctly.

...

> Or - looking from a different angle - how can that one
and only class
> serve as a hint for so different outputs as pdf, html,
voice?

(see below next section for a reply - trying to keep the
thread focused)

>>If a user needs to maintain the contextual
information then they should
>>use the original source XML.
> 
> 
> Which was exactly what I had intended to do with
Smartlides when you
> argued that all data had to go through the common
format.

I still argue that common data should go through the
intermediate format 
whenever they need to be *rendered*. It is not necessary to
maintain 
context when rendering since there is no *explicit* context
in the final 
output document. There is plenty of implicit context, for
example, 
headings are larger than paragraphs,  but there is no
explicit context 
(at least not explicit to a machine).

Of course, Forrest is built on Cocoon and has a plugin
framework. It is 
easy to extend Forrest so that you can do additional
processing of the 
original source, but in this instance you are building a
webapp and 
Forrest is only the publishing part of that webapp.

[now back to the CSS stuff from above the previous section]

>>Remember
>>XDoc is our intermediate format, it is not intended
for human consumption.
> 
> 
> I understand that. But I think that software like
out-plugins might
> have even more need to know meaning than humans.
> For example: The slidy transformations need to know
where the chapters
> of a presentation are in order to process them
correctly. A formatting
> hint like ("make this a big heading") would
be useless.

Formatting hints do not have a meaning attached to them. It
is up to the 
renderer to decide what that hint means. So your example of
"make this a 
big heading" is not a hint, that is an instruction. A
"big_heading" hint 
could be interpreted as:

"make this 120% the size of other headings"
"make this bold"
"say this at 120% volume of other text"
"create a new page and centre this text"

etc.

The slidy plugin only needs to know what is a chapter in
order to render 
it in a particulatr way, so class="chapter" is
sufficient, XSL can be 
used to add further rules. If this really does not work for
your use 
case (and every 6 months or so someone claims it doesn't)
please provide 
a concrete use case with an input XML snippet and a desired
output XHTML 
(or whatever) snippet and I'll show you the intermediate
representation. 
If I fail to do so then I'll concede the point 

>>>- 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
> 
> This is one important part. I might have missed the
outcome of the
> debate on having more that one class-name in a
class-attribute.

It is safe to go ahead. The final rendering engine can
choose to ignore 
hints it does not understand.

> One reason to come up with the prefix-scheme was to
avoid long
> prefixed like "forrest-" in the future. While
I'm usually much in
> favour of speaking names, here I would strongly object
because we
> would really increase the overhead of each page when we
carry long
> class-names in every generated element.

So use "for-" instead 

>>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.
> 
> 
> Seems to me like one more reason to have prefixes. Why
would you have
> the same class name for two very differnt parts of a
page?

I meant that "for-highlight" might appear in the
tabs and in the body 
but is still the same hint in both locations. In your
example names you 
had things like "for-tabs-*" and
"for-body-*", I interpreted this to 
mean my hightligh class would become two hints with
identical CSS meanings.

However, you are saying that it may have a different meaning
in the tabs 
as to the body. I don't think this is not a problem though,
CSS allows 
you do define different definitions depending on where the
class is found.

Thorsten has already done some work on CSS naming
conventions (long time 
ago now). I'd suggest scouring the archives and seeing what
he 
suggested. My vague recollections are that it was quite
similar to your 
proposal here. Things will have changed a bit because we now
have the 
dispatcher (which incorporates many of those original
ideas).

>>Actually *all* elements in XDoc allow a class, so we
this is already
>>covered by your desire to carry over all classes.
> 
> 
> Well, not really. Because in these indirect
translations there are a
> number of different ways to make a class go into the
body class in the
> end. And to keep things kompatible (especially with
plugins) it would
> really help to document the way we want it to be.
> 
> For example: If our transformations support a direct
translation form
> xdoc-body to html-body, we should make that clear
because the
> transformations inbetween will be rather hard to
follow.

I'm not following you here. I agree to documentation being
needed 
though, perhaps I will follow then 

Ross

[1] http://www.w3.org/TR/xhtml2/mod-core.html#adef_core_cla
ss

El lun, 09-01-2006 a las 12:32 +0000, Ross Gardler
escribió:

...
> > One reason to come up with the prefix-scheme was
to avoid long
> > prefixed like "forrest-" in the future.
While I'm usually much in
> > favour of speaking names, here I would strongly
object because we
> > would really increase the overhead of each page
when we carry long
> > class-names in every generated element.
> 
> So use "for-" instead 
> 

+1

> >>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.
> > 
> > 
> > Seems to me like one more reason to have prefixes.
Why would you have
> > the same class name for two very differnt parts of
a page?
> 
> I meant that "for-highlight" might appear in
the tabs and in the body 
> but is still the same hint in both locations. In your
example names you 
> had things like "for-tabs-*" and
"for-body-*", I interpreted this to 
> mean my hightligh class would become two hints with
identical CSS meanings.
> 
> However, you are saying that it may have a different
meaning in the tabs 
> as to the body. I don't think this is not a problem
though, CSS allows 
> you do define different definitions depending on where
the class is found.
> 
> Thorsten has already done some work on CSS naming
conventions (long time 
> ago now). I'd suggest scouring the archives and seeing
what he 
> suggested. My vague recollections are that it was quite
similar to your 
> proposal here. Things will have changed a bit because
we now have the 
> dispatcher (which incorporates many of those original
ideas).
> 

http:/
/forrest.apache.org/docs_0_80/views.html
http:
//svn.apache.org/viewcvs.cgi/forrest/trunk/main/webapp/skins
/leather-dev/brainstorming.txt?view=markup
h
ttp://svn.apache.org/viewcvs.cgi/forrest/trunk/main/webapp/s
kins/leather-dev/contracts.initial.txt?view=markup

Contracts are following already this convention.

HTH

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)