[Docutils-develop] FAQ directive (was Re: Transforms...?)

[David G. <go...@us...>]

[David]
>>>> However, a simple enumerated or bulleted list will do just fine
>>>> for syntax. A directive could treat the list specially; e.g. the
>>>> first paragraph could be treated as a question, the remainder as
>>>> the answer (multiple answers could be represented by nested
>>>> lists).

[Adam]
>>> But with that aproach you have the same problem: you can only have
>>> short questions!

[David]
>> No, the question paragraph could be as long as you like.

[Adam]
> Yes, but you would not be able to have several paragraphs or other
> construct (like a table), which *might* be useful to explain the
> question more (although I agree that this is normally not the case
> for a FAQ).

In that case, extra syntax of some kind would be required (see answer
below).

>>> Wouldn't it make more sense to use a bulleted list for the
>>> questions and answers, and alternating between them (ie. the first
>>> bullet is a question, the second the answer, the third the
>>> question, and so on)?
>> 
>> No, that would be too clumsy.
> 
> Why do you think that?

Because questions and answers together form a logical unit (a "Q&A
list item").  With each question and each answer entered as individual
bullet list items, it would be hard to keep track of which is which.
You'd have to scan the contents to see if it contained question words
(why, what, etc.) or a question mark at the end.  If every "question"
list item had exactly one "answer" list item, it would be easy for the
parser to keep track, but perhaps not so easy for the reader.  Thus
the "Q" and "A" symbols that often accompany Q&A lists.

But sometimes there are questions without answers.  And sometimes
there are questions with multiple answers.  So a simple bullet list
with individual items for each question and each answer *isn't* enough
for the parser to keep track.  Both the human readers and the software
parser will need something more explicit.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/