Mailing-List: contact couchdb-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: couchdb-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of cmlenz@gmx.de designates
 213.165.64.20 as permitted sender)
Message-Id: <24C8D502-552B-4EF2-816F-A56CD3488EE9@gmx.de>
From: Christopher Lenz <cmlenz@gmx.de>
To: couchdb-dev@incubator.apache.org
In-Reply-To: <20080330051051.GC30571@bytesexual.org>
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v919.2)
Subject: Re: Status Update
Date: Sun, 30 Mar 2008 12:08:25 +0200
References: <2B562960-67A2-4E01-A88E-757B1FF77E43@gmx.de>
 <20080330051051.GC30571@bytesexual.org>

On 30.03.2008, at 07:10, Noah Slater wrote:
> * I have updated all the source documentation to use Markdown  
> following Chris's
>   changes for the CouchDB incubation site.

What source documentation is that?

> * I have removed the generated HTML files from Subversion, this  
> didn't seem
>   like a good use of revision control.

Oops, we'll have to revert that. From <http://incubator.apache.org/guides/sites.html 
 >

   "Regardless of which tool you use, the web site should be  
maintained in the svn repository, and include the site generation tool  
as a binary file. This simplifies the process of site generation and  
enables changes to the site to be made by any committer. The generated  
site should also be checked into svn. This allows the generated site  
to be relocated to any part of the Apache site after incubation is  
complete."

> * I have modified the site build script to construct the following  
> pages directly
>   from /trunk/README, /trunk/TROUBLESHOOTING, /trunk/NEWS in the  
> source:
>
>     http://incubator.apache.org/couchdb/docs/installation.html
>     http://incubator.apache.org/couchdb/docs/troubleshooting.html
>     http://incubator.apache.org/couchdb/docs/changelog.html
>
>   Chris, you may not like my specific modifications, I have no  
> attachment to
>   the current implementation, but it seemed like the easiest way to  
> get this
>   done on FreeBSD. I am more than happy to change things around.

For some reason these changes don't seem to have come through on  
couchdb-commits@ yet. I'm looking into them now.

> * I have added the /site/publish.sh script which can be run directly  
> from a
>   source checkout on minotaur to build and publish the site.

See above, this needs to be as simple (and was) as just an `svn up`.

> * I would like to suggest we move the /site directory into the / 
> trunk so that
>   the documentation can be built as part of the package at  
> distribution
>   time. From my perspective as the Debian maintainer for CouchDB I  
> would dearly
>   like to include a static copy of the HTML documentation in the  
> package.

I don't think we should include the site in trunk, if only because of  
the requirement of keeping the generated files in the repository.

Having generated HTML docs in tarballs is certainly a nice goal, but  
we should analyse what we'd like there and how to best achieve it.  
That includes defining what kind of docs we want on the website, what  
on the wiki, and what should come with the releases. It gets tricky  
when there is overlap.

Cheers,
Chris
--
Christopher Lenz
   cmlenz at gmx.de
   http://www.cmlenz.net/