You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Antonio Gallardo <ag...@agsoftware.dnsalias.com> on 2003/10/20 08:53:43 UTC
Forrest docs in old format.
Hi:
I noted almost all the docs in Cocoon website is in the "old" document v10
of Forrest:
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
Can we change to the "new" format v12?
Best Regards,
Antonio Gallardo
Re: Forrest docs in old format.
Posted by David Crossley <cr...@indexgeo.com.au>.
Antonio Gallardo wrote:
> Upayavira dijo:
<snip/>
> > Are you saying that, in order to access the docs by doing cocoon servlet
> > then http://localhost:8888/docs/ would access a local Forrest dist,
> > rather than the Cocoon dist itself, but would use the local Cocoon? That
> > could work. It would need a suitable "to see the docs, download
> > Forrest" message.
> >
> > But you know what that would mean? I would actually, after all this
> > time, actually have to download Forrest!
Ah, we strike this chicken-and-egg problem again (or is it
tree-and-seed).
But Forrest does not give you everything with its packaged Cocoon.
Many blocks are deliberately omitted.
> Maybe yes or not...
>
> One solution can be test if forrest is installed:
>
> if (forrest != installed) {
> <map:redirect to uri="the official website">
> }
Yes we would need some sort of test. Would it be better that this
happens during 'build webapp' rather than at runtime? The welcome.html
page is generated.
> I understand the problem. But maybe removing forrest from the distribution
> is a good start.
>
> Another solution can be:
>
> 1-Before releasing, generate all the cocoon docs with forrest.
> 2-Zip all the generated docs.
> 3-Make a sitemap for docs that read directly from the zip file?
>
> Is that ok? or this will increase the size of the distribution?
This sounds like a good solution, and in sync with Carsten's comment
earlier in this thread. Item 1 is already done with 'build dist'.
Another option is that the sitemap just "reads" the relevant
pre-prepared html doc, i.e. without the zip phase.
--David
Re: Forrest docs in old format.
Posted by Antonio Gallardo <ag...@agsoftware.dnsalias.com>.
Upayavira dijo:
> Antonio Gallardo wrote:
>>David Crossley dijo:
>>>David Crossley wrote:
>>>>Antonio Gallardo wrote:
>>>>>I noted almost all the docs in Cocoon website is in the "old"
>>>>document v10 of Forrest:
>>>>
>>>>><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
>>>>"../dtd/document-v10.dtd">
>>>>
>>>>>Can we change to the "new" format v12?
>>>>>
>>>>Yes, but there is a problem. We could change all the docs to v1.2 and
>>>> the generation of docs via 'build docs' should be okay.
>>>>
>>>>However, remember that docs are also built via the webapp
>>>>localhost:8888/docs/
>>>>and this still uses stylesheets that are specific to v1.0
>>>>
>>>>http://wiki.cocoondev.org/Wiki.jsp?page=ForrestProposal
>>>>... this identifies some of the issues. The complexity is probably
>>>> why no-one has been brave enough to do this job yet.
>>>>
>>>Perhaps we can solve this dilemma by avoiding it. We could
>>>remove the docs generation stuff from the webapp. If people
>>>want to do live docs, then they could install Forrest and
>>>'forrest run' on another port. We already ask them to install
>>>Forrest if they want to 'build docs'.
>>
>>+1
>>
>>That way we will don't worry about the forrest version inside cocoon.
>> And will can also remove it at all.
>>
>>I am also aware about the upayavira comment. I think the idea is not to
>> remove the docs from Cocoon, just allow to generate using an external
>> forrest dist.
>>
> Are you saying that, in order to access the docs by doing cocoon servlet
> then http://localhost:8888/docs/ would access a local Forrest dist,
> rather than the Cocoon dist itself, but would use the local Cocoon? That
> could work. It would need a suitable "to see the docs, download
> Forrest" message.
>
> But you know what that would mean? I would actually, after all this
> time, actually have to download Forrest!
Maybe yes or not...
One solution can be test if forrest is installed:
if (forrest != installed) {
<map:redirect to uri="the official website">
}
I understand the problem. But maybe removing forrest from the distribution
is a good start.
Another solution can be:
1-Before releasing, generate all the cocoon docs with forrest.
2-Zip all the generated docs.
3-Make a sitemap for docs that read directly from the zip file?
Is that ok? or this will increase the size of the distribution?
Best Regards,
Antonio Gallardo
Re: Forrest docs in old format.
Posted by Upayavira <uv...@upaya.co.uk>.
Antonio Gallardo wrote:
>David Crossley dijo:
>
>
>>David Crossley wrote:
>>
>>
>>>Antonio Gallardo wrote:
>>>
>>>
>>>>I noted almost all the docs in Cocoon website is in the "old"
>>>>
>>>>
>>>document v10 of Forrest:
>>>
>>>
>>>><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
>>>>
>>>>
>>>"../dtd/document-v10.dtd">
>>>
>>>
>>>>Can we change to the "new" format v12?
>>>>
>>>>
>>>Yes, but there is a problem. We could change all the docs to v1.2 and
>>>the generation of docs via 'build docs' should be okay.
>>>
>>>However, remember that docs are also built via the webapp
>>>localhost:8888/docs/
>>>and this still uses stylesheets that are specific to v1.0
>>>
>>>http://wiki.cocoondev.org/Wiki.jsp?page=ForrestProposal
>>>... this identifies some of the issues. The complexity is probably why
>>>no-one has been brave enough to do this job yet.
>>>
>>>
>>Perhaps we can solve this dilemma by avoiding it. We could
>>remove the docs generation stuff from the webapp. If people
>>want to do live docs, then they could install Forrest and
>>'forrest run' on another port. We already ask them to install
>>Forrest if they want to 'build docs'.
>>
>>
>
>+1
>
>That way we will don't worry about the forrest version inside cocoon. And
>will can also remove it at all.
>
>I am also aware about the upayavira comment. I think the idea is not to
>remove the docs from Cocoon, just allow to generate using an external
>forrest dist.
>
>
Are you saying that, in order to access the docs by doing cocoon servlet
then http://localhost:8888/docs/ would access a local Forrest dist,
rather than the Cocoon dist itself, but would use the local Cocoon? That
could work. It would need a suitable "to see the docs, download Forrest"
message.
But you know what that would mean? I would actually, after all this
time, actually have to download Forrest!
Regards, Upayavira
Re: Forrest docs in old format.
Posted by Antonio Gallardo <ag...@agsoftware.dnsalias.com>.
David Crossley dijo:
> David Crossley wrote:
>> Antonio Gallardo wrote:
>> >
>> > I noted almost all the docs in Cocoon website is in the "old"
>> document v10 of Forrest:
>> >
>> > <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
>> "../dtd/document-v10.dtd">
>> >
>> > Can we change to the "new" format v12?
>>
>> Yes, but there is a problem. We could change all the docs to v1.2 and
>> the generation of docs via 'build docs' should be okay.
>>
>> However, remember that docs are also built via the webapp
>> localhost:8888/docs/
>> and this still uses stylesheets that are specific to v1.0
>>
>> http://wiki.cocoondev.org/Wiki.jsp?page=ForrestProposal
>> ... this identifies some of the issues. The complexity is probably why
>> no-one has been brave enough to do this job yet.
>
> Perhaps we can solve this dilemma by avoiding it. We could
> remove the docs generation stuff from the webapp. If people
> want to do live docs, then they could install Forrest and
> 'forrest run' on another port. We already ask them to install
> Forrest if they want to 'build docs'.
+1
That way we will don't worry about the forrest version inside cocoon. And
will can also remove it at all.
I am also aware about the upayavira comment. I think the idea is not to
remove the docs from Cocoon, just allow to generate using an external
forrest dist.
Best Regards,
Antonio Gallardo.
>
> --David
Re: Forrest docs in old format.
Posted by Upayavira <uv...@upaya.co.uk>.
Carsten Ziegeler wrote:
>Upayavira wrote:
>
>
>>No, to use the CLI, I need a webapp, just like the servlet. And to test
>>the CLI, I need a webapp with some pages in it. Therefore, I use the
>>docs in the webapp (build/webapp/docs/) to test it.
>>
>>
>>
>>>Even if you would use that directory as your source you can
>>>use the src\docs directory.
>>>
>>>
>>>
>>>
>>We could configure the webapp\docs to use src\docs which would avoid
>>some copying, but I'm not sure if that really helps us all that much.
>>
>>Clearer now?
>>
>>
>>
>Yes, thank you!
>
>So, if you would use, e.g. the samples to test you wouldn't need
>the docs, I guess.
>
>
Yup. I've always steared clear of the samples, as there will be some
that are not suited to CLI generation (e.g Woody samples. But there are
some that would be suited, and the CLI now has include/exclude support,
which could be used there.
Having said that, I would still like to create a test suite. It would be
pages that don't make much sense to a user, but show up the sort of
thing that might go wrong (e.g paths not being calculated right).
Regards, Upayavira
RE: Forrest docs in old format.
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Upayavira wrote:
> No, to use the CLI, I need a webapp, just like the servlet. And to test
> the CLI, I need a webapp with some pages in it. Therefore, I use the
> docs in the webapp (build/webapp/docs/) to test it.
>
> >Even if you would use that directory as your source you can
> >use the src\docs directory.
> >
> >
> We could configure the webapp\docs to use src\docs which would avoid
> some copying, but I'm not sure if that really helps us all that much.
>
> Clearer now?
>
Yes, thank you!
So, if you would use, e.g. the samples to test you wouldn't need
the docs, I guess.
Carsten
Re: Forrest docs in old format.
Posted by Upayavira <uv...@upaya.co.uk>.
Carsten Ziegeler wrote:
>Upayavira wrote:
>
>
>>I get the CLI to generate /docs/index.html and follow links. If it
>>generates the whole site, it gives me a good idea as to how it is
>>working, and how fast it is working.
>>
>>It isn't the best test method, as there are features of the CLI that
>>this isn't testing - e.g. link rewriting. I can see that I need a more
>>targetted test suite, aimed to show up flaws in these features.
>>
>>One reason why I haven't done this because I haven't worked out how to.
>>Should I just create a sample, or I guess I could add my tests to
>>src/webapp/tests/. And have a cli-test.xconf somewhere that can be used
>>to run the tests. (I would like to come up with a way to automate the
>>checking of the results, but for the time being, checking the resulting
>>pages will be a manual process).
>>
>>Does all this make sense? The better the idea - the easier it'll be for
>>me to implement.
>>
>>Until we've done this, the docs is all I have!
>>
>>
>>
>:)
>
>Now, perhaps I did get something wrong, but as far as I understand
>you, you are using the CLI and generate the whole site from the
>docs directory. But this has nothing to do with the docs directory
>in the build\webapps directory, or am I wrong?
>
No, to use the CLI, I need a webapp, just like the servlet. And to test
the CLI, I need a webapp with some pages in it. Therefore, I use the
docs in the webapp (build/webapp/docs/) to test it.
>Even if you would use that directory as your source you can
>use the src\docs directory.
>
>
We could configure the webapp\docs to use src\docs which would avoid
some copying, but I'm not sure if that really helps us all that much.
Clearer now?
Regards, Upayavira
RE: Forrest docs in old format.
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Upayavira wrote:
>
> I get the CLI to generate /docs/index.html and follow links. If it
> generates the whole site, it gives me a good idea as to how it is
> working, and how fast it is working.
>
> It isn't the best test method, as there are features of the CLI that
> this isn't testing - e.g. link rewriting. I can see that I need a more
> targetted test suite, aimed to show up flaws in these features.
>
> One reason why I haven't done this because I haven't worked out how to.
> Should I just create a sample, or I guess I could add my tests to
> src/webapp/tests/. And have a cli-test.xconf somewhere that can be used
> to run the tests. (I would like to come up with a way to automate the
> checking of the results, but for the time being, checking the resulting
> pages will be a manual process).
>
> Does all this make sense? The better the idea - the easier it'll be for
> me to implement.
>
> Until we've done this, the docs is all I have!
>
:)
Now, perhaps I did get something wrong, but as far as I understand
you, you are using the CLI and generate the whole site from the
docs directory. But this has nothing to do with the docs directory
in the build\webapps directory, or am I wrong?
Even if you would use that directory as your source you can
use the src\docs directory.
Do we mean the same :) ?
Carsten
Re: Forrest docs in old format.
Posted by Upayavira <uv...@upaya.co.uk>.
Carsten Ziegeler wrote:
>Upayavira wrote:
>
>
>>For the moment I would be against removing the docs from the webapp, as
>>it is my primary means of testing the CLI/bean.
>>
>>
>>
>How do you test the CLI with the docs copied to the webapp? (Just curious)
>
>Carsten
>
>
>
I get the CLI to generate /docs/index.html and follow links. If it
generates the whole site, it gives me a good idea as to how it is
working, and how fast it is working.
It isn't the best test method, as there are features of the CLI that
this isn't testing - e.g. link rewriting. I can see that I need a more
targetted test suite, aimed to show up flaws in these features.
One reason why I haven't done this because I haven't worked out how to.
Should I just create a sample, or I guess I could add my tests to
src/webapp/tests/. And have a cli-test.xconf somewhere that can be used
to run the tests. (I would like to come up with a way to automate the
checking of the results, but for the time being, checking the resulting
pages will be a manual process).
Does all this make sense? The better the idea - the easier it'll be for
me to implement.
Until we've done this, the docs is all I have!
I'm off on a retreat for next week, so I won't be doing this for a
little while.
Regards, Upayavira
RE: Forrest docs in old format.
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
Upayavira wrote:
>
> For the moment I would be against removing the docs from the webapp, as
> it is my primary means of testing the CLI/bean.
>
How do you test the CLI with the docs copied to the webapp? (Just curious)
Carsten
Re: Forrest docs in old format.
Posted by Upayavira <uv...@upaya.co.uk>.
Carsten Ziegeler wrote:
>David Crossley wrote:
>
>
>>Perhaps we can solve this dilemma by avoiding it. We could
>>remove the docs generation stuff from the webapp. If people
>>want to do live docs, then they could install Forrest and
>>'forrest run' on another port. We already ask them to install
>>Forrest if they want to 'build docs'.
>>
>>
>>
>+1
>
>We could (don't know if it's worth), run forrest and add the
>generated html pages to the webapp.
>
>Carsten
>
>
>
For the moment I would be against removing the docs from the webapp, as
it is my primary means of testing the CLI/bean.
However, I do have it in mind to add some kind of 'cli-test' sample to
the samples, that includes pages specifically geared to test the CLI
functionality (e.g. pages that need their links rewriting, etc).
Until such CLI testing samples are present, I would be against removing
the docs stuff from the webapp.
Regards, Upayavira
RE: Forrest docs in old format.
Posted by Carsten Ziegeler <cz...@s-und-n.de>.
David Crossley wrote:
>
> Perhaps we can solve this dilemma by avoiding it. We could
> remove the docs generation stuff from the webapp. If people
> want to do live docs, then they could install Forrest and
> 'forrest run' on another port. We already ask them to install
> Forrest if they want to 'build docs'.
>
+1
We could (don't know if it's worth), run forrest and add the
generated html pages to the webapp.
Carsten
Re: Forrest docs in old format.
Posted by David Crossley <cr...@indexgeo.com.au>.
David Crossley wrote:
> Antonio Gallardo wrote:
> >
> > I noted almost all the docs in Cocoon website is in the "old" document v10
> > of Forrest:
> >
> > <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
> > "../dtd/document-v10.dtd">
> >
> > Can we change to the "new" format v12?
>
> Yes, but there is a problem. We could change all the docs to v1.2
> and the generation of docs via 'build docs' should be okay.
>
> However, remember that docs are also built via the webapp
> localhost:8888/docs/
> and this still uses stylesheets that are specific to v1.0
>
> http://wiki.cocoondev.org/Wiki.jsp?page=ForrestProposal
> ... this identifies some of the issues. The complexity is probably
> why no-one has been brave enough to do this job yet.
Perhaps we can solve this dilemma by avoiding it. We could
remove the docs generation stuff from the webapp. If people
want to do live docs, then they could install Forrest and
'forrest run' on another port. We already ask them to install
Forrest if they want to 'build docs'.
--David
Re: Forrest docs in old format.
Posted by David Crossley <cr...@indexgeo.com.au>.
Antonio Gallardo wrote:
> Hi:
>
> I noted almost all the docs in Cocoon website is in the "old" document v10
> of Forrest:
>
> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
> "../dtd/document-v10.dtd">
>
> Can we change to the "new" format v12?
Yes, but there is a problem. We could change all the docs to v1.2
and the generation of docs via 'build docs' should be okay.
However, remember that docs are also built via the webapp
localhost:8888/docs/
and this still uses stylesheets that are specific to v1.0
http://wiki.cocoondev.org/Wiki.jsp?page=ForrestProposal
... this identifies some of the issues. The complexity is probably
why no-one has been brave enough to do this job yet.
--David