Use `table-of-contents` for contents of toc, make `toc` a boolean.

Changed markdown, rtf, and HTML-based templates accordingly.

This allows you to set `toc: true` in the metadata; this
previously produced strange results in some output formats.

Closes #2872.

For backwards compatibility, `toc` is still set to the
toc contents.  But it is recommended that you update templates
to use `table-of-contents` for the toc contents and `toc`
for a boolean flag.

14 files changed, 29 insertions, 17 deletions

diff --git a/data/templates/default.commonmark b/data/templates/default.commonmark
index 95d7e52cc..9f6ca96de 100644
--- a/data/templates/default.commonmark
+++ b/data/templates/default.commonmark
@@ -11,7 +11,7 @@ $include-before$
 
 $endfor$
 $if(toc)$
-$toc$
+$table-of-contents$
 
 $endif$
 $body$
diff --git a/data/templates/default.dzslides b/data/templates/default.dzslides
index ef4f03c8d..479d2f06e 100644
--- a/data/templates/default.dzslides
+++ b/data/templates/default.dzslides
@@ -186,7 +186,7 @@ $endif$
 $endif$
 $if(toc)$
 <section id="$idprefix$TOC">
-$toc$
+$table-of-contents$
 </section>
 $endif$
 $for(include-before)$
diff --git a/data/templates/default.html4 b/data/templates/default.html4
index 9745f3ba8..837b20080 100644
--- a/data/templates/default.html4
+++ b/data/templates/default.html4
@@ -57,7 +57,7 @@ $endif$
 $endif$
 $if(toc)$
 <div id="$idprefix$TOC">
-$toc$
+$table-of-contents$
 </div>
 $endif$
 $body$
diff --git a/data/templates/default.html5 b/data/templates/default.html5
index dfc66cf4e..203001f21 100644
--- a/data/templates/default.html5
+++ b/data/templates/default.html5
@@ -60,7 +60,7 @@ $endif$
 $endif$
 $if(toc)$
 <nav id="$idprefix$TOC">
-$toc$
+$table-of-contents$
 </nav>
 $endif$
 $body$
diff --git a/data/templates/default.markdown b/data/templates/default.markdown
index 95d7e52cc..9f6ca96de 100644
--- a/data/templates/default.markdown
+++ b/data/templates/default.markdown
@@ -11,7 +11,7 @@ $include-before$
 
 $endfor$
 $if(toc)$
-$toc$
+$table-of-contents$
 
 $endif$
 $body$
diff --git a/data/templates/default.plain b/data/templates/default.plain
index 95d7e52cc..9f6ca96de 100644
--- a/data/templates/default.plain
+++ b/data/templates/default.plain
@@ -11,7 +11,7 @@ $include-before$
 
 $endfor$
 $if(toc)$
-$toc$
+$table-of-contents$
 
 $endif$
 $body$
diff --git a/data/templates/default.revealjs b/data/templates/default.revealjs
index a3f39885e..4350c80e8 100644
--- a/data/templates/default.revealjs
+++ b/data/templates/default.revealjs
@@ -79,7 +79,7 @@ $endif$
 $endif$
 $if(toc)$
 <section id="$idprefix$TOC">
-$toc$
+$table-of-contents$
 </section>
 $endif$
 
diff --git a/data/templates/default.rtf b/data/templates/default.rtf
index 59e132b3f..a7f79376d 100644
--- a/data/templates/default.rtf
+++ b/data/templates/default.rtf
@@ -18,7 +18,7 @@ $if(spacer)$
 {\pard \ql \f0 \sa180 \li0 \fi0 \par}
 $endif$
 $if(toc)$
-$toc$
+$table-of-contents$
 $endif$
 $for(include-before)$
 $include-before$
diff --git a/data/templates/default.s5 b/data/templates/default.s5
index e4fa970d3..1ba3998c3 100644
--- a/data/templates/default.s5
+++ b/data/templates/default.s5
@@ -78,7 +78,7 @@ $endif$
 $endif$
 $if(toc)$
 <div class="slide" id="$idprefix$TOC">
-$toc$
+$table-of-contents$
 </div>
 $endif$
 $body$
diff --git a/data/templates/default.slideous b/data/templates/default.slideous
index c7dbb5969..7f6364cfc 100644
--- a/data/templates/default.slideous
+++ b/data/templates/default.slideous
@@ -83,7 +83,7 @@ $endif$
 $endif$
 $if(toc)$
 <div class="slide" id="$idprefix$TOC">
