Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
Content-Type: text/plain;
  charset="iso-8859-1"
From: David Crossley <crossley@indexgeo.com.au>
Reply-To: crossley@indexgeo.com.au
To: cocoon-dev@xml.apache.org
Subject: Re: VOTE: Restructuring FAQ file
Date: Tue, 25 Dec 2001 18:52:39 +1100
References: <3C27BAE6.6060708@a1.net>
In-Reply-To: <3C27BAE6.6060708@a1.net>
MIME-Version: 1.0
Message-Id: <01122518523900.00848@igacer>
Content-Transfer-Encoding: 8bit

Bernhard Huber wrote:
> As I examined that faq.xml is not a faq10 DTD valid document

A recent checkin of faq.xml introduced a new simple
validation error. I have patched and committed that, so
the faq.xml does now conform to the current faq10 DTD.

> I thought about restructuring the FAQ layout.
> Looking like this :
> Question
>   {faq-section-title-1}
>      {question}
>       ...
>    {faq-section-title-2}
>       {question}
>        ....
> ...
> 
> I'd like to restructure the documentation/xdocs/faq.xml FAQ file.
> 
> I'd like to change the faqv10.dtd to faqv11.dtd adding
> faq-section element like it was in Cocoon1.
> Doing this I hope to structure the Table of Content displaying
> all question as single unordered list.
> Having faq-section will help the reader to find question he
> or she is interested in more easily.

This is a good idea. However, i reckon that one large FAQ
will be clumsy and slow to use. It would be better to have
multiple faq documents, one for each topic. The faqsection
idea is still useful at the topic level.

However, let us step back a little to ask:
Why is the faq-v10.dtd (and associated stylesheet) in C2
different to the faq-v10.dtd in C1? The C1 version has the
functionality that Bernhard suggests. Whereas the C2 version
appears to be an even older version of the latest C1 DTD.

Either something was out of sync when C2 was first created,
or the functionality was deliberately repealed. There is no
message in CVS to suggest the latter.

> Thus DTD becomes:
> <!ELEMENT faqs (authors?, (faqsection | faq)+)>
> <!ATTLIST faqs %common.att;
>                %title.att;>
> 
> <!ELEMENT faq-section (faq)+>
> <!ATTLIST faq-section %common.att;
>                      %title.att;>
> 
> <!ELEMENT faq (question, answer)>
> 
> <!ELEMENT question (%content.mix;)*>
> <!ATTLIST question %common.att;>
> 
> <!ELEMENT answer (%blocks;)*>
> <!ATTLIST answer author IDREF #IMPLIED>
> 
> Moreover I'd like to classify the current FAQ having following
> faq-section titles:
> 
> Building
>   About compiling cocoon sources
> 
> Configuring             
>   About configuring sitemap,
> 
> Installing                  
>   About installing cocoon for a servlet engine
> 
> Startup Troubles
>   Questiong Cocoon does not work
> 
> Database Troubles   
>   About Cocoon and databases
> 
> Sitemap Troubles
>   About Sitemap setups
> 
> Misc
>   Anything that does not fit in the above category titles

There was some previous discussion on this topic:
 http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=99830982412347&w=2
 [PROPOSAL] xdocs/faq.xml needs split into topic-based FAQs
However, i did not have enough spare time to proceed.
We obvious need to sort out the mystery of the DTD and
stylesheet before proceeding.
--David


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org