gump-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Adam R. B. Jack" <aj...@trysybase.com>
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
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" <ajack@trysybase.com>
To: "Gump code and data" <general@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


Mime
View raw message