[Proposal] Forrest Terminology

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

Whenever I start explaining Forrest, I stumble into the problem of
crossing terminology borders, using terms like 'build', 'compile',
'run' for the Forrest program and at the same time applying them to
Forrest projects.

If this is not just my ignorance about the proper terms, can we
perhaps try and define a terminology that makes it easier to know
whether the instruction

        'after that run Forrest'

        means

        - 'execute a "Forrest run" from the commandline'
           or
        - 'execute "Forrest" from the commandline'

Or whether

        'after that re-build your forrest'

        means that I should rebuild the Java sources or run Forrest to
        rebuild the static pages.

I find this extremely frustrating because you either have to assume
that a user will know what to do from context or you have to use
unpleasantly detailed wording to be sure they get it right.

If nobody objects, I'd be happy to suggest some changes to fix these
conflicts.
        

--
Ferdinand Soethe

Re: [Proposal] Forrest Terminology

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

Ferdinand Soethe wrote:
> Whenever I start explaining Forrest, I stumble into the problem of
> crossing terminology borders, using terms like 'build', 'compile',
> 'run' for the Forrest program and at the same time applying them to
> Forrest projects.

...

> If nobody objects, I'd be happy to suggest some changes to fix these
> conflicts.

We'd never object to suggestions ;-)

In this case I don't see the problem, but as you say that is because I 
am a user who can infer the context. If you can improve things for new 
users then we're all listening.

Ross

Re: [Proposal] Forrest Terminology

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

Thanks for Thorsten for pointing this out:

> http://issues.cocoondev.org/browse/FOR-362

Sorry for not having read the issues first. I'd be fine with the
renaming of targets suggested here if my proposals find less
support.


--
Ferdinand Soethe

Re: [Proposal] Forrest Terminology

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

David Crossley wrote:

DC> I too find it difficult to write Forrest documentation.
DC> However, i reckon that i have managed to use carefully
DC> chosen words, and putting all commands in single quotes,
DC> and qualifying whether it is their project or the core.
DC> e.g. then do 'forrest run' to launch the local server
DC> e.g. after that, re-build the Forrest core
DC> e.g. now re-build your Forrest project

Yes, no doubt it can be done and so far everybody has managed pretty
well. 

But - to explain myself more clearly to those who are not from the
documentation side of town - it becomes a problem when you write more
and longer pieces of doc and want to use variations in language ('do a
forrest run', 'run forrest' ...) that make it easier to read and
'flow' more smoothly.

Even worse in trainings and talks where conveying quotes in spoken
language is even harder and saying command line expressions will break
your tongue and everybody else's concentration.

Not to forget writing a book where - as a writer - you are happy about
any variation you can use because after a couple of chapters you and
your readers get very tired of all these repetitions.

DC> I do agree with your drive to get better terminology.
DC> When we do, we should document it in an FAQ section,
DC> and use it consistently throughout our docs. We can then
DC> assume that people know what we mean.

Definitely. That is one one major part once we agree on the terms.
Though I'd suggest to add a glossary of terms instead of putting that
into the FAQs. (Ross, is your glossary plugIn available)?

DC> However, i am a bit concerned about the timing of these
DC> changes. We have been trying to get the 0.7 released

I'd be happy to make this (and the change in directory) structure an issue for
version 0.8 and get 0.7 rolled out now. No point in 'breaking this
over the knee' as we say in German :-)

--
Ferdinand Soethe

Re: [Proposal] Forrest Terminology

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

Ferdinand Soethe wrote:
> 
> Whenever I start explaining Forrest, I stumble into the problem of
> crossing terminology borders, using terms like 'build', 'compile',
> 'run' for the Forrest program and at the same time applying them to
> Forrest projects.
> 
> If this is not just my ignorance about the proper terms, can we
> perhaps try and define a terminology that makes it easier to know
> whether the instruction
> 
>         'after that run Forrest'
> 
>         means
> 
>         - 'execute a "Forrest run" from the commandline'
>            or
>         - 'execute "Forrest" from the commandline'
> 
> Or whether
> 
>         'after that re-build your forrest'
> 
>         means that I should rebuild the Java sources or run Forrest to
>         rebuild the static pages.
> 
> I find this extremely frustrating because you either have to assume
> that a user will know what to do from context or you have to use
> unpleasantly detailed wording to be sure they get it right.
> 
> If nobody objects, I'd be happy to suggest some changes to fix these
> conflicts.

I too find it difficult to write Forrest documentation.
However, i reckon that i have managed to use carefully
chosen words, and putting all commands in single quotes,
and qualifying whether it is their project or the core.
e.g. then do 'forrest run' to launch the local server
e.g. after that, re-build the Forrest core
e.g. now re-build your Forrest project

I do agree with your drive to get better terminology.
When we do, we should document it in an FAQ section,
and use it consistently throughout our docs. We can then
assume that people know what we mean.

However, i am a bit concerned about the timing of these
changes. We have been trying to get the 0.7 released
for months now. Changes such as this will delay it
considerably longer, as there is a huge task to review all
the documentation, Ant build files, and stylesheets,
to make these changes.

On the other hand, 0.7 has already made some big
structural changes, e.g. src/core/ is now main/
and FORREST_HOME has moved. So it might be better to delay
the release again, to make all such changes in one sweep.

--David

Re: [Proposal] Forrest Terminology (Off topic)

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

> Oooops, sorry I was obviously in my own little world last night.

No worries, it was a good point after all.

> Errr.. yes, it is a verb... nothing wrong with a verb, errr... it was
> late... errr... I'd had a very large Whiskey.... errrr... I was looking

See! Had you shared instead of gulping down the good stuff all by
yourself I would have never noticed :-)

