forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Piroumian, Konstantin" <KPiroum...@flagship.ru>
Subject RE: [Vote] Automatic vs. Manual Documentation Structure
Date Fri, 15 Mar 2002 15:47:18 GMT
> Ok folks,
> 
> this is a major issue and we have to decide what to do.
> 
> There are two solutions:
> 
>  1) Automatic Documentation Structure: the ToC is 
> auto-generated out of
> file system layout or database tree layout.
> 
>  2) Manual Documentation Structure: the ToC is manually created (as in
> current book.xml files).
> 
> The first option is more technologically advanced, but has some major
> drawbacks:
> 
>  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.
> 
> So, even if the manual solution appears less technologically 
> advanced, I
> believe it's the way to go. This is the direction I vote to take, even
> if this is in contrast with my past assumption (simply, I changed my
> mind!)
> 
> Place your vote or alternative proposals.

What about a combined ToC file with some hypotetical directory-xpath
logicsheet:

<menu>
	<menu-item href="exp.htm">Explicit item</menu-item>
	<dir:for-each select="*.xml">
		<menu-item href="."><dir:value-of
select="/document/@label"></menu-item>
	</dir:for-each>
</menu>

Seems a little complicated, but rather flexible.

Konstantin
> 
> -- 
> Stefano Mazzocchi      One must still have chaos in oneself to be
>                           able to give birth to a dancing star.
> <stefano@apache.org>                             Friedrich Nietzsche
> --------------------------------------------------------------------
> 
> 

Mime
View raw message