Return-Path: Delivered-To: apmail-xml-cocoon-docs-archive@xml.apache.org Received: (qmail 39091 invoked by uid 500); 19 Nov 2002 17:06:58 -0000 Mailing-List: contact cocoon-docs-help@xml.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: cocoon-docs@xml.apache.org Delivered-To: mailing list cocoon-docs@xml.apache.org Received: (qmail 39071 invoked from network); 19 Nov 2002 17:06:57 -0000 Received: from unknown (HELO dns.ascii27.net) (63.209.103.150) by daedalus.apache.org with SMTP; 19 Nov 2002 17:06:57 -0000 Received: from netarcana.com (localhost.localdomain [127.0.0.1]) by dns.ascii27.net (8.12.1/8.12.1) with SMTP id gAJH70xD018695 for ; Tue, 19 Nov 2002 12:07:00 -0500 Received: from 128.159.142.62 (SquirrelMail authenticated user ajl) by netarcana.com with HTTP; Tue, 19 Nov 2002 12:07:00 -0500 (EST) Message-ID: <1333.128.159.142.62.1037725620.squirrel@netarcana.com> Date: Tue, 19 Nov 2002 12:07:00 -0500 (EST) Subject: Re: Documentation Format... From: "Andy Lewis" To: In-Reply-To: <19B7BF90-FAEE-11D6-8E6A-0030653FE818@apache.org> References: <20021118074532.298CB23CD8@dj.codeconsult.ch> <19B7BF90-FAEE-11D6-8E6A-0030653FE818@apache.org> X-Priority: 3 Importance: Normal X-MSMail-Priority: Normal Reply-To: ajl@ascii27.net X-Mailer: SquirrelMail (version 1.2.6) MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N > > On Monday, November 18, 2002, at 02:45 AM, Bertrand Delacretaz wrote: > >> >>> . . . >>> Well, if the effort needed was granular enough, we might get more help/resources. >>> . . . >> >> I think the concept of man pages (one page for each component)using javadocs >> tags (as proposed by several people here) is a nice way of making the effort >> more granular. > > Yes, but....., I don't consider it a panacea (cure-all) for docs. It's really a subset of > granular info or topics that can be used by other docs. Because it's so tied to the code, it > doesn't necessarily cover the range of topics needed by other docs. > > Diana The use of javadoc tags or this is...well....I'm not sure. I think there is some stuf that goes in the code, but my intent with the man pages was user-levle technical documentation. - such as what apramters does this generator recognize, and what are valid values, or how shoudl the URI be formatter, or what tags does a transformetr understand. User docs for each component. It certainly won't solve all the documentation concerns, I agree, but it will provide a base level of reference docs for users to work with. And it is vvery ganular, and should be easy to start, and there is a very strong possibility of having the developers maintain it in a timely fashion. -- "The heights of genius are only measurable by the depths of stupidity."