forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Q: Site and unique element names
Date Wed, 20 Apr 2005 18:12:20 GMT
Ferdinand Soethe wrote:
> I know this has come up before, but I'm not sure which of the info in
> old threads is still relevant today so I'll ask again:

Well my answer may not be complete for the same reason, but...

> Why does Forrest expect unique element names in site.xml.

Because of the site: linking protocol (see the indirect linking part of 
the docs)

> One reason I found in the archives is that you need to have a unique
> ID to distinguish between two entries pointing to the same file such
> as
> 
> <about1 label="About 1">
>     <index label="Index" href="index.html" description="Welcome to MyProj"/>
> </about>
> 
> <about2 label="About 2">
>     <index label="Index from somewhere else" href="index.html" description="Welcome
to MyProj"/>
> </about>
> 
> But then, why not use an ID-Attribute to achieve this?

Perhaps this is because we can't use an ID attribute in the site: 
protocol (I'm guessing, I do not know this to be the case).

> Two reasons for my question:
> 
> - For Forrest to be used by "normal people" it would be great to be
>   able to use a grammar aware editor and its functions to simplify creation and
>   insure accurate structure. Unfortunately having open element names AFAIK keeps
>   me from writing a grammar and validating against it.

I agree. This is one reason why Burrokeet built the IMS Plugin.

>   
> - Studying the IMSManifest-plugin-code I realized (I think) that it generates
>   several elements with the same name. Does that mean that different
>   element names are only required for some special tricks and are not
>   a requirement?

Yes, if you use the IMSManifest, you cannot use the site: protocol (or 
the ext: for that matter). This is not a problem for users of 
IMSManifests since an IMSManifest must be readable by any IMS compliant 
system and tehy would not understand those protocols.

>   If so, I would probably try and write an internal plugin that
>   accepts a simple and grammar based structure file and generates site
>   and tab.xml from it.

Actually, I've just been looking at the Eclipse help system. That uses 
are really clever system TOC system where we would use site.xml. It 
allows external sites to "plugin" to an existing TOC file. That is you 
don't actually need write access to the original TOC in order to add 
your own content to it - this is cool in my book. A use case would be 
Forrest docs could provide points for plugins to add documentation, for 
example, where we describe the site.xml file the IMSManifest plugin 
could insert navigation links to its alternative implementation.

The downside of this is that it is quite complex to write a TOC document 
in this way. So they provide a different way of writing the files that 
is more intuitive for those writing by hand and not needing these 
advanced features. In this case the toc file looks very similar to our 
site.xml file, but it conforms to a schema (interestingly the same 
schema as for the other method of defining TOCs).

I need to look into this further to fully understand the implications, 
but if you do build a plugin for this purpose I would urge you to 
consider using the Eclipse TOC format.

Ross

Mime
View raw message