> Just a suggestion since I was negative about your own suggestions. Call
> it brainstorming to keep us moving.

No problem. Though I won't make it a new topic now.


--
Ferdinand Soethe

Re: [Proposal] Forrest Terminology

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

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 
> RG> Ferdinand Soethe wrote:
> 
>>>So how about renaming the command line options as follows
>>>(alternatives in order of decreasing preference)
>>>
>>>        rename          to be
>>>
>>>        forrest site => forrest mksite
>>>                        forrest static
>>>                        forrest makestatic
> 
> 
> RG> It's worth reminding ourselves of why Ferdinand feels this renaming is
> RG> important. He points out that some users are using Forrest to generate
> RG> stuff other than web sites, so "site" can be misleading. This is true
> RG> for much of my own work where I am building Learning Objects.
> 
> That's true (even though I didn't say that :-)). My reason is to
> clarify what these command will actually do, avoid overlapping meanings
> with building and compiling the forrest program itself or generic
> terms like run.

Oooops, sorry I was obviously in my own little world last night.

> RG> -1 on serve (serve is an adjective)
> 
> It is a verb isn't it? What's wrong about using a verb to
> start an ongoing process. 'Run' is a verb too isn't it?

Errr.. yes, it is a verb... nothing wrong with a verb, errr... it was 
late... errr... I'd had a very large Whiskey.... errrr... I was looking 
for a reason I didn't like it, errrr.... I'd also invented my own 
language to go into my own little world.

Sorry.

(I still don't like it though, not sure why, it just doesn't "feel" right)

> RG> I am happy with "run", nevertheless, since I am mostly against
> 
> run is my worst nightmare because it creates the fatal double meaning
> 'run forrest' / 'forrest run' (see my original posting)

OK, I'm not objecting to a change, just stating I've grown comfortable 
with it. I do aknowledge your point and will not stand in your way.

> RG> forrest servlet
> 
> Fine by me. Although many non-technical users probably don't know what
> a 'servlet' is. But certainly better than 'run'

Just a suggestion since I was negative about your own suggestions. Call 
it brainstorming to keep us moving.

> RG> I'm +1 one on splitting the stuff generated by building the Forrest
> RG> application and the stuff generated by "forrest site" (or whatever it
> RG> may become).
> 
> OK, I wasn't sure if tmp and webapp are used by the servlet
> exclusively. Is so, sure leavem them in one dir and call it something
> other than 'build'

I'll respond to this in a different thread.

Ross

Re: Splitting build and output directories (was Re: [Proposal] Forrest Terminology)

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

