Add option for top-level division type

The `--chapters` option is replaced with `--top-level-division` which allows
users to specify the type as which top-level headers should be output. Possible
values are `section` (the default), `chapter`, or `part`.

The formats LaTeX, ConTeXt, and Docbook allow `part` as top-level division, TEI
only allows to set the `type` attribute on `div` containers.  The writers are
altered to respect this option in a sensible way.

1 files changed, 13 insertions, 10 deletions

diff --git a/MANUAL.txt b/MANUAL.txt
index 4125dba35..3c66ba658 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -661,16 +661,19 @@ Options affecting specific writers
 
 `--chapters`
 
-:   Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
-    output.  When the LaTeX document class is set to `report`, `book`,
-    or `memoir` (unless the `article` option is specified), this
-    option is implied.  If `beamer` is the output format, top-level
-    headers will become `\part{..}`.
-
-`--parts`
-:   Treat top-level headers as parts in LaTeX output.  The second level
-    headers will be chapters, i.e. `--chapters` is implied.  This does not
-    effect the `beamer` output format.
+:   Deprecated synonym for `--top-level-division=chapter`.
+
+`--top-level-division=[section|chapter|part]`
+
+:   Treat top-level headers as the given division type in LaTeX, ConTeXt,
+    DocBook, and  TEI output. The hierarchy order is part, chapter, then section;
+    all headers are shifted such that the top-level header becomes the specified
+    type.  The default is `section`. When the LaTeX document class is set to
+    `report`, `book`, or `memoir` (unless the `article` option is specified),
+    `chapter` is implied as the setting for this option.  If `beamer` is the
+    output format, specifying either `chapter` or `part` will cause top-level
+    headers to become `\part{..}`, while second-level headers remain as their
+    default type.
 
 `-N`, `--number-sections`