forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [Proposal] Forrest Terminology
Date Wed, 11 May 2005 02:34:04 GMT
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

Mime
View raw message