add command line and API support for list of figures (lof) and list o…

…f tables (lot)

use lof and lot options in latex and context
implement lof and lot for docx

[command line] add options `--lof[=true|false]`, `--list-of-figures[=true|false]`
[command line] add options `--lot[=true|false]`, `--list-of-tables[=true|false]`

[API change] `WriterOptions`: add property `list_of_figures`
[API change] `WriterOptions`: add property `list_of_tables`

[API change] `Options`: add `writerListOfFigures :: Bool`
[API change] `Options`: add `writerListOfTables :: Bool`

[API change] `App/Opt`: add `optListOfFigures :: Bool`
[API change] `App/Opt`: add `optListOfTables :: Bool`

Co-authored-by: John MacFarlane <jgm@berkeley.edu>

MANUAL.txt

@@ -870,6 +870,22 @@ header when requesting a document from a URL:
     of contents.  The default is 3 (which means that level-1, 2, and 3
     headings will be listed in the contents).
 
+`--lof[=true|false]`, `--list-of-figures[=true|false]`
+
+:   Include an automatically generated list of figures (or, in
+    some formats, an instruction to create one) in the output
+    document. This option has no effect unless `-s/--standalone`
+    is used, and it only has an effect on `latex`, `context`, and
+    `docx` output.
+
+`--lot[=true|false]`, `--list-of-tables[=true|false]`
+
+:   Include an automatically generated list of tables (or, in
+    some formats, an instruction to create one) in the output
+    document. This option has no effect unless `-s/--standalone`
+    is used, and it only has an effect on `latex`, `context`, and
+    `docx` output.
+
 `--strip-comments[=true|false]`
 
 :   Strip out HTML comments in the Markdown or Textile source,
@@ -2027,6 +2043,22 @@ To include the built-in citeproc filter, use either `citeproc` or
 | ```                              | ```                               |
 +----------------------------------+-----------------------------------+
 | ```                              | ``` yaml                          |
+| --list-of-figures                | list-of-figures: true             |
+| ```                              | ```                               |
++----------------------------------+-----------------------------------+
+| ```                              | ``` yaml                          |
+| --lof                            | lof: true                         |
+| ```                              | ```                               |
++----------------------------------+-----------------------------------+
+| ```                              | ``` yaml                          |
+| --list-of-tables                 | list-of-tables: true              |
+| ```                              | ```                               |
++----------------------------------+-----------------------------------+
+| ```                              | ``` yaml                          |
+| --lot                            | lot: true                         |
+| ```                              | ```                               |
++----------------------------------+-----------------------------------+
+| ```                              | ``` yaml                          |
 | --incremental                    | incremental: true                 |
 | ```                              | ```                               |
 +----------------------------------+-----------------------------------+
@@ -3079,7 +3111,8 @@ Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
 #### Front matter
 
 `lof`, `lot`
-:   include list of figures, list of tables
+:   include list of figures, list of tables (can also be set using
+    `--lof/--list-of-figures`, `--lot/--list-of-tables`)
 
 `thanks`
 :   contents of acknowledgments footnote after document title

data/templates/default.openxml

@@ -49,6 +49,12 @@ $for(include-before)$
 $endfor$
 $if(toc)$
     $toc$
+$endif$
+$if(lof)$
+    $lof$
+$endif$
+$if(lot)$
+    $lot$
 $endif$
     $body$
 $for(include-after)$

doc/pandoc-server.md

@@ -190,6 +190,14 @@ the first one given is the default.
 
 :   Depth of sections to include in the table of contents.
 
+`list-of-figures` (boolean, default false)
+
+:   Include a list of figures (in supported formats).
+
+`list-of-tables` (boolean, default false)
+
+:   Include a list of tables (in supported formats).
+
 `strip-comments` (boolean, default false)
 
 :   Causes HTML comments to be stripped in Markdown or Textile

pandoc-lua-engine/src/Text/Pandoc/Lua/Marshal/WriterOptions.hs

@@ -145,6 +145,16 @@ typeWriterOptions = deftype "WriterOptions"
     (pushBool, writerIncremental)
     (peekBool, \opts x -> opts{ writerIncremental = x })
 
