presentation.tex

\documentclass[smaller,ignorenonframetext,]{beamer}
\setbeamertemplate{caption}[numbered]
\setbeamertemplate{caption label separator}{:}
\setbeamercolor{caption name}{fg=normal text.fg}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage{fixltx2e} % provides \textsubscript
\usepackage{lmodern}
\ifxetex
  \usepackage{fontspec,xltxtra,xunicode}
  \defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
  \newcommand{\euro}{€}
\else
  \ifluatex
    \usepackage{fontspec}
    \defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
    \newcommand{\euro}{€}
  \else
    \usepackage[T1]{fontenc}
    \usepackage[utf8]{inputenc}
      \fi
\fi
% use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
% use microtype if available
\IfFileExists{microtype.sty}{\usepackage{microtype}}{}
\usepackage{listings}
\usepackage{url}
\usepackage{graphicx}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>\textheight0.8\textheight\else\Gin@nat@height\fi}
\makeatother
% Scale images if necessary, so that they will not overflow the page
% margins by default, and it is still possible to overwrite the defaults
% using explicit options in \includegraphics[width, height, ...]{}
\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}

% Comment these out if you don't want a slide with just the
% part/section/subsection/subsubsection title:
\AtBeginPart{
  \let\insertpartnumber\relax
  \let\partname\relax
  \frame{\partpage}
}
\AtBeginSection{
  \let\insertsectionnumber\relax
  \let\sectionname\relax
  \frame{\sectionpage}
}
\AtBeginSubsection{
  \let\insertsubsectionnumber\relax
  \let\subsectionname\relax
  \frame{\subsectionpage}
}

\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
\setlength{\emergencystretch}{3em}  % prevent overfull lines
\setcounter{secnumdepth}{0}