Ross Gardler wrote:
> Ferdinand Soethe wrote:
> 
>> Ross Gardler wrote:
>>
>>
>>> Ferdinand Soethe wrote:
> 
> 
> [OT: we've started getting duplicates of your mais]
> 
>>  >> Doesn't webapp contain logfiles that you want to look at?
>>
>>
>>> Yes it does. It'll be difficult for us to find the right dividing line.
>>> The way I was thinking was that if a document is generated for use 
>>> outside the Forrest environment then it should go into this "output"
>>> directory you are proposing (i.e. static pages and war file). This will
>>> mean there is only one directory to copy, no need to "learn" which one.
>>
>>
>>
>> I see a problem there because you'd mix log files from dynamic serving
>> with static output. But we could have the log files remain in the
>> serverspace and perhaps later on find a cocoon way of serving them as
>> part of the active site.
> 
> 
> Exactly, that is my point. I do not believe the log files should be 
> moved out of the build directory.

Sorry I just reread your point (must have a residual effect from last 
nights whiskey), let me respond again:

The issue of mixing dynamic content with static content is my point. I 
do not believe we should move the log files out of the build directory.

With resepct to your second point, having forrest serve them as a part 
of the site is possible, but it only makes sense in a dynamically 
generated site. Again this would indicate it should be in the build 
directory.

(incidentally, the log plugin in whiteboard could be used to provide a 
pretty version of the logs in a dynamically hosted site)

Ross

Re: Splitting build and output directories (was Re: [Proposal] Forrest Terminology)

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

Ferdinand Soethe wrote:

<snip what="lots of potentially confused stuff because..."/>

>>>>By the time we have moved webapp and the plugin stuff there isn't
>>>>really much left in build. Which then begs the question do we need it?
> 
> 
>>>Right. I do want to get rid of it because of the naming overlap wih
>>>building the programm.
> 
> 
>>I'm not convinced. The files that are built with forrest are required by
>>a dynamically served site. Therefore there is no distinction between the
>>forrest appication and a site hosted in the forrest appication.
> 
> 
> Ah, I'm beginning to understand. But the why are they not part of the
> forrest programm tree? Why have them in the project tree at all?

It seems we have been talking at cross-purposes. I was referring to the 
build directory in the Forrest directory, not in the project directory.
If this isn't a perfect example of a need for clearer names I don't know 
what is :-))

If I understand you correctly you are actually referring to the "build" 
directory in a project. Would you like to restate your proposal for this 
restructuring since I may have taken us way off track.

Ross

Re: Splitting build and output directories (was Re: [Proposal] Forrest Terminology)

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

> Where is this "resources"?

The sugessted myproject/resources branch could have a plugin-dir

> What is the "serverspace"? There are three distinct options in running a
> server:

> 1 - host the static site in a web server (no plugins required)
> 2 - host dynamically in a forrest server (plugins are in the Forrest webapp)
> 3 - host dynamically in some other servlet container (plugins are a part
> of the war)

I guess I don't understand Forrest enough to follow you into this
discussion. So unless I will understand this later on, I'm fine with
keeping the webapp as a directory and the place for plugIns. But I'd
still vote for renaming the build-dir.

>>>By the time we have moved webapp and the plugin stuff there isn't
>>>really much left in build. Which then begs the question do we need it?

>> Right. I do want to get rid of it because of the naming overlap wih
>> building the programm.

> I'm not convinced. The files that are built with forrest are required by
> a dynamically served site. Therefore there is no distinction between the
> forrest appication and a site hosted in the forrest appication.

Ah, I'm beginning to understand. But the why are they not part of the
forrest programm tree? Why have them in the project tree at all?

> There is a danger of confusing things by creating too many places a file
> may logically be located.

So anyway. If that is required for some reason that 'build' is
appropriate naming I guess. In that case we should just take site out
of there?

--
Ferdinand Soethe

Re: Splitting build and output directories (was Re: [Proposal] Forrest Terminology)

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

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 
> 
>>Ferdinand Soethe wrote:

