forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: Understanding linking
Date Sun, 08 Aug 2004 14:33:11 GMT
Charles Palmer wrote:
> I've been spending a bunch of time trying to understand how to link
> between files. I certainly have a better idea now than I did yesterday
> morning. Not being critical, but some of the documentation wasn't too
> clear, so I've tried to write my own, and would like to pass it back
> to be checked, corrected, enhanced, and if  thought worthwhile, used
> to replace the existing sample2.xml file that comes out of the forrest
> seed operation.

Thanks. This is one way that documentation will be improved,
by people making contributions.

> A few things:
>  
> 1    I don't know whether user@forrest.apache.org accepts file
> attachments - I'll find out soon enough!

We would far prefer that people use the Issue tracker.
Some reasons:

* Easy to overlook it in a busy mail archive.

* With the Issue tracker, one of us can assign the task
and work on adding it. With mail attachment we could
needlessly duplicate our work.

* Now every one of us has a copy in our local email
archives.

* Needless copy is sitting in every remote email archive.

* Issue tracker provides a better audit trail.

> 2    You will need to make the small alteration to site.xml that the
> file talks about.
> 3    The process does give error messages like: 
>  
>  ../site/test1.html  BROKEN:
> C:\Forrest\projects\Improved_Original\build\tmp\context\content\site\test1.xml (The system
cannot find the path specified) 
>  
> No doubt there is a way of fixing this, that could be added to my
> work.
>
> 4   In terms of future documentation work, IMHO it would be good if
> the documentation uses the site that forrest seed creates for examples
> of useage.

That is a good idea for examples of usage. Yesterday i improved
the ihtml sample.

However i think that comprehensive documentation like your
contribution should be in the core documentation.

> After all, that is what users will have on their local machine, and
> they can easily examine the code and make their own changes.

However you have the full documentation for the forrest website
in your local forrest too. Do 'forrest run' in the top-level
forrest directory.

> In contrast the menus and linking document at
> http://forrest.apache.org/docs/linking.html uses extracts from the
> main forrest site, which is more difficult for users to examine, or
> even theoretical examples that users can't examine.

The main documentation will still be the core forrest docs.
We definitely should enhance the 'forrest seed' too.

Thanks again for your contribution. We will investigate.

-- 
David Crossley


Mime
View raw message