Add support for list of figures (lof) and list of tables (lot) (#10029)

Two new command-line options are added:

`--lof[=true|false]`, `--list-of-figures[=true|false]`
`--lot[=true|false]`, `--list-of-tables[=true|false]`

Only docx, latex, and context are supported at this point.

Setting the `lof` and `lot` variables will also work for the formats that are
currently supported.

[API changes]

+ Lua: `list_of_figures` and `list_of_tables` can now be used in writer options.
+ Text.Pandoc.Options:  add `writerListOfFigures` and `writerListOfTables` fields
  to `WriterOptions`.
+ Text.Pandoc.App.Opt: add `optListOfFigures` and `optListOfTables` to `Opt`.

Closes #8245.

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