Enable usage of "self-contained" without "standalone" for HTML

[mjfs]

Using the option self-contained currently implies the option standalone when producing HTML output. This is not desired in all use cases, especially not when using Pandoc as an external renderer in certain context (Content Management System, Templating etc.).

It would be useful to have an option to produce data URIs (i.e. not requiring external images) for a part of included document, rendering only HTML body in that case without other HTML declarations (that are a part of the master document).

Introducing an additional Pandoc option would perhaps be the cleanest way of addressing the mentioned use case, since it would not break existing usage, e.g. something like embed-resources (or embedded-references or embed-media

[jgm]

Yeah, this makes a lot of sense to me.
The only problem is that the suggested change has the potential to break a lot of existing workflows, since people may have gotten used to specifying --self-contained without --standalone.

[mjfs]

Actually, the alternative that I have mentioned in the last paragraph would not have any impact on existing workflows:

1. self-contained would imply standalone as well as embed-resources (or embedded-references or embed-media or whichever option name would be chosen)

2. embed-resources would then be the option that would enable generating data URIs

Both, new use workflows would be covered as well as compatibility with existing ones assured by using this approach.

[jgm]

So, if understand correctly, you're suggesting that --self-contained be factored into --embed-resources + --standalone.

That may be the best way forward (and actually --embed-resources is a better name than --self-contained).

[jgm]

IF we did this I'd be inclined to deprecate --self-contained.

[cagix]

maybe you can keep --self-contained for one or two releases and emit a deprecation warning? that would allow people to adjust their workflows.

[mjfs]

@jgm: Yes, that is what I was suggesting. I am however not entirely sure regarding the depreciation of existing option (--self-contained), since even with the introduction of new one (--embed-resources), one could still see the existing one as a shortcut (for --embed-resources + --standalone). Counterargument is perhaps the fact that --self-contained does not come with a shorter form as is the case for --standalone. Apart from that I guess it is more the matter of general policy regarding composite options and personal preference. Depreciation (with eventual removal further on) seems cleaner to me, since composites can lead to ambiguity, but I do not have strong feelings regarding that either way.

[jgm]

maybe you can keep --self-contained for one or two releases and emit a deprecation warning? that would allow people to adjust their workflows.

That's the idea. The reason for deprecating is just that it's confusing to have two options that are so similar.

[jgm]

Note: in the mean time, here's a workaround: just use a custom template containing simply

$body$

[mjfs]

@jgm: Thank you for suggested workaround, I have already put it into good use.

Less important, but possibly also helpful, to avoid the Pandoc warning when executing the command, --metadata title=" " can be added to the parameters that one uses (this does of course depend on the use case and input data).