[jdom-interest] Re: [jdom-commits] CVS Update: jdom-site/docs/apidocs

[Elliotte Rusty Harold]

I got a *lot* CVS commit messages in my inbox this morning. It's 
great to see JDOM moving again. However, maybe we can cut down on the 
volume a little. In particular I just noted a batch of commit 
messages for JavaDoc HTML files.It's normally considered best 
practice *not* to store generated files such as JavaDoc in your 
version control system. Andy Hunt and Dave Thomas discuss this on p. 
10 of Pragmatic Version Control (The Pargmatic Programmers LLC, 2003):


   If we store all the things needed to build the project, does that mean
   that we should also be storing all the generated files? For example,
   we might run JavaDoc to generate the API documentation for our source
   tree. Should that documentation be stored in the version control
   system's repository?

   The simple answer is "no." If a generate file can be reconstituted
   from other files, then storing it is simply duplication. Why is this
   duplication bad? It isn't because we're worried about wasting disk
   space. It's because we don't want things to get out of step. If we
   store the source and the documentation, and then change the source,
   the documentation is now outdated. If we forget to update it and check
   it back in, we've now got misleading documentation in our repository.
   So in this case, we'd want to keep a single source of the information,
   the source code.

So I recommend we delete all the generated JavaDoc from the CVS tree. 
Obviously this doesn't apply to things like package.html files that 
are used to generate the overviews and are independent of the source 
code.



At 3:28 AM -0700 2/6/04, nobody wrote:
>****************************************
>Date:   Fri Feb  6, 2004 @03:28:07 MST
>Author:
>
>Update of /home/cvs/jdom-site/docs/apidocs
>In directory chimbo:/tmp/cvs-serv22247
>
>Modified Files:
>allclasses-frame.html allclasses-noframe.html
>constant-values.html deprecated-list.html help-doc.html
>index.html overview-frame.html overview-summary.html
>overview-tree.html packages.html serialized-form.html
>Log Message:
>Checking in javadocs for jdom-b10-rc1 so they'll be easily viewable
>on the website.
>
>-jh-
>
>===================================================================
>File: allclasses-frame.html	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/allclasses-frame.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: allclasses-noframe.html	Status: Up-to-date
>
>    Working revision:	1.4	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.4 
>	/home/cvs/jdom-site/docs/apidocs/allclasses-noframe.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.3)
>
>===================================================================
>File: constant-values.html	Status: Up-to-date
>
>    Working revision:	1.4	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.4 
>	/home/cvs/jdom-site/docs/apidocs/constant-values.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.3)
>
>===================================================================
>File: deprecated-list.html	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/deprecated-list.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: help-doc.html    	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/help-doc.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: index.html       	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/index.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: overview-frame.html	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/overview-frame.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: overview-summary.html	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/overview-summary.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: overview-tree.html	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/overview-tree.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: packages.html    	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/packages.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>===================================================================
>File: serialized-form.html	Status: Up-to-date
>
>    Working revision:	1.7	Fri Feb  6 10:27:55 2004
>    Repository revision:	1.7 
>	/home/cvs/jdom-site/docs/apidocs/serialized-form.html,v
>
>    Existing Tags:
>	jdom_1_0_b9              	(revision: 1.6)
>
>_______________________________________________
>To control your jdom-commits membership:
>http://lists.denveronline.net/mailman/options/jdom-commits/youraddr@yourhost.com

-- 

   Elliotte Rusty Harold
   elharo at metalab.unc.edu
   Effective XML (Addison-Wesley, 2003)
   http://www.cafeconleche.org/books/effectivexml
   http://www.amazon.com/exec/obidos/ISBN%3D0321150406/ref%3Dnosim/cafeaulaitA