Idiot's guide

[Ad...@ao.uscourts.gov]

Hello all,

I have just found Forrest.  I am a total newbie with XML and any kind of 
program of this nature.  Forrest looks like an excellent tool for my 
needs.  I had been playing with writing in docbook in Oxygen, but this 
seems much simpler for my needs - once I figure out how to use it.

I have found that the documentation is not very good for a total noob like 
me.  There are certain assumptions made and gaps that I have had to work 
through.  I really do like the concept of this project though so I have 
been patiently screwing stuff up and fixing it to get the hang of it all. 
I've started taking notes on the things that I messed up or felt the need 
to guess. I would like to either create or contribute to an existing 
beginners documentation that is really down on the level of an idiot's 
guide, step-by-step (like "Where should I unzip the file?" - I knew this, 
but you get the idea).  One of my problems was that in setting the 
environment variables I just copied and pasted what was there on the web 
page(%PATH%;%FORREST_HOME%\bin) for the PATH setting and so I overwrote 
all the stuff that was in my path already.  I had to go back and manually 
fix my path variable (and lord knows if I got everything).  I am much more 
knowledgeable about html, css and php then I am about the windows OS.  I 
think there are more and more people who are looking for tools to help 
them and are willing to invest some time to figure it out - if they have a 
clear guide and can ascertain whether or not they can figure it out in a 
reasonable amount of time.

Anyway, I am willing to help with newbie documentation in any way you see 
useful.  Please let me know where to go, who to get in touch with.

Thanks
Addi

Re: Idiot's guide

[Antonio Gallardo <ag...@agssa.net>]

Hi:

I hope all the info you need to write new or improve the docos is here:

http://forrest.apache.org/contrib.html

If you need more info, don't hesitate to ask. We will be glad to help you.

Best Regards,

Antonio Gallardo

On Mar, 17 de Mayo de 2005, 13:19, Addi_Berry@ao.uscourts.gov dijo:
> Hello all,
>
> I have just found Forrest.  I am a total newbie with XML and any kind of
> program of this nature.  Forrest looks like an excellent tool for my
> needs.  I had been playing with writing in docbook in Oxygen, but this
> seems much simpler for my needs - once I figure out how to use it.
>
> I have found that the documentation is not very good for a total noob like
> me.  There are certain assumptions made and gaps that I have had to work
> through.  I really do like the concept of this project though so I have
> been patiently screwing stuff up and fixing it to get the hang of it all.
> I've started taking notes on the things that I messed up or felt the need
> to guess. I would like to either create or contribute to an existing
> beginners documentation that is really down on the level of an idiot's
> guide, step-by-step (like "Where should I unzip the file?" - I knew this,
> but you get the idea).  One of my problems was that in setting the
> environment variables I just copied and pasted what was there on the web
> page(%PATH%;%FORREST_HOME%\bin) for the PATH setting and so I overwrote
> all the stuff that was in my path already.  I had to go back and manually
> fix my path variable (and lord knows if I got everything).  I am much more
> knowledgeable about html, css and php then I am about the windows OS.  I
> think there are more and more people who are looking for tools to help
> them and are willing to invest some time to figure it out - if they have a
> clear guide and can ascertain whether or not they can figure it out in a
> reasonable amount of time.
>
> Anyway, I am willing to help with newbie documentation in any way you see
> useful.  Please let me know where to go, who to get in touch with.
>
> Thanks
> Addi

Re: Idiot's guide

[Ross Gardler <rg...@apache.org>]

Addi_Berry@ao.uscourts.gov wrote:
> I have found that the documentation is not very good for a total noob 
> like me.  

Yes, we admit it :-(

> There are certain assumptions made and gaps that I have had to 
> work through.  I really do like the concept of this project though so I 
> have been patiently screwing stuff up and fixing it to get the hang of 
> it all.

Sounds like we need to keep you around :-))

> I've started taking notes on the things that I messed up or 
> felt the need to guess. I would like to either create or contribute to 
> an existing beginners documentation that is really down on the level of 
> an idiot's guide, step-by-step (like "Where should I unzip the file?" - 
> I knew this, but you get the idea).

This would be useful.

> I am much more knowledgeable about html, css and php then 
> I am about the windows OS.

Let me pick up on one of the things you said you *are* knowledgeable 
about CSS

We have some outstanding issues with our skin that need the attention of 
someone with CSS skills. Perhaps you could take a look. In particular I 
am thinking of:

http://issues.cocoondev.org/browse/FOR-336

If you think you have the CSS skills to tackle this but need to ask 
questions about Forrest then the dev list is the place to be. We'll 
point you at the right files/docs to get you going.

> Anyway, I am willing to help with newbie documentation in any way you 
> see useful.  Please let me know where to go, who to get in touch with.

There are many ways you can help in addition to the CSS issues above.

1) stay subscribed to this list and as you knowledge grows help us 
respond to user questions

2) join the dev list where we discuss all issues to do with the 
development of Forrest (including docs).

3) do as you are doing, take notes of the pitfalls you find, if the 
notes are not enough to form a Howto or a document on their own then 
consider adding them to our FAQ.

(please do not send HTML mails to our list, we prefer plain text - thanks)

Ross