+  , property "list_of_figures"
+    "Include list of figures"
+    (pushBool, writerListOfFigures)
+    (peekBool, \opts x -> opts{ writerListOfFigures = x })
+
+  , property "list_of_tables"
+    "Include list of tables"
+    (pushBool, writerListOfTables)
+    (peekBool, \opts x -> opts{ writerListOfTables = x })
+
   , property "listings"
     "Use listings package for code"
     (pushBool, writerListings)

pandoc-server/src/Text/Pandoc/Server.hs

@@ -312,6 +312,8 @@ server = convertBytes
              , writerSyntaxMap = defaultSyntaxMap
              , writerVariables = optVariables opts
              , writerTableOfContents = optTableOfContents opts
+             , writerListOfFigures = optListOfFigures opts
+             , writerListOfTables = optListOfTables opts
              , writerIncremental = optIncremental opts
              , writerHTMLMathMethod = optHTMLMathMethod opts
              , writerNumberSections = optNumberSections opts

src/Text/Pandoc/App/CommandLineOptions.hs

@@ -410,6 +410,22 @@ options =
                  "NUMBER")
                  "" -- "Number of levels to include in TOC"
 
+    , Option "" ["lof", "list-of-figures"]
+                (OptArg
+                 (\arg opt -> do
+                        boolValue <- readBoolFromOptArg "--lof/--list-of-figures" arg
+                        return opt { optListOfFigures = boolValue })
+                 "true|false")
+               "" -- "Include list of figures"
+
+    , Option "" ["lot", "list-of-tables"]
+                (OptArg
+                 (\arg opt -> do
+                        boolValue <- readBoolFromOptArg "--lot/--list-of-tables" arg
+                        return opt { optListOfTables = boolValue })
+                 "true|false")
+               "" -- "Include list of tables"
+
     , Option "N" ["number-sections"]
                   (OptArg
                    (\arg opt -> do

src/Text/Pandoc/App/Opt.hs

@@ -107,6 +107,8 @@ data Opt = Opt
     , optFrom                  :: Maybe Text  -- ^ Reader format
     , optTo                    :: Maybe Text  -- ^ Writer format
     , optTableOfContents       :: Bool    -- ^ Include table of contents
+    , optListOfFigures         :: Bool    -- ^ Include list of figures
+    , optListOfTables          :: Bool    -- ^ Include list of tables
     , optShiftHeadingLevelBy   :: Int     -- ^ Shift heading level by
     , optTemplate              :: Maybe FilePath  -- ^ Custom template
     , optVariables             :: Context Text    -- ^ Template variables to set
@@ -192,6 +194,8 @@ instance FromJSON Opt where
        <*> o .:? "from"
        <*> o .:? "to"
        <*> o .:? "table-of-contents" .!= optTableOfContents defaultOpts
+       <*> o .:? "list-of-figures" .!= optListOfFigures defaultOpts
+       <*> o .:? "list-of-tables" .!= optListOfTables defaultOpts
        <*> o .:? "shift-heading-level-by" .!= optShiftHeadingLevelBy defaultOpts
        <*> o .:? "template"
        <*> o .:? "variables" .!= optVariables defaultOpts
@@ -480,6 +484,14 @@ doOpt (k,v) = do
       parseJSON v >>= \x -> return (\o -> o{ optTableOfContents = x })
     "toc" ->
       parseJSON v >>= \x -> return (\o -> o{ optTableOfContents = x })
+    "list-of-figures" ->
+      parseJSON v >>= \x -> return (\o -> o{ optListOfFigures = x })
+    "lof" ->
+      parseJSON v >>= \x -> return (\o -> o{ optListOfFigures = x })
+    "list-of-tables" ->
+      parseJSON v >>= \x -> return (\o -> o{ optListOfTables = x })
+    "lot" ->
+      parseJSON v >>= \x -> return (\o -> o{ optListOfTables = x })
     "from" ->
       parseJSON v >>= \x -> return (\o -> o{ optFrom = x })
     "reader" ->
@@ -744,6 +756,8 @@ defaultOpts = Opt
     , optFrom                  = Nothing
     , optTo                    = Nothing
     , optTableOfContents       = False
+    , optListOfFigures         = False
+    , optListOfTables          = False
     , optShiftHeadingLevelBy   = 0
     , optTemplate              = Nothing
     , optVariables             = mempty

src/Text/Pandoc/App/OutputSettings.hs

@@ -229,6 +229,8 @@ optToOutputSettings scriptingEngine opts = do
         , writerVariables        = variables
         , writerTabStop          = optTabStop opts
         , writerTableOfContents  = optTableOfContents opts
+        , writerListOfFigures    = optListOfFigures opts
+        , writerListOfTables     = optListOfTables opts
         , writerHTMLMathMethod   = optHTMLMathMethod opts
         , writerIncremental      = optIncremental opts
         , writerCiteMethod       = optCiteMethod opts

src/Text/Pandoc/Options.hs

@@ -309,6 +309,8 @@ data WriterOptions = WriterOptions
   , writerVariables         :: Context Text -- ^ Variables to set in template
   , writerTabStop           :: Int    -- ^ Tabstop for conversion btw spaces and tabs
   , writerTableOfContents   :: Bool   -- ^ Include table of contents
+  , writerListOfFigures     :: Bool   -- ^ Include list of figures
+  , writerListOfTables      :: Bool   -- ^ Include list of tables
   , writerIncremental       :: Bool   -- ^ True if lists should be incremental
   , writerHTMLMathMethod    :: HTMLMathMethod  -- ^ How to print math in HTML
   , writerNumberSections    :: Bool   -- ^ Number sections in LaTeX
@@ -352,6 +354,8 @@ instance Default WriterOptions where
                       , writerVariables        = mempty
                       , writerTabStop          = 4
                       , writerTableOfContents  = False
+                      , writerListOfFigures    = False
+                      , writerListOfTables     = False
                       , writerIncremental      = False
                       , writerHTMLMathMethod   = PlainMath
                       , writerNumberSections   = False

src/Text/Pandoc/Writers/ConTeXt.hs

@@ -104,6 +104,8 @@ pandocToConTeXt options (Pandoc meta blocks) = do
   mblang <- fromBCP47 (getLang options meta)
   st <- get
   let context =   defField "toc" (writerTableOfContents options)
+                $ defField "lof" (writerListOfFigures options)
+                $ defField "lot" (writerListOfTables options)
                 $ defField "placelist"
                    (mconcat . intersperse ("," :: Doc Text) $
                      take (writerTOCDepth options +

src/Text/Pandoc/Writers/Docx/OpenXML.hs

@@ -44,6 +44,7 @@ import Text.Pandoc.Translations (Term(Abstract), translateTerm)
 import Text.Pandoc.MediaBag (lookupMedia, MediaItem(..))
 import qualified Text.Pandoc.Translations as Term
 import qualified Text.Pandoc.Class.PandocMonad as P
+import qualified Text.Pandoc.Builder as B
 import Text.Pandoc.UTF8 (fromTextLazy)
 import Text.Pandoc.Definition
 import Text.Pandoc.Highlighting (highlight)
@@ -170,6 +171,56 @@ makeTOC opts = do
       ])
     ]] -- w:sdt
 
