You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by David Crossley <cr...@indexgeo.com.au> on 2002/03/12 01:45:11 UTC
Forrest needs xdocs ASAP for direction
Konstantin wrote:
> > > So, the next questions are (after co from CVS):
> > > Where do I start? Is there any ToDo list or description of
> > > goals/tasks?
> >
> > Not really, use these as starters:
> >
> > http://marc.theaimsgroup.com/?t=101441112100004&r=1&w=2
> > http://marc.theaimsgroup.com/?t=101465347800003&r=1&w=2
> > http://marc.theaimsgroup.com/?t=101431907500006&r=1&w=2
>
> Thanks once again.
> I've found also project-info.xml in xml-forrest root with a brief
> description. What about of using it instead of index.xml?
These are all just placeholder documents to get the project
started. Now that things are moving, we need to have some
decent overview of the project. I find that we are all getting lost,
and we certainly do not want to scare away any newcomers.
So we definitely need some clear statement of direction.
There is the initial README document, and there is the
discussion in the three threads that Steven declares above.
As with most Open Source projects, the ideas seem to stay
in the mail list archives. We must get it out into the open.
I am busy with some paid work at the moment. When i return
then, if the job is not started, i will try to extract some stuff
and put it into xdocs. I reckon that we need a very concise
index.xml and then an overview.xml to provide detail for the
vision.
-- David
Re: Forrest needs xdocs ASAP for direction
Posted by Gianugo Rabellino <gi...@apache.org>.
Piroumian, Konstantin wrote:
>>Another thing is to use the Generator that Gianugo made that uses xpath to
>>make it possible to remove all book.xml files.
>
> Do you mean XMLDB generator? I'll take a look at it, never used it before.
> Do you think that xdocs contain enough data to be used for menu generation?
> I'll take a look at it too.
No, I think he was thinking about the (it's in scratchpad)
XPathDirectoryGenerator, which basically allows you to run an XPath
query on a set of documents.
However, Stefano is right pointing out the issue of automatic vs. manual
descriptors. I'm a bit biased towards the automatic solution, but it's
true that manual work tends to be more accurate (hmmm... stone in the
lake: how about a namespaced "book.xml" fragment in every document?).
Ciao,
--
Gianugo Rabellino
Re: Forrest needs xdocs ASAP for direction
Posted by Gianugo Rabellino <gi...@apache.org>.
Steven Noels wrote:
>
> As far as Gianugo's Generator is concerned, I'm lost: I can't find it
> anymore.
Uh?
http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/src/scratchpad/src/org/apache/cocoon/generation/XPathDirectoryGenerator.java
Ciao,
--
Gianugo
RE: Forrest needs xdocs ASAP for direction
Posted by Steven Noels <st...@outerthought.org>.
> "Piroumian, Konstantin" wrote:
> >
> >
> > Wow! I haven't seen that one. Looks cool. (Just was going
> to write that
> > current index.htm is like a teenager's Home page ;))
Hey, I'm 30 years old and a father of 2 (almost 3) kids :-)
That was only meant as a placeholder, for sure.
Stefano wrote:
> > > Another thing is to use the Generator that Gianugo made
> that uses xpath to
> > > make it possible to remove all book.xml files.
>
> I would like to talk more about this. We have to decide
> whether we want
> implicity or explicit documentation descriptors.
Hm. Good point.
As for our own site, we have a little commandline directory traverser
which is comparable to the DirectoryGenerator but does an extra XSLT
transformation on each XML document which extracts the document
title/label and puts that in an XML tree document. Nothing which can't
be done using the default DirectoryGenerator and a stylesheet using the
dreaded document() function. We use the same global XML tree to
automatically add a 'yahoo-path' (global-path in Konstantin's proposed
home.xml) to each aggregated document, and a ToC where the current
document is highlighted.
As far as Gianugo's Generator is concerned, I'm lost: I can't find it
anymore.
I also would like to remove the book.xml files, but how will be keep
track of sequence? Using something like a DirectoryTraverser, we lose
the notion of document order, since we can only sort them using some
file attribute. Using a book.xml-like mechanism, we can sort the
documents in any order we want (manually, alas).
One idea we had was having an site-index.xml document inside each
directory, listing the documents inside that directory that should be
put in a specific order, the rest of them would be appended to that list
alfabetically. For the entire site ToC, we then only needed to aggregate
all site-index.xml docs into one large document. Dunnow if this would be
good practice.
> > Do you mean XMLDB generator? I'll take a look at it, never
> used it before.
> > Do you think that xdocs contain enough data to be used for
> menu generation?
> > I'll take a look at it too.
They should, centralizing this is bound to cause problems in terms of
maintainability.
Why not add an extra attribute 'label' to the xdocs document element?
On a side note: shouldn't we decide what to do with the title attribute
for sections... I'd really like to change that into a title element,
instead, if only to be able to use some cosmetical elements child
elements inside when necessary (I sometimes include <code> fragments
inside my kind of <title> elements).
> > Are we using document-v11 format for docs? I've seen a
> DocBook proposal.
>
> I think there is consensus around here to use Document_v1.1 as the
> markup and augment it as necessary, but with *great* caution.
Yep - we already went through the obligatory Docbook vs xdocs
discussion. Let's KISS.
</Steven>
Re: Forrest needs xdocs ASAP for direction
Posted by Stefano Mazzocchi <st...@apache.org>.
"Piroumian, Konstantin" wrote:
>
> >
> > Konstantin , what can be done now is to take the html mockup and make it
> as
> > a skin for the docs generation.
>
> Wow! I haven't seen that one. Looks cool. (Just was going to write that
> current index.htm is like a teenager's Home page ;))
>
> That is the right place to start with. Who is the author of the layout?
I am, I resurrected my past of graphic designer :)
> > Another thing is to use the Generator that Gianugo made that uses xpath to
> > make it possible to remove all book.xml files.
I would like to talk more about this. We have to decide whether we want
implicity or explicit documentation descriptors.
> Do you mean XMLDB generator? I'll take a look at it, never used it before.
> Do you think that xdocs contain enough data to be used for menu generation?
> I'll take a look at it too.
>
> Are we using document-v11 format for docs? I've seen a DocBook proposal.
I think there is consensus around here to use Document_v1.1 as the
markup and augment it as necessary, but with *great* caution.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Re: Forrest needs xdocs ASAP for direction
Posted by "Piroumian, Konstantin" <KP...@flagship.ru>.
>
> Konstantin , what can be done now is to take the html mockup and make it
as
> a skin for the docs generation.
Wow! I haven't seen that one. Looks cool. (Just was going to write that
current index.htm is like a teenager's Home page ;))
That is the right place to start with. Who is the author of the layout?
> Another thing is to use the Generator that Gianugo made that uses xpath to
> make it possible to remove all book.xml files.
Do you mean XMLDB generator? I'll take a look at it, never used it before.
Do you think that xdocs contain enough data to be used for menu generation?
I'll take a look at it too.
Are we using document-v11 format for docs? I've seen a DocBook proposal.
> Then, we need a look at how to structure aggregation to generate the docs.
>
> So, basically we need to get the docs up with these points.
> I'm busy with Cocoon+POI for now, so it seems that you found a job! ;-P
If I hadn't one already that is hardly Cocoon related... ;)
> I'm sure that with your knowledge of Cocoon, you can come up with good
> stuff.
Not sure about my knowledge of Cocoon, I didn't use it for real projects for
a very long time, but I will do my best.
>
> Just one tip: don't modify anything in ./tools; the build targets are
under
> ./src/targets/project.xtarget.
Ok. Having readonly access I can't modify anything without permission ;)
Regards,
Konstantin.
>
> :-)
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
>
Re: Forrest needs xdocs ASAP for direction
Posted by Nicola Ken Barozzi <ni...@apache.org>.
From: "David Crossley" <cr...@indexgeo.com.au>
> Konstantin wrote:
> > > > So, the next questions are (after co from CVS):
> > > > Where do I start? Is there any ToDo list or description of
> > > > goals/tasks?
> > >
> > > Not really, use these as starters:
> > >
> > > http://marc.theaimsgroup.com/?t=101441112100004&r=1&w=2
> > > http://marc.theaimsgroup.com/?t=101465347800003&r=1&w=2
> > > http://marc.theaimsgroup.com/?t=101431907500006&r=1&w=2
> >
> > Thanks once again.
> > I've found also project-info.xml in xml-forrest root with a brief
> > description. What about of using it instead of index.xml?
>
> These are all just placeholder documents to get the project
> started. Now that things are moving, we need to have some
> decent overview of the project. I find that we are all getting lost,
> and we certainly do not want to scare away any newcomers.
Konstantin , what can be done now is to take the html mockup and make it as
a skin for the docs generation.
Another thing is to use the Generator that Gianugo made that uses xpath to
make it possible to remove all book.xml files.
Then, we need a look at how to structure aggregation to generate the docs.
So, basically we need to get the docs up with these points.
I'm busy with Cocoon+POI for now, so it seems that you found a job! ;-P
I'm sure that with your knowledge of Cocoon, you can come up with good
stuff.
Just one tip: don't modify anything in ./tools; the build targets are under
./src/targets/project.xtarget.
:-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------