From 6ff4972ca9ed194aae36d6a3cdfa90e4050713da Mon Sep 17 00:00:00 2001
From: Elliot Bobrow <77182873+ebobrow@users.noreply.github.com>
Date: Tue, 14 Jun 2022 16:00:18 -0700
Subject: [PATCH] add `--embed-resources` flag (#8121)
* Add `--embed-resources` flag for `--self-contained` without implying
`--standalone`
* Deprecate `--self-contained flag`
Closes #7331
---
MANUAL.txt | 18 +++++++++++-------
doc/faqs.md | 2 +-
doc/lua-filters.md | 6 +++---
src/Text/Pandoc/App.hs | 2 +-
src/Text/Pandoc/App/CommandLineOptions.hs | 9 ++++++++-
src/Text/Pandoc/App/Opt.hs | 6 +++++-
6 files changed, 29 insertions(+), 14 deletions(-)
diff --git a/MANUAL.txt b/MANUAL.txt
index 44946813d..34b87c93e 100644
--- a/MANUAL.txt
+++ b/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
diff --git a/doc/faqs.md b/doc/faqs.md
index 2dffcbf16..70d95cfa8 100644
--- a/doc/faqs.md
+++ b/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
diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 9f3bb6928..f64c77298 100644
--- a/doc/lua-filters.md
+++ b/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
diff --git a/src/Text/Pandoc/App.hs b/src/Text/Pandoc/App.hs
index 1a694abb0..2bddcf1a3 100644
--- a/src/Text/Pandoc/App.hs
+++ b/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
diff --git a/src/Text/Pandoc/App/CommandLineOptions.hs b/src/Text/Pandoc/App/CommandLineOptions.hs
index 2db1fe53c..ce6ff4a35 100644
--- a/src/Text/Pandoc/App/CommandLineOptions.hs
+++ b/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"]
diff --git a/src/Text/Pandoc/App/Opt.hs b/src/Text/Pandoc/App/Opt.hs
index ae1248833..5d15560d8 100644
--- a/src/Text/Pandoc/App/Opt.hs
+++ b/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 = []