forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ed Steenhoek" <edst...@pi.net>
Subject Proposal for future direction of site.xml
Date Mon, 10 Feb 2003 20:58:50 GMT
To follow up on what was part of the menu truncation discussion, I've 
started this separate thread.

The background:

>>[X] The menu should be limited to files below the current directory
>>[ ] The menu should display all files in the site
>> 
>>On top of this I take the gamble as a newbie to add another item
>>into the discussion: if menu's are truncated then shouldn't 
>>tabs.xml be integrated into site.xml?
>> 
>>If tabs.xml is needed somewhere during the generation process it
>>should be able to generate it out of site.xml. Doing so will reduce
>>the number of places where navigation information is maintained.
>
> 
>You're right, tabs could to be merged into site.xml in the future.
>I have this niggling feeling though, that site.xml is mixing 
>concerns:
> 
>1) Raw data, that could be generated directly from the filesystem
>   (directory structure, label and href, ie 90% of site.xml)
>2) Classification of pages. Eg <about label="About"> around a block
>   of entries. This is semantics, not structure, so probably ought
>   to be separate.
>3) Then again, we need to create 'views' of site.xml for each page.
>   Currently the 'view' is hardcoded: everything (0.3) or
>   everything-below-current (0.3.1).  Would be nice to make this 
>   more fine-grained.
> 
>So there's lots that should happen with site.xml.  I think tabs fit
>into 3), a view of the data.  Or perhaps 2).  Anyway, I'm a bit
>reluctant to throw anything more into site.xml until 1) is 
>automated, and the relationships become clearer.
> 
> --Jeff


I don't know if I agree with the extend of automation you're looking 
for. I do agree that things have to become clearer before making 
further changes and there it might be time to get a common 
understanding of the direction into which site.xml should develop. In 
the remainder of this mail I give my view on this.

In the first steps of this process I ignore the presentation issues.

To me site.xml should be a file that contains at least one primary 
hierarchy of navigation items and optionally one or more secondary 
hierarchies. Such a hierarchy is a mixture of containers and nodes.
The main difference between containers and nodes being that nodes are 
not parent to one or more children where containers are.

The order of the nodes and containers is implicitly their position in 
the hierarchy. This is important because this is something that imho 
can not be retrieved from the filesystem.

Secondary hierarchies can be used to define the books, as an 
alternative view on the same information as is part of the primary 
hierarchy or for external references.

Please note: the usage of external references as they are now in 
site.xml is not yet fully clear to me. If it is the intend to let 
site.xml be the place to maintain all external references and use 
only semantic links from all source documents, then the concept if ok 
but I'll doubt if this will remain userfriendly if a site becomes 
larger and larger. Time will tell.

The next important step is to understand what the meaning of tabs 
are. I think that there are 2 possibilities. Tabs could be:
1) all (primary and alternative) hierarchies
2) the top level containers of the primary hierarchy

Option 1 gives much more flexibility because it does includes the 2nd 
option (that is if you would split the primary hierarchy at top level 
containers into multiple hierarchies) but allows on the other hand 
the creation of alternative ordering of the primary hierarchy next to 
complete independent hierarchies. As mentioned these could include 
'books'.

Sometimes an example tells it all:

+ main-sitemap
  + container a
    + container b
      - node 1
      - node 2
    - node 3
  - node 4
  
+ alt-sitemap-1
  + container b
    + container a
      - node 1
      - node 2
      - node 3
      - node 4

+ alt-sitemap-2
  + container c
    - node 5
    - node 6
  + container d
    - node 7
    - node 8
    
+ alt-sitemap-3
  - node 1
  - node 2
  - node 3
  - node 4
  - node 5
  - node 6
  - node 7
  - node 8
  
To continue towards presentation, there are two more decisions to 
make.

First decision: Are we to have containers that are just that or are 
they a node at the same time? This is important because at some stage 
a click on the container when rendered in e.g. HTML will lead to some 
action.
Up until now I have come across scenarios where containers are nodes 
at the same time and - incase where they are not - implicitly inherit 
node behavior form the first child node.
The first can make the site.xml become difficult to read and 
understand because of the additional attributes that are needed.
The second - although more pure - is limited because of the implicit 
coupling with the first node.
To me a solution where a container is just that is best especially 
when we include the ability to reference one of the child nodes as 
the default node to be coupled with the container when applicable. 
When presentation comes along this becomes clear I guess. Still again 
an example:

+ main-sitemap
  + container a def-node=node 3
    + container b def-node=node-1
      - node 1
      - node 2
    - node 3
  - node 4

+ alt-sitemap-1
  + container b def-node=node-1
    + container a def-node=node-1
      - node 1
      - node 2
      - node 3
      - node 4

Second decision: what are the node-types we will support?

1) URL referencing (e.g. http://xml.apache.org)
   Requires information on target (same or second window)

2) Semantic referencing (e.g. site:about)
   Including cross sitemap referencing and logical pointers like the
   'home' of a sitemap

3) Relative referencing (e.g. index.html)
   Requires that its container can specify relative folder
   information

4) Directory directives (e.g. news*)
   Requires some processing that expands this single node into as
   many nodes as there are source files matching the expression
   pattern

5) XPath referencing (e.g. somefile/element/element[@attrib='value'])
   This one is particularly interesting because it can possibly be
   used not only for getting a piece out of a larger document but
   also breaking up a larger document in which case it will also be
   expanding into multiple nodes like #section in the default seed.
   
Are there more types? I think that the ihtml and ehtml as given in 
the sample seed do fit into these types but if not that might be due 
to me not having understood the peculiarities of them.

Once we step into the presentation of all this we need to have access 
to some information that allows to make the right decision on the 
right time.

For every node and container we need to know if it is visible in the 
results of the build. This allows us to have node that are only 
available during the build. Maybe 'active' is a better term because 
visibility is also something to be controlled by CSS.

For every node we need to know its target window and maybe other HTML 
href parameters.

A global 'property' is needed to specify where to get the relevant 
information for the tabs. There are 3 indicators: single, multi and 
none.
Single indicates that only one hierarchy is used for the tabs and 
from this hierarchy the top level folders are used to generate the 
tabs. To prevent arbitrary selection of an hierarchy, this indicator 
is accompanied with a reference to the hierarchy that is to be used.
Multi indicates that all hierarchies are to be used to generate the 
tabs. All in this sense are all hierarchies that are either 'sitemap' 
or 'book'.
None indicates that no tabs are to be generated.

Of course labels and a source expression (in one of the 5 types as 
specified above) are needed.

For directory directives we need to specify the sort order.

There are undoubtfully more parameters needed once all gets more 
support.

I have created a DTD and a sample XML file that contains the above 
concept.

Maybe this is just a beginning of a long discussion, maybe it's bad, 
maybe it's already a large step into a good solution. Whatever it may 
be, I think it is a good point to start even though I considder 
myself still as a newbie to Forrest.

Regards,

Ed


Mime
View raw message