add --embed-resources flag (#8121)

* Add `--embed-resources` flag for `--self-contained` without implying
  `--standalone`
* Deprecate `--self-contained flag`

Closes #7331

MANUAL.txt

@@ -944,15 +944,19 @@ header when requesting a document from a URL:
 
 `--self-contained`
 
+:   *Deprecated synonym for `--embed-resources --standalone`.*
+
+`--embed-resources`
+
 :   Produce a standalone HTML file with no external dependencies, using
     `data:` URIs to incorporate the contents of linked scripts, stylesheets,
-    images, and videos. Implies `--standalone`. The resulting file should be
-    "self-contained," in the sense that it needs no external files and no net
-    access to be displayed properly by a browser. This option works only with
-    HTML output formats, including `html4`, `html5`, `html+lhs`, `html5+lhs`,
-    `s5`, `slidy`, `slideous`, `dzslides`, and `revealjs`. Scripts, images,
-    and stylesheets at absolute URLs will be downloaded; those at relative
-    URLs will be sought relative to the working directory (if the first source
+    images, and videos. The resulting file should be "self-contained," in the
+    sense that it needs no external files and no net access to be displayed
+    properly by a browser. This option works only with HTML output formats,
+    including `html4`, `html5`, `html+lhs`, `html5+lhs`, `s5`, `slidy`,
+    `slideous`, `dzslides`, and `revealjs`. Scripts, images, and stylesheets at
+    absolute URLs will be downloaded; those at relative URLs will be sought
+    relative to the working directory (if the first source
     file is local) or relative to the base URL (if the first source
     file is remote).  Elements with the attribute
     `data-external="1"` will be left alone; the documents they

doc/faqs.md

@@ -136,7 +136,7 @@ example,
 
 First, unless your target is a binary format (docx, odt, epub),
 you must use either `--extract-media` or (for HTML only)
-`--self-contained` to make the images in the ipynb container
+`--embed-resources` to make the images in the ipynb container
 available to your output file.
 
 Second, some Jupyter extensions, especially those that use JavaScript

doc/lua-filters.md

@@ -686,7 +686,7 @@ Images are added to the mediabag. For output to binary formats,
 pandoc will use images in the mediabag. For textual formats, use
 `--extract-media` to specify a directory where the files in the
 mediabag will be written, or (for HTML only) use
-`--self-contained`.
+`--embed-resources`.
 
 ``` lua
 -- Pandoc filter to process code blocks with class "abc" containing
@@ -694,7 +694,7 @@ mediabag will be written, or (for HTML only) use
 --
 -- * Assumes that abcm2ps and ImageMagick's convert are in the path.
 -- * For textual output formats, use --extract-media=abc-images
--- * For HTML formats, you may alternatively use --self-contained
+-- * For HTML formats, you may alternatively use --embed-resources
 
 local filetypes = { html = {"png", "image/png"}
                   , latex = {"pdf", "application/pdf"}
@@ -3779,7 +3779,7 @@ Usage:
 
 The `pandoc.mediabag` module allows accessing pandoc's media
 storage. The "media bag" is used when pandoc is called with the
-`--extract-media` or (for HTML only) `--self-contained` option.
+`--extract-media` or (for HTML only) `--embed-resources` option.
 
 The module is loaded as part of module `pandoc` and can either
 be accessed via the `pandoc.mediabag` field, or explicitly

src/Text/Pandoc/App.hs

@@ -351,7 +351,7 @@ convertWithOpts opts = do
                       | T.null t || T.last t /= '\n' = t <> T.singleton '\n'
                       | otherwise = t
                 textOutput <- ensureNl <$> f writerOptions doc
-                if optSelfContained opts && htmlFormat format
+                if (optSelfContained opts || optEmbedResources opts) && htmlFormat format
                    then TextOutput <$> makeSelfContained textOutput
                    else return $ TextOutput textOutput
     reports <- getLog

src/Text/Pandoc/App/CommandLineOptions.hs

@@ -439,7 +439,14 @@ options =
 
     , Option "" ["self-contained"]
                  (NoArg
-                  (\opt -> return opt { optSelfContained = True }))
+                  (\opt -> do
+                    deprecatedOption "--self-contained" "use --embed-resources --standalone"
+                    return opt { optSelfContained = True }))
+                 "" -- "Make slide shows include all the needed js and css (deprecated)"
+
+    , Option "" ["embed-resources"]
+                 (NoArg
+                  (\opt -> return opt { optEmbedResources = True }))
                  "" -- "Make slide shows include all the needed js and css"
 
     , Option "" ["request-header"]

src/Text/Pandoc/App/Opt.hs

@@ -96,7 +96,8 @@ data Opt = Opt
     , optNumberOffset          :: [Int]   -- ^ Starting number for sections
     , optSectionDivs           :: Bool    -- ^ Put sections in div tags in HTML
     , optIncremental           :: Bool    -- ^ Use incremental lists in Slidy/Slideous/S5
-    , optSelfContained         :: Bool    -- ^ Make HTML accessible offline
+    , optSelfContained         :: Bool    -- ^ Make HTML accessible offline (deprecated)
+    , optEmbedResources        :: Bool    -- ^ Make HTML accessible offline
     , optHtmlQTags             :: Bool    -- ^ Use <q> tags in HTML
     , optHighlightStyle        :: Maybe Text -- ^ Style to use for highlighted code
     , optSyntaxDefinitions     :: [FilePath]  -- ^ xml syntax defs to load
@@ -415,6 +416,8 @@ doOpt (k,v) = do
       parseJSON v >>= \x -> return (\o -> o{ optIncremental = x })
     "self-contained" ->
       parseJSON v >>= \x -> return (\o -> o{ optSelfContained = x })
+    "embed-resources" ->
+      parseJSON v >>= \x -> return (\o -> o{ optEmbedResources = x })
     "html-q-tags" ->
       parseJSON v >>= \x -> return (\o -> o{ optHtmlQTags = x })
     "highlight-style" ->
@@ -622,6 +625,7 @@ defaultOpts = Opt
     , optSectionDivs           = False
     , optIncremental           = False
     , optSelfContained         = False
+    , optEmbedResources        = False
     , optHtmlQTags             = False
     , optHighlightStyle        = Just "pygments"
     , optSyntaxDefinitions     = []