You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Ross Gardler <rg...@wkwyw.net> on 2003/12/27 04:00:31 UTC
Allow "role" attribute in document DTD
I recall a discussion about moving to XHTML as an intermediate document
format rather than the document DTD so the answer to this question may
be something bigger than I expect, but I'll take that risk ;-)
In my skin I have turned of validation so that I can add a role
attribute to sections. This is because some sections get rendered by my
skin in a slides view, whilst others are rendered as normal. In a skin
without knowledge of these roles the slides get displayed as normal
sections.
I also use the role attribute in links to denote glossary entries,
cross-references and citations (these get rendered as special links into
the relevant pages).
I think that a role attribute in many elements within the DTD would make
sense. I therefore propose that we add it to the Document v2.0a DTD.
Does anyone have a problem with this, or perhaps an alternative
suggestion on how to achieve my goal (XHTML as intermediate format)?
Ross
Re: Allow "role" attribute in document DTD
Posted by Ross Gardler <rg...@wkwyw.net>.
Peter Hargreaves wrote:
> On Sat, 2003-12-27 at 03:00, Ross Gardler wrote:
>
>>I recall a discussion about moving to XHTML as an intermediate document
>>format rather than the document DTD so the answer to this question may
>>be something bigger than I expect, but I'll take that risk ;-)
>
>
> There is also the possibility of using Docbook (or a tiny subset) as the
> intermediate document format.
Well, the problem actually became smaller rather than larger. I am now
convinced class is the right thing once I am in the intermediate xdoc
format. As my original source format, I am going to look ad docbook -
thanks for the pointers.
Ross
Re: Allow "role" attribute in document DTD
Posted by Peter Hargreaves <su...@pdh-online.info>.
On Sat, 2003-12-27 at 03:00, Ross Gardler wrote:
> I recall a discussion about moving to XHTML as an intermediate document
> format rather than the document DTD so the answer to this question may
> be something bigger than I expect, but I'll take that risk ;-)
There is also the possibility of using Docbook (or a tiny subset) as the
intermediate document format.
> In my skin I have turned of validation so that I can add a role
> attribute to sections. This is because some sections get rendered by my
> skin in a slides view, whilst others are rendered as normal. In a skin
> without knowledge of these roles the slides get displayed as normal
> sections.
>
> I also use the role attribute in links to denote glossary entries,
> cross-references and citations (these get rendered as special links into
> the relevant pages).
The following are the section attributes taken from Norman Walsh's
"DocBook: The Definitive Guide". Hope you find it relevant:
label
Label specifies an identifying string for presentation purposes.
Generally, an explicit Label attribute is used only if the
processing system is incapable of generating the label
automatically. If present, the Label is normative; it will used
even if the processing system is capable of automatic labelling.
status
Status identifies the editorial or publication status of the
Section.
Publication status might be used to control formatting (for
example, printing a “draft” watermark on drafts) or processing
(perhaps a document with a status of “final” should not include
any components that are not final).
Peter
> I think that a role attribute in many elements within the DTD would make
> sense. I therefore propose that we add it to the Document v2.0a DTD.
>
> Does anyone have a problem with this, or perhaps an alternative
> suggestion on how to achieve my goal (XHTML as intermediate format)?
> Ross
>
--
--
Re: Allow "role" attribute in document DTD
Posted by Johan Kok <jk...@messianic.dyndns.org>.
Support the idea or roles +1, we have the following scenario:
A number of authors are developing various parts of the document (or
let's say 'books'). These are inter-disciplinary people covering
medical, forensics and the law. The following publishing rules exist:
Public:
Online on the web: Anybody can browse the content, page by page.
PDF files can be viewed, but are protected and cannot be saved and the
content not copied
Private (members):
Have access to a published version of the documents and free use of
content, including an uinprotected version of PDF files
Authors:
Currently all authors have full access to the document. I may change
towards a contribution based access or a membership class difference.
Authors exist in several levels:
1. Editor in charge (overall) -
Verify
1.1 Editor in charge (section, sub-section, sub-sub-section - can go
down interatively)
1.2 Associate section authors - specific subsections allocated or
selected (depending on the Section Editor's choice)
Check subsections in and out - we're looking at something
like CVS to control this in the mean-time.
Contributions are logged against any contributer (potential future
royalty basis).
We are currently publishing on seperate web-sites with different
configurations and access controls.
Ross Gardler wrote:
> I recall a discussion about moving to XHTML as an intermediate
> document format rather than the document DTD so the answer to this
> question may be something bigger than I expect, but I'll take that
> risk ;-)
>
> In my skin I have turned of validation so that I can add a role
> attribute to sections. This is because some sections get rendered by
> my skin in a slides view, whilst others are rendered as normal. In a
> skin without knowledge of these roles the slides get displayed as
> normal sections.
>
> I also use the role attribute in links to denote glossary entries,
> cross-references and citations (these get rendered as special links
> into the relevant pages).
>
> I think that a role attribute in many elements within the DTD would
> make sense. I therefore propose that we add it to the Document v2.0a DTD.
>
> Does anyone have a problem with this, or perhaps an alternative
> suggestion on how to achieve my goal (XHTML as intermediate format)?
>
> Ross
>
>
>
>
Re: Allow "role" attribute in document DTD
Posted by Ross Gardler <rg...@wkwyw.net>.
Marshall Roch wrote:
> Ross Gardler wrote:
>
>> I recall a discussion about moving to XHTML as an intermediate
>> document format rather than the document DTD so the answer to this
>> question may be something bigger than I expect, but I'll take that
>> risk ;-)
>
>
> Having control over what elements my authors can use is one of the
> features I really like about Forrest, so maybe something like Docbook
> (Simplified?) instead, but (IMHO) certainly not all of XHTML. But
> that's another thread, if people want to go there...
It's a discussion that has been had a few times. Plenty of stuff in the
archives.
>> This is because some sections get rendered by my skin in a slides
>> view, whilst others are rendered as normal. In a skin without
>> knowledge of these roles the slides get displayed as normal sections.
>
>
> Isn't that what the doctype declaration is for? Create a Slide content
> type (with its own DTD that extends Document), so that it will be passed
> to a different XSL stylesheet.
Yes, I have been working with my own extended DTD for some time (or
rather I turned of validation and let myself do what I wanted). It is
time to tidy it up. I'm just trying to ascertain a) am I doing it right
or should I be doing something else (such as use class) and b) if I'm
doing it right should it be in the Forrest DTD or should I stick with my
own DTD.
Ross
Re: Allow "role" attribute in document DTD
Posted by Marshall Roch <ma...@exclupen.com>.
Ross Gardler wrote:
> I recall a discussion about moving to XHTML as an intermediate document
> format rather than the document DTD so the answer to this question may
> be something bigger than I expect, but I'll take that risk ;-)
Having control over what elements my authors can use is one of the
features I really like about Forrest, so maybe something like Docbook
(Simplified?) instead, but (IMHO) certainly not all of XHTML. But
that's another thread, if people want to go there...
> In my skin I have turned of validation so that I can add a role
> attribute to sections.
I had the same problem with the class attribute. I ended up making a
custom Document DTD that added this, and will allow me to add any other
elements that apply to the whole site and don't merit their own specific
content type (like my iCalendar does).
> This is because some sections get rendered by my
> skin in a slides view, whilst others are rendered as normal. In a skin
> without knowledge of these roles the slides get displayed as normal
> sections.
Isn't that what the doctype declaration is for? Create a Slide content
type (with its own DTD that extends Document), so that it will be passed
to a different XSL stylesheet.
http://xml.apache.org/forrest/validation.html#Validating+new+XML+types
--
Marshall Roch
Re: Allow "role" attribute in document DTD
Posted by Peter Hargreaves <su...@pdh-online.info>.
On Sat, 2003-12-27 at 13:55, Ross Gardler wrote:
> >>Since class is intended to describe display information I'm not sure if
> >>it could be used for this same purpose, it may just confuse things as
> >>we'd likely end up with classes that didn't affect display.
> >
> >
> > That's fine, however there is already a 'role' attribute defined for
> > <link>.
>
> Yes, I forgot that, sorry, been a long time since I started using that,
> so my example was a very poor one, perhaps below will be better.
>
> > So do you want to define @role more generally, to apply to other
> > elements? If so, what is the use-case?
>
> At present the only plac my use case needs it is in the section element,
> but perhaps more general would be useful.
>
> Now that you are forcing me into explaining the use case I am becoming
> more convinced that you are right and this is in fact a class. However,
> I also introduced another attribute recently. This one was origianlly
> "level" as in level of detail (I use Forrest to deliver course support
> materials). However, I have recently decided this should be part of the
> role attribute.
>
> Basically, I tag some parts as being "BSc", "MSc", "MBA" etc. Other
> parts are tagged as course focus, for example case studies have roles
> such as "ECommerce_Analysis" or "MBA_Anaysis". I then use these to
> select which part of the document should be displayed. So if I have an
> MBA student veiwing the page they get the "BSc" + "MBA" content of
> general pages and the "MBA_Analysis" of case studies.
>
> Since much of the content is shared I do not want to split it into
> different documents, so I use role to enable me to do that dynamcally.
>
> > Isn't that use-case
> > presentational? If presentational, why not use class?
>
> I have to admit I'm a little unsure if this is presentational or not. I
> think of presentation as being *how* it is displayed whereas much of my
> use for the role attribute is *what* is displayed (clearly I use Forrest
> in a dynamic environment).
IMO - In your document it is not presentation, it is just content and
semantic markup, but your skin might later use the markup for
presentational purposes - if it feels that way inclined. After all most
of your dtd markup is used for presentational decisions.
So, forget about thinking presentation in your dtd and think about what
meaning you want to include in the document. So, why not:
<section usecase="BSc"> or as you suggest <section role="BSc">
I've used things like <section onlyfor="user,admin"> or <section
notfor="guest,visitor"> in my application.
Hope my comments help.
Peter.
P.S. DocBook is great for inspiration on markup.
> I have similar use cases with data from electronic sensor devices. The
> engineers get one lot of data, the management another etc.
>
> Ross
--
Re: Allow "role" attribute in document DTD
Posted by Jeff Turner <je...@apache.org>.
On Sat, Dec 27, 2003 at 09:55:59AM -0400, Ross Gardler wrote:
[on @role]
...
> Now that you are forcing me into explaining the use case I am becoming
> more convinced that you are right and this is in fact a class.
<evil grin>
...
> Basically, I tag some parts as being "BSc", "MSc", "MBA" etc. Other
> parts are tagged as course focus, for example case studies have roles
> such as "ECommerce_Analysis" or "MBA_Anaysis". I then use these to
> select which part of the document should be displayed. So if I have an
> MBA student veiwing the page they get the "BSc" + "MBA" content of
> general pages and the "MBA_Analysis" of case studies.
>
> Since much of the content is shared I do not want to split it into
> different documents, so I use role to enable me to do that dynamcally.
>
> > Isn't that use-case
> > presentational? If presentational, why not use class?
>
> I have to admit I'm a little unsure if this is presentational or not.
Sounds 'structural'.
> I think of presentation as being *how* it is displayed whereas much of
> my use for the role attribute is *what* is displayed (clearly I use
> Forrest in a dynamic environment).
>
> I have similar use cases with data from electronic sensor devices. The
> engineers get one lot of data, the management another etc.
This could be handled with an XSLT to include/exclude marked bits. I
assume you've already done something like this.
For the marker attribute, couldn't 'class' still work for this? Though
class is typically used for CSS, there's nothing to say it can't be used
for structural decisions. A hook is a hook, no matter what you hang on
it.
--Jeff
> Ross
>
Re: Allow "role" attribute in document DTD
Posted by Ross Gardler <rg...@wkwyw.net>.
>>Since class is intended to describe display information I'm not sure if
>>it could be used for this same purpose, it may just confuse things as
>>we'd likely end up with classes that didn't affect display.
>
>
> That's fine, however there is already a 'role' attribute defined for
> <link>.
Yes, I forgot that, sorry, been a long time since I started using that,
so my example was a very poor one, perhaps below will be better.
> So do you want to define @role more generally, to apply to other
> elements? If so, what is the use-case?
At present the only plac my use case needs it is in the section element,
but perhaps more general would be useful.
Now that you are forcing me into explaining the use case I am becoming
more convinced that you are right and this is in fact a class. However,
I also introduced another attribute recently. This one was origianlly
"level" as in level of detail (I use Forrest to deliver course support
materials). However, I have recently decided this should be part of the
role attribute.
Basically, I tag some parts as being "BSc", "MSc", "MBA" etc. Other
parts are tagged as course focus, for example case studies have roles
such as "ECommerce_Analysis" or "MBA_Anaysis". I then use these to
select which part of the document should be displayed. So if I have an
MBA student veiwing the page they get the "BSc" + "MBA" content of
general pages and the "MBA_Analysis" of case studies.
Since much of the content is shared I do not want to split it into
different documents, so I use role to enable me to do that dynamcally.
> Isn't that use-case
> presentational? If presentational, why not use class?
I have to admit I'm a little unsure if this is presentational or not. I
think of presentation as being *how* it is displayed whereas much of my
use for the role attribute is *what* is displayed (clearly I use Forrest
in a dynamic environment).
I have similar use cases with data from electronic sensor devices. The
engineers get one lot of data, the management another etc.
Ross
Re: Allow "role" attribute in document DTD
Posted by Jeff Turner <je...@apache.org>.
On Sat, Dec 27, 2003 at 02:25:26AM -0400, Ross Gardler wrote:
> Jeff Turner wrote:
> >+1 for the general idea.
> >
> >Perhaps 'class' (as in HTML) instead of 'role'? Is there a difference?
>
> I did think about class, and in most cases it will do the job. The
> reason I didn't go for it in the end was because I thought that there
> may be a need for different classes of (in my case) slides. However, I
> haven't actually come across a use case for this yet.
>
> Another reason for going with role was the REST architecture idea that
> an application could intelligently interpret the purpose of a part of a
> document using the role attribute. Class is about display only whereas
> "slide" or "glossary" are about the intended purpose of that section of
> data.
>
> In the original source document this is in the markup language
> itself, but in xdoc this is lost.
>
> An example of why this may be important...
>
> Suppose, we have a tutorial on how to build a Forrest web site. This
> tutorial has a series of links. Some of which give extra detail about a
> topic by linking to different tutorials. Some gice glossary definitions,
> some define a trail through the training materials. Using role you can
> indicate all of these. Consider the following code:
>
> An XML document ready for display by Forrest conforms to <link
> href="xdocDTD" role="forrestTrailIntermediate glossary">Document v1.2
> DTD</link>, however, you need not write your documents in this format.
> By configuring your <link href="sitemap" role="forrestTrailAdvanced
> glossary">sitemap.xmap</link> accordingly and providing <link href="xsl"
> role="glossary">XSL</link> you can cause Forrest to convert any source
> format into the native XDoc format ready for display.
>
> Here, we have three links. All of them have a role of "glossary", one
> indicates it is part of the intermediate forrest trail, the other is
> advanced. A client application can now be built that extracts all
> glossary terms from a website (by retrieving the XDoc source), or it
> could build a single document for the each of the forrest trails etc.
>
> Since class is intended to describe display information I'm not sure if
> it could be used for this same purpose, it may just confuse things as
> we'd likely end up with classes that didn't affect display.
That's fine, however there is already a 'role' attribute defined for
<link>.
So do you want to define @role more generally, to apply to other
elements? If so, what is the use-case? Isn't that use-case
presentational? If presentational, why not use class?
--Jeff
> Having said that, not using it may duplicate information.
>
> What do you think?
>
> Ross
>
Re: Allow "role" attribute in document DTD
Posted by Ross Gardler <rg...@wkwyw.net>.
Ivan Kurmanov wrote:
> I'm afraid of being out-of-context on this, but I'll just
> leave my comments. You decide if they are useful.
Actually it was my use case that was out of context on this one since
there is already a role attribute in the Link element!
The other problem I have is in identifying content in the XDoc format...
>>Here, we have three links. All of them have a role of "glossary", one
>>indicates it is part of the intermediate forrest trail, the other is
>>advanced. A client application can now be built that extracts all
>>glossary terms from a website (by retrieving the XDoc source), or it
>>could build a single document for the each of the forrest trails etc.
>
>
> If you want to extract all glossary terms from a website, it
> might be better to have all the terms marked-up respectively
> (as some kind of objects), then to extract that info from
> links. ...may be something like:
>
> <term id='xdocDTD'>
> <name>Document v1.2 DTD</name>
> <description>New version of the DTD for
> documents... </description>
> </term>
>
>
> Then, if you want, you can render all references to glossary
> terms in some special way, no need to mark that up in every
> occurence of it in the documents--but define a rendering
> rule in match="a[@ref]" template.
>
>
> Does that make any sense?
This makes total sense when you have the original source format. My
thinking has been that this information is lost when it is passed to
Forrest since the contextual information contained in the <term>
elements is lost. However, the more I think about/discuss this the more
I become convinced that, at the XDoc level, this is actually a class not
a role as Jeff original suggested.
Since XDoc is a format for display purposes we shouldn't be worried
about contextual information, just as long as it can be displayed
correctly.
Ross
Re: Allow "role" attribute in document DTD
Posted by Ivan Kurmanov <ku...@openlib.org>.
I'm afraid of being out-of-context on this, but I'll just
leave my comments. You decide if they are useful.
On 03-12-27, Ross Gardler wrote:
>
> Suppose, we have a tutorial on how to build a Forrest web site. This
> tutorial has a series of links. Some of which give extra detail about a
> topic by linking to different tutorials. Some gice glossary definitions,
> some define a trail through the training materials. Using role you can
> indicate all of these. Consider the following code:
>
> An XML document ready for display by Forrest conforms to <link
> href="xdocDTD" role="forrestTrailIntermediate glossary">Document v1.2
> DTD</link>, however, you need not write your documents in this format.
> By configuring your <link href="sitemap" role="forrestTrailAdvanced
> glossary">sitemap.xmap</link> accordingly and providing <link href="xsl"
> role="glossary">XSL</link> you can cause Forrest to convert any source
> format into the native XDoc format ready for display.
In my own XHTML-based document markup language, I use
<a> tags for links. For links to other pages of the site I
use <a> tag with "ref" attribute, eg I'd write:
An XML document ready for display by Forrest conforms to
<a ref="xdocDTD"/>, however, you need not write your
documents in this format. ...
On the output this would turn into something like
An XML document ready for display by Forrest conforms to
<a href="/gloss/xdocDTD.html" class="internal">Document
v1.2 DTD</a>, however, you need not write your documents
in this format. ...
> Here, we have three links. All of them have a role of "glossary", one
> indicates it is part of the intermediate forrest trail, the other is
> advanced. A client application can now be built that extracts all
> glossary terms from a website (by retrieving the XDoc source), or it
> could build a single document for the each of the forrest trails etc.
If you want to extract all glossary terms from a website, it
might be better to have all the terms marked-up respectively
(as some kind of objects), then to extract that info from
links. ...may be something like:
<term id='xdocDTD'>
<name>Document v1.2 DTD</name>
<description>New version of the DTD for
documents... </description>
</term>
Then, if you want, you can render all references to glossary
terms in some special way, no need to mark that up in every
occurence of it in the documents--but define a rendering
rule in match="a[@ref]" template.
Does that make any sense?
Kurmanov
http://www.ahinea.com/
Re: Allow "role" attribute in document DTD
Posted by Jeff Turner <je...@apache.org>.
Johan,
Wouldn't these use-cases be met with the <meta> tag in doc-v20a and
XHTML? The information seems to apply to the page as a whole.
On Sat, Dec 27, 2003 at 09:21:32AM +0200, Johan Kok wrote:
> Jeff/Ross:
>
> Role: could be developer vs user.
<meta name="audience">Developer | User</meta>
> Class: could be class of document, e.g. installation, training,
> reference, source code.
<meta name="category">Installation | training | reference | ... </meta>
(could auto-generate site.xml from this)
> Installation could be the same for all, user
> training should be quite different from developer training. User
> training is accessible to both users and developers, while developer
> training is available only to developers. The same would apply to
> references, bug "management". Source code would not be applicable to users.
'class' makes sense for these, if element-level granularity is required.
> IMHO Output/delivery format should not be a class. Be it WAP, HTML,
> PDF, Slides or whatever form of delivery, though I like the slides idea
> as it could be very useful, even if it is delivered as html slides. The
> latter will open a whole different "can of worms" (in the positive
> sense).
Agreed.
--Jeff
Re: Allow "role" attribute in document DTD
Posted by Johan Kok <jk...@messianic.dyndns.org>.
Jeff/Ross:
Role: could be developer vs user.
Class: could be class of document, e.g. installation, training,
reference, source code. Installation could be the same for all, user
training should be quite different from developer training. User
training is accessible to both users and developers, while developer
training is available only to developers. The same would apply to
references, bug "management". Source code would not be applicable to users.
IMHO Output/delivery format should not be a class. Be it WAP, HTML, PDF,
Slides or whatever form of delivery, though I like the slides idea as it
could be very useful, even if it is delivered as html slides. The latter
will open a whole different "can of worms" (in the positive sense).
>
Re: Allow "role" attribute in document DTD
Posted by Ross Gardler <rg...@wkwyw.net>.
Jeff Turner wrote:
> +1 for the general idea.
>
> Perhaps 'class' (as in HTML) instead of 'role'? Is there a difference?
I did think about class, and in most cases it will do the job. The
reason I didn't go for it in the end was because I thought that there
may be a need for different classes of (in my case) slides. However, I
haven't actually come across a use case for this yet.
Another reason for going with role was the REST architecture idea that
an application could intelligently interpret the purpose of a part of a
document using the role attribute. Class is about display only whereas
"slide" or "glossary" are about the intended purpose of that section of
data. In the original source document this is in the markup language
itself, but in xdoc this is lost.
An example of why this may be important...
Suppose, we have a tutorial on how to build a Forrest web site. This
tutorial has a series of links. Some of which give extra detail about a
topic by linking to different tutorials. Some gice glossary definitions,
some define a trail through the training materials. Using role you can
indicate all of these. Consider the following code:
An XML document ready for display by Forrest conforms to <link
href="xdocDTD" role="forrestTrailIntermediate glossary">Document v1.2
DTD</link>, however, you need not write your documents in this format.
By configuring your <link href="sitemap" role="forrestTrailAdvanced
glossary">sitemap.xmap</link> accordingly and providing <link href="xsl"
role="glossary">XSL</link> you can cause Forrest to convert any source
format into the native XDoc format ready for display.
Here, we have three links. All of them have a role of "glossary", one
indicates it is part of the intermediate forrest trail, the other is
advanced. A client application can now be built that extracts all
glossary terms from a website (by retrieving the XDoc source), or it
could build a single document for the each of the forrest trails etc.
Since class is intended to describe display information I'm not sure if
it could be used for this same purpose, it may just confuse things as
we'd likely end up with classes that didn't affect display.
Having said that, not using it may duplicate information.
What do you think?
Ross
Re: Allow "role" attribute in document DTD
Posted by Jeff Turner <je...@apache.org>.
+1 for the general idea.
Perhaps 'class' (as in HTML) instead of 'role'? Is there a difference?
--Jeff
On Fri, Dec 26, 2003 at 11:00:31PM -0400, Ross Gardler wrote:
> I recall a discussion about moving to XHTML as an intermediate document
> format rather than the document DTD so the answer to this question may
> be something bigger than I expect, but I'll take that risk ;-)
>
> In my skin I have turned of validation so that I can add a role
> attribute to sections. This is because some sections get rendered by my
> skin in a slides view, whilst others are rendered as normal. In a skin
> without knowledge of these roles the slides get displayed as normal
> sections.
>
> I also use the role attribute in links to denote glossary entries,
> cross-references and citations (these get rendered as special links into
> the relevant pages).
>
> I think that a role attribute in many elements within the DTD would make
> sense. I therefore propose that we add it to the Document v2.0a DTD.
>
> Does anyone have a problem with this, or perhaps an alternative
> suggestion on how to achieve my goal (XHTML as intermediate format)?
>
> Ross
>
>
Re: Allow "role" attribute in document DTD
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Ross Gardler wrote:
...
> I think that a role attribute in many elements within the DTD would make
> sense. I therefore propose that we add it to the Document v2.0a DTD.
I had proposed to add the class attribute to every element in the DTD.
It was "turned down" because it was not deemed too semantical or because
we would have gotten it with XHTML, no need to add it now. All this
IIRC and AFAIK.
In any case, you get my enthusiastic +1 to adding it to our doc DTD for
anything that goes in that direction, as long as it's also included in
the current XHTML2 spec, which is the one we will use.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------