commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Phil Steitz" <>
Subject RE: [math] where to cite references (was RE: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment
Date Tue, 06 Jul 2004 13:50:06 GMT
Then we should significantly change the content of the web site -- eliminating most of the
maven reports.  We will also need a way to acknowledge contributors in a timely way and to
maintain an up-to-date task list.  It is much simpler, IMHO, to use maven to do all of this
(actually a good bit of the value proposition for using maven at all).  Given volunteer time
constraints, I would prefer to keep things as simple and automated as possible.  

	-----Original Message----- 
	From: Al Chou [] 
	Sent: Mon 7/5/2004 10:33 PM 
	Subject: Re: [math] where to cite references (was RE: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment

	--- Phil Steitz <> wrote:
	> All good points below.  How about the following strategy:
	> 1) Web site always reflects state of current development (essentially CVS
	> head). We get better at keeping it up to date (I have been lazy about
	> this), trying to update it after every significant change and at least
	> once a month.
	IIRC, Mark will argue against having the Web site reflect the current state of
	development, and I now would agree with him.  The Web site should reflect the
	current official release version.  Perhaps we could have an additional section
	of the site where the current development version is reflected nightly?
	> 2) With each release (yes, there really will be releases ;-), we tar
	> generated html with relative links including both javadocs and user guide.
	> Struts and tomcat at least used to do this (haven't grabbed distros of
	> either recently).  That way users always have guide + javadoc matching
	> what they have deployed. This should not be a problem using maven.
	> 3) We try to limit dependencies on external html links as much as
	> possible, favoring inline exposition in the javadoc or user guide when
	> this is feasible and dead tree references when what is needed is a
	> reference citation. The last sentence conflicts with what we have in the
	> developer's guide, so I guess I am proposing that we change this policy.
	> I am just afraid that if we include a lot of external links in the html
	> that we distribute with releases, we will have no way of keeping them up
	> to date.  I am not proposing that we hold 1.0 until we get rid of them all
	> --just try to eliminate the less stable ones and do not continue to add more.
	I would prefer a stable hyperlink over a paper reference any day.  Providing
	both would be acceptable, so that if the hyperlink has gone stale, there's
	still a concrete reference to look up.  I for one would feel more confident
	doing a Web search when I found a reference link unreachable if I knew
	ultimately there was a paper reference to consult.
	> Phil
	> Mark R. Diggory wrote:
	> > Nightly update tends to be frowned upon because usually the site
	> > documentation is tied to a specific release. I think the Maven folks are
	> > working on a means to have older versions of docs archived so that they
	> > can be accessed.
	> >
	> > The issue is one of referential integrity. Say we release javadoc for
	> > version 1.0 and have user doc on the math site that it links to. Then
	> > (lets say) we update the doc on the site such that a page is removed.
	> > Now there are versions of the javadoc out in the wild that point to a
	> > dead link. So, linking in such a way is very restrictive to our being
	> > able to update the user guide.
	> >
	> > Now, I think the user guide is not that large that it couldn't be
	> > distributed on combination with the javadoc, then the javadoc references
	> > could be based on relative linking to the local copy of the userdoc.
	> >
	> > Ultimately we are trying to resolve the fact that we can't use xdoc in
	> > such a way as to embed it into javadoc directly. Would we even want to?!
	> > I think its best if we maintain a parallel xdoc structure to the javadoc
	> > package structure and distribute them together as one package that is
	> > relatively linked. This really just means packaging up portions of the
	> > site docs such that they are expanded from the tar file and that they
	> > can still be navigated in the local file system in a browser
	> >
	> > -Mark
	To unsubscribe, e-mail:
	For additional commands, e-mail:

View raw message