avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject RE: [Fwd: Re: Xdocs Standards]
Date Sun, 21 Jul 2002 16:14:52 GMT
Marc,

this clarified a lot. Basically I was worried about how to express
'ordering' of content, and it is only now I get that your idea here is
to express the ordering by having a filename specification.

Just looking at the main avalon page:

About
	Overview
	Features
	Getting Started
	Download Binaries
	Download Source
	Case Studies
	License
	Contributors
Sub-Projects
	Framework
	Excalibur
	Phoenix
	Cornerstone
	Applications
	LogKit
Guides
	Avalon for Beginners
	Developing with Avalon
	Developing with Phoenix
	Developing with Logkit
For Developers
	Coding standards
	CVS
	Mailing Lists

you'd express this as

about/
	1.Overview.xml
	2.Features.xml
	3.Getting-Started.xml
	4.Download-Binaries.xml
	5.Download-Source.xml
	6.Case-Studies.xml
	7.License.xml
	8.Contributors.xml
	9.FAQ.xml
Sub--Projects/
	1.Framework.xml
	2.Excalibur.xml
	3.Phoenix.xml
	...
Guides/
	menu.xml
For-Developers/
	menu.xml

with:
1.Overview.xml = some document-v11.dtd doc
9.FAQ.xml:
	<item name="FAQ" ref="faq/"/>
9.Framework.xml:
	<item	name="Framework"
		external="http://jakarta.apache.org/avalon/framework"/>
Guides/menu.xml
	<menu>
		<item	name="Developing with Avalon"
			include="developing/"/>
		<item	name="Avalon for Beginners"
	external="http://jakarta.apache.org/avalon/excalibur/tweety/beginners.xml"/>
	</menu>

etc etc.

that the idea?

I like =)

> > > Current libre incarnation should be seen as first prototype to get
> > > thoughts going, too bad it (the quircks in there?) has been doing the
> > > opposite...
> >
> > =)
> >
> > Which is why we shouldn't use it; using a 0.1 version of a product to
> > support a 4.1 version of a product is, well, not very smart.
> >
> 
> agree on not using it right now, but there could be a functional release
> soon
> if more discussions like this finally help discover the real use case
> it could be there before you know :-)
> 
> disagree on measuring intelligence ('smartness') in difference of version
> numbers

true. Avalon 2 was not for anyone to use, whereas mozilla 0.8 was
already way better than any other browser on the planet. Just I figured
from the docs that forrest is pretty much alpha.

> - and be honnest, the way I know avalon you could agree that the
> documentation project in there is not realy as 4.1 as the java code (or is
> that too blunt?)

true =)

> - otherwise: libre is nothing in size to be compared to avalon, this is just
> like a small component
>  (to compare avalon is not becoming less 4.1 when I use a fresh 0.1
> component from e.g. xmlBundle or
>   something, right?)

true =)

> it would be *smart* to start using something that gets your job done in a
> proven and reliable way
> I understand that that is book.xml for you now, if that could be libre in
> some months, I'll be glad to call it 4.1 to make you feel good :-)

:P

we've got two weeks to get something working (one of our developers has
set a fair 'deadline'; see it as a challenge =); otherwise we'll likely
use anakia for the next 6 months or so....

> maybe we offer too much of detail configuration level to the end user
> ==what you (or an other) described earlier in the list as 'like a
> programming language'

hmm. If you can auto-generate a complex file using a simple 'wizard',
then get all the power the complex file offers during tweaking, that is
nice. Nicola's got some ideas on this for centipede floating around.

> > The thing with FAQs: they grow. You usually need to group them according
> > to some order that cannot be machine-expressed. Ie the question "what is
> > avalon?" needs to be question number one in category number one.
> >
> then call it 01.01.what_is_avalon.faq.xml, and let libre use regexes on the
> filenames to get out what you want

gotcha.

> so we think that there could be a contract (== choosen libre-strategy) that
> the MR can put down and communicate to the CR.
> That could be e.g. for the faq
> - (if you don't like xpath) use a naming convention for the files so they
> start with 3 digits that make up the sequence order in which you want them
> to show up, followed by the question that needs to show in the menu, follwed
> by some .faq.xml suffix
> 
> - (or if you dislike those ugly filenames) the strategy could be such that
> menu-items are
> 
> - (or if you think xpath is cool) the strategy could be that the actual
> content of the faq does sepcify its order.

If you ask me, you should start with just a single strategy (probably
book.xml as most potential users already use it or something similar),
then implement more of those when it all works.

Then again, I'm starting to like the express-more-in-filenames idea more
and more as I think about it...

> > > some fast information:
> > > - one of the already expressed feelings was that at least libre
> > >   should do what book.xml is doing (not the case now)
> >
> > +1
> >
> 
> yep, just too foole quys like you to eventually use it anyway :-)
> actually the only thing we're missing now is the external links of book.xml,
> the rest is there

we need those =)

> > IOW, for the best site you need to do manual intervention in 99% of
> > cases. You don't want a menu sorted alphabetically, you want it sorted
> > according to some <XXX> human-interpreted sorting algorithm.
> 
> from now called 'the strategy' :-) offering a set of rules
> the human can more easily stear the sorting then to edit the book.xml

once again, start simple. Most cocoon guys I know have the general
tendency to implement everything at once. Might be their one flaw =)

> > I'm sceptical as to automating this.
> >
> 
> I'm getting to repeat myself... but I basically agree.
> It's not as much about automating as it is about more conveniently
> expressing.

we're definately on the same page. It's just the tone of the forrest
website suffers from the same problems as the avalon one: way too
technical without getting enough examples, context, and general idea
first.

> this sounds like Nicola could give me a head start on understanding
> everything that is going on?
> (hey wait, centipede, isn't that 0.1 :-) )

=)

I understand Nicola is active on forrest, which is why I mentioned the
project files. Integration with ant is instant added value; as is
integration with forrest.

> this is what forrest tries to become of course...
> I read in this thread that (you?) there were good vibes about the dtd's
> coming from forrest (it's docuheads over there off course, they know what
> they are doing), I think there will be more to like in the future (are the
> dtd's the only thing you use?)

the thing I want most. Doc tools change, DTDs should stay the same.

> only it is a different group/project so it
> will not always follow the dynamics your team is dealing with.
> (maybe forrest-dev should think about some sort of stewardship towards
> supporting the project teams that want to start on it, that said, it
> wouldn't be bad for the doc-lead inside your project to start biassing the
> forrest-dev :-))

uhuh. We've got Nicola =)

> > then take a look at all 'src/xdocs' directories you can find
> > in our various CVSes, and see how that transforms into the site.
> 
> jakarta-avalon module is the root that offers them all, right?

yep, but when stuff works I'll move the 'root' to avalon-site.


> no thanks, I think libre has some ideas at the basis to realize much of your
> visions
> (but obviously has not been doing a good job in making that clear to
> everyone)
> the forrest move around it facilitates even more, and it's only by working
> together
> with actual project teams that all of it will eventually get used :-)
> 
> there will obviously be more time and patience to be expected from both
> sides as we go allong :-)

yup. I look forward to having a neat system to use; problem is ours has
been broken there is not so much patience left. But don't let that rush
you into bad releases though =)

cheers,

- Leo



--
To unsubscribe, e-mail:   <mailto:avalon-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-dev-help@jakarta.apache.org>


Mime
View raw message