[OT: we've started getting duplicates of your mais]

>  >> Doesn't webapp contain logfiles that you want to look at?
> 
> 
>>Yes it does. It'll be difficult for us to find the right dividing line.
>>The way I was thinking was that if a document is generated for use 
>>outside the Forrest environment then it should go into this "output"
>>directory you are proposing (i.e. static pages and war file). This will
>>mean there is only one directory to copy, no need to "learn" which one.
> 
> 
> I see a problem there because you'd mix log files from dynamic serving
> with static output. But we could have the log files remain in the
> serverspace and perhaps later on find a cocoon way of serving them as
> part of the active site.

Exactly, that is my point. I do not believe the log files should be 
moved out of the build directory.

>>If we should move those as well, then what about the plugin
>>stuff?
> 
> 
> Wouldn't it make sense to have the plugins stored in resources? If not
> I think they'd be tmp or part of the serverspace.

Where is this "resources"?

What is the "serverspace"? There are three distinct options in running a 
server:

1 - host the static site in a web server (no plugins required)
2 - host dynamically in a forrest server (plugins are in the Forrest webapp)
3 - host dynamically in some other servlet container (plugins are a part 
of the war)

>>By the time we have moved webapp and the plugin stuff there isn't
>>really much left in build. Which then begs the question do we need it?
> 
> 
> Right. I do want to get rid of it because of the naming overlap wih
> building the programm.

I'm not convinced. The files that are built with forrest are required by 
a dynamically served site. Therefore there is no distinction between the 
forrest appication and a site hosted in the forrest appication.

There is a danger of confusing things by creating too many places a file 
may logically be located.

Ross

Re: Splitting build and output directories (was Re: [Proposal] Forrest Terminology)

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

Ross Gardler wrote:

> Ferdinand Soethe wrote:

>> OK, I wasn't sure if tmp and webapp are used by the servlet
>> exclusively. Is so, sure leavem them in one dir and call it something
>> other than 'build'

> Actually, the broken links file appears in tmp. I've often thought that
> we should move this into the generated docs and add a stylesheet to the
> projectInfo plugin to render it witin an admin section of the docs, 
> perhaps as part of the todo page.

+1 I always wondered why we are no using forrest to make them look
   nice.

 >> Doesn't webapp contain logfiles that you want to look at?

> Yes it does. It'll be difficult for us to find the right dividing line.
> The way I was thinking was that if a document is generated for use 
> outside the Forrest environment then it should go into this "output"
> directory you are proposing (i.e. static pages and war file). This will
> mean there is only one directory to copy, no need to "learn" which one.

I see a problem there because you'd mix log files from dynamic serving
with static output. But we could have the log files remain in the
serverspace and perhaps later on find a cocoon way of serving them as
part of the active site.

> The log files are only of use if being run inside the forrest 
> environment.

Right. See my comment above.

> If we should move those as well, then what about the plugin
> stuff?

Wouldn't it make sense to have the plugins stored in resources? If not
I think they'd be tmp or part of the serverspace.

> By the time we have moved webapp and the plugin stuff there isn't
> really much left in build. Which then begs the question do we need it?

Right. I do want to get rid of it because of the naming overlap wih
building the programm.

>> RG> The static contents should go into another directory, as should the war
>> RG> file if generated for remote hosting.
>> 
>> Yes, that is the most important aspect.

> So it's just where to join draw the line and also to decide if we 
> actually *want* to split these. As I say I am +1 for it, but this is a
> major change and should be taken to a vote as it may have some unforseen
> consequences.

I suggest to join this thread with '[RT] Directory structure and
configuration' and sort out the remaining issues so that we all know
what we are voting for and have resolved as many open question as
possible.

Since this will probably take 0.8 to happen, I think we have the time
and I'm willing to take the discussion to a final proposal and see
that it won't get lost again.


Ferdinand Soethe

Splitting build and output directories (was Re: [Proposal] Forrest Terminology)

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

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 
> RG> Ferdinand Soethe wrote:
> 

...

> RG> I'm +1 one on splitting the stuff generated by building the Forrest
> RG> application and the stuff generated by "forrest site" (or whatever it
> RG> may become).
> 
> OK, I wasn't sure if tmp and webapp are used by the servlet
> exclusively. Is so, sure leavem them in one dir and call it something
> other than 'build'

Actually, the broken links file appears in tmp. I've often thought that 
we should move this into the generated docs and add a stylesheet to the 
projectInfo plugin to render it witin an admin section of the docs, 
perhaps as part of the todo page.

 > RG> But I don't see the need to go further and have all these
 > RG> different directories. To me webapp and tmp both belong in build 
since
 > RG> they are only of interest to forrest itself, not to the end user.
 >
 > Doesn't webapp contain logfiles that you want to look at?

Yes it does. It'll be difficult for us to find the right dividing line. 
The way I was thinking was that if a document is generated for use 
outside the Forrest environment then it should go into this "output" 
directory you are proposing (i.e. static pages and war file). This will 
mean there is only one directory to copy, no need to "learn" which one.

The log files are only of use if being run inside the forrest 
environment. If we should move those as well, then what about the plugin 
stuff? By the time we have moved webapp and the plugin stuff there isn't 
really much left in build. Which then begs the question do we need it?

> RG> The static contents should go into another directory, as should the war
> RG> file if generated for remote hosting.
> 
> Yes, that is the most important aspect.

So it's just where to join draw the line and also to decide if we 
actually *want* to split these. As I say I am +1 for it, but this is a 
major change and should be taken to a vote as it may have some unforseen 
consequences.

Ross

Re: [Proposal] Forrest Terminology

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

Ross Gardler wrote:

RG> Ferdinand Soethe wrote:
>> 
>> So how about renaming the command line options as follows
>> (alternatives in order of decreasing preference)
>> 
>>         rename          to be
>> 
>>         forrest site => forrest mksite
>>                         forrest static
>>                         forrest makestatic

RG> It's worth reminding ourselves of why Ferdinand feels this renaming is
RG> important. He points out that some users are using Forrest to generate
RG> stuff other than web sites, so "site" can be misleading. This is true
RG> for much of my own work where I am building Learning Objects.

That's true (even though I didn't say that :-)). My reason is to
clarify what these command will actually do, avoid overlapping meanings
with building and compiling the forrest program itself or generic
terms like run.

