improved subdocs documentation

git-svn-id: http://svn.code.sf.net/p/docutils/code/branches/subdocs@5400 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 14 insertions, 3 deletions

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index c56442655..722a7c612 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1116,9 +1116,10 @@ The content block of the "subdocs" directive is a single bullet list,
 the list items of which specify the files to be included as
 sub-documents.
 
-Each sub-document must contain one or more top-level sections,
-(possibly interspersed by transitions).  These sections will be
-inserted in place of the "subdocs" directive, in order.
+Each sub-document must contain one or more top-level sections
+(possibly interspersed by transitions).  There must not be any content
+in front of the first section. [#content-in-front]_ These sections
+will be inserted in place of the "subdocs" directive, in order.
 
 If a sub-document has only one top-level section, you can add a nested
 bullet list after the file name ("``chapter-2-section-1.txt``" and
@@ -1128,6 +1129,16 @@ list; it may itself contain nested bullet lists.  The sections of the
 sub-documents specified by the nested bullet lists are inserted at the
 end of the containing sub-document.
 
+.. [#content-in-front] As an obscure feature, the doctitle_xform_
+   setting is enabled for all sub-documents; this means that invisible
+   elements (such as comments, targets, etc.) in front of the document
+   title are allowed (since the DocTitle transform will move them
+   after the document title), but only if the document contains only
+   one top-level section.
+
+   .. Should this be documented at all?  Feel free to remove.
+   .. _doctitle_xform: ../../user/config.html#doctitle-xform
+
 
 .. _docset-root: