Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Message-ID: <019c01c1cc37$b19e8c70$670004c0@PC103>
Reply-To: "Nicola Ken Barozzi" <nicolaken@apache.org>
From: "Nicola Ken Barozzi" <nicolaken@apache.org>
To: <forrest-dev@xml.apache.org>
References: <3C91E807.8534D03F@apache.org>
Subject: Re: [Vote] Automatic vs. Manual Documentation Structure
Date: Fri, 15 Mar 2002 16:40:11 +0100
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit

From: "Stefano Mazzocchi" <stefano@apache.org>

> There are two solutions:
>
>  1) Automatic Documentation Structure: the ToC is auto-generated out of
> file system layout or database tree layout.

-1  reason:

>  a) it's implicit: in order to trigger a change in the ToC, the database
> or file system must be changed and things moved around. This reminds me
> of implicit parallel between the URI space and the file system space
> which we now consider harmful.
>
>  b) it's poor: how can we have external links in the ToC?
>
>  c) it mixes concerns: who writes and stores the document is the one who
> decides where it should go in the ToC. This is not the case.

 as for

>  2) Manual Documentation Structure: the ToC is manually created (as in
> current book.xml files).

+0  Since it can get out of synch, I propose that a special Ant target
checks that all files in the dir are present; if not, it adds it to a
report, so we know its there but not referenced.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------