'forrest site' leaves people guessing what it will do. Although I could
live with it (much better than 'run')

>>         forrest run  => forrest serve
>>                         forrest server
>>                         forrest dynamic

RG> -1 on serve (serve is an adjective)

It is a verb isn't it? What's wrong about using a verb to
start an ongoing process. 'Run' is a verb too isn't it?

RG> I am happy with "run", nevertheless, since I am mostly against

run is my worst nightmare because it creates the fatal double meaning
'run forrest' / 'forrest run' (see my original posting)

RG> forrest servlet

Fine by me. Although many non-technical users probably don't know what
a 'servlet' is. But certainly better than 'run'


RG> I'm +1 one on splitting the stuff generated by building the Forrest
RG> application and the stuff generated by "forrest site" (or whatever it
RG> may become).

OK, I wasn't sure if tmp and webapp are used by the servlet
exclusively. Is so, sure leavem them in one dir and call it something
other than 'build'

RG> But I don't see the need to go further and have all these
RG> different directories. To me webapp and tmp both belong in build since
RG> they are only of interest to forrest itself, not to the end user.

Doesn't webapp contain logfiles that you want to look at?

RG> The static contents should go into another directory, as should the war
RG> file if generated for remote hosting.

Yes, that is the most important aspect.


--
Ferdinand Soethe

Re: [Proposal] Forrest Terminology

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

Ferdinand Soethe wrote:
> 
> So how about renaming the command line options as follows
> (alternatives in order of decreasing preference)
> 
>         rename          to be
> 
>         forrest site => forrest mksite
>                         forrest static
>                         forrest makestatic

-1 on mksite (I don't like accronyms in commands)
+0 on static (I'm not +1 since I have no problem with site, but I'll not 
object if others like this)
-0.5 on makestatic (as above, but I prefer static)

It's worth reminding ourselves of why Ferdinand feels this renaming is 
important. He points out that some users are using Forrest to generate 
stuff other than web sites, so "site" can be misleading. This is true 
for much of my own work where I am building Learning Objects.

>         forrest run  => forrest serve
>                         forrest server
>                         forrest dynamic

-1 on serve (serve is an adjective)
-1 on server (too generic)
-0.5 on dynamic (it doesn't say what it does)

I am happy with "run", nevertheless, since I am mostly against 
Ferdinands suggestions I'll make another proposal to see if it suits our 
needs:

forrest servlet

> Renaming the 'build' directory is difficult because of it's mixed use,
> but I'd still suggest naming it 'output' to avoid confusion with the
> software build and because this is much easier for non programmers to
> understand.

> Even better would be to split build into the functional units, move
> its three sub directories up and name them
> 
>         'tmp' (as before),
>         'staticsite' (instead of 'site') and
>         'serverworkspace' (instead of 'webapp').

I'm +1 one on splitting the stuff generated by building the Forrest 
application and the stuff generated by "forrest site" (or whatever it 
may become). But I don't see the need to go further and have all these 
different directories. To me webapp and tmp both belong in build since 
they are only of interest to forrest itself, not to the end user.

The static contents should go into another directory, as should the war 
file if generated for remote hosting.

I'm not sure about "output", but I have no better suggestions at present.

Ross

Re: [Proposal] Forrest Terminology

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

So how about renaming the command line options as follows
(alternatives in order of decreasing preference)

        rename          to be

        forrest site => forrest mksite
                        forrest static
                        forrest makestatic

        forrest run  => forrest serve
                        forrest server
                        forrest dynamic


Renaming the 'build' directory is difficult because of it's mixed use,
but I'd still suggest naming it 'output' to avoid confusion with the
software build and because this is much easier for non programmers to
understand.

Even better would be to split build into the functional units, move
its three sub directories up and name them

        'tmp' (as before),
        'staticsite' (instead of 'site') and
        'serverworkspace' (instead of 'webapp').

wdyt?

--
Ferdinand Soethe