forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Marc Portier" <...@outerthought.org>
Subject FW: [Fwd: Re: Xdocs Standards]
Date Sun, 21 Jul 2002 08:17:33 GMT
there were some new ideas expressed...
-marc=

> -----Original Message-----
> From: Marc Portier [mailto:mpo@outerthought.org]
> Sent: zondag 21 juli 2002 10:15
> To: Avalon Developers List
> Subject: RE: [Fwd: Re: Xdocs Standards]
>
>
> 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:
> <mailto:avalon-dev-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail:
<mailto:avalon-dev-help@jakarta.apache.org>


Mime
View raw message