Note
The ``text/plain`` alternative may look … odd.
I'm trying to make this readable both as text/html
e-mail and text/plain
but have little control over how the text/plain
alternative comes out. I've added extra horizontal rules before the included files to make the file contents stand out more, even though the text/html
alternative doesn't need it. Unfortunately, the automatic process that converts the text/html
alternative into the text/plan
alternative leaves blank lines before and after the file contents, which is distressing since the bug I'm talking about is about an extra blank line. Gmail, sometimes I hate you.
It turns out that the -w native
output of an RST input file with an include
directive with the :code:
option shows that there is an extra blank line at the end of the CodeBlock
in the AST. This causes the generated output for HTML, ms, LaTeX, and ConTeXt to have extra blank lines at the ends of those code blocks.
My Pandoc version is:
pandoc 2.9.2.1
Compiled with pandoc-types 1.20, texmath 0.12.0.1, skylighting 0.8.3.2
My OS information is:
Mac OS X, Version 10.15.4, Build 19E287
I generated the output to check with the following commands:
pandoc -r rst -w native --output=elii-rst.native elii.rst
pandoc -r rst -w html --output=elii-rst.html elii.rst
pandoc -r rst -w ms --output=elii-rst.ms elii.rst
pandoc -r rst -w latex --pdf-engine=xelatex --output=elii-rst.ltx elii.rst
pandoc -r rst -w context --output=elii-rst.ctx elii.rst
(I'm only going to include the native and HTML output in this message, but I did check the other output formats.)
So, for the ReStructuredText input (file elii.rst
):
Extra Line in Include Directive Output for HTML, ms, LaTeX, and ConTeXt Output
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Here's a ``include`` directive **without** a ``:code:`` option:
.. include:: three.txt
Did it have an extra line at the end? **No**, in HTML, ms, LaTeX,
and ConTeXt output. Note that this will not show up when the HTML is
rendered as a web page, just in the HTML source itself.
Here's a ``include`` directive with a ``:code:`` option:
.. include:: three.txt
:code:
Did it have an extra line at the end? **Yes**, in HTML, ms, LaTeX,
and ConTeXt output.
which includes a text file (three.txt
) using the include
directive with a :code:
option:
1st line.
2nd line.
3rd line.
the resulting native
output (elii-rst.native
) is generated:
[Header 1 ("extra-line-in-include-directive-output-for-html-ms-latex-and-context-output",[],[]) [Str "Extra",Space,Str "Line",Space,Str "in",Space,Str "Include",Space,Str "Directive",Space,Str "Output",Space,Str "for",Space,Str "HTML,",Space,Str "ms,",Space,Str "LaTeX,",Space,Str "and",Space,Str "ConTeXt",Space,Str "Output"]
,Para [Str "Here's",Space,Str "a",Space,Code ("",[],[]) "include",Space,Str "directive",Space,Strong [Str "without"],Space,Str "a",Space,Code ("",[],[]) ":code:",Space,Str "option:"]
,Para [Str "1st",Space,Str "line.",SoftBreak,Str "2nd",Space,Str "line.",SoftBreak,Str "3rd",Space,Str "line."]
,Para [Str "Did",Space,Str "it",Space,Str "have",Space,Str "an",Space,Str "extra",Space,Str "line",Space,Str "at",Space,Str "the",Space,Str "end?",Space,Strong [Str "No"],Str ",",Space,Str "in",Space,Str "HTML,",Space,Str "ms,",Space,Str "LaTeX,",SoftBreak,Str "and",Space,Str "ConTeXt",Space,Str "output.",Space,Str "Note",Space,Str "that",Space,Str "this",Space,Str "will",Space,Str "not",Space,Str "show",Space,Str "up",Space,Str "when",Space,Str "the",Space,Str "HTML",Space,Str "is",SoftBreak,Str "rendered",Space,Str "as",Space,Str "a",Space,Str "web",Space,Str "page,",Space,Str "just",Space,Str "in",Space,Str "the",Space,Str "HTML",Space,Str "source",Space,Str "itself."]
,Para [Str "Here's",Space,Str "a",Space,Code ("",[],[]) "include",Space,Str "directive",Space,Str "with",Space,Str "a",Space,Code ("",[],[]) ":code:",Space,Str "option:"]
,CodeBlock ("",[""],[]) "1st line.\n2nd line.\n3rd line.\n\n"
,Para [Str "Did",Space,Str "it",Space,Str "have",Space,Str "an",Space,Str "extra",Space,Str "line",Space,Str "at",Space,Str "the",Space,Str "end?",Space,Strong [Str "Yes"],Str ",",Space,Str "in",Space,Str "HTML,",Space,Str "ms,",Space,Str "LaTeX,",SoftBreak,Str "and",Space,Str "ConTeXt",Space,Str "output."]]
If you look at the CodeBlock element you can see it ends with \n\n
. The original included text file ends with just one \n
.
The HTML output (elii-rst.html
) is:
<h1 id="extra-line-in-include-directive-output-for-html-ms-latex-and-context-output">Extra Line in Include Directive Output for HTML, ms, LaTeX, and ConTeXt Output</h1>
<p>Here's a <code>include</code> directive <strong>without</strong> a <code>:code:</code> option:</p>
<p>1st line. 2nd line. 3rd line.</p>
<p>Did it have an extra line at the end? <strong>No</strong>, in HTML, ms, LaTeX, and ConTeXt output. Note that this will not show up when the HTML is rendered as a web page, just in the HTML source itself.</p>
<p>Here's a <code>include</code> directive with a <code>:code:</code> option:</p>
<pre class=""><code>1st line.
2nd line.
3rd line.
</code></pre>
<p>Did it have an extra line at the end? <strong>Yes</strong>, in HTML, ms, LaTeX, and ConTeXt output.</p>
I've checked and HTML, ms, LaTeX, and ConTeXt output all have these blank lines at the end of generated text for those code blocks.
Note: This message was written as RST input with include
directives with the :code:
option but does not have the extra blank lines at the ends of the included code (at least in the text/html
alternative, see the note about the text/plain
alternative at the beginning of this message) because I preprocessed it with
pandoc -s -r rst -w rst -o elii-email.rst elii-email-in.rst
which converted the include
directives with the :code:
option to inline code
directives, which don't the extra lines at the end. Very useful workaround. I use GNU Make to build all the various generated files.