commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Mark R. Diggory" <>
Subject Re: [math] where to cite references (was RE: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment
Date Mon, 05 Jul 2004 18:21:33 GMT
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


Al Chou wrote:
> I rather prefer hyperlinks in the Javadoc as well.  I don't see why it should
> be brittle to link from the Javadoc to the user guide -- it's not as if we're
> frequently changing the list of references.  The fact that the user guide is
> online at the project site should help us keep it up to date (it's visible to
> the public, which always gives me more incentive to do the right thing <g>).
> One thing that occurs to me as I look at the [math] site:  like other Apache
> project sites, it's not immediately obvious from the navigation menu (or any
> other part of the home page) how one should submit feedback about the project. 
> Sure, there are several links that sound promising (e.g., About Us >
> Contributors, General Information > Contributing Patches, Jakarta Community >
> Mailing Lists), but these typically point to Jakarta Commons in general rather
> than Commons-Math specifically (I realize that may be because we're using a
> Commons template to generate the page), but no obvious "submit a bug report",
> "submit feedback", "request support", "ask a question" sort of feature.  Users
> have to be rather motivated to discover a way to send us a message (most likely
> Project Documentation > Issue Tracking), and I think the project is probably
> the poorer for it, as many users aren't nearly motivated enough to dig in that
> far (the company where I work develops a product that helps address that and
> many other related issues with Web sites/apps).
> On a different note, I'm not current on how the Commons-Math site is generated;
> I have a vague memory that Mark's been initiating that process manually.  Is
> there a strong reason the nightly build shouldn't do it?  Some of the content
> seems a little (a few weeks, as opposed to months) out of date, such as the
> TODO list, which Phil, Mark, and Brent have diligently been working through
> (apologies to any whom I forgot to mention).
> Al
> --- Phil Steitz <> wrote:
>>I would prefer to keep the references that we actually need in the javadoc
>>itself.  The ones that I removed were just references to (standard,
>>straightforward) definitions, which I had added inline.  In general, I want
>>to include definitions in the javadoc unless this is not tractable (too many
>>dependent concepts, formulas too complex, etc.), in which case a reference to
>>a definitive source should be included.  When we use algorithms that are not
>>elementary or widely known, we should include references to docs or papers
>>(e.g. the Chan et al references for the moment updating formulas).
>>Unfortunately, the first sentence above is a PITA to maintain and leaves us
>>open to broken links (last time I rank linkcheck, the p-value reference was
>>broken :-(   That makes suggestions like Mark's appealing, but I don't like
>>losing the hyperlinks.   Is it excessively brittle to include links from the
>>javadoc back to the user guide?  If so, is there any stable place (better
>>than ~psteitz) where I can host some definitions?
>>	-----Original Message----- 
>>	From: Mark R. Diggory [] 
>>	Sent: Fri 7/2/2004 8:51 AM 
>>	To: Jakarta Commons Developers List
>>	Subject: Re: cvs commit:
>>	What if we maintained "Citation Numbers" in the javadoc and then
>>	maintained references to external sources in the Math Site documentation?
>>	Al Chou wrote:
>>	>--- wrote:
>>	> 
>>	>
>>	>>psteitz     2004/07/01 22:29:14
>>	>>
>>	>>  Modified:   
>>	>>              
>>	>>  Log:
>>	>>  Removed link to external definition, as formula has been added to
>>	>
>>	>Maybe it's my grad school experiences talking, but I would prefer to retain
>>	>links to external references.  That way if a user (or even one of us
>>	>developers) ever needs to look up the original references, its easy to do,
>>	>there's an explicit statement of which source of information we used,
>>	>than doing a Web search and wondering which (if any) of the resulting
>>	>was the original reference.  Maybe that doesn't matter to anyone but me?
>>	>
>>	>
>>	>Al
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

Mark Diggory
Software Developer
Harvard MIT Data Center

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message