You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Nicola Ken Barozzi <ni...@apache.org> on 2002/07/19 20:46:23 UTC
[Fwd: Re: Xdocs Standards]
-------- Original Message --------
Subject: Re: Xdocs Standards
Date: 19 Jul 2002 20:43:03 +0200
From: Leo Simons <le...@apache.org>
Reply-To: "Avalon Developers List" <av...@jakarta.apache.org>
To: Avalon Development <av...@jakarta.apache.org>
References: <00...@Gabriel>
<3D...@apache.org>
> > Libre markup is ugly. Is it automagically generated? The project.xml
> > format is fine for that purpose.
>
> Then join forrest-dev@xml.apache.org .
> Libre generates stuff automatically as part of the gen process, so that
> it can enhance book.xml-like stuff.
>
> In which way "Libre markup is ugly"?
There is semantic content (menu order and structure) to express about
the menu which is very natural to do in book.xml, while the way I
understand it in libre this is a chore.
Book.xml is just about as easy as it gets for writing a menu xml file, I
think.
- Leo
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
RE: [Fwd: Re: Xdocs Standards]
Posted by Leo Simons <le...@apache.org>.
> > 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.
> >
> or by having xpath lookups ;-)
> (the or is exclusive at your own coice)
>
> in every case ordering based on xpath would be mostly not a good idea
> better use :
> - labeling: getting the caption for the menu from the file itself (more
> expressive then the filename often: eg for faq the full question)
> - filtering based on e.g. an attribute value priority="high" etc etc
>
> (you'll even start to love xpath when we're done :-))
Truth be told I know quite a bit about xpath. It's just that its syntax
can get so horridly complex...it needs to be optional.
> > 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....
> >
>
> I don't know anakia, and can't expect you to dislike it as a solution
anakia is coupling xml with velocity. It is neat in concept =)
> I'll do a serious effort the coming week is the only thing I can say
cool.
> If you can still evaluate then ?
the 'two week deadline' is not solid as a rock =) This is still OSS dev,
which is supposed to be somewhat fun at times...that deadline would be
two weeks from last friday or somethin'. I just find having deadlines
means stuff gets done...or you'll know when to abandon something when
you miss it by a month.
> Also, I'll be asking stupid questions to get around faster, so bear with me
> please...
no prob =)
> > once again, start simple. Most cocoon guys I know have the general
> > tendency to implement everything at once. Might be their one flaw =)
>
> there must be more wrong with them ;-)
sssht! (they're listening...)
> > 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.
>
> hey, blame yourself, you're in a 4.1 release, we're just starting 0.1,
> remember ;-)
we do blame ourselves, all the time =)
It's just most of avalon is best explained in a computer science master
class tone, and it is hard for some of us not to..............
> > 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.
>
> I don't get this fully yet, but someone just told me I shouldn't try doing
> all at once :-)
hmm. Basically everyone uses and loves ant, so if there is a jar file
you can drop into your ant ext directory and then you have an
easy-to-use <forrest/> task, that is neat. However, if forrest is
worthy, someone will no doubt contribute that task...
> > the thing I want most. Doc tools change, DTDs should stay the same.
>
> question was: are you using the forrest (cocoonbased) generation process?
> or are you using ant and <style> instead?
part of our site is cocoon (framework, excalibur, apps), while other
parts (logkit, phoenix) use anakia (the <anakia/> task). We used to be
completely cocoon but parts were converted to anakia because our
cocoon-based setup was broken (and slow when it did work). Some of us
are now going to put in time (though none of us ever has any =) to get
the cocoon-based setup work. When that fails it is likely we will
convert everything to anakia.
Either way, we will probably convert to the forrest DTDs.
> > 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 =)
>
> patience is a virtue, as is working hard I guess... so if it comes from both
> sides we'll get there
I don't doubt it. Just a matter of time, it is.
> and euh, we already had one bad release :-)
> this time it feels like I could have a *user* which will (no doubt) make it
> infinitaly better
I will not dig into development then =)
If you get everyone on the avalon-dev to be happy about forrest, you're
going to get loads of users. Avalon is one of the big projects around
here, documentation-wise.
> regards, and be ready for some dull questions flying around tomorrow
=) Keeps me from actual work, so its welcome...
cheers,
- Leo
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: [Fwd: Re: Xdocs Standards]
Posted by Marc Portier <mp...@outerthought.org>.
Leo,
> 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.
>
or by having xpath lookups ;-)
(the or is exclusive at your own coice)
in every case ordering based on xpath would be mostly not a good idea
better use :
- labeling: getting the caption for the menu from the file itself (more
expressive then the filename often: eg for faq the full question)
- filtering based on e.g. an attribute value priority="high" etc etc
(you'll even start to love xpath when we're done :-))
> 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
>
I would probably express it a bit more future safe:
3 digit prefixes, and not using the full sequence right on
010.overview
020.nextone
etc etc
> 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/beginn
> ers.xml"/>
> </menu>
>
> etc etc.
>
> that the idea?
>
> I like =)
>
anything to please you chap :-)
<snip subject="version numbers" />
>
> 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....
>
I don't know anakia, and can't expect you to dislike it as a solution
I'll do a serious effort the coming week is the only thing I can say
If you can still evaluate then ?
Also, I'll be asking stupid questions to get around faster, so bear with me
please...
> > 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.
we can fix that later, I guess
>
> > > 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.
>
book.xml is the null-strategy, the actual ones kick in when you start using
<auto>
> Then again, I'm starting to like the express-more-in-filenames idea more
> and more as I think about it...
>
Like any contract it can get dangerous, but if we pull it off for the
complexity of avalon I think we have a major case.
> > > > 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 =)
>
you'll get it, the strategies are harder, believe me
> > > 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 =)
>
there must be more wrong with them ;-)
> > > 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.
>
hey, blame yourself, you're in a 4.1 release, we're just starting 0.1,
remember ;-)
> > 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.
>
I don't get this fully yet, but someone just told me I shouldn't try doing
all at once :-)
> > 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.
>
question was: are you using the forrest (cocoonbased) generation process?
or are you using ant and <style> instead?
> > 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 =)
he's everywhere if you ask me :-)
>
> > > 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 =)
>
patience is a virtue, as is working hard I guess... so if it comes from both
sides we'll get there
and euh, we already had one bad release :-)
this time it feels like I could have a *user* which will (no doubt) make it
infinitaly better
regards, and be ready for some dull questions flying around tomorrow
-marc=
> cheers,
>
> - Leo
>
>
>
> --
> To unsubscribe, e-mail:
<ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: [Fwd: Re: Xdocs Standards]
Posted by Leo Simons <le...@apache.org>.
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: [Fwd: Re: Xdocs Standards]
Posted by Marc Portier <mp...@outerthought.org>.
yo there,
> hi! Just gonna throw thoughts at ya...
this is me in catch-mode:
>
> > 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
- libre is in fact not even 0.1 ( rather 0.0 alfa :-))
- there is more crap out there that depicts version numbers as years
counting since the birth of christ
- 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?)
- 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?)
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 :-)
> > We are currently rethinking the libre.xml on the forrest-dev mailinglist
> > http://marc.theaimsgroup.com/?l=forrest-dev&w=2&r=1&s=%5Blibre%5D&q=b
> > (look for the msgs since June 11 with [libre] in the subj.
> > basically we're trying to find the use cases that reveal some of the
> > book.xml nags... so we can find the right syntax and ways of working
> > around them.)
>
> just read up on that. Some good ideas. Especially the one about the
> auto-faq management. One note:
>
thanx
> <libre>
> <entry location="20020713.01.important_howtolibre.xml">
> <label>
> <xpath expression="//question/text()" />
> </label>
> <href>
> <property name="path" />
> </href>
> </entry>
> <!-- more entries to be made here -->
> <auto> <!-- don't filter and just do alphabetic sorting -->
> <label>
> <xpath expression="//question/text()" />
> </label>
> <href>
> <property name="path" />
> </href> </auto>
> </libre>
>
> I, as a FAQ maintainer, do not want to have to deal with xpath
> expressions! This sort of thing really must not change often, or it'll
> hurt (or it should be auto-generated).
>
As I said earlier: the libre.xml normally should be set up once
unless you use it like a book.xml of course :-)
however you do make me think about levels of usage here...
maybe it would be nicer for libre.xml to express it's usage in more high
level terms
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'
hmmm, I'm now thinking about offering access to what libre does in terms of
a predefined 'strategy'
that you could then pick from a list rather then need to express completely
by hand & inline
> 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
point is it will _have_ to be machine expressed...
I mean: either way you have to tell the machine in which order they need to
come up in the menu,
prooving my point: you do this with book.xml (and feeling happy about it)
the point is separation of concerns, right... in the documentation scheme
there is one role (MR) deciding on the menu (==editing book.xml now) and you
have one role (CR) providing the content (==writing up the actual faq using
some DTD)
if you like MR is the one expressing to the machine what the order is going
to be.
[sidenote: while it's a good thing the responsabilities are separated the
reality is often that CR and MR are played by one and the same person]
now only: in a book.xml solution the MR has to hook up the work of the CR
(always)
(reminding me of the old days were doing web apps required the developer to
cut and paste HTML design in some servlet after there was a new look and
feel, even if there were no changes to the actual business logic, we all now
this story, I really feel it's the same)
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.
in all cases the MR has done his work in advance, the CR knows the rules,
creates the faq, applies the DTD's, gives the file a good name, puts in the
dir... job done, no MR to wake up.
you could look at it as rules that pick up metadata from file system and
file content pretty much as you would otherwise use somehting like webdav,
or some other database or document repository to add properties to the
collections and items...
PLUS the generator that will automatically pick up and use this metadata to
produce a sorted and filtered menu-structure
> It needs to be trivial to specify this order. I can't think of a way to
> express it inside the FAQ snippets (maybe with 'next' and 'previous',
> but it is usually easier for authors to modify a hierarchy than specify
> a list by linking).
definately, lesser document management actions is our concern, linking up
lists would do some of the opposite
>
> Thus you end up with something like:
>
> <faq>
> <group name="Common questions">
> <item href="whatis.xml"/>
> <item href="whatisnot.xml"/>
> </group>
> <group name="Avalon Phoenix questions">
> <item href="whatis.xml"/>
> <item href="whatisnot.xml"/>
> </group>
> </faq>
>
> ie remarkably similar to book.xml.
>
yep, but they grow... and you get loads of docs, and you get a big list, and
you edit it each time there is one to add
instead of writing down the <item>s we think about a
<group name="...">
<item-list-by-strategy strategy="someid">
</group>
which is far from the current syntax, but is something I start liking more
and more
the thing is now the 'strategy' is expressed inline, and that is obviously
scaring off people
> > I would greately appreciate if you (all) could find the time to
> > formulate how you 'ld like it better for your purpose(s)
>
> no prob. Thanks for taking time early on to talk to us!
>
one of those days I guess, family out on the beach, 21 degrees Celsius, cool
sea wather
you could say I had no other plans :-)
> > 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
> > - in surplus it should allow not to need to write all
> > the book.xml files at each level
>
> +1, but not that important for me (I usually do
> `$MY_EDITOR $(find -name 'book.xml'` which works perfectly well).
>
there is more add-to's expressed on forrest dev, but less relevant for this
discussion
> > - by becoming a combination of syntax-file and interpreting
> > code (currently generator, for next version I think about
> > a source implementation rather) I think it will be
> > more self-contained then the book.xml with xpathdirgen
> > combined
>
> above my hat. Any talk of xpath means you'll loose user immediately.
the docuheads at forrest-dev seem to like it :-)
but I guess bundling it up into more human sensible 'strategy' they can pick
from would be nice
>
> > I agree with your comment about the current syntax.
> > It's not machine generated, but it has been
> > hitsorically shaped we're only looking at the first
> > refactoring, so yes there is change needed (and
> > some of it expressed in
> > http://www.krysalis.org/forrest/libre-intro.html.
> > the good news is you can influence that.
>
> =)
>
> > And while the 'chore' argument may hold for now it's
> > our goal to get that out of the way soon...
> > Point is with libre you'll need to think about a
> > maintenance strategy for any directory (and it's subs)
> > in terms of which xml will be in there, which filenames
> > to use etc etc... so afterwards you can just dump the
> > xml and the subdirs in there... the libre.xml is created
> > at the start and once, while the book.xml needs manual
> > intervention for each new doc (that's the filosophy)
>
> got it.
>
> Thing is, everytime you add a new item to the menu of your site, you
> should think about where it should be placed, how your menu structure
> might need to be reorganized etc etc.
>
think yes, but of some upfront thought was done, expressing that hookup
could be done differently then open up another editor and edit book.xml (see
above)
> 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
>
> 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.
> A syntax of
>
> <menulist project="avalon">
> <item href="index.xml"/>
> <item href="features.xml"/>
> <item href="blah.xml"/>
>
> <menu name="avalon framework">
> <menu name="essentials">
>
> <item href="bla.xml"/>
> <item href="bla2.xml"/>
>
> <menu name="Patterns">
> <item href="bla.xml"/>
> <item href="bla2.xml"/>
> </menu>
>
> <menu name="COP">
> <item href="bla.xml"/>
> <item href="bla2.xml"/>
> </menu>
> </menu>
> <menu name="guide">
> <item href="bla.xml"/>
> <item href="bla2.xml"/>
> </menu>
> <menu name="reference">
> <item href="bla.xml"/>
> <item href="bla2.xml"/>
> </menu>
> <menu name="project-info" type="auto-generated" />
> </menu>
>
> <menu name="avalon excalibur">
> <item href="bla.xml"/>
> <item href="bla2.xml"/>
>
> <menu name="project-info" type="auto-generated" />
> </menu>
>
> <menu><!-- determine name from bla.xml -->
> <item href="bla.xml"/>
> <item href="bla2.xml"/>
>
> <menu name="project-info" type="auto-generated" />
> </menu>
> <menu type="faq" base="faq/">
> <menu name="Basic Questions" base="basic" />
> <menu name="Difficult Questions" base="difficult" />
> </menu>
> </menulist>
>
> is nice. Essentially consolidate many book.xml documents into one.
> However, with avalon it's not, mostly. All our subprojects split into
> different CVSes, and often split into smaller modules at that.
>
yep...
the libre.xml also works on each separate level
only, if you fall into a level
- by using some selected <auto> strategy
- and on that level there is no libre.xml
then it just continuous by inheriting the strategy of the parent level
> They're maintained by different people. For example, the module 'tweety'
> inside Avalon Excalibur
> (http://jakarta.apache.org/avalon/excalibur/tweety/) is something me and
> Nicola wrote. Berin Loritsch wrote "Developing with Avalon"
> (http://jakarta.apache.org/avalon/developing/index.html) and has nothing
> to do with Tweety. He should not be bothered with the menu structure for
> tweety.
>
with libre
the tweety guys could choose to inherit the ordering-strategy applicable for
avalon
or provide a libre.xml on their own level to override that
> So what we need is a some file for expressing hierarchical information
> about a menu, and a way to tie in those menus together. What I really
> would like is:
>
> jakarta-avalon/src/xdocs/menu.xml
>
> <menu>
> <item href="overview.xml"/>
> <item href="features.xml"/>
>
> <menu include="framework/" level="1"/>
> <menu include="developing/"/>
> </menu>
>
> jakarta-avalon/src/xdocs/developing/menu.xml
>
> <menu>
> <item href="overview.xml"/>
> <item href="features.xml"/>
> </menu>
>
> jakarta-avalon/src/xdocs/framework/menu.xml
>
> <menu>
> <item href="overview.xml"/>
> <item href="features.xml"/>
>
> <menu include="patterns/" level="2"/>
> <menu include="cop/" level="2"/>
> </menu>
>
> jakarta-avalon/src/xdocs/framework/patterns/menu.xml
>
> <menu>
> <!-- this file is not inlined into inside xdocs/menu.xml,
> as that file
> declares one level of inlining. -->
> <item href="overview.xml"/>
> <item href="features.xml"/>
>
> <menu include="soc/" level="1"/>
> <menu include="cop/" level="1"/>
> </menu>
>
> jakarta-avalon/src/xdocs/framework/patterns/soc/menu.xml
>
> <menu>
> <!-- this file is inlined into inside
> xdocs/framework/menu.xml, as that
> file declares two levels of inlining. -->
> <item href="overview.xml"/>
> <item href="features.xml"/>
> </menu>
>
> jakarta-avalon/src/xdocs/framework/patterns/cop/menu.xml does not exist,
> it is autogenerated based on directory contents.
>
>
> jakarta-avalon/src/xdocs/framework/cop/menu.xml
>
> <menu>
> <!-- this file is not inlined into inside xdocs/menu.xml,
> as that file
> declares one level of inlining. -->
> <item href="overview.xml"/>
> <item href="features.xml"/>
> </menu>
>
part from the <menu> tag this looks rather libre :-)
at those places where you would dare to 'let it all go Neo' you would use
libre's <auto> and nested you'ld specify a strategy (or pick one from the
list... still thinking about that)
> the support for different 'levels' is something that could be added at a
> later date (the current l&f doesn't allow for it anyway). Basically this
> setup says: for each submenu, there's a separate directory. In that
> directory may be another menu.xml file, or if it isn't there it is
> auto-generated using some setting (ie alpabetic sorting).
>
yep, all with you, specially since it is how libre works now :-)
> The next step is to have a project files something like so:
>
not into project.xml files yet...
although it does make me think about what we try to do @forrest for remote
building
> jakarta-avalon-site/project.xml
>
> <project>
> <menu
> base="../jakarta-avalon/src/xdocs"
> output="../jakarta-avalon/build/docs" />
> <project file="../jakarta-avalon-excalibur/site/project/xml" />
> <menu
> base="../jakarta-avalon-apps/site/src/xdocs"
> output="../jakarta-avalon-apps/site/build/docs" />
> <menu
> base="../jakarta-avalon-cornerstone/src/xdocs"
> output="../jakarta-avalon-cornerstone/build/docs" />
> <menu
> base="../jakarta-avalon-phoenix/src/xdocs"
> output="../jakarta-avalon-phoenix/build/docs" />
> </project>
>
> jakarta-avalon-excalibur/site/project.xml
>
> <project>
> <menu name="containers">
> <menu
> base="../assembly/src/xdocs"
> output="../assembly/build/docs" />
> <menu
> base="../component/src/xdocs"
> output="../component/build/docs" />
> </menu>
> <menu name="stuff">
> <menu
> base="../configuration/src/xdocs"
> output="../configuration/build/docs" />
> </menu>
> </project>
>
> where centipede feeds the relevant parts into forrest and all your docs
> are generated.
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 :-) )
>
> > -marc=
> > PS: I'll be happy to read in the avalon-dev archive to
> > understand your use cases (could you give some pointers
> > (subject lines and keywords) on related discussions?)
>
> hmm. Our use case is all but completely the same as that of every other
> software project, I guess. Forgetting all I wrote above and going back
> to the basics
>
> - we need to write docs (in xml using document-v11.dtd)
> - we need to write a FAQ (in xml)
> - we need a 'interesting threads' sort of page where we can link to
> mailing list archive threads (in xml)
> - we need project information (mailing list, cvs repo, code conventions,
> the stuff maven generates for you) (as little maintaince as possible)
> - we need online javadoc (from source)
> - we need online javasrc (from source)
> - we need online UML (from source)
> - we need to specify a 'skin' for all that since we're never happy with
> default skins, and perform customization on that skin like our own logo
>
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?) 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 :-))
> besides that
>
> - we need to be able to modularize this in the same way we modularize
> our projects
> - we need to be able to express relationships between modules
> - we need some kind of 'master process' that takes all the input (all
> our src/xdocs files, all our source code), then generates all the output
> (and puts it on a website)
sounds like the upcoming forrestbot, although there isn't real solution for
cross-refs here, maybe the avalon case would offer the forrest team the
actual use case to solve the issue?
> - we also need a kind of 'mini process' that takes the input for a
> single module and generates the output for that single module (and puts
> it on the relevant part of the website)
>
should be snap by reusing parts of the forrestbot templates (chinese for
you, but I'll be copying to forrest-dev)
>
> What I'd suggest you do instead of reading the archives (if you want to
> take the time) is take a look at browsing through our website (it's
I have, there are some broken links :-(
> extensive),
It is.
> 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?
>
> Seems like I've given you a lot of information =)
>
lengthy mails are normally my trademark :-)
> anyway, thanks for your time again, and regards,
>
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 :-)
-marc=
> - Leo
>
>
>
> --
> To unsubscribe, e-mail:
<ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: [Fwd: Re: Xdocs Standards]
Posted by Leo Simons <le...@apache.org>.
On Sat, 2002-07-20 at 10:36, Marc Portier wrote:
> Hi Leo et al.
hi! Just gonna throw thoughts at ya...
> 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.
> We are currently rethinking the libre.xml on the forrest-dev mailinglist
> http://marc.theaimsgroup.com/?l=forrest-dev&w=2&r=1&s=%5Blibre%5D&q=b
> (look for the msgs since June 11 with [libre] in the subj.
> basically we're trying to find the use cases that reveal some of the
> book.xml nags... so we can find the right syntax and ways of working
> around them.)
just read up on that. Some good ideas. Especially the one about the
auto-faq management. One note:
<libre>
<entry location="20020713.01.important_howtolibre.xml">
<label>
<xpath expression="//question/text()" />
</label>
<href>
<property name="path" />
</href>
</entry>
<!-- more entries to be made here -->
<auto> <!-- don't filter and just do alphabetic sorting -->
<label>
<xpath expression="//question/text()" />
</label>
<href>
<property name="path" />
</href> </auto>
</libre>
I, as a FAQ maintainer, do not want to have to deal with xpath
expressions! This sort of thing really must not change often, or it'll
hurt (or it should be auto-generated).
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.
It needs to be trivial to specify this order. I can't think of a way to
express it inside the FAQ snippets (maybe with 'next' and 'previous',
but it is usually easier for authors to modify a hierarchy than specify
a list by linking).
Thus you end up with something like:
<faq>
<group name="Common questions">
<item href="whatis.xml"/>
<item href="whatisnot.xml"/>
</group>
<group name="Avalon Phoenix questions">
<item href="whatis.xml"/>
<item href="whatisnot.xml"/>
</group>
</faq>
ie remarkably similar to book.xml.
> I would greately appreciate if you (all) could find the time to
> formulate how you 'ld like it better for your purpose(s)
no prob. Thanks for taking time early on to talk to us!
> 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
> - in surplus it should allow not to need to write all
> the book.xml files at each level
+1, but not that important for me (I usually do
`$MY_EDITOR $(find -name 'book.xml'` which works perfectly well).
> - by becoming a combination of syntax-file and interpreting
> code (currently generator, for next version I think about
> a source implementation rather) I think it will be
> more self-contained then the book.xml with xpathdirgen
> combined
above my hat. Any talk of xpath means you'll loose user immediately.
> I agree with your comment about the current syntax.
> It's not machine generated, but it has been
> hitsorically shaped we're only looking at the first
> refactoring, so yes there is change needed (and
> some of it expressed in
> http://www.krysalis.org/forrest/libre-intro.html.
> the good news is you can influence that.
=)
> And while the 'chore' argument may hold for now it's
> our goal to get that out of the way soon...
> Point is with libre you'll need to think about a
> maintenance strategy for any directory (and it's subs)
> in terms of which xml will be in there, which filenames
> to use etc etc... so afterwards you can just dump the
> xml and the subdirs in there... the libre.xml is created
> at the start and once, while the book.xml needs manual
> intervention for each new doc (that's the filosophy)
got it.
Thing is, everytime you add a new item to the menu of your site, you
should think about where it should be placed, how your menu structure
might need to be reorganized etc etc.
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.
I'm sceptical as to automating this.
A syntax of
<menulist project="avalon">
<item href="index.xml"/>
<item href="features.xml"/>
<item href="blah.xml"/>
<menu name="avalon framework">
<menu name="essentials">
<item href="bla.xml"/>
<item href="bla2.xml"/>
<menu name="Patterns">
<item href="bla.xml"/>
<item href="bla2.xml"/>
</menu>
<menu name="COP">
<item href="bla.xml"/>
<item href="bla2.xml"/>
</menu>
</menu>
<menu name="guide">
<item href="bla.xml"/>
<item href="bla2.xml"/>
</menu>
<menu name="reference">
<item href="bla.xml"/>
<item href="bla2.xml"/>
</menu>
<menu name="project-info" type="auto-generated" />
</menu>
<menu name="avalon excalibur">
<item href="bla.xml"/>
<item href="bla2.xml"/>
<menu name="project-info" type="auto-generated" />
</menu>
<menu><!-- determine name from bla.xml -->
<item href="bla.xml"/>
<item href="bla2.xml"/>
<menu name="project-info" type="auto-generated" />
</menu>
<menu type="faq" base="faq/">
<menu name="Basic Questions" base="basic" />
<menu name="Difficult Questions" base="difficult" />
</menu>
</menulist>
is nice. Essentially consolidate many book.xml documents into one.
However, with avalon it's not, mostly. All our subprojects split into
different CVSes, and often split into smaller modules at that.
They're maintained by different people. For example, the module 'tweety'
inside Avalon Excalibur
(http://jakarta.apache.org/avalon/excalibur/tweety/) is something me and
Nicola wrote. Berin Loritsch wrote "Developing with Avalon"
(http://jakarta.apache.org/avalon/developing/index.html) and has nothing
to do with Tweety. He should not be bothered with the menu structure for
tweety.
So what we need is a some file for expressing hierarchical information
about a menu, and a way to tie in those menus together. What I really
would like is:
jakarta-avalon/src/xdocs/menu.xml
<menu>
<item href="overview.xml"/>
<item href="features.xml"/>
<menu include="framework/" level="1"/>
<menu include="developing/"/>
</menu>
jakarta-avalon/src/xdocs/developing/menu.xml
<menu>
<item href="overview.xml"/>
<item href="features.xml"/>
</menu>
jakarta-avalon/src/xdocs/framework/menu.xml
<menu>
<item href="overview.xml"/>
<item href="features.xml"/>
<menu include="patterns/" level="2"/>
<menu include="cop/" level="2"/>
</menu>
jakarta-avalon/src/xdocs/framework/patterns/menu.xml
<menu>
<!-- this file is not inlined into inside xdocs/menu.xml, as that file
declares one level of inlining. -->
<item href="overview.xml"/>
<item href="features.xml"/>
<menu include="soc/" level="1"/>
<menu include="cop/" level="1"/>
</menu>
jakarta-avalon/src/xdocs/framework/patterns/soc/menu.xml
<menu>
<!-- this file is inlined into inside xdocs/framework/menu.xml, as that
file declares two levels of inlining. -->
<item href="overview.xml"/>
<item href="features.xml"/>
</menu>
jakarta-avalon/src/xdocs/framework/patterns/cop/menu.xml does not exist,
it is autogenerated based on directory contents.
jakarta-avalon/src/xdocs/framework/cop/menu.xml
<menu>
<!-- this file is not inlined into inside xdocs/menu.xml, as that file
declares one level of inlining. -->
<item href="overview.xml"/>
<item href="features.xml"/>
</menu>
the support for different 'levels' is something that could be added at a
later date (the current l&f doesn't allow for it anyway). Basically this
setup says: for each submenu, there's a separate directory. In that
directory may be another menu.xml file, or if it isn't there it is
auto-generated using some setting (ie alpabetic sorting).
The next step is to have a project files something like so:
jakarta-avalon-site/project.xml
<project>
<menu
base="../jakarta-avalon/src/xdocs"
output="../jakarta-avalon/build/docs" />
<project file="../jakarta-avalon-excalibur/site/project/xml" />
<menu
base="../jakarta-avalon-apps/site/src/xdocs"
output="../jakarta-avalon-apps/site/build/docs" />
<menu
base="../jakarta-avalon-cornerstone/src/xdocs"
output="../jakarta-avalon-cornerstone/build/docs" />
<menu
base="../jakarta-avalon-phoenix/src/xdocs"
output="../jakarta-avalon-phoenix/build/docs" />
</project>
jakarta-avalon-excalibur/site/project.xml
<project>
<menu name="containers">
<menu
base="../assembly/src/xdocs"
output="../assembly/build/docs" />
<menu
base="../component/src/xdocs"
output="../component/build/docs" />
</menu>
<menu name="stuff">
<menu
base="../configuration/src/xdocs"
output="../configuration/build/docs" />
</menu>
</project>
where centipede feeds the relevant parts into forrest and all your docs
are generated.
> -marc=
> PS: I'll be happy to read in the avalon-dev archive to
> understand your use cases (could you give some pointers
> (subject lines and keywords) on related discussions?)
hmm. Our use case is all but completely the same as that of every other
software project, I guess. Forgetting all I wrote above and going back
to the basics
- we need to write docs (in xml using document-v11.dtd)
- we need to write a FAQ (in xml)
- we need a 'interesting threads' sort of page where we can link to
mailing list archive threads (in xml)
- we need project information (mailing list, cvs repo, code conventions,
the stuff maven generates for you) (as little maintaince as possible)
- we need online javadoc (from source)
- we need online javasrc (from source)
- we need online UML (from source)
- we need to specify a 'skin' for all that since we're never happy with
default skins, and perform customization on that skin like our own logo
besides that
- we need to be able to modularize this in the same way we modularize
our projects
- we need to be able to express relationships between modules
- we need some kind of 'master process' that takes all the input (all
our src/xdocs files, all our source code), then generates all the output
(and puts it on a website)
- we also need a kind of 'mini process' that takes the input for a
single module and generates the output for that single module (and puts
it on the relevant part of the website)
What I'd suggest you do instead of reading the archives (if you want to
take the time) is take a look at browsing through our website (it's
extensive), then take a look at all 'src/xdocs' directories you can find
in our various CVSes, and see how that transforms into the site.
Seems like I've given you a lot of information =)
anyway, thanks for your time again, and regards,
- Leo
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: [Fwd: Re: Xdocs Standards]
Posted by Marc Portier <mp...@outerthought.org>.
Hi Leo et al.
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...
We are currently rethinking the libre.xml on the forrest-dev mailinglist
http://marc.theaimsgroup.com/?l=forrest-dev&w=2&r=1&s=%5Blibre%5D&q=b
(look for the msgs since June 11 with [libre] in the subj.
basically we're trying to find the use cases that reveal some of the
book.xml nags... so we can find the right syntax and ways of working
around them.)
I would greately appreciate if you (all) could find the time to
formulate how you 'ld like it better for your purpose(s)
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)
- in surplus it should allow not to need to write all
the book.xml files at each level
- by becoming a combination of syntax-file and interpreting
code (currently generator, for next version I think about
a source implementation rather) I think it will be
more self-contained then the book.xml with xpathdirgen
combined
I agree with your comment about the current syntax.
It's not machine generated, but it has been
hitsorically shaped we're only looking at the first
refactoring, so yes there is change needed (and
some of it expressed in
http://www.krysalis.org/forrest/libre-intro.html.
the good news is you can influence that.
And while the 'chore' argument may hold for now it's
our goal to get that out of the way soon...
Point is with libre you'll need to think about a
maintenance strategy for any directory (and it's subs)
in terms of which xml will be in there, which filenames
to use etc etc... so afterwards you can just dump the
xml and the subdirs in there... the libre.xml is created
at the start and once, while the book.xml needs manual
intervention for each new doc (that's the filosophy)
-marc=
PS: I'll be happy to read in the avalon-dev archive to
understand your use cases (could you give some pointers
(subject lines and keywords) on related discussions?)
> -----Original Message-----
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> Sent: vrijdag 19 juli 2002 20:46
> To: forrest-dev@xml.apache.org
> Subject: [Fwd: Re: Xdocs Standards]
>
>
>
>
> -------- Original Message --------
> Subject: Re: Xdocs Standards
> Date: 19 Jul 2002 20:43:03 +0200
> From: Leo Simons <le...@apache.org>
> Reply-To: "Avalon Developers List" <av...@jakarta.apache.org>
> To: Avalon Development <av...@jakarta.apache.org>
> References: <00...@Gabriel>
> <3D...@apache.org>
>
> > > Libre markup is ugly. Is it automagically generated? The
> project.xml
> > > format is fine for that purpose.
> >
> > Then join forrest-dev@xml.apache.org .
> > Libre generates stuff automatically as part of the gen process, so that
> > it can enhance book.xml-like stuff.
> >
> > In which way "Libre markup is ugly"?
>
> There is semantic content (menu order and structure) to express about
> the menu which is very natural to do in book.xml, while the way I
> understand it in libre this is a chore.
>
> Book.xml is just about as easy as it gets for writing a menu xml file, I
> think.
>
> - Leo
>
>
>
> --
> To unsubscribe, e-mail:
> <ma...@jakarta.apache.org>
> For additional commands, e-mail:
> <ma...@jakarta.apache.org>
>
>
>
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
RE: [Fwd: Re: Xdocs Standards]
Posted by Marc Portier <mp...@outerthought.org>.
Hi Leo et al.
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...
We are currently rethinking the libre.xml on the forrest-dev mailinglist
http://marc.theaimsgroup.com/?l=forrest-dev&w=2&r=1&s=%5Blibre%5D&q=b
(look for the msgs since June 11 with [libre] in the subj.
basically we're trying to find the use cases that reveal some of the
book.xml nags... so we can find the right syntax and ways of working
around them.)
I would greately appreciate if you (all) could find the time to
formulate how you 'ld like it better for your purpose(s)
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)
- in surplus it should allow not to need to write all
the book.xml files at each level
- by becoming a combination of syntax-file and interpreting
code (currently generator, for next version I think about
a source implementation rather) I think it will be
more self-contained then the book.xml with xpathdirgen
combined
I agree with your comment about the current syntax.
It's not machine generated, but it has been
hitsorically shaped we're only looking at the first
refactoring, so yes there is change needed (and
some of it expressed in
http://www.krysalis.org/forrest/libre-intro.html.
the good news is you can influence that.
And while the 'chore' argument may hold for now it's
our goal to get that out of the way soon...
Point is with libre you'll need to think about a
maintenance strategy for any directory (and it's subs)
in terms of which xml will be in there, which filenames
to use etc etc... so afterwards you can just dump the
xml and the subdirs in there... the libre.xml is created
at the start and once, while the book.xml needs manual
intervention for each new doc (that's the filosophy)
-marc=
PS: I'll be happy to read in the avalon-dev archive to
understand your use cases (could you give some pointers
(subject lines and keywords) on related discussions?)
> -----Original Message-----
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> Sent: vrijdag 19 juli 2002 20:46
> To: forrest-dev@xml.apache.org
> Subject: [Fwd: Re: Xdocs Standards]
>
>
>
>
> -------- Original Message --------
> Subject: Re: Xdocs Standards
> Date: 19 Jul 2002 20:43:03 +0200
> From: Leo Simons <le...@apache.org>
> Reply-To: "Avalon Developers List" <av...@jakarta.apache.org>
> To: Avalon Development <av...@jakarta.apache.org>
> References: <00...@Gabriel>
> <3D...@apache.org>
>
> > > Libre markup is ugly. Is it automagically generated? The
> project.xml
> > > format is fine for that purpose.
> >
> > Then join forrest-dev@xml.apache.org .
> > Libre generates stuff automatically as part of the gen process, so that
> > it can enhance book.xml-like stuff.
> >
> > In which way "Libre markup is ugly"?
>
> There is semantic content (menu order and structure) to express about
> the menu which is very natural to do in book.xml, while the way I
> understand it in libre this is a chore.
>
> Book.xml is just about as easy as it gets for writing a menu xml file, I
> think.
>
> - Leo
>
>
>
> --
> To unsubscribe, e-mail:
> <ma...@jakarta.apache.org>
> For additional commands, e-mail:
> <ma...@jakarta.apache.org>
>
>
>
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>