%%% Enhance support for image inclusion
%
% Resize images that are too large (in width or height).
% Pandoc already includes a similar hack for the width,
% but images can also be too heigh.
%
% Depending on the beamer template used and the resulting
% available space, you might want to adjust the target
% maximum height (here: 0.65, which is 65% of the frame
% height) to another value. Remember headline, footline
% and titles may need additional space.
%
% References:
% - https://groups.google.com/forum/#!topic/pandoc-discuss/6H-6NcFtFUk
% - http://tex.stackexchange.com/a/67462/11198
\usepackage{letltxmacro}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else0.65\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>0.65\textheight 0.65\textheight\else0.65\Gin@nat@height\fi}
\makeatother
\AtBeginDocument{
  \LetLtxMacro\OOldincludegraphics\includegraphics
  \renewcommand{\includegraphics}[2][]{%
    \OOldincludegraphics[#1,width=\maxwidth,height=\maxheight,keepaspectratio]{#2}}
}


%%% Custom example LaTeX header code %%%
%
% This is example LaTeX header code I commonly use to enhance
% default behavior, fix some quirks or import packages I use.
% These can be savely removed and mainly have the purpose of
% demonstrating custom changes.

% Listings and algorithms
\usepackage{listings,algorithm,algorithmic}
\lstset{
	basicstyle=\ttfamily\footnotesize,	% monospaced font
	breaklines=true,										% prevent overflow
  keywordstyle=\color{blue}\ttfamily,
  stringstyle=\color{red}\ttfamily,
  commentstyle=\color{green}\ttfamily,
  morecomment=[l][\color{magenta}]{\#A},
  frame=lrtb,
  framerule=1px,
  xleftmargin=1em,
}
% Don't break quotes in listings
\usepackage{textcomp}
\lstset{upquote=true}

% Only show footnotes after the item is actually displayed
\renewcommand\footnoterule{%
  \vspace*{1.5ex}\rule{.4\columnwidth}{0.4pt}\vspace*{.5ex}}

% Move paragraphs a little bit close to each other
\setlength{\parskip}{1ex plus4mm minus3mm}

% Support tifs by converting them.
% http://tex.stackexchange.com/a/89993
% \usepackage{epstopdf}
% \DeclareGraphicsRule{.tiff}{png}{.png}{%
%   \noexpand\epstopdfcall{convert #1 \noexpand\OutputFile}%
% }
\DeclareGraphicsRule{.tif}{png}{.png}{%
  \noexpand\epstopdfcall{convert #1 \noexpand\OutputFile}%
}

\title{Scientific Markdown}
\subtitle{Publications using Markdown and Pandoc}
\author{Jens Erat}
\date{February 3rd, 2015}

\begin{document}
\frame{\titlepage}


\begin{frame}[t]

\frametitle{Outline}


\tableofcontents[hideallsubsections]

\vspace*{2em}

\begin{center}

\OOldincludegraphics[scale=0.5]{images/by-sa.pdf}

\scriptsize This work is licensed under the Creative Commons
Attribution-ShareAlike 3.0 Unported License.\\ To view a copy
of this license, visit
\url{http://creativecommons.org/licenses/by-sa/3.0/}.

\end{center}
\end{frame}

\section{\LaTeX~and Beamer are Great}\label{and-beamer-are-great}

\section{Why \LaTeX~Sucks}\label{why-sucks}

\begin{frame}[fragile]{Counting Braces {[}2{]}}

\begin{lstlisting}
! Too many }'s.
l.6 \date December 2004}
\end{lstlisting}

\end{frame}

\begin{frame}[fragile]{Not in Mathematics Mode {[}2{]}}

\begin{lstlisting}
! Missing $ inserted
\end{lstlisting}

\end{frame}

\begin{frame}[fragile]{Counting Braces, ctd. {[}2{]}}

\begin{lstlisting}
Runaway argument?
{December 2004 \maketitle
! Paragraph ended before \date was complete.
<to be read again>
\par
l.8
\end{lstlisting}

\end{frame}

\begin{frame}[fragile]{Reading \LaTeX~Documents is a Mess}

\begin{lstlisting}
\section{Markdown}\label{markdown}

\href{http://daringfireball.net/projects/markdown/}{Markdown}
syntax is \emph{much} easier to read, but powerful enough for
\(95%\) of your document.

\begin{figure}[htbp]
\centering
\includegraphics{images/markdown.png}
\caption{Markdown Logo}
\end{figure}

\section{Pandoc}\label{pandoc}

\href{http://johnmacfarlane.net/pandoc/}{Pandoc} is a great
tool for converting Markdown (and lots of other documents) to
different output formats.
\end{lstlisting}

\end{frame}

\begin{frame}[fragile]{Reading Markdown Documents is Easy and Fun}

\begin{lstlisting}
# Markdown

[Markdown] syntax is _much_ easier to read, but powerful enough
for $95%$ of your document.

![Markdown Logo]

# Pandoc

[Pandoc] is a great tool for converting Markdown (and lots of
other documents) to different output formats.

[Markdown]:      http://daringfireball.net/projects/markdown/
[Markdown Logo]: images/markdown.png
[Pandoc]:        http://johnmacfarlane.net/pandoc/
\end{lstlisting}

\end{frame}

\section{The (Common) Markdown Tool
Chain}\label{the-common-markdown-tool-chain}

\begin{frame}{Disclaimer}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  no GUI
\item
  command line
\item
  we will still see \LaTeX, sometimes
\end{itemize}

\end{frame}

\begin{frame}{Overview}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \textbf{Pandoc}: convert from enhanced Markdown syntax to \LaTeX
\item
  \textbf{\LaTeX~} and the \textbf{Beamer} package: typeset
  great-looking documents
\item
  \textbf{latexmk}: run \LaTeX
\item
  \textbf{make}: put everything together
\end{itemize}

\end{frame}

\begin{frame}{Pandoc}

\begin{quote}
If you need to convert files from one markup format into another, pandoc
is your swiss-army knife. {[}1{]}
\end{quote}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  convert Markdown documents to either plain \LaTeX~or Beamer format
\item
  uses templates
\item
  arbitrary \TeX~commands allowed in-between!
\end{itemize}

\begin{block}{Output Format}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  could also directly create PDF files
\item
  intermediate \LaTeX~makes finding problems easier
\end{itemize}

\end{block}

\end{frame}

\begin{frame}[fragile]{Including \LaTeX Files}

Using enforced templates, title pages, content slides, footers and
similar often require falling back to plain \LaTeX.

Including files {[}4{]}:

\begin{lstlisting}
-H FILE, --include-in-header=FILE
-B FILE, --include-before-body=FILE
-A FILE, --include-after-body=FILE
\end{lstlisting}

Use \LaTeX~where necessary, but fall back to Markdown for most of the
document.

\end{frame}

\begin{frame}[fragile]{latexmk}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \lstinline!latexmk! helps at compiling \LaTeX files
\item
  repeatedly compiles until no further changes

  \begin{itemize}
  \itemsep1pt\parskip0pt\parsep0pt
  \item
    table of contents
  \item
    bibliography
  \item
    \dots
  \end{itemize}
\item
  helps cleaning up
\item
  result: PDF files
\end{itemize}

\end{frame}

\begin{frame}[fragile]{make}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  originally used for compiling software
\item
  run several commands, one after the other
\end{itemize}

~

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \lstinline!make presentation! and \lstinline!make report! instead of
  complicated, long command lines
\item
  could be easyily replaced by Windows batch files, \dots
\end{itemize}

\end{frame}

\section{Demo Time}\label{demo-time}

\section{Practice and Limitations}\label{practice-and-limitations}

\begin{frame}[fragile]{Markdown and Pandoc}

\begin{itemize}
\item
  you're allowed to use \TeX~everywhere

\begin{lstlisting}
Have a look at figure \ref{example}.

![Some nice figure \label{example}](images/figure.png)
\end{lstlisting}
\item
  finish Markdown files with an empty line

  \begin{itemize}
  \itemsep1pt\parskip0pt\parsep0pt
  \item
    otherwise, weird things might happen when using multiple files
  \end{itemize}
\item
  use an editor with Markdown support and preview
\item
  always use the newest Pandoc release\footnote<.->{http://johnmacfarlane.net/pandoc/installing.html}
\end{itemize}

\end{frame}

\begin{frame}[fragile]{Structuring Slides}

\begin{itemize}
\item
  Pauses using ``horizontal lines''

\begin{lstlisting}
. . .
\end{lstlisting}
\item
  Break apart lists with comments or protected whitespace

\begin{lstlisting}
- item 1
- item 2

\ 
<!-- -->

- item 1
- item 2
\end{lstlisting}
\item
  Protected whitespace also helpful for images not wrapped in figures

\begin{lstlisting}
![Inline image](example.png)\ 
\end{lstlisting}
\end{itemize}

\end{frame}

\begin{frame}{Multi-Column Frames}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  not supported by Pandoc
\item
  really needed?
\item
  extending pandoc with a filter\footnote<.->{http://stackoverflow.com/a/24040087/695343}
\end{itemize}

\end{frame}

\begin{frame}[fragile]{Source Code Highlighting}

\begin{itemize}
\item
  use fenced code blocks to declare the language used

\begin{lstlisting}
```java
public static void foo(String bar) {
  return "batz";
}
```
\end{lstlisting}
\item
  setting up highlighting in your header include (see
  \lstinline!listings! reference {[}3{]})
\end{itemize}

\end{frame}

\begin{frame}[fragile]{Tables}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  a mess in both \LaTeX~and Markdown
\end{itemize}

~

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \textbf{Markdown tables} are automatically put into figures

  \begin{itemize}
  \item
    online editors\footnote<.->{eg.
      http://www.tablesgenerator.com/markdown\_tables}
  \item
    clean up by ``converting from markdown to markdown''

\begin{lstlisting}
pandoc --to markdown table.md
\end{lstlisting}
  \item
    different syntax possibilities
  \end{itemize}
\item
  \textbf{\LaTeX~tables} (ie. for large, complicated tables)
\end{itemize}

\end{frame}

\begin{frame}[fragile]{References}

\begin{itemize}
\item
  Use pseudo classes for changing frame/section properties

  \begin{itemize}
  \itemsep1pt\parskip0pt\parsep0pt
  \item
    \lstinline!{.allowframebreaks}! to allow splitting long reference
    lists to multiple frames
  \item
    \lstinline!{.unnumbered}! to have an unnumbered section title
  \end{itemize}
\item
  Beamer example:

\begin{lstlisting}
# References

## References {.allowframebreaks}
\end{lstlisting}
\end{itemize}

\end{frame}

\begin{frame}[fragile]{Bibliography}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  ingredients:

  \begin{itemize}
  \itemsep1pt\parskip0pt\parsep0pt
  \item
    bibliography file (typically BibTex, other formats supported)
  \item
    citation style (\lstinline!.csl! file)
  \item
    references in document (\lstinline![@bibtex:reference]!)
  \end{itemize}
\item
  handled by pandoc: also works with HTML export
\end{itemize}

\end{frame}

\begin{frame}{Bonus}

\begin{center}\Large
A presentation is a paper is a presentation.
\end{center}

\end{frame}

\begin{frame}{On GitHub. Tomorrow.}

All files will be uploaded to GitHub.

\textbf{\large\url{https://github.com/JensErat/scientific-markdown}}

(and linked on the Fachschaft's web page)

\includegraphics[]{images/qrcode.png}~

Jens Erat, jens.erat@uni-konstanz.de

\end{frame}

\section{References}\label{references-1}

\begin{frame}{References}

{[}1{]} About pandoc: \emph{\url{http://johnmacfarlane.net/pandoc/}}.
Accessed: 2015-02-03.

{[}2{]} LaTeX/Errors and warnings --- wikibooks, the free textbook
project: 2014.
\emph{\url{http://en.wikibooks.org/w/index.php?title=LaTeX/Errors_and_Warnings\&oldid=2739496}}.

{[}3{]} Listings -- typeset source code listings using laTeX:
\emph{\url{http://www.ctan.org/pkg/listings}}. Accessed: 2015-02-03.

{[}4{]} Pandoc user's guide:
\emph{\url{http://johnmacfarlane.net/pandoc/README.html}}. Accessed:
2015-02-03.

\end{frame}

\end{document}