forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: FAQ DTD changes #2
Date Tue, 06 May 2003 11:50:18 GMT
On Mon, May 05, 2003 at 09:37:18PM +0200, J.Pietschmann wrote:
> Jeff Turner wrote:
> >> Add <elaboration> element to <question>.
> 
> An interesting and quite useful enhancement!
> However:
> 
> >  <question>
> >    How can I ...
> >    <elaboration>For example, so that I could...</elaboration>
> >  </question>
> 
> Mixed text works best when it is used for, well, mixed text. I
> have the gut feeling that mixing text and <elaboration> at the
> same level does not quite fit this model.

Warning bells were going off when I found myself using <xsl:if> to
implement it, but I couldn't figure out exactly why it's bad.  Perhaps
you can explain it better.  Btw, the doc-v12 DTD (and XHTML) both have a
'flow' data type which mixes block-level and inline elements ('flow' is
used in li, dd, etc).

> This means the standard text should probably also enclosed in an
> element in this case, maybe like
> 
>   <question>
>     <common>How can I ...</common>
>     <elaboration>For example, so that I could...</elaboration>
>   </question>

Hmm.. rather kills ease of use.

In RT-mode..

How about introducing the <elaboration> element in the main doc-v20 DTD?
It could be rendered either:

 - As a sidebar.
 - As a [?] superscript link, which opens a popup with the elaboration
   text.
 - Text that displays somewhere (in a tooltip?) on mouseover.

For instance, from Forrest's index.xml, we could change:

  ...Forrest uses these to render the XML source content into a website
  via command-line, robot, or a dynamic web application.</p>

to:

  ...Forrest uses these to render the XML source content into a website
  via command-line, <span id="robot">robot</span>, or a dynamic web application.</p>

  <elaboration idref="robot">
    <title>Automated Publishing with Forrest</title>
    <p>
      Forrest provides some plumbing to provide an automated
      documentation building system.  An deployment of this can be seen
      <a href="http://forrestbot.cocoondev.org>here</a>.
    </p>
  </elaboration>

> Further enhancements, like adding more metadata, might be easier to
> fit in.

Extra metadata for FAQs would be great.  Stuff I'd like to have:

 - Date the FAQ was added, rendered as a "New!" icon for FAQs that are
   less than X weeks old.
 - Version of software the FAQ applies to, allowing automatic
   filtering-out of irrelevant FAQs.
 - Author, mailing list ref, etc.

We can do this in faq-v20 with a <meta name="..."> ... </meta> tag
allowed inside <faq>. 

> BTW will you rename the FAQ <part> to <faqsection>?

I have done so for faq-v20a.


--Jeff

> J.Pietschmann
> 

Mime
View raw message