+makeLOF :: (PandocMonad m) => WriterOptions -> WS m [Element]
+makeLOF opts = do
+  let lofCmd = "TOC \\h \\z \\t \"Image Caption\" \\c" :: Text
+  lofTitle <- B.toList <$> B.text <$> translateTerm Term.ListOfFigures
+  title <- withParaPropM (pStyleM "TOC Heading") (blocksToOpenXML opts [Para lofTitle])
+  return
+    [mknode "w:sdt" [] [
+      mknode "w:sdtPr" [] (
+        mknode "w:docPartObj" []
+          [mknode "w:docPartGallery" [("w:val","List of Figures")] (),
+          mknode "w:docPartUnique" [] ()]
+         -- w:docPartObj
+      ), -- w:sdtPr
+      mknode "w:sdtContent" [] (title ++ [ Elem $
+        mknode "w:p" [] (
+          mknode "w:r" [] [
+            mknode "w:fldChar" [("w:fldCharType","begin"),("w:dirty","true")] (),
+            mknode "w:instrText" [("xml:space","preserve")] lofCmd,
+            mknode "w:fldChar" [("w:fldCharType","separate")] (),
+            mknode "w:fldChar" [("w:fldCharType","end")] ()
+          ] -- w:r
+        ) -- w:p
+      ]) -- w:sdtContent
+    ]] -- w:sdt
+
+makeLOT :: (PandocMonad m) => WriterOptions -> WS m [Element]
+makeLOT opts = do
+  let lotCmd = "TOC \\h \\z \\t \"Table Caption\" \\c" :: Text
+  lotTitle <- B.toList <$> B.text <$> translateTerm Term.ListOfTables
+  title <- withParaPropM (pStyleM "TOC Heading") (blocksToOpenXML opts [Para lotTitle])
+  return
+    [mknode "w:sdt" [] [
+      mknode "w:sdtPr" [] (
+        mknode "w:docPartObj" []
+          [mknode "w:docPartGallery" [("w:val","List of Tables")] (),
+          mknode "w:docPartUnique" [] ()]
+         -- w:docPartObj
+      ), -- w:sdtPr
+      mknode "w:sdtContent" [] (title ++ [ Elem $
+        mknode "w:p" [] (
+          mknode "w:r" [] [
+            mknode "w:fldChar" [("w:fldCharType","begin"),("w:dirty","true")] (),
+            mknode "w:instrText" [("xml:space","preserve")] lotCmd,
+            mknode "w:fldChar" [("w:fldCharType","separate")] (),
+            mknode "w:fldChar" [("w:fldCharType","end")] ()
+          ] -- w:r
+        ) -- w:p
+      ]) -- w:sdtContent
+    ]] -- w:sdt
+
 -- | Convert Pandoc document to rendered document contents plus two lists of
 -- OpenXML elements (footnotes and comments).
 writeOpenXML :: PandocMonad m
