forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject [RT] Directory structure and configuration
Date Mon, 29 Nov 2004 09:42:06 GMT

Currently we have (C = configuration) :

  my-project/
     status.xml
     forrest.properties (C)
     src/
       documentation/
         skinconf.xml   (C)
         content/
           xdocs/
             site.xml   (C)
             tabs.xml   (C)
           classes/
             CatalogManager.properties (C)
           resources/
             images/
               **.gif||jpg||...


Assumptions on how it should change:

1 - shallower dir structure
2 - single dir for configuration
3 - single dir for content
4 - content dir contains only content, not configuration
5 - no Forrest content outside of the conf and content dirs

  my-project/
         documentation/
           conf/
                forrest.properties
                skinconf.xml
                site.xml
                tabs.xml
           content/
                status.xml
                ** all other content

Notes:

a - the /documentation dir can be anywhere: when Forrest first starts
     it shall search for some predefined directories, and then in the
     whole directory structure till it finds forrest.properties.
     Then it caches it in the user dir and uses that to resolve all
     other directories.

b - status.xml will become like all other files, and will not be
     anymore in a fixed position, as it will match on DTD-

Now here is a different layout (we may as well decide a mix between this 
and the previous one):

  my-project/
         forrest.xml

         documentation/
              status.xml
              ** all other content

              FORREST-INF/
                skinconf.xml
                site.xml
                tabs.xml

Notes:

c - forrest.properties is renamed forrest.xml and uses xml; this
     ensures that the paths do not contain whitespace at the end.
     Furthermore having forrest in the base dir is a clear sign
     the the documentation of the project is done with Forrest, and
     that it's to be launched in that dir.
     This file must only contain the link to the *main* Forrest dir
     and the output dir.

d - The configuration is kept inside the documentation dir under
     FORREST-INF/, in a similar way to WEB-INF. This shortens the
     path to the documentation.

This configuration has the advantage that the whole documentation is in 
one directory, and can be used also without forrest.xml.
Let me enhance the discussion by talking about configuration.

                     - O -

We now have configuration in many different places, and I want to see it 
reduced.

Furthermore, there have been requests to make our sitewide configuration 
more pinpointed to single dirs or files (special headers), and 
documentation set joins (multiproject docs).

IMHO the way to achieve this is to revolutionize our way of seeing 
metadata:

    metadata is defined for each and every file

Example shource file:

<html>
   <head>
     <meta name="org.apache.forrest.disable-pdf-link"
           content="true"/>
     <meta name="org.apache.forrest.searchsite-domain"
           content="incubator.apache.org"/>
     <meta name="org.apache.forrest.searchsite-name"
           content="Apache Incubator"/>
     <meta name="org.apache.forrest.color.header"
           content="#ffffff"/>
     etc...
  ...

This means that every single file can have it's own metadata and 
customizations.

   :-)

Ok, but how to make sitewide default metadata? This is needed because I 
don't want all of my files to have all the same metadata, I only want it 
to specify the parts it wants to change.

For this, we have our usual 'skinconf.xml' that is used for fallback.

A particularity of this is *hierarchical* metadata.

  my-project/
         forrest.xml
         documentation/
              status.xml
               ** all other content
              FORREST-INF/
                skinconf.xml
                site.xml
                tabs.xml
              subsite/
                status.xml
                ** all other subsite content
                /FORREST-INF/
                   skinconf.xml
                   site.xml
                   tabs.xml

This means that I should be able to define metadata nearer to the file 
that needs it, and define subsections. All that forrest.xml has to 
indicate is the base directory where to start traversing.

                     - O -

The configuration format has to change, and has to become more flexible.

Here is a simplified draft proposal.

<metadata>

   <meta name="credits.title.name" content="Built with Forrest">
   <meta name="credits.title.url"  content="http://forrest.apache.org/">
   <meta name="credits.title.image"
         content="images/built-with-forrest-button.png">
   <meta name="disable-pdf-link"   content="false">
     <exclude file="**/index.html">
   </meta>

</metadata>

Fire at will! :-)

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message