forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: documentation additions and issue tracking (Was: App vs Data)
Date Sun, 29 May 2005 11:52:00 GMT
Maurice Lanselle wrote:
> Phil Sullivan said the following on 28/05/2005 16:30:
> 
> >What would have (and would be :-))  useful for me was clearer doc's 
> >around the tabbing structure. I got it working through trial and 
> >error. A real newbie might not be willing to do that. 
> 
> I agree.  After I started playing with the colors of the pelt skin, I 
> was intrigued by the way level-2-tabs (are supposed to) work and which 
> menu items get assigned to each tab.  I checked both the 0.6 and the 0.7 
> doc on menus.
> a) subtabs are not mentioned.
> b) there is an explanation of an example site.xml and tabs.xml showing 
> what the result is, but it leaves a lot of unanswered questions for 
> someone who wants a different result.

I recorded a note of these requirements at our issue tracker.
When someone has time, they will add such documentation.

>  Like, can you have multiple <faq 
> > elements as long as they have different labels, or should you call 
> them <faq1 >, <faq2 >, etc?  Are you allowed to call them <faq1 >,
<faq2 
> >, etc or are the tags in menus constrained by a DTD?  Same question 
> for groupings of elements.

Unique element names. The labels can be whatever you want.

<faq label="FAQs" href="faq.html">
  <tech label="Technical" href="faq-tech.html">
    <docbook href="#docbook"/>
    <ignoring_javadocs href="#ignoring_javadocs"/>
  </tech>
  <user label="User" href="faq-user.html">
</faq>

That will create a menu like this with three links:
 FAQs
   Technical
   User

These documents can be linked to from other documents, like this:
 <a href="site:faq/tech"> link to the top of the Tech FAQs
 <a href="site:faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs

If that "docbook" entry was a unique name in yor site.xml then you
can shorten that latter link:
 <a href="site:docbook"> link to the DocBook FAQ in the Tech FAQs

We will add a doc explaining site.xml in user terms.

> So I fully agree that how-to manage the navigation experience and how-to 
> go beyond modifying template content is needed.
> 
> >I also had a hard time getting my head around where static html pages 
> >should go ...(i.e an existing html page outputed from say word or open 
> >office).

The examples in the 'forrest seed site' explain this and have been enhanced
in the upcoming 0.7 version.

> >Finally i never was able to figure out how to use other skins (which 
> >someone else brought up recently). This was not important to me...so i 
> >went withthe default.
> >
> *someone else* here: tigris seems to work and I like its less colorful 
> look, but leather-dev seems to look like pelt but with the menu in the 
> middle of the page.

If you don't like the default colours in "pelt" then just change them.
Comments have been added to the "colors" element of skinconf.xml
to explain the process. Basically un-comment one of the example sets
of colours and adjust the relevant elements.

The "leather-dev" skin is obviously under development. It will probably
be gone soon in favour of the new viewHelper plugin.

> But even in *basic* skin use, for example, a project name longer than 
> "MyProject" can cause appearance problems, and there are not many clues 
> on what to do about it:  we need an explanation of how-to adjust if your 
> project logo doesn't fit in the default settings (I sketched that in my 
> first post here and will rework it if necessary.)

This issue is improved in 0.7 version. Today i added an FAQ
to explain how to do that.
http://forrest.apache.org/faq.html#project-logo-svg

> Oh, and it took me 
> longer than it should to find the how-to.xml template in the 
> distribution--I was only looking in the seeded project for useable 
> templates! Nobody told me...

That is a good point. We need to remind people that they have
a comprehensive set of examples right in front of them. The Forrest
website documents are included in your distribution. Look at the
site.xml etc. for guidance.

--David

Mime
View raw message