You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Jeff Turner <je...@apache.org> on 2003/05/05 14:07:50 UTC
FAQ DTD changes #2
On Mon, May 05, 2003 at 11:46:43AM -0000, jefft@apache.org wrote:
> jefft 2003/05/05 04:46:43
>
> Modified: . status.xml
> src/resources/schema/dtd faq-v12.mod
> src/resources/stylesheets faq2document.xsl
> Log:
> Add <elaboration> element to <question>. The content of <elaboration> is
> displayed in the FAQ body, but not in the FAQ question list.
...
> <action dev="JT" type="update" context="schemas">
> + Add <elaborate> to the FAQ <question> element, which lets one
> + provide some background (elaboration) in the FAQ body without cluttering
> + the FAQ list.
> + </action>
I've found that occasionally, a question requires a lot of words to
explain. Perhaps it includes an example, stacktrace, URL or mailing list
reference. These long questions make the TOC hard to scan quickly. So
the idea is to have an <elaboration> part which is only displayed in the
FAQ body:
<faq>
<question>
How can I ...
<elaboration>For example, so that I could...</elaboration>
</question>
<answer>
...
</answer>
</faq>
--Jeff
Re: FAQ DTD changes #2
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Nicola Ken Barozzi wrote:
>> <question>
>> <common>How can I ...</common>
>> <elaboration>For example, so that I could...</elaboration>
>> </question>
>
>
> Seems fine (apart from the "common" name that I don't like).
No prob. Lacking imagination, I took the first name not yet
obviously assigned to some other semantics. On a second thought
it's indeed the same as the FAQ part.
> But how would you describe this WRT this:
>
> <section>
> <title>AAA</title>
> BBBB
> </section>
What about "Aaaaaaargh!" :-)
J.Pietschmann
Re: FAQ DTD changes #2
Posted by Nicola Ken Barozzi <ni...@apache.org>.
J.Pietschmann wrote, On 05/05/2003 21.37:
> Jeff Turner wrote:
>
>>> Add <elaboration> element to <question>.
>
>
> An interesting and quite useful enhancement!
> However:
...
> 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>
Seems fine (apart from the "common" name that I don't like). I didn't
think of it myself when I saw it, but it makes sense.
But how would you describe this WRT this:
<section>
<title>AAA</title>
BBBB
</section>
> Further enhancements, like adding more metadata, might be easier to
> fit in.
>
> BTW will you rename the FAQ <part> to <faqsection>?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: FAQ DTD changes #2
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Jeff Turner wrote:
> What is out-of-band about <elaboration> in the FAQ?
Well, given the following
[inlining elaborations]
> That's a feature not a bug ;P
I think I got the intention a bit wrong. If you actually want
to inline elaborations, your approach is ok.
This raises the question why you wrote you needed an xsl:if.
I'd do
<xsl:template match="elaboration" mode="index"/>
<xsl:template match="elaboration">
<!-- normal operation -->
<xsl:apply-templates/>
</xsl:template>
Am I missing something?
It might be an issue that <question> is expected to result
in a single text block. If <elaboration> may suddenly introduce
block-like stuff, like your <pre> above, things may become
interesting.
An alternative idea would be to keep the full info in <question>
and resort to a separate optional <title> for the index:
<qa>
<title>NullPointerException at Forrest startup</title>
<question>
I am trying to run Forrest v0.4 on a W2K box running JDK 1.3.1
and keep getting a NullPointerException on startup. The
stacktrace I get is:
<pre>
....
</pre>
What am I doing wrong?
</question>
<answer>
...
[snip]
> Optional metadata of course. If metadata has some obvious benefit, people
> will use it.
The problem is that the metadata is often only really beneficial
if it is consistently used. Take your example of the FAQ creation
date, mostly for the benefit of flagging new FAQs. Someone adds
an important FAQ in a hurry without supplying a date, or mistyping
it grossly, or the patch with a proper adding date wasn't applied
until the "new" period passed. The FAQ is not flagged. People get
upset, but probably no action is taken. The next FAQ is also added
without date. There is no longer an obvious benefit in providing an
adding date in patches. The feature falls into disuse.
Well, the demise is not inevitable, but I've often seen a small
fluktuation in available ressources causing it ("...will do later...").
Once a certain amount of data with unmaintained metadata accumulated,
not even the most dedicated fellows will bother to fix it.
If you want metadata to be useful:
1. Make it *mandatory*, not optional.
2. Provide automated plausibility checks.
3. Preferably provide some automation tools.
4. Fix all the old data.
5. Sell its advantages aggressively.
>>> <meta name="..."> ... </meta> tag allowed inside <faq>.
>>*Cough*! Do you want people asking why the encoding they
>>added to a FAQ "doesn't work"?
> Character encoding? Unsupported tags inside <meta>?
The possible problem I see is that <meta> for documents goes more
or less unchanged into the HTML (I may be wrong here), which might
cause people to think the FAQ <meta> has a very similar purpose,
and that the possible <meta> keys are basically to the ones often
seen in HTML.
This could be an interesting application for namespaces:
The document/XHTML schema defines stuff for general purpose layout
and closely associated stuff, like <xhtml:meta> or <doc:meta> for
general purpose document level metadata.
The FAQ schema could use <faq:meta> for FAQ metadata and faq:section
for structuring FAQs, compared to <xhtml:section> or <doc:section>
for structuring general purpose documents.
J.Pietschmann
Re: FAQ DTD changes #2
Posted by Jeff Turner <je...@apache.org>.
On Tue, May 06, 2003 at 11:34:34PM +0200, J.Pietschmann wrote:
> Jeff Turner wrote:
> >>Mixed text works best when it is used for, well, mixed text.
> ...
> >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).
>
> That's not really critical, usually. It's still all content.
> You were mixing text content and a sort of out-of band data.
What is out-of-band about <elaboration> in the FAQ?
> This *is* critical.
>
> Note that a DTD would have a content model of
> <!ELEMENT question (#PCDATA|elaboration)*>
> which would also validate
> <question>
> Bla bla bla
> <elaboration>stuff</elaboration>
> more bla bla bla
> <elaboration>more stuff</elaboration>
> even more bla bla bla
> </question>
> Ouch!
That's a feature not a bug ;P
<question>
I am trying to run Forrest
<elaboration>v0.4 on a W2K box running JDK 1.3.1</elaboration>
and keep getting a NullPointerException on startup.
<elaboration>The stacktrace I get is:
<pre>
....
</pre>
</elaboration>
What am I doing wrong?
</question>
> >Extra metadata for FAQs would be great.
>
> Oh, certainly. The problem with most metadata is that it tends to
> fall into disuse unless automatically managed.
Optional metadata of course. If metadata has some obvious benefit, people
will use it.
> >We can do this in faq-v20 with a <meta name="..."> ... </meta> tag
> >allowed inside <faq>.
>
> *Cough*! Do you want people asking why the encoding they
> added to a FAQ "doesn't work"?
Character encoding? Unsupported tags inside <meta>?
--Jeff
> J.Pietschmann
>
Re: FAQ DTD changes #2
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Jeff Turner wrote:
>>Mixed text works best when it is used for, well, mixed text.
...
> 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).
That's not really critical, usually. It's still all content.
You were mixing text content and a sort of out-of band data.
This *is* critical.
Note that a DTD would have a content model of
<!ELEMENT question (#PCDATA|elaboration)*>
which would also validate
<question>
Bla bla bla
<elaboration>stuff</elaboration>
more bla bla bla
<elaboration>more stuff</elaboration>
even more bla bla bla
</question>
Ouch!
> Extra metadata for FAQs would be great.
Oh, certainly. The problem with most metadata is that it tends to
fall into disuse unless automatically managed.
> - 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.
Neat ideas. But don't expect this to be added consistently
unless either
- committing fails unless plausible values are entered (or
send nag mails, or something else obnoxious), or
- there is a dead-easy to use app for updating FAQs which takes
care of the metadata, and only a minority uses more-or-less-
plain-text editors and gets shouted at if the valuable
metadata is missing...
Note that if there is even only a temorary problem with keeping
the metadata accurate, it no longer provides added value, and
the whole idea usually collapses very quickly.
You wouldn't belive how often I experienced this already.
> We can do this in faq-v20 with a <meta name="..."> ... </meta> tag
> allowed inside <faq>.
*Cough*! Do you want people asking why the encoding they
added to a FAQ "doesn't work"?
>>BTW will you rename the FAQ <part> to <faqsection>?
> I have done so for faq-v20a.
Finally!
J.Pietschmann
Re: FAQ DTD changes #2
Posted by Jeff Turner <je...@apache.org>.
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
>
Re: FAQ DTD changes #2
Posted by "J.Pietschmann" <j3...@yahoo.de>.
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. 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>
Further enhancements, like adding more metadata, might be easier to
fit in.
BTW will you rename the FAQ <part> to <faqsection>?
J.Pietschmann