Added --slide-level option to override default.

This allows users to select a slide level below the first
header level with content.

Note that content under sections above the slide level will not appear
in slides (either in beamer or in HTML slide shows).

This is primarily useful for creating documents that can be made
into both slides and handouts (which contain additional content
outside the slides).

1 files changed, 21 insertions, 8 deletions

diff --git a/README b/README
index 2034783f0..eab0f1bcb 100644
--- a/README
+++ b/README
@@ -306,6 +306,15 @@ Options
 :   Produce LaTeX output for the `beamer` document class.
     This has an effect only for `latex` or `pdf` output.
 
+`--slide-level`=*NUMBER*
+:   Specifies that headers with the specified level create
+    slides (for `beamer`, `s5`, `slidy`, `dzslides`).  Headers
+    above this level in the hierarchy are used to divide the
+    slide show into sections; headers below this level create
+    subheads within a slide.  The default is to set the slide level
+    based on the contents of the document; see
+    [Structuring the slide show](#structuring-the-slide-show), below.
+
 `--section-divs`
 :   Wrap sections in `<div>` tags (or `<section>` tags in HTML5),
     and attach identifiers to the enclosing `<div>` (or `<section>`)
@@ -2006,20 +2015,24 @@ slide show, including linked scripts, stylesheets, images, and videos.
 Structuring the slide show
 --------------------------
 
+By default, the *slide level* is the highest header level in
+the hierarchy that is followed immediately by content, and not another
+header, somewhere in the document. In the example above, level 1 headers
+are always followed by level 2 headers, which are followed by content,
+so 2 is the slide level.  This default can be overridden using
+the `--slide-level` option.
+
 The document is carved up into slides according to the following
-rules. The *content level* is the the highest header level in the hierarchy
-that is followed immediately by content, and not another header, somewhere in
-the document. In the example above, level 1 headers are always followed by
-level 2 headers, which are followed by content, so 2 is the content level.
+rules:
 
   * A horizontal rule always starts a new slide.
 
-  * A header at the content level always starts a new slide.
+  * A header at the slide level always starts a new slide.
 
-  * Headers *below* the content level in the hierarchy create
+  * Headers *below* the slide level in the hierarchy create
     headers *within* a slide.
 
-  * Headers *above* the content level in the hierarchy create
+  * Headers *above* the slide level in the hierarchy create
     "title slides," which just contain the section title
     and help to break the slide show into sections.
 
@@ -2030,7 +2043,7 @@ level 2 headers, which are followed by content, so 2 is the content level.
 These rules are designed to support many different styles of slide show. If
 you don't care about structuring your slides into sections and subsections,
 you can just use level 1 headers for all each slide. (In that case, level 1
-will be the content level.) But you can also structure the slide show into
+will be the slide level.) But you can also structure the slide show into
 sections, as in the example above.
 
 For Slidy and S5, the file produced by pandoc with the `-s/--standalone`