gump-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Adam R. B. Jack" <>
Subject Re: --xdocs
Date Thu, 22 Apr 2004 21:25:53 GMT
Made some progress towards this today, with a lot of help from Nick. Thanks

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.


----- Original Message ----- 
From: "Adam R. B. Jack" <>
To: "Gump code and data" <>
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
> 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. ;-)]
> isn't so much of an issue with dynamic pages, as stray flotsom/jetsam
> affect other pages.
> That said, even with the new (dynamic) approach I feel there is merit in
> 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
> 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
> but will listen.
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message