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/20 12:14:15 UTC
[Fwd: RE: [Fwd: Re: Xdocs Standards]]
-------- Original Message --------
Subject: RE: [Fwd: Re: Xdocs Standards]
Date: 20 Jul 2002 11:36:33 +0200
From: Leo Simons <le...@apache.org>
Reply-To: "Avalon Developers List" <av...@jakarta.apache.org>
To: Avalon Developers List <av...@jakarta.apache.org>
References: <LO...@outerthought.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>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------