commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <p...@steitz.com>
Subject Re: [math] where to cite references (was RE: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment Kurtosis.java Skewness.java)
Date Tue, 06 Jul 2004 03:43:56 GMT
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.

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.

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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message