parse markdown in begin and end by using macros Begin and End like jg…

…m/pandoc#2453
mathematicalcoffee · Nov 19, 2016 · 2bf80e3 · 2bf80e3
1 parent b4a1ceb
commit 2bf80e3
Show file tree

Hide file tree

Showing 3 changed files with 146 additions and 106 deletions.
diff --git a/Readme.md b/Readme.md
@@ -47,3 +47,34 @@ columnwidth: '0.3\paperwidth' # default is 0.3\paperwidth
 
 The macro `\colwid` is available for use within the template, and the `calc` package allows for further specifications like `2\colwid`.
 It is set to `0.3\paperwidth` by default but you can override it in the YAML frontmatter if you like.
+
+## Markdown
+
+One problem is that when writing beamer, a lot of `\begin{}` and `\end{}` are used (block, column, ...) and pandoc will not parse text inside a block. Since the entire poster is usually in columns and blocks, this means you end up writing the whole poster in latex anyway, defeating the purpose of using pandoc. To get around this, we use the workaround in [jgm/pandoc #2453](https://github.com/jgm/pandoc/issues/2453#issuecomment-219233316) and provide aliases `\Begin{}` and `\End{}`, and the contents of these *will* be parsed as markdown/pandoc.
+
+However if the begin/end block has an optional argument (e.g. `\Begin{figure}[t]`, this will not be properly treated; rather, the trailing `[t]` will be treated as literal text by Pandoc. In cases like these you need to use `\nopandoc` (which is just the identity command) as in `\nopandoc{\begin{figure}[t]}`, which (surprisingly) works.
+
+A number of other unpleasant side-effects of parsing within LaTeX are that if you have comments using `%`, they'll be parsed as literal percent signs by pandoc; pandoc recognises the HTML-style comments only.
+
+And also if you indent your latex/text for readability within blocks, if it's indented more than 4 spaces it'll probably get treated as a code block. So unindent it :/
+
+## Troubleshooting
+
+### Font problems (mathkerncmssi)
+
+```
+!pdfTeX error: pdflatex (file mathkerncmssi17): Font mathkerncmssi17 at 864 not
+ found
+ ==> Fatal error occurred, no output PDF file produced!
+
+kpathsea: Running mktexpk --mfmode / --bdpi 600 --mag 1+264/600 --dpi 864 mathkerncmssi17
+mktexpk: don't know how to create bitmap font for mathkerncmssi17.
+mktexpk: perhaps mathkerncmssi17 is missing from the map file.
+kpathsea: Appending font creation commands to missfont.log.
+```
+
+This worked:
+
+```
+./updmap-sys --enable Map sansmathaccent.map
+```
diff --git a/example.rmd b/example.rmd
@@ -1,12 +1,4 @@
 ---
-# NOTE: although this is a rmd, markdown won't work. You should write it in TeX.
-# (if I make a Rnw then it won't use pandoc so the YAML header is ignored)
-# Hmm. I need knitr output to be in TeX. But if I save as Rnw it goes
-# knitr {rtex -> tex} then pdflatex {tex -> pdf} without going through pandoc
-#  [which is handy for the template]
-#
-# I guess what I want is
-# knitr {rtex -> tex} then pandoc {tex -> tex; purely to insert the template} then pdflatex.
 title: Unnecessarily complicated research title
 date: "`r format(Sys.time(), format='%Y-%m-%d %H:%M:%S %z')`"
 author:
@@ -49,127 +41,131 @@ beamerconfig:
 papersize: a0 # the default.
 columnwidth: '0.3\paperwidth' # the default is 0.3\textwidth and you get \colwid set to it.
 ---
-\DefineShortVerb{\`}
 <!--
 %-----------------------------------------------------------
 % When including a figure in your poster, be sure that the commands are typed in the following order:
-% \begin{figure}
+% \Begin{figure}
 % \includegraphics[...]{...}
 % \caption{...}
-% \end{figure}
+% \End{figure}
 % That is, put the \caption after the \includegraphics
 %-----------------------------------------------------------
 -->
-\begin{center}%
-  \begin{minipage}{.7\textwidth}%
-    \begin{exampleblock}{Summary}%
-    Here is a barebones document for an A0 poster.
-    It was based off http://www.nathanieljohnston.com/2009/08/latex-poster-template/ but has been modified to work as an R Markdown file to be compiled with knitr (rmd to md) and then pandoc (md to tex) and then latex (tex to pdf).
+\Begin{center}
+  \Begin{minipage}{.7\textwidth}
+    \Begin{exampleblock}{Summary}
+Here is a barebones document for an A0 poster.
+It was based off [this poster provided by Nathaniel Johnston](http://www.nathanieljohnston.com/2009/08/latex-poster-template/) but has been heavily modified to work as an R Markdown file to be compiled with knitr (rmd to md) and then pandoc (md to tex) and then latex (tex to pdf).
 
-    This comes with its downsides (notably: that you can't use markdown within the blocks!!), but meh.
-    \end{exampleblock}%
-  \end{minipage}%
-\end{center}
+In order to use markdown within blocks, you must use `\Begin{}` and `\End{}` for these blocks and their parents. Contents of these are parsed. Optional arguments to the begin/end are *not* properly handled, to do this you need to `\nopandoc{\begin{figure}[t]}` for example. Yes, it's stupid.
+
+An undesirable side-effect of this is that the odd `%` comment symbols you litter throughout your TeX will be treated as literal by pandoc (!). Use HTML-style comments `<!-- comment -->` instead.
+
+And if you indent the LaTeX, content of your blocks etc for readability, pandoc will probably think they're code blocks :/ This kind of sucks.
+
+So not ideal, but better than nothing (you can always use `\begin{}` and `\end{}` if you want nothing within to be parsed).
+    \End{exampleblock}
+  \End{minipage}
+\End{center}
 \vskip1in
-\begin{columns}[t] % align top
-  \begin{column}{\colwid}
-    \begin{block}{The Setup}
-      Required files:
-
-      \begin{itemize}
-        \item `poste.rmd`, this example R Markdown file.
-        \item `poster-pandoc-template.tex`, the pandoc template for the poster.
-        \item `beamerthemeconfposter.sty`, the beamer style file (I \emph{think} you may be able to substitute your own, but I used the one from \url{https://www.overleaf.com/latex/templates/landscape-beamer-poster-template/vjpmsxxdvtqk}
-      \end{itemize}
+\nopandoc{\begin{columns}[t]} <!-- align top. If I use Begin, pandoc takes the [t] ... -->
+  \Begin{column}{\colwid}
+    \Begin{block}{The Setup}
+Required files:
+
+* `poster.md`, this example R Markdown file.
+* `poster-pandoc-template.tex`, the pandoc template for the poster.
+* `beamerthemeconfposter.sty`, the beamer style file (I **think** you may be able to substitute your own, but I used the one from [here (
+Computational Physics and Biophysics Group, Jacobs University, with modification by Nathaniel Johnston and Vel Gayevskiy)](https://www.overleaf.com/latex/templates/landscape-beamer-poster-template/vjpmsxxdvtqk)
 
-      Also: 
-      \begin{itemize}
-        \item LaTeX packages `latexbeamer`, `pgf` (Tikz), `beamerposter`
-        \item R package `knitr`
-        \item pandoc
-      \end{itemize}
-
-      I've only tested this compiling from Rstudio.
-      You can set authors and affiliations in the YAML metadata, along with limited beamer styling (block rounded corners and so on).
-
-    \end{block}
+Also: 
+
+* LaTeX packages `latexbeamer`, `pgf` (Tikz), `beamerposter`
+* R package `knitr`
+* pandoc
+
+I've only tested this compiling from Rstudio.
+  You can set authors and affiliations in the YAML metadata, along with limited beamer styling (block rounded corners and so on).
+    \End{block}
     \vskip2ex
     \begin{alertblock}{An Alert Block}
-      The alert block environment looks like this. It also has justified text, but it has a border and a light background to make it stand out. You can create one like so:
+The alert block environment looks like this. It also has justified text, but it has a border and a light background to make it stand out. You can create one like so:
       \begin{semiverbatim}
-        {\color{red}\\begin}\{{\color{blue}alertblock}\}\{Title\}\newline
+        {\color{red}\\Begin}\{{\color{blue}alertblock}\}\{Title\}\newline
         \hskip1ex.......\newline
-        {\color{red}\\end}\{{\color{blue}alertblock}\}
+        {\color{red}\\End}\{{\color{blue}alertblock}\}
       \end{semiverbatim}
     \end{alertblock}
-  \end{column}
-  % column spanning two columns.
-  \begin{column}{2\colwid}
-    \begin{block}{Altering Column Spans}
-      You can make columns that span multiple other columns relatively easily. Lengths are defined in the template that make columns look normal-ish if you want to use a three-column layout like this poster. If you want to use a different number of columns, you can specify the base column width in the YAML preamble.
+  \End{column}
+  <!-- column spanning two columns. -->
+  \Begin{column}{2\colwid}
+    \Begin{block}{Altering Column Spans}
+You can make columns that span multiple other columns relatively easily. Lengths are defined in the template that make columns look normal-ish if you want to use a three-column layout like this poster. If you want to use a different number of columns, you can specify the base column width in the YAML preamble.
 
-      In particular, in the YAML:
-      \begin{verbatim}
-        columnwidth: '0.3\paperwidth'
-      \end{verbatim}
+In particular, in the YAML:
+
+~~~
+columnwidth: '0.3\paperwidth'
+~~~
       
-      You get `\colwid` for free, and using the `calc` package you can get multiples of it.
-    \end{block}
-
-    \begin{columns}[t,totalwidth=2.1\colwid]	% split up that two-column-wide column
-      \begin{column}{\colwid}
+You get `\colwid` for free, and using the `calc` package you can get multiples of it.
+  \End{block}
+   <!-- split up the 2-col wide column --> 
+   \nopandoc{\begin{columns}[t,totalwidth=2.1\colwid]}
+      \Begin{column}{\colwid}
         \setbeamercolor{block title}{fg=red,bg=white}%frame color
         \setbeamercolor{block body}{fg=black,bg=white}%body color
-        \begin{block}{Block Colours}
-          For the standard blocks there are two colours; one for the title and one for the block body:\\
-          \begin{semiverbatim}
-            {\color{red}\\setbeamercolor}\{block title\}\{fg=red,bg=white\}
-            {\color{red}\\setbeamercolor}\{block  body\}\{fg=black,bg=white\}
-          \end{semiverbatim}
-          The \emph{fg} colour sets the text colour and \emph{bg} sets the background colour.
-          For the normal blocks it makes no sense to use a background colour other than white. You \emph{can} change it, but it will look weird!
-        \end{block} % block colours
-        
-		    \begin{block}{Todo}
-		    \begin{itemize}
-  		    \item the only crucial thing in the sty is the headline definition, right? Can that be moved to the poster-pandoc.sty?
-  		    \item knitr...
-  		    \item the font looks funny.
-  		    \item theming: user puts in a theme e.g. warsaw first for colours if they like
-  		    \item more control over font size
-  		    \item spacing between institutions seems too large
-  		    \item logos
-  		    \item bibliography without explicit `\bibitem`, ie integrate biblatex?
-  		    \item more spacing between blocks//standard spacing
-  		    \item easy styling and so on.
-  		    \item [WONT] explicit control over separator width?
-		    \end{itemize}
-		    \end{block} % todo
-
+        \Begin{block}{Block Colours}
+For the standard blocks there are two colours; one for the title and one for the block body:
+
+\begin{semiverbatim}
+  {\color{red}\\setbeamercolor}\{block title\}\{fg=red,bg=white\}
+  {\color{red}\\setbeamercolor}\{block  body\}\{fg=black,bg=white\}
+\end{semiverbatim}
+
+The `fg` colour sets the text colour and `bg` sets the background colour.
+For the normal blocks it makes no sense to use a background colour other than white. You *can* change it, but it will look weird!
+        \End{block}<!-- Block colours -->
+		    \Begin{block}{Todo}
+
+* the only crucial thing in the sty is the headline definition, right? Can that be moved to the poster-pandoc.sty?
+* knitr...
+* the font looks funny.
+* theming: user puts in a theme e.g. warsaw first for colours if they like
+* more control over font size
+* spacing between institutions seems too large
+* logos
+* bibliography without explicit `\bibitem`, ie integrate biblatex?
+* more spacing between blocks//standard spacing
+* easy styling and so on.
+* [WONT] explicit control over separator width?
+
+<!---->\End{block}<!-- that stupidness is because pandoc will treat this as a
+                       code block o'wise and I want it indented for eadability. -->
         \begin{block}{References}
           Some references and a graphic to show you how it's done:
 
-		      \small{\begin{thebibliography}{99}%@TODO incorporate with a bibtex
+		      \small{\Begin{thebibliography}{99}%@TODO incorporate with a bibtex
 		        \bibitem{KLPL06} D.~W. Kribs, R. Laflamme, D. Poulin, M. Lesosky, Quantum Inf. \& Comp. \textbf{6} (2006), 383-399.
 		        \bibitem{zanardi97} P. Zanardi, M. Rasetti, Phys. Rev. Lett. \textbf{79},  3306 (1997).
-		      \end{thebibliography}}
-		    \end{block} % references
-      \end{column}
-      \begin{column}{\colwid}
-        \begin{block}{Demo}
-          Some maths:
-          \begin{equation*}
-          \sum_{i=1}^{\infty} \frac{1}{i}\text{ does not converge.}
-          \end{equation*}
-          
-          A figure:
-			    \begin{figure}
-            \includegraphics[width=\colwid]{example-image}
-            \caption{A caption.}
-			    \end{figure}
-        \end{block} % demo
-      \end{column}
-    \end{columns}
-    \vskip2.5ex
-  \end{column}
- \end{columns}
+		      \End{thebibliography}}
+		    \end{block} <!-- references -->
+   \End{column}
+   \Begin{column}{\colwid}
+    \Begin{block}{Demo}
+Some maths:
+\[
+\sum_{i=1}^{\infty} \frac{1}{i}\text{ does not converge.}
+\]
+
+A figure:
+\begin{figure}
+  \includegraphics[width=\colwid]{example-image}
+  \caption{A caption.}
+\end{figure}
+    \End{block} <!-- demo -->
+   \End{column}
+  \End{columns}
+  \vskip2.5ex
+ \End{column}
+\End{columns}
diff --git a/poster-pandoc-template.tex b/poster-pandoc-template.tex
@@ -51,6 +51,19 @@
 \setbeamercolor{$beamerconfig.colours.name$}{$beamerconfig.colours.style$}
 $endfor$
 
+%-----------------------------------------------------------
+% Pandoc stuff
+%-----------------------------------------------------------
+% hack for markdown-in-blocks
+\let\Begin\begin
+\let\End\end
+% the above doesn't work if there are optional arguments. so
+% then you have to [e.g.] \nopandoc{\begin{figure}[t]}
+\newcommand{\nopandoc}[1]{#1}
+% it uses tightlist in itemize (if you don't like it just try
+%  e.g. \def\tightlist{}
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
 %-----------------------------------------------------------
 % User-included preamble
 %-----------------------------------------------------------