pages tagged documentyakkinghttp://yakking.branchable.com/tags/document/yakkingikiwiki2016-02-17T12:00:13ZWriting documents with Pandochttp://yakking.branchable.com/posts/pandoc/Richard Maw2016-02-17T12:00:13Z2016-02-17T12:00:06Z
<p><a href="http://pandoc.org/">pandoc</a> is a tool for converting documents from one format
into another.</p>
<p>You could use it to read an <a href="https://en.wikipedia.org/wiki/Html">HTML</a> document
and convert it to <a href="https://daringfireball.net/projects/markdown/">markdown</a>.</p>
<p>I prefer to use it to produce nice <a href="https://en.wikipedia.org/wiki/Portable_Document_Format">PDF</a>s
but using <a href="https://daringfireball.net/projects/markdown/">markdown</a> instead of <a href="https://en.wikipedia.org/wiki/LaTeX">LaTeX</a>.</p>
<p>To do this,
you probably want both <a href="http://pandoc.org/">pandoc</a> and <a href="https://en.wikipedia.org/wiki/TeX_Live">texlive-full</a>.</p>
<p>Unfortunately, this can be a rather large thing to install:</p>
<pre><code>$ sudo apt-get install pandoc texlive-full
Reading package lists... Done
Building dependency tree
Reading state information... Done
…
The following NEW packages will be installed
aglfn chktex cm-super cm-super-minimal context context-modules
dvidvi dvipng feynmf fonts-cabin fonts-comfortaa
fonts-crosextra-caladea fonts-crosextra-carlito fonts-ebgaramond
fonts-ebgaramond-extra fonts-font-awesome fonts-freefont-otf
fonts-gfs-artemisia fonts-gfs-baskerville fonts-gfs-bodoni-classic
fonts-gfs-complutum fonts-gfs-didot fonts-gfs-didot-classic
fonts-gfs-gazis fonts-gfs-neohellenic fonts-gfs-olga
fonts-gfs-porson fonts-gfs-solomos fonts-gfs-theokritos
fonts-hosny-amiri fonts-inconsolata fonts-ipaexfont-gothic
fonts-ipaexfont-mincho fonts-junicode fonts-lato
fonts-linuxlibertine fonts-lmodern fonts-lobster fonts-lobstertwo
fonts-oflb-asana-math fonts-roboto fonts-sil-gentium
fonts-sil-gentium-basic fonts-sil-gentiumplus fonts-stix
fonts-texgyre fragmaster lacheck latex-cjk-all latex-cjk-chinese
latex-cjk-chinese-arphic-bkai00mp latex-cjk-chinese-arphic-bsmi00lp
latex-cjk-chinese-arphic-gbsn00lp latex-cjk-chinese-arphic-gkai00mp
latex-cjk-common latex-cjk-japanese latex-cjk-japanese-wadalab
latex-cjk-korean latex-cjk-thai latexdiff latexmk lcdf-typetools
libfile-homedir-perl libfile-which-perl libintl-perl libplot2c2
libpoppler-qt4-4 libpotrace0 libpstoedit0v5 libptexenc1 libsynctex1
libtexlua52 libtexluajit2 libtext-unidecode-perl libxml-libxml-perl
libxml-namespacesupport-perl libxml-sax-base-perl
libxml-sax-expat-perl libxml-sax-perl libzzip-0-13 lmodern m-tx
musixtex pandoc pandoc-data pfb2t1c2pfb pmx prerex
preview-latex-style prosper ps2eps pstoedit psutils purifyeps
tex-common tex-gyre tex4ht tex4ht-common texinfo texlive-base
texlive-bibtex-extra texlive-binaries texlive-extra-utils
texlive-font-utils texlive-fonts-extra texlive-fonts-extra-doc
texlive-fonts-recommended texlive-fonts-recommended-doc
texlive-formats-extra texlive-full texlive-games
texlive-generic-extra texlive-generic-recommended
texlive-humanities texlive-humanities-doc texlive-lang-african
texlive-lang-arabic texlive-lang-chinese texlive-lang-cjk
texlive-lang-cyrillic texlive-lang-czechslovak texlive-lang-english
texlive-lang-european texlive-lang-french texlive-lang-german
texlive-lang-greek texlive-lang-indic texlive-lang-italian
texlive-lang-japanese texlive-lang-korean texlive-lang-other
texlive-lang-polish texlive-lang-portuguese texlive-lang-spanish
texlive-latex-base texlive-latex-base-doc texlive-latex-extra
texlive-latex-extra-doc texlive-latex-recommended
texlive-latex-recommended-doc texlive-luatex texlive-math-extra
texlive-metapost texlive-metapost-doc texlive-music texlive-omega
texlive-pictures texlive-pictures-doc texlive-plain-extra
texlive-pstricks texlive-pstricks-doc texlive-publishers
texlive-publishers-doc texlive-science texlive-science-doc
texlive-xetex tipa ttf-adf-accanthis ttf-adf-gillius
ttf-adf-universalis vprerex
0 to upgrade, 161 to newly install, 0 to remove and 0 not to upgrade.
Need to get 1,782 MB of archives.
After this operation, 3,466 MB of additional disk space will be used.
</code></pre>
<p>You may find it convenient to define a simple <a href="https://www.gnu.org/software/make/">make</a> rule
for turning <a href="http://pandoc.org/">pandoc</a> <a href="https://daringfireball.net/projects/markdown/">markdown</a> documents into <a href="https://en.wikipedia.org/wiki/Portable_Document_Format">PDF</a>s,
as follows:</p>
<pre><code>$ cat >Makefile <<'EOF'
%.pdf : %.mdwn
pandoc -o $@ $<
EOF
</code></pre>
<p>Now you may write markdown files,
and convert them into <a href="https://en.wikipedia.org/wiki/Portable_Document_Format">PDF</a>s,
simply by running <code>make foo.pdf</code>
to turn <code>foo.mdwn</code> into <code>foo.pdf</code>.</p>
<p>If you use a <a href="https://en.wikipedia.org/wiki/Portable_Document_Format">PDF</a> viewer such as <a href="https://wiki.gnome.org/Apps/Evince">evince</a>,
if you have the document open,
and then generate a new version,
your viewer will refresh itself to view the new version.</p>
<p>You can make your <a href="https://en.wikipedia.org/wiki/Portable_Document_Format">PDF</a> viewer show live updates to your document
by combining this make rule with an <a href="http://man7.org/linux/man-pages/man7/inotify.7.html">inotify</a> watch command:</p>
<pre><code>$ while true; do inotifywait -e close_write,move_self foo.mdwn; make foo.pdf; done
</code></pre>
<p>You can write in-line <a href="https://en.wikipedia.org/wiki/LaTeX">LaTeX</a> to include content
that is not expressible in <a href="https://daringfireball.net/projects/markdown/">markdown</a>.</p>
<p><a href="https://daringfireball.net/projects/markdown/">markdown</a> also lacks a way of providing metadata,
but <a href="http://pandoc.org/">pandoc</a> has an extension
called <a href="http://pandoc.org/README.html#extension-yaml_metadata_block">yaml_metadata_block</a>,
which parses the header of a document as a <a href="http://yaml.org/">YAML</a> document.</p>
<pre><code>---
title: Foo
author: Joe Bloggs
header-includes:
- \usepackage{bytefield}
geometry: margin=3cm
---
# Title
This is an example bytefield figure:
\begin{bytefield}{16}
\wordbox{1}{A 16-bit field} \\
\bitbox{8}{8 bits} & \bitbox{8}{8 more bits} \\
\wordbox{2}{A 32-bit field. Note that text wraps within the box.}
\end{bytefield}
</code></pre>
<p>Without the header, you would otherwise need to write a separate file
containing the <code>\usepackage{bytefield}</code> directive,
and invoke pandoc with <code>--template=use-bytefield.latex</code>.</p>