You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cactus-dev@jakarta.apache.org by Vincent Massol <vm...@octo.com> on 2003/01/12 18:35:43 UTC
New web site generation and organization
Hi,
I've just committed some changed that I hacked while away on vacation
WRT the web site generation and xdoc files. Here are some more
information:
- Stylebook has now been removed in favor of pure and straight XSL. We
have a single stylesheet called document2html.xsl
- Our XSL now supports:
- arbitrary sub-directories
- menus that change with subdirectories
- several levels of sub-menus
- site map generation (i.e. a page that lists and described all
topics)
- Here are the changes that have been brought to the xdocs:
- each xdoc file must now have an id attribute as in:
<document id="some_unique_id">
- this id is used in the navigation.xml file which contains the menu
definitions for the current directory. Note: If a subdirectory does not
want to redefine a new menu, it still needs a navigation.xml file but it
should only contain <navigation/>
- every page (whether internal or external) is described in a special
file called sitemap.xml, using its id
- hrefs must be of the format site:id or ext:id
For example:
<link href="site:downloads"> or <link href="ext:junit">
where the id is the id of the page
I hope you like it. Please give me your feedback!
Thanks
-Vincent
Note: A pity jakarta does not have a standard xsl stylesheet like this
one! Forrest seems very fine but too complex to me (you have to install
it simply to generate a web site). Agreed, it does more than this
simplex XSL but for most cases, this XSL should probably be enough.
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: New web site generation and organization
Posted by Stefan Bodewig <bo...@apache.org>.
On Mon, 13 Jan 2003, Christopher Lenz <cm...@gmx.de> wrote:
> I would love to have such a task available anyway, maybe I'll be
> able to work on it soon...
<http://jakarta.apache.org/lucene/docs/lucene-sandbox/larm/overview.html>
might be a starting point (but then again, it may be too much).
Stefan
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: New web site generation and organization
Posted by Christopher Lenz <cm...@gmx.de>.
Vincent Massol wrote:
>>Really, there are many :-P
>>Do a search for href="*.html", and sort the external links from the
>>search results.
>
> Oops... You're right. I had forgotten lots of places .... I have now
> committed a modification to our stylesheet that reveals the problems.
Cool. When the links are fixed, we should add a terminate='yes' to the
<xsl:message> element, so that invalid links stop the build in the future.
[snip]
>>Yeah, but typos, or simply forgetting to put a new page in the sitemap
>>still produce broken links. Some automated quality control would be
>>nice, but of course we can do without - hey we could also do without
>>unit tests ;-)
>
> I have modified the stylesheet to report invalid ids, so typos should be
> caught now.
That seems like a good and simple solution.
--
Christopher Lenz
/=/ cmlenz at gmx.de
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: New web site generation and organization
Posted by Vincent Massol <vm...@octo.com>.
... but we still need something to validate the links (in sitemap):
- for internal links, it means verifying the "source" attr points to a
valid location
- for external links, it means verifying the "href" attr points to a
valid link
We can't do that in XSL, can we? In other words, is there a possibility
to extend the XSL processing? A Xalan feature using PIs?
-Vincent
> -----Original Message-----
> From: Vincent Massol [mailto:vmassol@octo.com]
> Sent: 13 January 2003 11:47
> To: 'Cactus Developers List'
> Subject: RE: New web site generation and organization
>
>
>
> > -----Original Message-----
> > From: Christopher Lenz [mailto:cmlenz@gmx.de]
> > Sent: 13 January 2003 11:07
> > To: Cactus Developers List
> > Subject: Re: New web site generation and organization
> >
> > Vincent Massol wrote:
> > [snip]
> > >>Currently, there are a lot of broken links on the pages, because
> they
> > >>haven't been converted to the size:id/ext:id URL format yet... but
I
> > >>guess you're aware of that ;-)
> > >
> > > Could you tell me where? I've tried to convert almost all I knew.
> BTW,
> > > external links will work even when not converted to the ext:id
> notation.
> >
> > Really, there are many :-P
> > Do a search for href="*.html", and sort the external links from the
> > search results.
>
> Oops... You're right. I had forgotten lots of places .... I have now
> committed a modification to our stylesheet that reveals the problems.
>
> >
> > If we want to enforce putting all internal and external links in the
> > sitemap, the stylesheet could probably check for that and issue an
> error
> > if the contract is violated.
>
> Yep. Done (first version).
>
> >
> > >>Hmm, it'd be nice to have some link-crawling ant task as build
step,
> > >>to check for broken links...
> > >
> > > hehe... I knew this one was coming :-). It's actually one of the
> reason
> > > for the sitemap so that we can easily have all the links in one
> place.
> >
> > Yeah, but typos, or simply forgetting to put a new page in the
sitemap
> > still produce broken links. Some automated quality control would be
> > nice, but of course we can do without - hey we could also do without
> > unit tests ;-)
> >
>
> I have modified the stylesheet to report invalid ids, so typos should
be
> caught now.
>
> > I would love to have such a task available anyway, maybe I'll be
able
> to
> > work on it soon...
> >
> > >>I also couldn't see the sub-menuing in action. A major revamp of
the
> > >>menus would probably have the most benefit for the documentation.
> > >
> > > Normal, I haven't used them yet in what I have committed :-). But
> the
> > > feature is there.
> >
> > Okay, cool.
> >
>
>
> -Vincent
>
>
>
> --
> To unsubscribe, e-mail: <mailto:cactus-dev-
> unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: <mailto:cactus-dev-
> help@jakarta.apache.org>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: New web site generation and organization
Posted by Vincent Massol <vm...@octo.com>.
> -----Original Message-----
> From: Christopher Lenz [mailto:cmlenz@gmx.de]
> Sent: 13 January 2003 11:07
> To: Cactus Developers List
> Subject: Re: New web site generation and organization
>
> Vincent Massol wrote:
> [snip]
> >>Currently, there are a lot of broken links on the pages, because
they
> >>haven't been converted to the size:id/ext:id URL format yet... but I
> >>guess you're aware of that ;-)
> >
> > Could you tell me where? I've tried to convert almost all I knew.
BTW,
> > external links will work even when not converted to the ext:id
notation.
>
> Really, there are many :-P
> Do a search for href="*.html", and sort the external links from the
> search results.
Oops... You're right. I had forgotten lots of places .... I have now
committed a modification to our stylesheet that reveals the problems.
>
> If we want to enforce putting all internal and external links in the
> sitemap, the stylesheet could probably check for that and issue an
error
> if the contract is violated.
Yep. Done (first version).
>
> >>Hmm, it'd be nice to have some link-crawling ant task as build step,
> >>to check for broken links...
> >
> > hehe... I knew this one was coming :-). It's actually one of the
reason
> > for the sitemap so that we can easily have all the links in one
place.
>
> Yeah, but typos, or simply forgetting to put a new page in the sitemap
> still produce broken links. Some automated quality control would be
> nice, but of course we can do without - hey we could also do without
> unit tests ;-)
>
I have modified the stylesheet to report invalid ids, so typos should be
caught now.
> I would love to have such a task available anyway, maybe I'll be able
to
> work on it soon...
>
> >>I also couldn't see the sub-menuing in action. A major revamp of the
> >>menus would probably have the most benefit for the documentation.
> >
> > Normal, I haven't used them yet in what I have committed :-). But
the
> > feature is there.
>
> Okay, cool.
>
-Vincent
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: New web site generation and organization
Posted by Christopher Lenz <cm...@gmx.de>.
Vincent Massol wrote:
[snip]
>>Currently, there are a lot of broken links on the pages, because they
>>haven't been converted to the size:id/ext:id URL format yet... but I
>>guess you're aware of that ;-)
>
> Could you tell me where? I've tried to convert almost all I knew. BTW,
> external links will work even when not converted to the ext:id notation.
Really, there are many :-P
Do a search for href="*.html", and sort the external links from the
search results.
If we want to enforce putting all internal and external links in the
sitemap, the stylesheet could probably check for that and issue an error
if the contract is violated.
>>Hmm, it'd be nice to have some link-crawling ant task as build step,
>>to check for broken links...
>
> hehe... I knew this one was coming :-). It's actually one of the reason
> for the sitemap so that we can easily have all the links in one place.
Yeah, but typos, or simply forgetting to put a new page in the sitemap
still produce broken links. Some automated quality control would be
nice, but of course we can do without - hey we could also do without
unit tests ;-)
I would love to have such a task available anyway, maybe I'll be able to
work on it soon...
>>I also couldn't see the sub-menuing in action. A major revamp of the
>>menus would probably have the most benefit for the documentation.
>
> Normal, I haven't used them yet in what I have committed :-). But the
> feature is there.
Okay, cool.
--
Christopher Lenz
/=/ cmlenz at gmx.de
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: New web site generation and organization
Posted by Vincent Massol <vm...@octo.com>.
> -----Original Message-----
> From: Christopher Lenz [mailto:cmlenz@gmx.de]
> Sent: 13 January 2003 10:35
> To: Cactus Developers List
> Subject: Re: New web site generation and organization
>
> Vincent Massol wrote:
> > Hi,
> >
> > I've just committed some changed that I hacked while away on
vacation
> > WRT the web site generation and xdoc files. Here are some more
> > information:
> >
> > - Stylebook has now been removed in favor of pure and straight XSL.
We
> > have a single stylesheet called document2html.xsl
> >
> > - Our XSL now supports:
> > - arbitrary sub-directories
> > - menus that change with subdirectories
> > - several levels of sub-menus
> > - site map generation (i.e. a page that lists and described all
> > topics)
> >
> > - Here are the changes that have been brought to the xdocs:
> > - each xdoc file must now have an id attribute as in:
> > <document id="some_unique_id">
> > - this id is used in the navigation.xml file which contains the
menu
> > definitions for the current directory. Note: If a subdirectory does
not
> > want to redefine a new menu, it still needs a navigation.xml file
but it
> > should only contain <navigation/>
> > - every page (whether internal or external) is described in a
special
> > file called sitemap.xml, using its id
> > - hrefs must be of the format site:id or ext:id
> > For example:
> > <link href="site:downloads"> or <link href="ext:junit">
> > where the id is the id of the page
> >
> > I hope you like it. Please give me your feedback!
>
> I like it :-)
>
> Currently, there are a lot of broken links on the pages, because they
> haven't been converted to the size:id/ext:id URL format yet... but I
> guess you're aware of that ;-)
Could you tell me where? I've tried to convert almost all I knew. BTW,
external links will work even when not converted to the ext:id notation.
>
> Hmm, it'd be nice to have some link-crawling ant task as build step,
to
> check for broken links...
hehe... I knew this one was coming :-). It's actually one of the reason
for the sitemap so that we can easily have all the links in one place.
>
> I also couldn't see the sub-menuing in action. A major revamp of the
> menus would probably have the most benefit for the documentation.
Normal, I haven't used them yet in what I have committed :-). But the
feature is there.
>
> > Thanks
> > -Vincent
> >
> > Note: A pity jakarta does not have a standard xsl stylesheet like
this
> > one! Forrest seems very fine but too complex to me (you have to
install
> > it simply to generate a web site). Agreed, it does more than this
> > simplex XSL but for most cases, this XSL should probably be enough.
>
> Yeah, technology wars stand in the way, mostly :-(
-Vincent
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: New web site generation and organization
Posted by Christopher Lenz <cm...@gmx.de>.
Vincent Massol wrote:
> Hi,
>
> I've just committed some changed that I hacked while away on vacation
> WRT the web site generation and xdoc files. Here are some more
> information:
>
> - Stylebook has now been removed in favor of pure and straight XSL. We
> have a single stylesheet called document2html.xsl
>
> - Our XSL now supports:
> - arbitrary sub-directories
> - menus that change with subdirectories
> - several levels of sub-menus
> - site map generation (i.e. a page that lists and described all
> topics)
>
> - Here are the changes that have been brought to the xdocs:
> - each xdoc file must now have an id attribute as in:
> <document id="some_unique_id">
> - this id is used in the navigation.xml file which contains the menu
> definitions for the current directory. Note: If a subdirectory does not
> want to redefine a new menu, it still needs a navigation.xml file but it
> should only contain <navigation/>
> - every page (whether internal or external) is described in a special
> file called sitemap.xml, using its id
> - hrefs must be of the format site:id or ext:id
> For example:
> <link href="site:downloads"> or <link href="ext:junit">
> where the id is the id of the page
>
> I hope you like it. Please give me your feedback!
I like it :-)
Currently, there are a lot of broken links on the pages, because they
haven't been converted to the size:id/ext:id URL format yet... but I
guess you're aware of that ;-)
Hmm, it'd be nice to have some link-crawling ant task as build step, to
check for broken links...
I also couldn't see the sub-menuing in action. A major revamp of the
menus would probably have the most benefit for the documentation.
> Thanks
> -Vincent
>
> Note: A pity jakarta does not have a standard xsl stylesheet like this
> one! Forrest seems very fine but too complex to me (you have to install
> it simply to generate a web site). Agreed, it does more than this
> simplex XSL but for most cases, this XSL should probably be enough.
Yeah, technology wars stand in the way, mostly :-(
--
Christopher Lenz
/=/ cmlenz at gmx.de
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>