Lacking Natural Simplicity (Posts about make)https://tkurtbond.github.io/categories/make.atom2024-01-23T18:49:40ZT. Kurt BondNikolaMaking digest-sized pages with pandoc and ms outputhttps://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/2020-03-13T14:01:10-04:002020-03-13T14:01:10-04:00T. Kurt Bond<aside class="admonition note">
<p class="admonition-title">Note</p>
<p>After I wrote this post, I made a last minute check of the options
to <span class="app">pandoc</span> and found that the <code class="docutils literal"><span class="pre">--pdf-engine-opt=</span></code> option
does exactly what I want. How embarrassing. So I changed this
post, showing both the easy way and the hard way to do it.</p>
</aside>
<p>I use <a class="reference external" href="https://pandoc.org/">pandoc</a> to produce digest-sized pages (5½×8½ inches) in PDF
documents from <a class="reference external" href="https://en.wikipedia.org/wiki/ReStructuredText">ReStructuredText</a>. I have a <span class="app">ms</span> output template,
<span class="file">digest2.ms</span> in <span class="file">~/pandoc/templates</span> that sets the page
width and page height correctly. Unfortunately, there is no way to
set the papersize properly in the template. <a class="footnote-reference brackets" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#heirloomtroff" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p>
<p>Luckily, <span class="app">pandoc</span> has the <code class="docutils literal"><span class="pre">--pdf-engine-opt=</span></code> option to pass
options to the PDF engine that <span class="app">pandoc</span> is using, in this case
<span class="app">pdfroff</span>. In the case of <span class="app">ms</span> output the thing to do is
pass the argument <code class="docutils literal"><span class="pre">--pdf-engine-opt=-P-p8.5i,5.5i</span></code> <a class="footnote-reference brackets" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#recursively" id="footnote-reference-2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>,
like below.</p>
<p><a class="reference external" href="https://tkurtbond.github.io/listings/GNUmakefile.pandoc-digest-pdf-engine-opt.html">GNUmakefile.pandoc-digest-pdf-engine-opt</a> <a class="reference external" href="https://tkurtbond.github.io/listings/GNUmakefile.pandoc-digest-pdf-engine-opt">(Source)</a></p>
<div class="code"><pre class="code make"><a id="rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-1" name="rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-1" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-1"></a><span class="nf">%.digest.ms.pdf </span><span class="o">:</span><span class="w"> </span>%.<span class="n">rst</span>
<a id="rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-2" name="rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-2" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-2"></a><span class="w"> </span>pandoc<span class="w"> </span>-s<span class="w"> </span>-r<span class="w"> </span>rst<span class="w"> </span>-w<span class="w"> </span>ms<span class="w"> </span>--template<span class="o">=</span>digest2<span class="w"> </span><span class="k">$(</span>VARIABLES<span class="k">)</span><span class="w"> </span><span class="se">\</span>
<a id="rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-3" name="rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-3" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_1b861f39b7eb4146bf4f1a5ef76b3610-3"></a><span class="w"> </span>--output<span class="o">=</span><span class="nv">$@</span><span class="w"> </span>--pdf-engine-opt<span class="o">=</span>-P-p8.5i,5.5i<span class="w"> </span>$<
</pre></div>
<p>Unfortunately when I originally had this need for digest pages I
hadn't realized that the <code class="docutils literal"><span class="pre">--pdf-engine-opt=</span></code> option existed.</p>
<p>So I used <code class="docutils literal">pandoc <span class="pre">--verbose</span></code> and found the <span class="app">pdfroff</span> invocation
<span class="app">pandoc</span> uses, and made my <span class="app">pandoc</span> invocation output
<span class="app">ms</span> instead of PDF, then passed it through a <span class="app">pdfroff</span>
command with the added <code class="docutils literal"><span class="pre">-P-p8.5i,5.5i</span></code> argument. Here's what I put
in my <span class="file">GNUmakefile</span>:</p>
<p><a class="reference external" href="https://tkurtbond.github.io/listings/GNUmakefile.pandoc-digest-save-ms.html">GNUmakefile.pandoc-digest-save-ms</a> <a class="reference external" href="https://tkurtbond.github.io/listings/GNUmakefile.pandoc-digest-save-ms">(Source)</a></p>
<div class="code"><pre class="code make"><a id="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-1" name="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-1" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_ef3c96423c2740559ec3b1ded58b3fc4-1"></a><span class="nf">%.digest.ms.pdf </span><span class="o">:</span><span class="w"> </span>%.<span class="n">rst</span>
<a id="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-2" name="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-2" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_ef3c96423c2740559ec3b1ded58b3fc4-2"></a><span class="w"> </span>pandoc<span class="w"> </span>-s<span class="w"> </span>-r<span class="w"> </span>rst<span class="w"> </span>-w<span class="w"> </span>ms<span class="w"> </span>-s<span class="w"> </span>--template<span class="o">=</span>digest2<span class="w"> </span><span class="k">$(</span>VARIABLES<span class="k">)</span><span class="w"> </span><span class="se">\</span>
<a id="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-3" name="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-3" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_ef3c96423c2740559ec3b1ded58b3fc4-3"></a><span class="w"> </span>--output<span class="o">=</span><span class="nv">$*</span>.ms<span class="w"> </span>$<
<a id="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-4" name="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-4" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_ef3c96423c2740559ec3b1ded58b3fc4-4"></a><span class="w"> </span>pdfroff<span class="w"> </span>-ms<span class="w"> </span>-mpdfmark<span class="w"> </span>-e<span class="w"> </span>-t<span class="w"> </span>-k<span class="w"> </span>-KUTF-8<span class="w"> </span>--no-toc-relocation<span class="w"> </span><span class="se">\</span>
<a id="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-5" name="rest_code_ef3c96423c2740559ec3b1ded58b3fc4-5" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_ef3c96423c2740559ec3b1ded58b3fc4-5"></a><span class="w"> </span>-P-p8.5i,5.5i<span class="w"> </span><span class="nv">$*</span>.ms<span class="w"> </span>><span class="w"> </span><span class="nv">$@</span>
</pre></div>
<p>Or, if you don't care about having the <span class="app">ms</span> output for debugging,
you could do it as a pipeline:</p>
<p><a class="reference external" href="https://tkurtbond.github.io/listings/GNUmakefile.pandoc-digest-pipeline.html">GNUmakefile.pandoc-digest-pipeline</a> <a class="reference external" href="https://tkurtbond.github.io/listings/GNUmakefile.pandoc-digest-pipeline">(Source)</a></p>
<div class="code"><pre class="code make"><a id="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-1" name="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-1" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_79e9e21f839c4c93b7a82a151d0f6b07-1"></a><span class="nf">%.digest.ms.pdf </span><span class="o">:</span><span class="w"> </span>%.<span class="n">rst</span>
<a id="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-2" name="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-2" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_79e9e21f839c4c93b7a82a151d0f6b07-2"></a><span class="w"> </span>pandoc<span class="w"> </span>-s<span class="w"> </span>-r<span class="w"> </span>rst<span class="w"> </span>-w<span class="w"> </span>ms<span class="w"> </span>-s<span class="w"> </span>--template<span class="o">=</span>digest2<span class="w"> </span><span class="k">$(</span>VARIABLES<span class="k">)</span><span class="w"> </span><span class="se">\</span>
<a id="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-3" name="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-3" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_79e9e21f839c4c93b7a82a151d0f6b07-3"></a><span class="w"> </span>--output<span class="o">=</span>-<span class="w"> </span>$<<span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="se">\</span>
<a id="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-4" name="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-4" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_79e9e21f839c4c93b7a82a151d0f6b07-4"></a><span class="w"> </span>pdfroff<span class="w"> </span>-ms<span class="w"> </span>-mpdfmark<span class="w"> </span>-e<span class="w"> </span>-t<span class="w"> </span>-k<span class="w"> </span>-KUTF-8<span class="w"> </span>--no-toc-relocation<span class="w"> </span><span class="se">\</span>
<a id="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-5" name="rest_code_79e9e21f839c4c93b7a82a151d0f6b07-5" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#rest_code_79e9e21f839c4c93b7a82a151d0f6b07-5"></a><span class="w"> </span>-P-p8.5i,5.5i<span class="w"> </span>-<span class="w"> </span>><span class="nv">$@</span>
</pre></div>
<p>There are still some instances where this technique of having
<span class="app">pandoc</span> output the <span class="app">ms</span> source directly and pass it through
<span class="app">pdfroff</span> yourself. For instance, if you have to do some
massaging of the <span class="app">ms</span> source, like changing <code class="docutils literal"><span class="pre">.RS/.RE</span></code> to
<code class="docutils literal"><span class="pre">.QS/.QE</span></code> to get around the problem with block quotes in <span class="app">ms</span>
output in the current <span class="app">pandoc</span> release, discussed <a class="reference external" href="https://tkurtbond.github.io/posts/2020/03/11/pandoc-discuss-post-can-the-rsre-macros-in-ms-output-be-replaced-with-qsqe/">here</a>.</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="heirloomtroff" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#footnote-reference-1">1</a><span class="fn-bracket">]</span></span>
<p>Heirloom Troff (originally at <a class="reference external" href="http://heirloom.sourceforge.net/doctools.html">H1</a>, but now <em>I
think</em> more up to date at <a class="reference external" href="http://n-t-roff.github.io/heirloom/doctools.html">H2</a> and <a class="reference external" href="https://github.com/n-t-roff/heirloom-doctools">H3</a>) has the <code class="docutils literal">.mediasize</code> and
<code class="docutils literal">.papersize</code> commands for that.</p>
</aside>
<aside class="footnote brackets" id="recursively" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="https://tkurtbond.github.io/posts/2020/03/13/making-digest-sized-pages-with-pandoc-and-ms-output/#footnote-reference-2">2</a><span class="fn-bracket">]</span></span>
<p>Amusingly, <span class="app">pandoc</span> passes the
<code class="docutils literal"><span class="pre">--pdf-engine-opt=-P-p8.5i,5.5i</span></code> argument to <span class="app">pdfroff</span>,
which passes the <code class="docutils literal"><span class="pre">-P-p8.5i,5.5i</span></code> part to <span class="app">groff</span>, which
passes the <code class="docutils literal"><span class="pre">-p8.5i,5.5i</span></code> part to the (final) post processor — I'm
not sure if <em>that</em> is <span class="app">grops</span> or <span class="app">gropdf</span>.</p>
</aside>
</aside>