-$toc$
+$table-of-contents$
 </div>
 $endif$
 $body$
diff --git a/data/templates/default.slidy b/data/templates/default.slidy
index e7b3278ff..48bb254ae 100644
--- a/data/templates/default.slidy
+++ b/data/templates/default.slidy
@@ -69,7 +69,7 @@ $endif$
 $endif$
 $if(toc)$
 <div class="slide" id="$idprefix$TOC">
-$toc$
+$table-of-contents$
 </div>
 $endif$
 $body$
diff --git a/src/Text/Pandoc/Writers/HTML.hs b/src/Text/Pandoc/Writers/HTML.hs
index 45c878781..451123a6d 100644
--- a/src/Text/Pandoc/Writers/HTML.hs
+++ b/src/Text/Pandoc/Writers/HTML.hs
@@ -241,7 +241,7 @@ pandocToHtml opts (Pandoc meta blocks) = do
                  then blocks
                  else prepSlides slideLevel blocks
   toc <- if writerTableOfContents opts && slideVariant /= S5Slides
-            then tableOfContents opts sects
+            then fmap renderHtml' <$> tableOfContents opts sects
             else return Nothing
   blocks' <- liftM (mconcat . intersperse (nl opts)) $
                  mapM (elementToHtml slideLevel opts) sects
@@ -292,7 +292,11 @@ pandocToHtml opts (Pandoc meta blocks) = do
                             MathJax _ -> True
                             _         -> False) $
                   defField "quotes" (stQuotes st) $
-                  maybe id (defField "toc" . renderHtml') toc $
+                  -- for backwards compatibility we populate toc
+                  -- with the contents of the toc, rather than a
+                  -- boolean:
+                  maybe id (defField "toc") toc $
+                  maybe id (defField "table-of-contents") toc $
                   defField "author-meta" authsMeta $
                   maybe id (defField "date-meta") (normalizeDate dateMeta) $
                   defField "pagetitle" (stringifyHTML (docTitle meta)) $
diff --git a/src/Text/Pandoc/Writers/Markdown.hs b/src/Text/Pandoc/Writers/Markdown.hs
index 6c7e662bf..b951288bc 100644
--- a/src/Text/Pandoc/Writers/Markdown.hs
+++ b/src/Text/Pandoc/Writers/Markdown.hs
@@ -209,8 +209,8 @@ pandocToMarkdown opts (Pandoc meta blocks) = do
                         Nothing -> empty
   let headerBlocks = filter isHeaderBlock blocks
   toc <- if writerTableOfContents opts
-         then tableOfContents opts headerBlocks
-         else return empty
+         then render' <$> tableOfContents opts headerBlocks
+         else return ""
   -- Strip off final 'references' header if markdown citations enabled
   let blocks' = if isEnabled Ext_citations opts
                    then case reverse blocks of
@@ -220,7 +220,11 @@ pandocToMarkdown opts (Pandoc meta blocks) = do
   body <- blockListToMarkdown opts blocks'
   notesAndRefs' <- notesAndRefs opts
   let main = render' $ body <> notesAndRefs'
-  let context  = defField "toc" (render' toc)
+  let context  = -- for backwards compatibility we populate toc
+                 -- with the contents of the toc, rather than a
+                 -- boolean:
+                 defField "toc" toc
+               $ defField "table-of-contents" toc
                $ defField "body" main
                $ (if isNullMeta meta
                      then id
diff --git a/src/Text/Pandoc/Writers/RTF.hs b/src/Text/Pandoc/Writers/RTF.hs
index 6666f6549..48d31c7bf 100644
--- a/src/Text/Pandoc/Writers/RTF.hs
+++ b/src/Text/Pandoc/Writers/RTF.hs
@@ -122,7 +122,11 @@ writeRTF options doc = do
   let context = defField "body" body
               $ defField "spacer" spacer
               $ (if writerTableOfContents options
-                    then defField "toc" toc
+                    then defField "table-of-contents" toc
+                         -- for backwards compatibility,
+                         -- we populate toc with the contents
+                         -- of the toc rather than a boolean:
+                         . defField "toc" toc
                     else id)
               $ metadata
   T.pack <$>