You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@forrest.apache.org by Tim Williams <wi...@gmail.com> on 2005/05/18 14:13:18 UTC
App vs Data
I'm having a difficult time understanding where the Forrest
application ends and where the data for the site begins. Is there
always a one-to-one relationship between the Forrest app and a site?
In other words can the app be used to operate on multiple sites or is
the site configuration so inter-twined with the application that one
needs separate "instances" of Forrest for each site (changing
"$FORREST_HOME" for each site)?
In terms of Forrest directory structure, I think here's what I'm asking:
Instead of:
..\src\documentation
..\src\site1-documentation
..\src\site2-documentation
..\src\site3-documentation
Where site1, site2, and site3 are totally different web sites. I
guess the command line would somehow have to support an extra
parameter naming the site to be built/run.
Any help in understanding this would be appreciated.
Thanks,
--tim
Re: documentation additions and issue tracking
Posted by David Crossley <cr...@apache.org>.
Addi wrote:
> ** (from users, brought over to dev - replies will go to dev) **
> Brought this over to dev to continue the discussion on exactly how to
> proceed with beginner documetation. As David points out we should
> figure out whether this is something that should be a separate HowTo,
> incorporated into the main docs or something else.
In my opinion a set of HowTo docs would be best. Each one would be
very concise, concentrating on specific topics. Some examples:
* Install Forrest on Windows.
... very specific instructions, no mention of UNIX, specific example
pathnames and environment settings. Another section of the doc could
mention variations for older version of Windows.
* Using Forrest in dynamic mode.
... Show how to create a new directory, do 'forrest seed', start
the dynamic forrest, and begin the edit/review cycle.
* Building a set of static documents.
... Show how to do 'forrest site', explain where the documents are
generated, how to view them, how to zip, them up and unpack on a
webserver.
* Interpreting the Forrest output messages.
... Explain the purpose of the output messages from running
forrest, show some specific messages to be aware of.
Each document would refer to other HowTo docs in the Prerequisites
section. That way there are tracks of documents.
If some tasks are very specific and would be linked to from various
other documents, then these should be FAQs.
It is hard to know when a doc should be complete Howto, or when to
use multiple Howtos, or when a main doc is better. There is recent
discussion in the forrest-dev mail archives which might help:
http://marc.theaimsgroup.com/?l=forrest-dev&m=111165685011990
(Start there and go forward.)
> Originally I was thinking of it as a HowTo and that we could take some
> of the more important bits and add them to the main docs. But I do
> think (actually hope) that the average user skills will decrease as
> forrest spreads. Right now it feels very geeky and I have friends who
> know something about html and css who may be interested in a program
> like this but would't really be able to pull this off with their current
> knowledge and, frankly, aren't going to take time to figure it out. If
> we want to bring more folks like that into the fold, then maybe moving
> more of the basic stuff into the main docs would make more sense. WDYT?
At this stage of Forrest we need more developers and especially ones
who are determined to understand the guts, so we don't yet go out
of our way to attract users. Our developer community is still small,
so it would be harder to provide support. People starting to help with
the docs, such as you, is a brilliant point to reach.
That said, of course we need beginner documentation and we need it now.
By the time we do get a rush of new users, we will have good supporting
docs. Getting people started quickly is very important, and it means
that we can save time and get on with answering more advanced questions
and more development. Such documentation helps everyone, including new
developers.
> To clarify a little what I mean by beginner, I am starting with as few
> assumptions as I think reasonable. The perspective is someone who uses
> html and css, probably using a GUI editor, has no command line
> experience and can follow directions :). Most linux users have some
> command line experience but from linux forums I can see lots of new to
> linux users who don't really grasp it beyond the specific thing they are
> told to type in an answer to their question. Most windows users don't
> have any of it. I use it all the time on my linux/unix boxes but
> forrest is the first time I had to figure any of it out in windows (I
> now hate backslashes in a whole new way).
>
> -Addi
>
> David Crossley wrote:
> >Addi wrote:
> >>I am planning on working on beginner, step by step type documentation
> >>over time (as I learn the answers to my own questions).
> >
> >It would be best if we created a shell of a new document
> >so that you and any others can work on it together.
> >More below about that ...
> >
> >>I was wondering
> >>if it would be OK to start a new issue in JIRA for an improvement in
> >>docs on this. That way, as people see problems that new users are
> >>having in the lists, we can add them to the list of those issues in JIRA
> >>to make it easier to keep track of it. Is that appropriate or is there
> >>another system set up for something like this? I feel that keeping my
> >>own scratchpad of issues is not terribly efficient, since I don't know
> >>all the issues ...
> >
> >This sounds like a good idea. I recommend separate issues
> >for each item. After we have incorporated that piece into
> >the documentation, then we close the issue. There is a category
> >for "Documentation". Give each issue a useful Summary title.
> >Keep the Description concise, and use Comments for more detail.
> >Link to mail list discussions where appropriate.
> >
> >Are you working with the head of development, i.e. the
> >trunk of SVN?
> >
> >>... and it would suck for myself and someone else to be
> >>writing docs on the same issue at the same time, thereby wasting
> >>someone's time.
> >
> >That is exactly why we try to work on every document
> >in the SVN repository. It is then collaborative.
> >
> >It is also good practice to do it bit by bit, i.e.
> >progressively build the document rather than do a
> >whole swag by yourself, only to find that when it
> >comes time for us to commit the work, that you
> >have gone off track.
> >
> >Remember too, that it is quite okay to have
> >"Fixme:" banners inside the published docs.
> >
> >It would probably be useful to discuss the overall aim
> >of this beginners documentation. Will it be one document
> >in the main section of the website, will it be a HowTo.
> >That sort of discussion is more appropriate for the
> >dev mailing list.
> >
> >This is exciting, thanks for helping out.
> >
> >--David
> >
> >>Ross Gardler wrote:
> >>>Tim Williams wrote:
> >>>>Embarrassingly enough, I was having a difficult time understanding the
> >>>>much simpler multiple statically built sites with one Forrest. Ross'
> >>>>answer was helpful and I think my problem was that I never created a
> >>>>subdirectory to do the seed in so that I had a single "src" at a
> >>>>higher level than it should have been. Having the "mkdir->cd->forrest
> >>>>see" and maybe a little explanation of having "multiple sites" would
> >>>>be helpful somewhere.
> >>>>
> >>>We would love a patch for the docs making this clearer, sometimes we
> >>>forget these critical points that are less obvious than we assume them
> >>>to be.
> >>>
> >>>Ross
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by David Crossley <cr...@apache.org>.
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
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by Maurice Lanselle <la...@evc.net>.
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. 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.
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).
>
> 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.
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.) 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...
> If it would be useful I would be willing to help with the
> documentation effort by reviewing it from the perspective of a person
> with limited knowledge of css, xml, or forrest ....
>
> Phil
>
> Addi wrote:
>
>> ** (from users, brought over to dev - replies will go to dev) **
>> Brought this over to dev to continue the discussion on exactly how to
>> proceed with beginner documetation. As David points out we should
>> figure out whether this is something that should be a separate
>> HowTo, incorporated into the main docs or something else.
>> Originally I was thinking of it as a HowTo and that we could take
>> some of the more important bits and add them to the main docs. But I
>> do think (actually hope) that the average user skills will decrease
>> as forrest spreads. Right now it feels very geeky and I have friends
>> who know something about html and css who may be interested in a
>> program like this but would't really be able to pull this off with
>> their current knowledge and, frankly, aren't going to take time to
>> figure it out. If we want to bring more folks like that into the
>> fold, then maybe moving more of the basic stuff into the main docs
>> would make more sense. WDYT?
>>
I agree. The seeded site is a great demo, and a good start for the
curious. But what do you do after 'forrest run' and you've finished
playing with the demo? How do you kill jetty? Reboot? ;-) Seriously,
you shouldn't tell people how to start something and not how to finish it.
I think a collection of HowTo's makes sense, or call it an "Owner's
Manual", like you get with a new car--something that might eventually
become tutorials as well. And with links from them to the
*Documentation* documentation to "learn more".
>> To clarify a little what I mean by beginner, I am starting with as
>> few assumptions as I think reasonable. The perspective is someone
>> who uses html and css, probably using a GUI editor, has no command
>> line experience and can follow directions :). Most linux users have
>> some command line experience but from linux forums I can see lots of
>> new to linux users who don't really grasp it beyond the specific
>> thing they are told to type in an answer to their question. Most
>> windows users don't have any of it. I use it all the time on my
>> linux/unix boxes but forrest is the first time I had to figure any of
>> it out in windows (I now hate backslashes in a whole new way).
>>
>> -Addi
>>
I totally agree with your assessment of challenges many potential users
face. I have trouble imagining my father using Forrest, yet he has
built his own static website editing html templates with Notepad or
Word. Does everyone have a JRE installed? Is that requirement mentioned
somewhere?
Furthermore, I hate backslashes, too. I have written a bat file to ease
my most common move: "cd c:\documents and settings\all
users\documents\www\myproject". And thanks to Forrest, I finally
learned how to set environment variables in Win XP.
I'll be glad to participate (but don't know how to use svn).
Maurice
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by Phil Sullivan <pa...@rcn.com>.
To help with the beginner definition, my experience may be useful.
I was attracted to Forrest precisely because i know *nothing* about CSS
. My html skills are very basic, although perhaps better than a typical
newbie. On the other hand my Command line, and O/S skills in both
windows and *nix environments is extensive.
The attraction was that after some effort at learning how to use the
templates and XML (which I also knew nothing about) i was able to spin
off a nicely formated web page....with really no development work - just
changing content from the seed site to my own. My intention is that
over time as I learn how forrest works I would gradually customize the
site - but it was a quick way to hammer out a basic site to start.
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 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).
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.
If it would be useful I would be willing to help with the documentation
effort by reviewing it from the perspective of a person with limited
knowledge of css, xml, or forrest ....
Phil
Addi wrote:
> ** (from users, brought over to dev - replies will go to dev) **
> Brought this over to dev to continue the discussion on exactly how to
> proceed with beginner documetation. As David points out we should
> figure out whether this is something that should be a separate HowTo,
> incorporated into the main docs or something else.
> Originally I was thinking of it as a HowTo and that we could take some
> of the more important bits and add them to the main docs. But I do
> think (actually hope) that the average user skills will decrease as
> forrest spreads. Right now it feels very geeky and I have friends who
> know something about html and css who may be interested in a program
> like this but would't really be able to pull this off with their
> current knowledge and, frankly, aren't going to take time to figure it
> out. If we want to bring more folks like that into the fold, then
> maybe moving more of the basic stuff into the main docs would make
> more sense. WDYT?
>
> To clarify a little what I mean by beginner, I am starting with as few
> assumptions as I think reasonable. The perspective is someone who
> uses html and css, probably using a GUI editor, has no command line
> experience and can follow directions :). Most linux users have some
> command line experience but from linux forums I can see lots of new to
> linux users who don't really grasp it beyond the specific thing they
> are told to type in an answer to their question. Most windows users
> don't have any of it. I use it all the time on my linux/unix boxes
> but forrest is the first time I had to figure any of it out in windows
> (I now hate backslashes in a whole new way).
>
> -Addi
>
> David Crossley wrote:
>
>> Addi wrote:
>>
>>
>>> I am planning on working on beginner, step by step type
>>> documentation over time (as I learn the answers to my own questions).
>>>
>>
>>
>> It would be best if we created a shell of a new document
>> so that you and any others can work on it together.
>> More below about that ...
>>
>>
>>
>>> I was wondering if it would be OK to start a new issue in JIRA for
>>> an improvement in docs on this. That way, as people see problems
>>> that new users are having in the lists, we can add them to the list
>>> of those issues in JIRA to make it easier to keep track of it. Is
>>> that appropriate or is there another system set up for something
>>> like this? I feel that keeping my own scratchpad of issues is not
>>> terribly efficient, since I don't know all the issues ...
>>>
>>
>>
>> This sounds like a good idea. I recommend separate issues
>> for each item. After we have incorporated that piece into
>> the documentation, then we close the issue. There is a category
>> for "Documentation". Give each issue a useful Summary title.
>> Keep the Description concise, and use Comments for more detail.
>> Link to mail list discussions where appropriate.
>>
>> Are you working with the head of development, i.e. the
>> trunk of SVN?
>>
>>
>>
>>> ... and it would suck for myself and someone else to be writing docs
>>> on the same issue at the same time, thereby wasting someone's time.
>>>
>>
>>
>> That is exactly why we try to work on every document
>> in the SVN repository. It is then collaborative.
>>
>> It is also good practice to do it bit by bit, i.e.
>> progressively build the document rather than do a
>> whole swag by yourself, only to find that when it
>> comes time for us to commit the work, that you
>> have gone off track.
>>
>> Remember too, that it is quite okay to have
>> "Fixme:" banners inside the published docs.
>>
>> It would probably be useful to discuss the overall aim
>> of this beginners documentation. Will it be one document
>> in the main section of the website, will it be a HowTo.
>> That sort of discussion is more appropriate for the
>> dev mailing list.
>>
>> This is exciting, thanks for helping out.
>>
>> --David
>>
>>
>>
>>> What do you all recommend/already have in place?
>>>
>>> Thanks
>>> Addi
>>>
>>>
>>> Ross Gardler wrote:
>>>
>>>
>>>
>>>> Tim Williams wrote:
>>>>
>>>>
>>>>
>>>>> Embarrassingly enough, I was having a difficult time understanding
>>>>> the
>>>>> much simpler multiple statically built sites with one Forrest. Ross'
>>>>> answer was helpful and I think my problem was that I never created a
>>>>> subdirectory to do the seed in so that I had a single "src" at a
>>>>> higher level than it should have been. Having the
>>>>> "mkdir->cd->forrest
>>>>> see" and maybe a little explanation of having "multiple sites" would
>>>>> be helpful somewhere.
>>>>>
>>>>>
>>>>
>>>> We would love a patch for the docs making this clearer, sometimes
>>>> we forget these critical points that are less obvious than we
>>>> assume them to be.
>>>>
>>>> Ross
>>>>
>>>
>>
>>
>>
>>
>>
>
>
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by Addi <ad...@rocktreesky.com>.
** (from users, brought over to dev - replies will go to dev) **
Brought this over to dev to continue the discussion on exactly how to
proceed with beginner documetation. As David points out we should
figure out whether this is something that should be a separate HowTo,
incorporated into the main docs or something else.
Originally I was thinking of it as a HowTo and that we could take some
of the more important bits and add them to the main docs. But I do
think (actually hope) that the average user skills will decrease as
forrest spreads. Right now it feels very geeky and I have friends who
know something about html and css who may be interested in a program
like this but would't really be able to pull this off with their current
knowledge and, frankly, aren't going to take time to figure it out. If
we want to bring more folks like that into the fold, then maybe moving
more of the basic stuff into the main docs would make more sense. WDYT?
To clarify a little what I mean by beginner, I am starting with as few
assumptions as I think reasonable. The perspective is someone who uses
html and css, probably using a GUI editor, has no command line
experience and can follow directions :). Most linux users have some
command line experience but from linux forums I can see lots of new to
linux users who don't really grasp it beyond the specific thing they are
told to type in an answer to their question. Most windows users don't
have any of it. I use it all the time on my linux/unix boxes but
forrest is the first time I had to figure any of it out in windows (I
now hate backslashes in a whole new way).
-Addi
David Crossley wrote:
>Addi wrote:
>
>
>>I am planning on working on beginner, step by step type documentation
>>over time (as I learn the answers to my own questions).
>>
>>
>
>It would be best if we created a shell of a new document
>so that you and any others can work on it together.
>More below about that ...
>
>
>
>>I was wondering
>>if it would be OK to start a new issue in JIRA for an improvement in
>>docs on this. That way, as people see problems that new users are
>>having in the lists, we can add them to the list of those issues in JIRA
>>to make it easier to keep track of it. Is that appropriate or is there
>>another system set up for something like this? I feel that keeping my
>>own scratchpad of issues is not terribly efficient, since I don't know
>>all the issues ...
>>
>>
>
>This sounds like a good idea. I recommend separate issues
>for each item. After we have incorporated that piece into
>the documentation, then we close the issue. There is a category
>for "Documentation". Give each issue a useful Summary title.
>Keep the Description concise, and use Comments for more detail.
>Link to mail list discussions where appropriate.
>
>Are you working with the head of development, i.e. the
>trunk of SVN?
>
>
>
>>... and it would suck for myself and someone else to be
>>writing docs on the same issue at the same time, thereby wasting
>>someone's time.
>>
>>
>
>That is exactly why we try to work on every document
>in the SVN repository. It is then collaborative.
>
>It is also good practice to do it bit by bit, i.e.
>progressively build the document rather than do a
>whole swag by yourself, only to find that when it
>comes time for us to commit the work, that you
>have gone off track.
>
>Remember too, that it is quite okay to have
>"Fixme:" banners inside the published docs.
>
>It would probably be useful to discuss the overall aim
>of this beginners documentation. Will it be one document
>in the main section of the website, will it be a HowTo.
>That sort of discussion is more appropriate for the
>dev mailing list.
>
>This is exciting, thanks for helping out.
>
>--David
>
>
>
>>What do you all recommend/already have in place?
>>
>>Thanks
>>Addi
>>
>>
>>Ross Gardler wrote:
>>
>>
>>
>>>Tim Williams wrote:
>>>
>>>
>>>
>>>>Embarrassingly enough, I was having a difficult time understanding the
>>>>much simpler multiple statically built sites with one Forrest. Ross'
>>>>answer was helpful and I think my problem was that I never created a
>>>>subdirectory to do the seed in so that I had a single "src" at a
>>>>higher level than it should have been. Having the "mkdir->cd->forrest
>>>>see" and maybe a little explanation of having "multiple sites" would
>>>>be helpful somewhere.
>>>>
>>>>
>>>>
>>>We would love a patch for the docs making this clearer, sometimes we
>>>forget these critical points that are less obvious than we assume them
>>>to be.
>>>
>>>Ross
>>>
>>>
>
>
>
>
>
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by David Crossley <cr...@apache.org>.
Sorry that email popped out before i had finished it ...
David Crossley wrote:
> Ferdinand Soethe wrote:
> > As you might know Ross and I have put considerable time into working
> > on a chapter structure for a book on Single Source Publishing with
> > Forrest. Since we didn't follow through with the project (there will
> > only be a German book) we are prepared to donate this structure (more
> > precisely: the rights to this concept for an English publication) as a
> > basis for the Forrest documentation project.
>
> Not sure what your mean by "rights to this concept". See the Apache License 2.0
and your Contributor License Agreement CLA
http://www.apache.org/licenses/
--David
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by David Crossley <cr...@apache.org>.
Actually Ferdinand, this discussion should be happening on the dev list.
We reserve the user list for questions an assistance. Development discussions
can get quite busy and touch many different topics. We don't want to frighten
new users away with that.
--David
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by David Crossley <cr...@apache.org>.
Ferdinand Soethe wrote:
> As you might know Ross and I have put considerable time into working
> on a chapter structure for a book on Single Source Publishing with
> Forrest. Since we didn't follow through with the project (there will
> only be a German book) we are prepared to donate this structure (more
> precisely: the rights to this concept for an English publication) as a
> basis for the Forrest documentation project.
Not sure what your mean by "rights to this concept". See the Apache License 2.0
> It might need some adjustments of course, but it was designed to
> introduce people with basic skills to Forrest so it seems compatible
> with what Addi had in mind.
>
> If people think this is helpful, I'd check the OpenOffice file with
> the concept into the issue tracker so that people can study it and add
> their comments and suggestions (preferably as a modified
> OpenOffice-document). Or is OpenOffice too proprietary to work with?
We can sure study it, but we need comments to come back to this mailing list.
We can't have design discussions shut away in separate documents.
Anyway, we have got to see what you are talking about first. I don't
really understand the three paragraphs below yet.
It would help to present a high-level overview to this mailing list.
--David
> Once we have finalized the chapter structure, we could create it as a
> new tab on Forrest main site with each chapter becoming a menu item
> pointing to a page with a short abstract for this chapter (not being
> written yet) and instructions on what to do if person wants to write
> and contribute this chapter.
>
> All open chapters could also become items in the issue tracker but I
> think that having them in a structured menu helps recognizing at what
> point in the documentation this chapter is placed and what its
> purpose is.
>
> I'm in favour of not writing a whole lot of basic documentation as
> FAQs and standalone documents because the unstructured web of docs
> created that way is much harder to comprehend (getting lost in the
> web) and also a pain to maintain in the long run.
>
> --
> Ferdinand Soethe
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by Ferdinand Soethe <sa...@soethe.net>.
As you might know Ross and I have put considerable time into working
on a chapter structure for a book on Single Source Publishing with
Forrest. Since we didn't follow through with the project (there will
only be a German book) we are prepared to donate this structure (more
precisely: the rights to this concept for an English publication) as a
basis for the Forrest documentation project.
It might need some adjustments of course, but it was designed to
introduce people with basic skills to Forrest so it seems compatible
with what Addi had in mind.
If people think this is helpful, I'd check the OpenOffice file with
the concept into the issue tracker so that people can study it and add
their comments and suggestions (preferably as a modified
OpenOffice-document). Or is OpenOffice too proprietary to work with?
Once we have finalized the chapter structure, we could create it as a
new tab on Forrest main site with each chapter becoming a menu item
pointing to a page with a short abstract for this chapter (not being
written yet) and instructions on what to do if person wants to write
and contribute this chapter.
All open chapters could also become items in the issue tracker but I
think that having them in a structured menu helps recognizing at what
point in the documentation this chapter is placed and what its
purpose is.
I'm in favour of not writing a whole lot of basic documentation as
FAQs and standalone documents because the unstructured web of docs
created that way is much harder to comprehend (getting lost in the
web) and also a pain to maintain in the long run.
--
Ferdinand Soethe
Re: documentation additions and issue tracking (Was: App vs Data)
Posted by Addi <ad...@rocktreesky.com>.
** (from users, brought over to dev - replies will go to dev) **
Brought this over to dev to continue the discussion on exactly how to
proceed with beginner documetation. As David points out we should
figure out whether this is something that should be a separate HowTo,
incorporated into the main docs or something else.
Originally I was thinking of it as a HowTo and that we could take some
of the more important bits and add them to the main docs. But I do
think (actually hope) that the average user skills will decrease as
forrest spreads. Right now it feels very geeky and I have friends who
know something about html and css who may be interested in a program
like this but would't really be able to pull this off with their current
knowledge and, frankly, aren't going to take time to figure it out. If
we want to bring more folks like that into the fold, then maybe moving
more of the basic stuff into the main docs would make more sense. WDYT?
To clarify a little what I mean by beginner, I am starting with as few
assumptions as I think reasonable. The perspective is someone who uses
html and css, probably using a GUI editor, has no command line
experience and can follow directions :). Most linux users have some
command line experience but from linux forums I can see lots of new to
linux users who don't really grasp it beyond the specific thing they are
told to type in an answer to their question. Most windows users don't
have any of it. I use it all the time on my linux/unix boxes but
forrest is the first time I had to figure any of it out in windows (I
now hate backslashes in a whole new way).
-Addi
David Crossley wrote:
>Addi wrote:
>
>
>>I am planning on working on beginner, step by step type documentation
>>over time (as I learn the answers to my own questions).
>>
>>
>
>It would be best if we created a shell of a new document
>so that you and any others can work on it together.
>More below about that ...
>
>
>
>>I was wondering
>>if it would be OK to start a new issue in JIRA for an improvement in
>>docs on this. That way, as people see problems that new users are
>>having in the lists, we can add them to the list of those issues in JIRA
>>to make it easier to keep track of it. Is that appropriate or is there
>>another system set up for something like this? I feel that keeping my
>>own scratchpad of issues is not terribly efficient, since I don't know
>>all the issues ...
>>
>>
>
>This sounds like a good idea. I recommend separate issues
>for each item. After we have incorporated that piece into
>the documentation, then we close the issue. There is a category
>for "Documentation". Give each issue a useful Summary title.
>Keep the Description concise, and use Comments for more detail.
>Link to mail list discussions where appropriate.
>
>Are you working with the head of development, i.e. the
>trunk of SVN?
>
>
>
>>... and it would suck for myself and someone else to be
>>writing docs on the same issue at the same time, thereby wasting
>>someone's time.
>>
>>
>
>That is exactly why we try to work on every document
>in the SVN repository. It is then collaborative.
>
>It is also good practice to do it bit by bit, i.e.
>progressively build the document rather than do a
>whole swag by yourself, only to find that when it
>comes time for us to commit the work, that you
>have gone off track.
>
>Remember too, that it is quite okay to have
>"Fixme:" banners inside the published docs.
>
>It would probably be useful to discuss the overall aim
>of this beginners documentation. Will it be one document
>in the main section of the website, will it be a HowTo.
>That sort of discussion is more appropriate for the
>dev mailing list.
>
>This is exciting, thanks for helping out.
>
>--David
>
>
>
>>What do you all recommend/already have in place?
>>
>>Thanks
>>Addi
>>
>>
>>Ross Gardler wrote:
>>
>>
>>
>>>Tim Williams wrote:
>>>
>>>
>>>
>>>>Embarrassingly enough, I was having a difficult time understanding the
>>>>much simpler multiple statically built sites with one Forrest. Ross'
>>>>answer was helpful and I think my problem was that I never created a
>>>>subdirectory to do the seed in so that I had a single "src" at a
>>>>higher level than it should have been. Having the "mkdir->cd->forrest
>>>>see" and maybe a little explanation of having "multiple sites" would
>>>>be helpful somewhere.
>>>>
>>>>
>>>>
>>>We would love a patch for the docs making this clearer, sometimes we
>>>forget these critical points that are less obvious than we assume them
>>>to be.
>>>
>>>Ross
>>>
>>>
>
>
>
>
>
documentation additions and issue tracking (Was: App vs Data)
Posted by David Crossley <cr...@apache.org>.
Addi wrote:
> I am planning on working on beginner, step by step type documentation
> over time (as I learn the answers to my own questions).
It would be best if we created a shell of a new document
so that you and any others can work on it together.
More below about that ...
> I was wondering
> if it would be OK to start a new issue in JIRA for an improvement in
> docs on this. That way, as people see problems that new users are
> having in the lists, we can add them to the list of those issues in JIRA
> to make it easier to keep track of it. Is that appropriate or is there
> another system set up for something like this? I feel that keeping my
> own scratchpad of issues is not terribly efficient, since I don't know
> all the issues ...
This sounds like a good idea. I recommend separate issues
for each item. After we have incorporated that piece into
the documentation, then we close the issue. There is a category
for "Documentation". Give each issue a useful Summary title.
Keep the Description concise, and use Comments for more detail.
Link to mail list discussions where appropriate.
Are you working with the head of development, i.e. the
trunk of SVN?
> ... and it would suck for myself and someone else to be
> writing docs on the same issue at the same time, thereby wasting
> someone's time.
That is exactly why we try to work on every document
in the SVN repository. It is then collaborative.
It is also good practice to do it bit by bit, i.e.
progressively build the document rather than do a
whole swag by yourself, only to find that when it
comes time for us to commit the work, that you
have gone off track.
Remember too, that it is quite okay to have
"Fixme:" banners inside the published docs.
It would probably be useful to discuss the overall aim
of this beginners documentation. Will it be one document
in the main section of the website, will it be a HowTo.
That sort of discussion is more appropriate for the
dev mailing list.
This is exciting, thanks for helping out.
--David
> What do you all recommend/already have in place?
>
> Thanks
> Addi
>
>
> Ross Gardler wrote:
>
> >Tim Williams wrote:
> >
> >>Embarrassingly enough, I was having a difficult time understanding the
> >>much simpler multiple statically built sites with one Forrest. Ross'
> >>answer was helpful and I think my problem was that I never created a
> >>subdirectory to do the seed in so that I had a single "src" at a
> >>higher level than it should have been. Having the "mkdir->cd->forrest
> >>see" and maybe a little explanation of having "multiple sites" would
> >>be helpful somewhere.
> >>
> >
> >We would love a patch for the docs making this clearer, sometimes we
> >forget these critical points that are less obvious than we assume them
> >to be.
> >
> >Ross
Re: App vs Data
Posted by Addi <ad...@rocktreesky.com>.
I am planning on working on beginner, step by step type documentation
over time (as I learn the answers to my own questions). I was wondering
if it would be OK to start a new issue in JIRA for an improvement in
docs on this. That way, as people see problems that new users are
having in the lists, we can add them to the list of those issues in JIRA
to make it easier to keep track of it. Is that appropriate or is there
another system set up for something like this? I feel that keeping my
own scratchpad of issues is not terribly efficient, since I don't know
all the issues and it would suck for myself and someone else to be
writing docs on the same issue at the same time, thereby wasting
someone's time.
What do you all recommend/already have in place?
Thanks
Addi
Ross Gardler wrote:
> Tim Williams wrote:
>
>> Embarrassingly enough, I was having a difficult time understanding the
>> much simpler multiple statically built sites with one Forrest. Ross'
>> answer was helpful and I think my problem was that I never created a
>> subdirectory to do the seed in so that I had a single "src" at a
>> higher level than it should have been. Having the "mkdir->cd->forrest
>> see" and maybe a little explanation of having "multiple sites" would
>> be helpful somewhere.
>>
>
> We would love a patch for the docs making this clearer, sometimes we
> forget these critical points that are less obvious than we assume them
> to be.
>
> Ross
>
>
>
Re: App vs Data
Posted by Ross Gardler <rg...@apache.org>.
Tim Williams wrote:
> Embarrassingly enough, I was having a difficult time understanding the
> much simpler multiple statically built sites with one Forrest. Ross'
> answer was helpful and I think my problem was that I never created a
> subdirectory to do the seed in so that I had a single "src" at a
> higher level than it should have been. Having the "mkdir->cd->forrest
> see" and maybe a little explanation of having "multiple sites" would
> be helpful somewhere.
>
We would love a patch for the docs making this clearer, sometimes we
forget these critical points that are less obvious than we assume them
to be.
Ross
Re: App vs Data
Posted by David Crossley <cr...@apache.org>.
Tim sent this directly to me, i am bringing it back onto the list.
More below ...
Tim Williams wrote:
> > Don't create that 'forrest seed' inside the forrest distribution.
> > Make a new directory at some completely different place on
> > your filesystem.
>
> I just downloaded a fresh 0.7 distro and created a totally separate
> "forrest-sites" directory where each subdirectory will be a site.
> That makes this much more understandable.
>
> I recommend changing
> " To try this out, create a completely new directory, change directory
> to it, and do 'forrest seed':"
>
> to
>
> "To try this out, create a completely new directory (outside the
> Forrest distribution), change directory to it, and do 'forrest seed':"
>
> It's looks trivial but I think if I wouldn't have made the mistake of
> seeding inside the distro I would never have been confused about the
> separation between the Forrest App and a site. Thank to everyone for
> your help.
This is a big help Tim. This is exactly the sort of clarification
that we need. I just now added that change to our SVN.
By the way, it would be much more efficient if people
changed their local copy of the doc and sent us the differences:
http://forrest.apache.org/0.7/contrib.html#patch
However, will gladly receive contributions in any form.
--David
Re: App vs Data
Posted by David Crossley <cr...@apache.org>.
Tim Williams wrote:
> Embarrassingly enough, I was having a difficult time understanding the
> much simpler multiple statically built sites with one Forrest. Ross'
> answer was helpful and I think my problem was that I never created a
> subdirectory to do the seed in so that I had a single "src" at a
> higher level than it should have been.
Don't create that 'forrest seed' inside the forrest distribution.
Make a new directory at some completely different place on
your filesystem.
--David
> Having the "mkdir->cd->forrest
> see" and maybe a little explanation of having "multiple sites" would
> be helpful somewhere.
>
> --tim
Re: App vs Data
Posted by Tim Williams <wi...@gmail.com>.
Embarrassingly enough, I was having a difficult time understanding the
much simpler multiple statically built sites with one Forrest. Ross'
answer was helpful and I think my problem was that I never created a
subdirectory to do the seed in so that I had a single "src" at a
higher level than it should have been. Having the "mkdir->cd->forrest
see" and maybe a little explanation of having "multiple sites" would
be helpful somewhere.
--tim
On 5/19/05, Johannes Schaefer <jo...@uidesign.de> wrote:
>
>
> Ross Gardler schrieb:
> > Tim Williams wrote:
> >
> >> I'm having a difficult time understanding where the Forrest
> >> application ends and where the data for the site begins. Is there
> >> always a one-to-one relationship between the Forrest app and a site?
>
> Yes. You can have multiple Forrest/Jetty instances
> running if you change the port, see
> http://forrest.apache.org/0.7/docs/faq.html#run_port
>
> But see also this feature request
> "Serve multiple sites on a single Forrest instance"
> http://issues.cocoondev.org/browse/FOR-490
>
> Johannes
>
>
> >> In other words can the app be used to operate on multiple sites or is
> >> the site configuration so inter-twined with the application that one
> >> needs separate "instances" of Forrest for each site (changing
> >> "$FORREST_HOME" for each site)?
> >
> >
> > All configs for a site, are site dependant. That is they are defined in
> > the site not in Forrest itself. SO the answer is you need 1 instance of
> > Forrest for any number of sites.
> >
> >> In terms of Forrest directory structure, I think here's what I'm asking:
> >>
> >> Instead of:
> >> ..\src\documentation
> >>
> >> ..\src\site1-documentation
> >> ..\src\site2-documentation
> >> ..\src\site3-documentation
> >>
> >> Where site1, site2, and site3 are totally different web sites. I
> >> guess the command line would somehow have to support an extra
> >> parameter naming the site to be built/run.
> >>
> >> Any help in understanding this would be appreciated.
> >
> >
> > You should have:
> >
> > site1/src/documentation
> > site2/src/documentation
> > site3/src/docuemntation
> >
> > In order to get started we provide a "forrest seed" command that will
> > create the necessary config files and directory structure. So all you
> > need to do is:
> >
> > mkdir site1
> > cd site1
> > forrest seed
> >
> > and then start editing your configuration and site data.
> >
> > See out docs for more info:
> >
> > http://forrest.apache.org/0.7/docs/your-project.html
> >
> > Ross
> >
> > Ross
> >
> >
>
Re: App vs Data
Posted by Johannes Schaefer <jo...@uidesign.de>.
Ross Gardler schrieb:
> Tim Williams wrote:
>
>> I'm having a difficult time understanding where the Forrest
>> application ends and where the data for the site begins. Is there
>> always a one-to-one relationship between the Forrest app and a site?
Yes. You can have multiple Forrest/Jetty instances
running if you change the port, see
http://forrest.apache.org/0.7/docs/faq.html#run_port
But see also this feature request
"Serve multiple sites on a single Forrest instance"
http://issues.cocoondev.org/browse/FOR-490
Johannes
>> In other words can the app be used to operate on multiple sites or is
>> the site configuration so inter-twined with the application that one
>> needs separate "instances" of Forrest for each site (changing
>> "$FORREST_HOME" for each site)?
>
>
> All configs for a site, are site dependant. That is they are defined in
> the site not in Forrest itself. SO the answer is you need 1 instance of
> Forrest for any number of sites.
>
>> In terms of Forrest directory structure, I think here's what I'm asking:
>>
>> Instead of:
>> ..\src\documentation
>>
>> ..\src\site1-documentation
>> ..\src\site2-documentation
>> ..\src\site3-documentation
>>
>> Where site1, site2, and site3 are totally different web sites. I
>> guess the command line would somehow have to support an extra
>> parameter naming the site to be built/run.
>>
>> Any help in understanding this would be appreciated.
>
>
> You should have:
>
> site1/src/documentation
> site2/src/documentation
> site3/src/docuemntation
>
> In order to get started we provide a "forrest seed" command that will
> create the necessary config files and directory structure. So all you
> need to do is:
>
> mkdir site1
> cd site1
> forrest seed
>
> and then start editing your configuration and site data.
>
> See out docs for more info:
>
> http://forrest.apache.org/0.7/docs/your-project.html
>
> Ross
>
> Ross
>
>
Re: App vs Data
Posted by Ross Gardler <rg...@apache.org>.
Tim Williams wrote:
> I'm having a difficult time understanding where the Forrest
> application ends and where the data for the site begins. Is there
> always a one-to-one relationship between the Forrest app and a site?
> In other words can the app be used to operate on multiple sites or is
> the site configuration so inter-twined with the application that one
> needs separate "instances" of Forrest for each site (changing
> "$FORREST_HOME" for each site)?
All configs for a site, are site dependant. That is they are defined in
the site not in Forrest itself. SO the answer is you need 1 instance of
Forrest for any number of sites.
> In terms of Forrest directory structure, I think here's what I'm asking:
>
> Instead of:
> ..\src\documentation
>
> ..\src\site1-documentation
> ..\src\site2-documentation
> ..\src\site3-documentation
>
> Where site1, site2, and site3 are totally different web sites. I
> guess the command line would somehow have to support an extra
> parameter naming the site to be built/run.
>
> Any help in understanding this would be appreciated.
You should have:
site1/src/documentation
site2/src/documentation
site3/src/docuemntation
In order to get started we provide a "forrest seed" command that will
create the necessary config files and directory structure. So all you
need to do is:
mkdir site1
cd site1
forrest seed
and then start editing your configuration and site data.
See out docs for more info:
http://forrest.apache.org/0.7/docs/your-project.html
Ross
Ross