Re: Path Setting (was Re: Idiot's guide)

[Ross Gardler <rg...@apache.org>]

(Moved to dev list, replies will go there)


Ferdinand Soethe wrote:
> I'd suggest to add a minimum installer to Forrest 0.8 that does at
> least one thing:
> 
> - set the path properly
> 
> and while we are at it
> 
> - add ways to execute forrest run, forrest (compile) and forrest clean
>   for a given project (directory) from the windows explorer
>   (I'm thinking about either send-tos) or associating a dummy file
>   in the project root with these commands.
> 
> Can anybody recommend an open source install software for windows?

I've been using izPack lately. The next version will be Apache licensed
and it is cross platform. They even provide a launcher for windows that
will help install Java if not already present on Windows.

http://www.izforge.com/izpack/

Ross

Re: Path Setting (was Re: Idiot's guide)

[Ross Gardler <rg...@apache.org>]

(Moved to dev list, replies will go there)


Ferdinand Soethe wrote:
> I'd suggest to add a minimum installer to Forrest 0.8 that does at
> least one thing:
> 
> - set the path properly
> 
> and while we are at it
> 
> - add ways to execute forrest run, forrest (compile) and forrest clean
>   for a given project (directory) from the windows explorer
>   (I'm thinking about either send-tos) or associating a dummy file
>   in the project root with these commands.
> 
> Can anybody recommend an open source install software for windows?

I've been using izPack lately. The next version will be Apache licensed
and it is cross platform. They even provide a launcher for windows that
will help install Java if not already present on Windows.

http://www.izforge.com/izpack/

Ross

Path Setting (was Re: Idiot's guide)

[Ferdinand Soethe <sa...@soethe.net>]

David wrote

> I don't know what you mean by that. I don't do Window$, but that setting
> looks like it would take the existing PATH and append the location of
> forrest bin directory.

Your are right in theorie. If you used this expression in a bat file
to set the path variable it would work.

But if you used it in the gui-dialogs of the more recent windows
versions and replaced the path settings there with this, you'd
effectively delete the old path settings.

> No-one has ever complained about this before,
> and we have plenty of users on that system. Perhaps you have found
> a typo that everyone else has missed. Please tell us which document
> you are referring to.

It's not a typo. If you understand the context it it correct. But the
context here is pretty complex and the instructions needed would be
different between windows versions and languages, a doc nightmare.

I'd suggest to add a minimum installer to Forrest 0.8 that does at
least one thing:

- set the path properly

and while we are at it

- add ways to execute forrest run, forrest (compile) and forrest clean
  for a given project (directory) from the windows explorer
  (I'm thinking about either send-tos) or associating a dummy file
  in the project root with these commands.

Can anybody recommend an open source install software for windows?

--
Ferdinand Soethe

Re: Idiot's guide

[David Crossley <cr...@apache.org>]

Addi_Berry@ao.uscourts.gov wrote:
> Hello all,
> 
> I have just found Forrest.  I am a total newbie with XML and any kind of 
> program of this nature.  Forrest looks like an excellent tool for my 
> needs.  I had been playing with writing in docbook in Oxygen, but this 
> seems much simpler for my needs - once I figure out how to use it.

Creating the source content is a different issue from using Forrest.
The source format can be in such formats as HTML, OpenOffice.org,
Forrest's own xdocs format, and we even have initial support for using
some DocBook formats, etc.

> I have found that the documentation is not very good for a total noob like 
> me.  There are certain assumptions made and gaps that I have had to work 
> through.

You have not told us which version of Forrest you are using.
All the effort in enhancing docs is going into the next version,
(0.7) which is due to be released real soon now.

>  I really do like the concept of this project though so I have 
> been patiently screwing stuff up and fixing it to get the hang of it all. 

That is a very good way to learn.

> I've started taking notes on the things that I messed up or felt the need 
> to guess. I would like to either create or contribute to an existing 
> beginners documentation that is really down on the level of an idiot's 
> guide, step-by-step (like "Where should I unzip the file?" - I knew this, 
> but you get the idea).

At this stage of your learning, i suggest that you send separate
questions to this user mail list. We will answer them and add to
the docs if necessary.

>  One of my problems was that in setting the 
> environment variables I just copied and pasted what was there on the web 
> page(%PATH%;%FORREST_HOME%\bin) for the PATH setting and so I overwrote 
> all the stuff that was in my path already.  I had to go back and manually 
> fix my path variable (and lord knows if I got everything).

I don't know what you mean by that. I don't do Window$, but that setting
looks like it would take the existing PATH and append the location of
forrest bin directory. No-one has ever complained about this before,
and we have plenty of users on that system. Perhaps you have found
a typo that everyone else has missed. Please tell us which document
you are referring to.

>  I am much more 
> knowledgeable about html, css and php then I am about the windows OS.  I 
> think there are more and more people who are looking for tools to help 
> them and are willing to invest some time to figure it out - if they have a 
> clear guide and can ascertain whether or not they can figure it out in a 
> reasonable amount of time.
> 
> Anyway, I am willing to help with newbie documentation in any way you see 
> useful.  Please let me know where to go, who to get in touch with.

Send questions to this list. Wait until you understand Forrest
a bit more before writing new documentation, and don't bother
until using the upcoming 0.7 version (there were lots of changes
to directory structure). The 0.6 docs will only be updated for
critical errors.

We do understand the need for super-basic introduction documentation.
This will probably be addressed after the 0.7 release, as we don't
want to delay it at this stage.

--David