You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Ferdinand Soethe <fe...@apache.org> on 2006/01/05 08:55:57 UTC
[Proposal] 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
Re: [Proposal] Rules for Forrest Use of class-Attributes
Posted by Thorsten Scherler <th...@apache.org>.
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
http://svn.apache.org/viewcvs.cgi/forrest/trunk/main/webapp/skins/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)
Re: [Proposal] Rules for Forrest Use of class-Attributes
Posted by Ross Gardler <rg...@apache.org>.
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_class
Re: [Proposal] Rules for Forrest Use of class-Attributes
Posted by Ferdinand Soethe <fe...@apache.org>.
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
Re: [Proposal] Rules for Forrest Use of class-Attributes
Posted by Ross Gardler <rg...@apache.org>.
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