Date: 2005-12-01 01:56:35 +0100 (Thu, 01 Dec 2005)
New Revision: 4120
removed "qa" directive idea from docs/dev/todo.txt; added it to docs/dev/rst/alternatives.txt ("not implemented"); added FAQ entry about marking up FAQs
--- trunk/docutils/FAQ.txt 2005-11-30 23:52:13 UTC (rev 4119)
+++ trunk/docutils/FAQ.txt 2005-12-01 00:56:35 UTC (rev 4120)
@@ -9,12 +9,6 @@
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.
-.. Please note that until there's a Q&A-specific construct available,
- this FAQ will use section titles for questions. Therefore
- questions must fit on one line. The title may be a summary of the
- question, with the full question in the section body.
@@ -700,6 +694,57 @@
+How can I mark up a FAQ or other list of questions & answers?
+There is no specific syntax for FAQs and Q&A lists. Here are two
+1. For a FAQ (Frequently Asked Questions, usually with answers), a
+ convenient way to mark up the questions is as section titles, with
+ the answer(s) as section content. This document is marked up in
+ this way.
+ The advantages of using section titles for questions are: sections
+ can be numbered automatically, and a table of contents can be
+ generated automatically. One limitation of this format is that
+ questions must fit on one line (section titles may not wrap, in the
+ source text). For very long questions, the title may be a summary
+ of the question, with the full question in the section body.
+2. Field lists work well as Q&A lists::
+ :Q: What kind of questions can we
+ put here?
+ :A: Any kind we like!
+ In order to separate questions, lists can be used:
+ 1. :Q: What kind of question can we
+ put here?
+ :A: Any kind we like!
+ 2. :Q: How many answers can a question have?
+ :A: It can have one,
+ :A: or more.
+ :A3: Answers can be numbered like this.
+ :A: 1. Or like this.
+ 2. We're flexible!
+ If you don't want to number or otherwise mark questions, you can
+ use an empty comment between individual field lists to separate
+ :Q: First question?
+ :A: Answer.
+ :Q: Second question?
+ :A: Answer.
--- trunk/docutils/docs/dev/rst/alternatives.txt 2005-11-30 23:52:13 UTC (rev 4119)
+++ trunk/docutils/docs/dev/rst/alternatives.txt 2005-12-01 00:56:35 UTC (rev 4120)
@@ -2095,6 +2095,49 @@
and citation references have also been added.
+Syntax for Questions & Answers
+Implement as a generic two-column marked list? As a standalone
+(non-directive) construct? (Is the markup ambiguous?) Add support to
+New elements would be required. Perhaps::
+ <!ELEMENT question_list (question_list_item+)>
+ <!ATTLIST question_list
+ numbering (none | local | global)
+ start NUMBER #IMPLIED>
+ <!ELEMENT question_list_item (question, answer*)>
+ <!ELEMENT question %text.model;>
+ <!ELEMENT answer (%body.elements;)+>
+Originally I thought of implementing a Q&A list with special syntax::
+ Q: What am I?
+ A: You are a question-and-answer
+ Q: What are you?
+ A: I am the omniscient "we".
+Where each "Q" and "A" could also be numbered (e.g., "Q1"). 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). Without special
+syntax, this directive becomes low priority.
+As described in the FAQ__, no special syntax or directive is needed
+for this application.
@@ -3076,7 +3119,6 @@
Add a "term" role for unfamiliar or specialized terminology? Probably
not; there is no real use case, and emphasis is enough for most cases.
--- trunk/docutils/docs/dev/todo.txt 2005-11-30 23:52:13 UTC (rev 4119)
+++ trunk/docutils/docs/dev/todo.txt 2005-12-01 00:56:35 UTC (rev 4120)
@@ -1284,42 +1284,6 @@
- - _`body.qa` (directive a.k.a. "faq", "questions"): Questions &
- Answers. Implement as a generic two-column marked list? As a
- standalone (non-directive) construct? (Is the markup ambiguous?)
- Add support to parts.contents.
- New elements would be required. Perhaps::
- <!ELEMENT question_list (question_list_item+)>
- <!ATTLIST question_list
- numbering (none | local | global)
- start NUMBER #IMPLIED>
- <!ELEMENT question_list_item (question, answer*)>
- <!ELEMENT question %text.model;>
- <!ELEMENT answer (%body.elements;)+>
- Originally I thought of implementing a Q&A list with special
- Q: What am I?
- A: You are a question-and-answer
- Q: What are you?
- A: I am the omniscient "we".
- Where each "Q" and "A" could also be numbered (e.g., "Q1").
- 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). Without special syntax, this directive becomes low
- _`body.example`: Examples; suggested by Simon Hefti. Semantics as
per Docbook's "example"; admonition-style, numbered, reference,
with a caption/title.
@@ -1704,6 +1668,14 @@
* Add support for _`multiple stylesheets`. See
+* Idea for field-list rendering: hanging indent::
+ Field name (bold): First paragraph of field body begins
+ with the field name inline.
+ If the first item of a field body is not a paragraph,
+ it would begin on the following line.
* Add more support for <link> elements, especially for navigation