forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nicola Ken Barozzi" <nicola...@apache.org>
Subject Re: [Vote] Automatic vs. Manual Documentation Structure
Date Fri, 15 Mar 2002 15:40:11 GMT
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)
---------------------------------------------------------------------


Mime
View raw message