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" <[EMAIL PROTECTED]>
To: "Gump code and data" <[EMAIL PROTECTED]>
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: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
