You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@gump.apache.org by "Adam R. B. Jack" <aj...@trysybase.com> on 2004/04/06 20:04:28 UTC
--xdocs
Ok, an --xdocs on the commandline makes Gump not run forrest on the xdocs it
generates into the work directory, but sync's them into the log directory.
Note, it copies in the template first (which has much of this below) As such
it creates:
status.xml
forrest.properties
forrest-targets.ent (ought this be removed?)
./src/documentation
./src/documentation/skinconf
./src/documentation/content
./src/documentation/content/xdocs
it then fills up:
./src/documentation/content
./src/documentation/content/xdocs
Does this seem right for dynamic forrest?
regards,
Adam
--
Experience the Unwired Enterprise:
http://www.sybase.com/unwiredenterprise
Try Sybase: http://www.try.sybase.com
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
Re: --xdocs
Posted by Leo Simons <ls...@jicarilla.org>.
Adam R. B. Jack wrote:
> Any feedback on this plan, or a lazy JFDI?
read it twice, don't quite get what it's about, so yeah, JFDI.
--
cheers,
- Leo Simons
-----------------------------------------------------------------------
Weblog -- http://leosimons.com/
Component Community -- http://componentplanet.org/
Component Glue -- http://jicarilla.org/
-----------------------------------------------------------------------
"We started off trying to set up a small anarchist community, but
people wouldn't obey the rules."
-- Alan Bennett
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
Re: --xdocs
Posted by "Adam R. B. Jack" <aj...@trysybase.com>.
Any feedback on this plan, or a lazy JFDI?
regards
Adam
----- Original Message -----
From: "Adam R. B. Jack" <aj...@trysybase.com>
To: "Gump code and data" <ge...@gump.apache.org>
Sent: Tuesday, April 06, 2004 3:20 PM
Subject: Re: --xdocs
>
> > and then write directly too the tomcat/forrest/docs (or whatever) dir.
> >
> > Don't sync from write dir but write them directly.
>
> The main reason I was so anal about doing a sync was because I'd run a
full
> forrest, and any old invalid xdoc would bring down the whole site
> generation. [It wasn't just that I fell in love w/ Antoine's code. ;-)]
This
> isn't so much of an issue with dynamic pages, as stray flotsom/jetsam
don't
> affect other pages.
>
> That said, even with the new (dynamic) approach I feel there is merit in
the
> sync solution (I feel), and I'd like to explore it...
>
> The pseudo-code (ignoring modules for a mo):
>
> documenter.prepare() [1]
>
> for project in gumpRun.getProjects():
> build(project)
> documenter.documentProject(project) [2]
>
> documenter.documentRun(gumpRun) [3]
>
> The activity:
>
> 1) Copy the template into the log directory (so skins/properties updated.)
> [Copy not Sync]
>
> This is a tad premature (it could lead to a few broken links), but I think
> with a dynamic site no time is ever perfect.
>
> 2) Create the project xdoc pages (but know we are doing this 'early', see
> note.):
>
> .../{module}/{project}.xml
> .../{module}/work/{work1..N}.xml
> .../{module}/images/*.svg (soon I hope :-)
>
> Note -- I would estimate that 90% of the effort is in the ./work directory
> (the build logs).
>
> Note -- project pages sometime refer to other projects, project that have
> not yet been built. (e.g. table of dependees). We ought avoid this when
> doing things 'early', so pass this as a flag to those methods.
>
> BTW: I think it might be time to change this to .../{module}/{project}/ so
> sync is easier.
>
> [Ought we update buildLog.xml page here? I suspect so.]
>
> 3) Redo all of the above -- we'll the pages that might change (e.g. )
>
> 1) generate module/project documentation (now everything is done)
> 2) generate stats & xref information
> 3) generate workspace information
>
> 3.1) is basically recreating index.xml pages (and maybe some pretty
*.svgs)
> not more.
>
> With this, we can have our cake & eat it (IMHO). Using sync we have the
> smallest window of broken links, and the freshest data, cheapest.
>
> BTW: I ought add that generating xdocs is not (IMO) expensive, they zip
> along (especially now they no longer leak). [i.e. It isn't xdoc generation
> that is expensive, it is running forrest on them.]
>
> regards,
>
> Adam
>
> P.S. How many folk think I am over complicating this? ;-) I don't think
so,
> but will listen.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
> For additional commands, e-mail: general-help@gump.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
'Documentation' (was Re: --xdocs)
Posted by "Adam R. B. Jack" <aj...@trysybase.com>.
As I understand the situation it is this:
- The current process for 'documenting a run' is to wait until everything is
over, and then spew everything out to somewhere. This is dissatisfying to
folks who prefer documentation to be more real-time (like logging).
- The use cases are 'script' (to stdout), 'GUI' (to whatever, could
[perhaps] capture something like stdout), and 'WWW site'
(HTML/xdocs/whatever).
- The Forrest solution is painful (especially now) 'cos we can't seem to get
a CVS HEAD version of dynamic working.
- Longer term folks would like a cheetah solution (to allow HTML generation
with or without forrest, based off templates) so there is only less (large)
installation dependency.
BTW: The logging library is an interesting possibility for where to push
real-time output to. Any votes towards using this not stdout?
Anyway, I am going to add 'documentEntity' next to 'documentRun' -- where
documentEntity is 'real-time'. For a 'text' documenter this will allow us to
write to stdout at the same time as some capture file (perhaps). For
'forrest' document this will allow generation of xdocs, including updating
of the buildRun xdoc. If/when GUI is brought back to life, the
'documentEntity' could be some sort of listener mechanism or whatever.
I'll do what I can today.
regards,
Adam
----- Original Message -----
From: "Adam R. B. Jack" <aj...@trysybase.com>
To: "Gump code and data" <ge...@gump.apache.org>
Sent: Tuesday, April 06, 2004 3:20 PM
Subject: Re: --xdocs
>
> > and then write directly too the tomcat/forrest/docs (or whatever) dir.
> >
> > Don't sync from write dir but write them directly.
>
> The main reason I was so anal about doing a sync was because I'd run a
full
> forrest, and any old invalid xdoc would bring down the whole site
> generation. [It wasn't just that I fell in love w/ Antoine's code. ;-)]
This
> isn't so much of an issue with dynamic pages, as stray flotsom/jetsam
don't
> affect other pages.
>
> That said, even with the new (dynamic) approach I feel there is merit in
the
> sync solution (I feel), and I'd like to explore it...
>
> The pseudo-code (ignoring modules for a mo):
>
> documenter.prepare() [1]
>
> for project in gumpRun.getProjects():
> build(project)
> documenter.documentProject(project) [2]
>
> documenter.documentRun(gumpRun) [3]
>
> The activity:
>
> 1) Copy the template into the log directory (so skins/properties updated.)
> [Copy not Sync]
>
> This is a tad premature (it could lead to a few broken links), but I think
> with a dynamic site no time is ever perfect.
>
> 2) Create the project xdoc pages (but know we are doing this 'early', see
> note.):
>
> .../{module}/{project}.xml
> .../{module}/work/{work1..N}.xml
> .../{module}/images/*.svg (soon I hope :-)
>
> Note -- I would estimate that 90% of the effort is in the ./work directory
> (the build logs).
>
> Note -- project pages sometime refer to other projects, project that have
> not yet been built. (e.g. table of dependees). We ought avoid this when
> doing things 'early', so pass this as a flag to those methods.
>
> BTW: I think it might be time to change this to .../{module}/{project}/ so
> sync is easier.
>
> [Ought we update buildLog.xml page here? I suspect so.]
>
> 3) Redo all of the above -- we'll the pages that might change (e.g. )
>
> 1) generate module/project documentation (now everything is done)
> 2) generate stats & xref information
> 3) generate workspace information
>
> 3.1) is basically recreating index.xml pages (and maybe some pretty
*.svgs)
> not more.
>
> With this, we can have our cake & eat it (IMHO). Using sync we have the
> smallest window of broken links, and the freshest data, cheapest.
>
> BTW: I ought add that generating xdocs is not (IMO) expensive, they zip
> along (especially now they no longer leak). [i.e. It isn't xdoc generation
> that is expensive, it is running forrest on them.]
>
> regards,
>
> Adam
>
> P.S. How many folk think I am over complicating this? ;-) I don't think
so,
> but will listen.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
> For additional commands, e-mail: general-help@gump.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
Re: --xdocs
Posted by "Adam R. B. Jack" <aj...@trysybase.com>.
Made some progress towards this today, with a lot of help from Nick. Thanks
Nick.
On Nick's machine forrest is installed as a web application, and having
removed 'src/documentation' from the sub-path (under forrest-work)
"Gump --xdocs" now synchronizes it's forrest-work/contents/... to
${log}/contents/..., which Forrest/Cocoon now servers. For first-cut
implementation simplicity the parent directory (with *.xmap and ./WEB-INF
stuff) is not affected, so a forrest webapp needs to be seeded first.
Next steps are to do this during the run using the 'documentEntity' call
that now occurs during the run.
regards,
Adam
----- Original Message -----
From: "Adam R. B. Jack" <aj...@trysybase.com>
To: "Gump code and data" <ge...@gump.apache.org>
Sent: Tuesday, April 06, 2004 3:20 PM
Subject: Re: --xdocs
>
> > and then write directly too the tomcat/forrest/docs (or whatever) dir.
> >
> > Don't sync from write dir but write them directly.
>
> The main reason I was so anal about doing a sync was because I'd run a
full
> forrest, and any old invalid xdoc would bring down the whole site
> generation. [It wasn't just that I fell in love w/ Antoine's code. ;-)]
This
> isn't so much of an issue with dynamic pages, as stray flotsom/jetsam
don't
> affect other pages.
>
> That said, even with the new (dynamic) approach I feel there is merit in
the
> sync solution (I feel), and I'd like to explore it...
>
> The pseudo-code (ignoring modules for a mo):
>
> documenter.prepare() [1]
>
> for project in gumpRun.getProjects():
> build(project)
> documenter.documentProject(project) [2]
>
> documenter.documentRun(gumpRun) [3]
>
> The activity:
>
> 1) Copy the template into the log directory (so skins/properties updated.)
> [Copy not Sync]
>
> This is a tad premature (it could lead to a few broken links), but I think
> with a dynamic site no time is ever perfect.
>
> 2) Create the project xdoc pages (but know we are doing this 'early', see
> note.):
>
> .../{module}/{project}.xml
> .../{module}/work/{work1..N}.xml
> .../{module}/images/*.svg (soon I hope :-)
>
> Note -- I would estimate that 90% of the effort is in the ./work directory
> (the build logs).
>
> Note -- project pages sometime refer to other projects, project that have
> not yet been built. (e.g. table of dependees). We ought avoid this when
> doing things 'early', so pass this as a flag to those methods.
>
> BTW: I think it might be time to change this to .../{module}/{project}/ so
> sync is easier.
>
> [Ought we update buildLog.xml page here? I suspect so.]
>
> 3) Redo all of the above -- we'll the pages that might change (e.g. )
>
> 1) generate module/project documentation (now everything is done)
> 2) generate stats & xref information
> 3) generate workspace information
>
> 3.1) is basically recreating index.xml pages (and maybe some pretty
*.svgs)
> not more.
>
> With this, we can have our cake & eat it (IMHO). Using sync we have the
> smallest window of broken links, and the freshest data, cheapest.
>
> BTW: I ought add that generating xdocs is not (IMO) expensive, they zip
> along (especially now they no longer leak). [i.e. It isn't xdoc generation
> that is expensive, it is running forrest on them.]
>
> regards,
>
> Adam
>
> P.S. How many folk think I am over complicating this? ;-) I don't think
so,
> but will listen.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
> For additional commands, e-mail: general-help@gump.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
Re: --xdocs
Posted by "Adam R. B. Jack" <aj...@trysybase.com>.
> and then write directly too the tomcat/forrest/docs (or whatever) dir.
>
> Don't sync from write dir but write them directly.
The main reason I was so anal about doing a sync was because I'd run a full
forrest, and any old invalid xdoc would bring down the whole site
generation. [It wasn't just that I fell in love w/ Antoine's code. ;-)] This
isn't so much of an issue with dynamic pages, as stray flotsom/jetsam don't
affect other pages.
That said, even with the new (dynamic) approach I feel there is merit in the
sync solution (I feel), and I'd like to explore it...
The pseudo-code (ignoring modules for a mo):
documenter.prepare() [1]
for project in gumpRun.getProjects():
build(project)
documenter.documentProject(project) [2]
documenter.documentRun(gumpRun) [3]
The activity:
1) Copy the template into the log directory (so skins/properties updated.)
[Copy not Sync]
This is a tad premature (it could lead to a few broken links), but I think
with a dynamic site no time is ever perfect.
2) Create the project xdoc pages (but know we are doing this 'early', see
note.):
.../{module}/{project}.xml
.../{module}/work/{work1..N}.xml
.../{module}/images/*.svg (soon I hope :-)
Note -- I would estimate that 90% of the effort is in the ./work directory
(the build logs).
Note -- project pages sometime refer to other projects, project that have
not yet been built. (e.g. table of dependees). We ought avoid this when
doing things 'early', so pass this as a flag to those methods.
BTW: I think it might be time to change this to .../{module}/{project}/ so
sync is easier.
[Ought we update buildLog.xml page here? I suspect so.]
3) Redo all of the above -- we'll the pages that might change (e.g. )
1) generate module/project documentation (now everything is done)
2) generate stats & xref information
3) generate workspace information
3.1) is basically recreating index.xml pages (and maybe some pretty *.svgs)
not more.
With this, we can have our cake & eat it (IMHO). Using sync we have the
smallest window of broken links, and the freshest data, cheapest.
BTW: I ought add that generating xdocs is not (IMO) expensive, they zip
along (especially now they no longer leak). [i.e. It isn't xdoc generation
that is expensive, it is running forrest on them.]
regards,
Adam
P.S. How many folk think I am over complicating this? ;-) I don't think so,
but will listen.
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
Re: --xdocs
Posted by Stefano Mazzocchi <st...@apache.org>.
Nick Chalko wrote:
> I would do this.
> copy from template
>
> ./src/documentation/skinconf
> ./src/documentation/resources
>
> to the tomcat/forrest/docs
> and then write directly too the tomcat/forrest/docs (or whatever) dir.
>
> Don't sync from write dir but write them directly.
I would just make gump dump the xdocs in a configurable directory.
Forrest dynamic will take care of the rest. SoC.
--
Stefano.
Re: --xdocs
Posted by Nick Chalko <ni...@chalko.com>.
I would do this.
copy from template
./src/documentation/skinconf
./src/documentation/resources
to the tomcat/forrest/docs
and then write directly too the tomcat/forrest/docs (or whatever) dir.
Don't sync from write dir but write them directly.
Adam R. B. Jack wrote:
>Ok, an --xdocs on the commandline makes Gump not run forrest on the xdocs it
>generates into the work directory, but sync's them into the log directory.
>Note, it copies in the template first (which has much of this below) As such
>it creates:
>
> status.xml
> forrest.properties
> forrest-targets.ent (ought this be removed?)
> ./src/documentation
> ./src/documentation/skinconf
> ./src/documentation/content
> ./src/documentation/content/xdocs
>
>it then fills up:
>
> ./src/documentation/content
> ./src/documentation/content/xdocs
>
>Does this seem right for dynamic forrest?
>
>regards,
>
>Adam
>--
>Experience the Unwired Enterprise:
>http://www.sybase.com/unwiredenterprise
>Try Sybase: http://www.try.sybase.com
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
>For additional commands, e-mail: general-help@gump.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
Re: --xdocs
Posted by "Adam R. B. Jack" <aj...@trysybase.com>.
> Curious, are you using templates already or are you still using DOM?
I wish I were that fast, I'd be earning a lot more money. ;) [I almost
started hacking Cheetah, then felt it deserved more Pythonic/Cheetonic
thought than I'd given it. (Hey, I live in America, where they add words to
the English language all the time, and I've picked up the habit. ;-)]
No, I am still writing xdocs one by one (in a DOM-like fashion) I just use
sync to move them over, instead of using forrest to generate a site to
staging, and syncing that. [BTW: I still maintain this isn't a bad way of
doing things. We can compare end results when we have two.]
So with --xdocs we have:
i.e. write xdocs to $xdocs and then
sync $work -> $log
instead of :
write xdocs to $xdocs and then
forrest $work -> $staging and then
sync $staging -> $log.
That said, I am working with Nicola to create a Template approach that will
generate HTML (via Cheetah), making Forrest optional.
BTW: Also, this is still at the end of the run, not sooner. That is a future
step.
regards,
Adam
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org
Re: --xdocs
Posted by Stefano Mazzocchi <st...@apache.org>.
Adam R. B. Jack wrote:
> Ok, an --xdocs on the commandline makes Gump not run forrest on the xdocs it
> generates into the work directory, but sync's them into the log directory.
> Note, it copies in the template first (which has much of this below) As such
> it creates:
>
> status.xml
> forrest.properties
> forrest-targets.ent (ought this be removed?)
> ./src/documentation
> ./src/documentation/skinconf
> ./src/documentation/content
> ./src/documentation/content/xdocs
>
> it then fills up:
>
> ./src/documentation/content
> ./src/documentation/content/xdocs
>
> Does this seem right for dynamic forrest?
Yes.
Curious, are you using templates already or are you still using DOM?
--
Stefano.