@@ -178,6 +229,8 @@ writeOpenXML :: PandocMonad m
 writeOpenXML opts (Pandoc meta blocks) = do
   setupTranslations meta
   let includeTOC = writerTableOfContents opts || lookupMetaBool "toc" meta
+  let includeLOF = writerListOfFigures opts || lookupMetaBool "lof" meta
+  let includeLOT = writerListOfTables opts || lookupMetaBool "lot" meta
   abstractTitle <- case lookupMeta "abstract-title" meta of
       Just (MetaBlocks bs)   -> pure $ stringify bs
       Just (MetaInlines ils) -> pure $ stringify ils
@@ -224,13 +277,23 @@ writeOpenXML opts (Pandoc meta blocks) = do
   toc <- if includeTOC
             then makeTOC opts
             else return []
+  lof <- if includeLOF
+            then makeLOF opts
+            else return []
+  lot <- if includeLOT
+            then makeLOT opts
+            else return []
   metadata <- metaToContext opts
                  (fmap (vcat . map (literal . showContent)) . blocksToOpenXML opts)
                  (fmap (hcat . map (literal . showContent)) . inlinesToOpenXML opts)
                  meta
   let context = resetField "body" body
               . resetField "toc"
                    (vcat (map (literal . showElement) toc))
+              . resetField "lof"
+                   (vcat (map (literal . showElement) lof))
+              . resetField "lot"
+                   (vcat (map (literal . showElement) lot))
               . resetField "title" title
               . resetField "subtitle" subtitle
               . resetField "author" author

src/Text/Pandoc/Writers/LaTeX.hs

@@ -194,6 +194,8 @@ pandocToLaTeX options (Pandoc meta blocks) = do
                     $ lookupMetaInlines "nocite" meta
 
   let context  =  defField "toc" (writerTableOfContents options) $
+                  defField "lof" (writerListOfFigures options) $
+                  defField "lot" (writerListOfTables options) $
                   defField "toc-depth" (tshow
                                         (writerTOCDepth options -
                                               if stHasChapters st