You are viewing a plain text version of this content. The canonical link for it is here.
Posted to phoenix-dev@avalon.apache.org by Nicola Ken Barozzi <ni...@apache.org> on 2002/11/16 14:28:37 UTC
[DOCS] Conversion of the Phoenix documentation to Forrest
In these days I've converted the Phoenix documentation to Forrest format
http://xml.apache.org/forrest/ , by making xsl stylesheets (that BTW
Pete seems to have used for the Avalon Framework stuff before than me ;-)
I'm going to commit the documentation in ./src/documentation/ , which is
the forrest default.
There are two possibilities for the xdocs, and maybe it's better I ask
what you guys prefer.
case 1
./src/documentation/content/** (all files here added verbatim)
./src/documentation/content/xdocs/** (here are the xml docs)
case 2
./src/documentation/content/** (all files here added verbatim)
./src/documentation/content/**.xml (here are the xml docs)
I'm going with case 2, so that we keep all the docs in a single dir
structure.
I'll put the images in ./src/documentation/resources/images/** because
of a current Forrest bug (Jeff calls it feature ;-) , but I'd like to
move them under the unified doc hierarchy structure later, when the
issue gets resolved.
If there are no objections, I'll commit the docs as per case2 later today.
Thank you :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Peter Donald wrote:
> On Tue, 19 Nov 2002 18:54, Nicola Ken Barozzi wrote:
>
>>>>The sources to change are in ./build/webapp, you will need to synch them
>>>>with the actual docs manually.
>>>
>>>Is there anyways to update the jetty integration so this is not required
>>>- as thats precisely the reason I avoid using it.
>>
>>What if in the build we add for now a copy of newer files from webapp to
>>content?
>
> That makes my skin crawl ;) Too many times have I buggered up with auto
> copying around. I once lost about 3 days work on avalon because of this ...
> it was right before I made sure our build process did no copying ;)
And that's the reason actually why I haven't yet put it in place...
> If we can detect newer/modified files and then copy them to another directory
> (as backup). Then have the user go through the directory manually and copy
> back to original position then I would be kool with that. I just get really
> really really nervous when doing overwrites ;)
... ahh, ok, good suggestion.
I'll see what I can do.
> I can keep going with CLI even if, as Jeff puts it, "it is pure evil!" :)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Peter Donald <pe...@apache.org>.
On Tue, 19 Nov 2002 18:54, Nicola Ken Barozzi wrote:
> >>The sources to change are in ./build/webapp, you will need to synch them
> >>with the actual docs manually.
> >
> > Is there anyways to update the jetty integration so this is not required
> > - as thats precisely the reason I avoid using it.
>
> What if in the build we add for now a copy of newer files from webapp to
> content?
That makes my skin crawl ;) Too many times have I buggered up with auto
copying around. I once lost about 3 days work on avalon because of this ...
it was right before I made sure our build process did no copying ;)
If we can detect newer/modified files and then copy them to another directory
(as backup). Then have the user go through the directory manually and copy
back to original position then I would be kool with that. I just get really
really really nervous when doing overwrites ;)
I can keep going with CLI even if, as Jeff puts it, "it is pure evil!" :)
--
Cheers,
Peter Donald
--------------------------------------------------
"An intellectual is someone who has been educated
beyond their intelligence."
--------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Peter Donald wrote:
> On Tue, 19 Nov 2002 09:41, Nicola Ken Barozzi wrote:
>
>>Nicola Ken Barozzi wrote:
>>
>>>In these days I've converted the Phoenix documentation to Forrest format
>>>http://xml.apache.org/forrest/ , by making xsl stylesheets (that BTW
>>>Pete seems to have used for the Avalon Framework stuff before than me ;-)
>>
>
> Nah - A-F was in document 1.0 format so hacked together a 1.0 -> 1.1
> stylehseet.
>
>
>>I committed the Phoenix docs in Forrest format in the Phoenix CVS, and
>>changed the build file and tools to support the new doc system.
>>
>>I have tested the site, site-all, announcement targets but not yet the
>>dist targets because I have speed problems with my internet connection
>>at home and I'm having a hard time in downloading MX4J; I'll test them
>>tomorrow.
>>
>>If anyone has the opportunity to give it a test please report and I'll
>>fix it ASAP.
>
> ATM several of the pages don't validate and thus the docs don't build. I will
> look into fixing it.
Hmmm, that's really strange, I actually managed to build them without
errors, it's really puzzleing :-?
Oh well, as long as it now works, good :-)
>>The docs use a new avalon-tigris skin that Peter Donald has submitted to
>>Forrest.
>>
>>If you are ok with this version, I can regenerate the site and put it up
>>live, after fixing a bug there seems to be in the <code> tag handling,
>
> the tigris skin also has some problems handling non-selected tab elements. It
> is just a css issue than needs to be fixed I assume but I haven't gotten back
> to it. There is also an issue in the way that menu items are highlighted.
> Sometimes multiple get highlighted - not sure about why but will have to fix
> it somehow.
Ok.
>>after adding a link to every page for PDF files,
>
> I would prefer not. I eventually plan to move towards uber docbook docs with
> one pdf per "book" and I don't think there is any significant advantage in
> duplicating the html content as pdf at this stage.
Ok.
>>The sources to change are in ./build/webapp, you will need to synch them
>>with the actual docs manually.
>
> Is there anyways to update the jetty integration so this is not required - as
> thats precisely the reason I avoid using it.
What if in the build we add for now a copy of newer files from webapp to
content?
>>There is a broken link in getting-started.xml:
>>
>>"
>>Firstly you will need to get the demo-helloword.sar file and drop it
>>into the apps directory of Phoenix.
>>Get it from <link href="TODO">TODO</link>
>>" ^^^^^^^^^^^^^^^^^^^^
>
>
> Will fix.
>
> Thanks for doing that!
:-)
It was the main reason I came here for. You haven't seen much progress
in past months because I used the time to help get Forrest and Cocoon
better, like making the CLI output a bit better (still need working),
not choking on links, Forrest webapp for speed, etc.
I'm happy we finally got to this point.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Peter Donald <pe...@apache.org>.
On Tue, 19 Nov 2002 09:41, Nicola Ken Barozzi wrote:
> Nicola Ken Barozzi wrote:
> > In these days I've converted the Phoenix documentation to Forrest format
> > http://xml.apache.org/forrest/ , by making xsl stylesheets (that BTW
> > Pete seems to have used for the Avalon Framework stuff before than me ;-)
Nah - A-F was in document 1.0 format so hacked together a 1.0 -> 1.1
stylehseet.
> I committed the Phoenix docs in Forrest format in the Phoenix CVS, and
> changed the build file and tools to support the new doc system.
>
> I have tested the site, site-all, announcement targets but not yet the
> dist targets because I have speed problems with my internet connection
> at home and I'm having a hard time in downloading MX4J; I'll test them
> tomorrow.
>
> If anyone has the opportunity to give it a test please report and I'll
> fix it ASAP.
ATM several of the pages don't validate and thus the docs don't build. I will
look into fixing it.
> The docs use a new avalon-tigris skin that Peter Donald has submitted to
> Forrest.
>
> If you are ok with this version, I can regenerate the site and put it up
> live, after fixing a bug there seems to be in the <code> tag handling,
the tigris skin also has some problems handling non-selected tab elements. It
is just a css issue than needs to be fixed I assume but I haven't gotten back
to it. There is also an issue in the way that menu items are highlighted.
Sometimes multiple get highlighted - not sure about why but will have to fix
it somehow.
> after adding a link to every page for PDF files,
I would prefer not. I eventually plan to move towards uber docbook docs with
one pdf per "book" and I don't think there is any significant advantage in
duplicating the html content as pdf at this stage.
> The sources to change are in ./build/webapp, you will need to synch them
> with the actual docs manually.
Is there anyways to update the jetty integration so this is not required - as
thats precisely the reason I avoid using it.
> There is a broken link in getting-started.xml:
>
> "
> Firstly you will need to get the demo-helloword.sar file and drop it
> into the apps directory of Phoenix.
> Get it from <link href="TODO">TODO</link>
> " ^^^^^^^^^^^^^^^^^^^^
Will fix.
Thanks for doing that!
--
Cheers,
Peter Donald
"Artists can color the sky red because they know it's blue. Those of us who
aren't artists must color things the way they really are or people might
think we're stupid." -- Jules Feiffer
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Peter Donald <pe...@apache.org>.
syntax error. Inserting word to make more sense...
On Tue, 19 Nov 2002 11:10, Peter Donald wrote:
> BTW - I just added an resources/stylesheets/avfilterlinks.xsl - if you
> could add that at the end of the "links" view pipeline then that would be
> great. It essentially strips out api docs.
>
> Also - if you want to put the content related images in main content
> directory and then add a bunch of special case rules then I don't
mind
> maintaining them and I think it would probably be a good thing to separate
> out style/content images.
--
Cheers,
Peter Donald
---------------------------------------------------
"It is easy to dodge our responsibilities, but we
cannot dodge the consequences of dodging our
responsibilities." -Josiah Stamp
---------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Peter Donald <pe...@apache.org>.
On Tue, 19 Nov 2002 20:24, Nicola Ken Barozzi wrote:
> Peter Donald wrote:
> > BTW - I just added an resources/stylesheets/avfilterlinks.xsl - if you
> > could add that at the end of the "links" view pipeline then that would be
> > great. It essentially strips out api docs.
>
> This is part of a wider design discussion about how to merge URI spaces
> in Forrest with outer generated docs.
> In the meantime, we can just keep the links and then copy the
> outer-generated docs over, like the javadocs do now.
> Could this do, without having to change anything?
I would prefer not to have any errors in our build process. An error shoul d
indicate an error - not something we know will fail.
--
Cheers,
Peter Donald
----------------------------------------------------------------
Fools ignore complexity. Pragmatists suffer it.
Some can avoid it. Geniuses remove it.
-- Perlis's Programming Proverb #58, SIGPLAN Notices, Sept. 1982
----------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Peter Donald wrote:
> BTW - I just added an resources/stylesheets/avfilterlinks.xsl - if you could
> add that at the end of the "links" view pipeline then that would be great. It
> essentially strips out api docs.
This is part of a wider design discussion about how to merge URI spaces
in Forrest with outer generated docs.
In the meantime, we can just keep the links and then copy the
outer-generated docs over, like the javadocs do now.
Could this do, without having to change anything?
> Also - if you want to put the content related images in main content directory
> and then add a bunch of special case rules then I don't maintaining them and
> I think it would probably be a good thing to separate out style/content
> images.
ATM they are in the resources/images and will remain there till we
finalize the discussion on the mixed content dirs on the Forrest list,
so no special rules are needed.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Peter Donald <pe...@apache.org>.
BTW - I just added an resources/stylesheets/avfilterlinks.xsl - if you could
add that at the end of the "links" view pipeline then that would be great. It
essentially strips out api docs.
Also - if you want to put the content related images in main content directory
and then add a bunch of special case rules then I don't maintaining them and
I think it would probably be a good thing to separate out style/content
images.
--
Cheers,
Peter Donald
*--------------------------------*
| Every rule has an exception, |
| except the rule of exceptions. |
*--------------------------------*
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [DOCS] Conversion of the Phoenix documentation to Forrest
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Nicola Ken Barozzi wrote:
>
> In these days I've converted the Phoenix documentation to Forrest format
> http://xml.apache.org/forrest/ , by making xsl stylesheets (that BTW
> Pete seems to have used for the Avalon Framework stuff before than me ;-)
>
> I'm going to commit the documentation in ./src/documentation/ , which is
> the forrest default.
[...]
> case 2
> ./src/documentation/content/** (all files here added verbatim)
> ./src/documentation/content/**.xml (here are the xml docs)
>
[...]
> If there are no objections, I'll commit the docs as per case2 later today.
I committed the Phoenix docs in Forrest format in the Phoenix CVS, and
changed the build file and tools to support the new doc system.
I have tested the site, site-all, announcement targets but not yet the
dist targets because I have speed problems with my internet connection
at home and I'm having a hard time in downloading MX4J; I'll test them
tomorrow.
If anyone has the opportunity to give it a test please report and I'll
fix it ASAP.
The docs use a new avalon-tigris skin that Peter Donald has submitted to
Forrest.
If you are ok with this version, I can regenerate the site and put it up
live, after fixing a bug there seems to be in the <code> tag handling,
after adding a link to every page for PDF files, and after adding the
top links to other Avalon sub-projects.
_INFO about the new docs system_
New docs dir:
jakarta-avalon-phoenix/src/documentation
New content dir:
jakarta-avalon-phoenix/src/documentation/content
New resources and images dir:
jakarta-avalon-phoenix/src/documentation/resources
To build the documentation download Forrest from CVS
http://xml.apache.org/forrest/your-project.html#N10022
install it as described here
http://xml.apache.org/forrest/your-project.html#N10036
cd in the jakarta-avalon-phoenix dir and run "forrest"
To see the site real-time from a local embedded webserver run
forrest run
and point the browser to http://localhost:8888/
The sources to change are in ./build/webapp, you will need to synch them
with the actual docs manually.
Or run the Phoenix build.xml with target "site".
To add also javadocs run "site-all".
_NOTE_
There is a broken link in getting-started.xml:
"
Firstly you will need to get the demo-helloword.sar file and drop it
into the apps directory of Phoenix.
Get it from <link href="TODO">TODO</link>
" ^^^^^^^^^^^^^^^^^^^^
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>