#+Title: Tutorial: Writing papers for ACPD using emacs org-mode
#+LaTeX_HEADER: \usepackage{natbib}
#+options: toc:nil ^:nil H:5
#+BEGIN_LaTeX
\definecolor{mintedbg}{rgb}{0.95,0.95,0.95}
#+END_LaTeX
#+BEGIN_SRC elisp :exports results
(setq org-latex-minted-options
'(("bgcolor" "mintedbg") ("frame" "single") ("framesep" "6pt") ("mathescape" "true") ("fontsize" "\\footnotesize")))
""
#+END_SRC
#+RESULTS:
#+BEGIN_SRC elisp :exports results :results result org raw
(setq org-latex-minted-langs '((elisp "common-lisp")))
""
#+END_SRC
#+HTML:
#+BEGIN_ABSTRACT
Emacs Org mode is an excellent tool for [[http://www.jstatsoft.org/v46/i03/][reproducible research]],[fn:3] but research is only relevant if people learn about it.[fn:1] To reach people with scientific work, you need to publish your results in a Journal, so I show here how to publish in [[http://www.atmos-chem-phys-discuss.net/][ACPD]] with Emacs Org mode.[fn:2]
#+END_ABSTRACT
#+TOC: headlines 2
* Requirements
To use this tutorial, you need
- a fairly recent version of [[http://orgmode.org][org-mode]] (8.0 or later - not yet shipped with emacs 24.3, so you will need to install it separately) and naturally
- [[http://gnu.org/s/emacs][Emacs]]. Also you need to download the
- [[http://www.atmospheric-chemistry-and-physics.net/Copernicus_LaTeX_Package_v_2_7.zip][copernicus latex package]]. And it can’t hurt to have a look at the [[http://www.atmospheric-chemistry-and-physics.net/submission/latex_instructions.html][latex-instructions]] from ACP. I used them to create my setup.
- [[http://tug.ctan.org/tex-archive/macros/latex/contrib/lineno/lineno.sty][lineno.sty]]. This is required by copernicus, but not included in the package - and neither in the texlive version I use.
* Basic Setup
** Emacs
The first step in publishing to ACPD is to activate org-mode and latex export and to create a latex-class in Emacs. To do so, just add the following to your ~/.emacs (or ~/.emacs.d/init.el) and eval it (for example by moving to the closing parenthesis and typing /C-x C-e/):
#+BEGIN_SRC elisp
(require 'org)
(require 'org-latex)
(require 'ox-latex)
(setq org-latex-packages-alist
(quote (("" "color" t) ("" "minted" t) ("" "parskip" t)))
org-latex-pdf-process
(quote (
"pdflatex -interaction nonstopmode -shell-escape -output-directory %o %f"
"bibtex $(basename %b)"
"pdflatex -interaction nonstopmode -shell-escape -output-directory %o %f"
"pdflatex -interaction nonstopmode -shell-escape -output-directory %o %f")))
(add-to-list 'org-latex-classes
`("copernicus_discussions"
"\\documentclass{copernicus_discussions}
[NO-DEFAULT-PACKAGES]
[PACKAGES]
[EXTRA]"
("\\section{%s}" . "\\section*{%s}")
("\\subsection{%s}" "\\newpage" "\\subsection*{%s}" "\\newpage")
("\\subsubsection{%s}" . "\\subsubsection*{%s}")
("\\paragraph{%s}" . "\\paragraph*{%s}")
("\\subparagraph{%s}" . "\\subparagraph*{%s}"))
)
#+END_SRC
This allows you to use /#+Latex_Class: copernicus_discussions/ in your org-mode file to set the PDF to export for ACPD.
Also you will likely want to use [[http://www.gnu.org/software/auctex/reftex.html][reftex]] for nice bibtex integration. To get it, add the following to your ~/.emacs or ~/.emacs.d/init.el:
#+BEGIN_SRC elisp
(require 'reftex-cite)
(defun org-mode-reftex-setup ()
(interactive)
(and (buffer-file-name) (file-exists-p (buffer-file-name))
(progn
; Reftex should use the org file as master file. See C-h v TeX-master for infos.
(setq TeX-master t)
(turn-on-reftex)
; enable auto-revert-mode to update reftex when bibtex file changes on disk
(global-auto-revert-mode t) ; careful: this can kill the undo
; history when you change the file
; on-disk.
(reftex-parse-all)
; add a custom reftex cite format to insert links
; This also changes any call to org-citation!
(reftex-set-cite-format
'((?c . "\\citet{%l}") ; natbib inline text
(?i . "\\citep{%l}") ; natbib with parens
))))
(define-key org-mode-map (kbd "C-c )") 'reftex-citation)
(define-key org-mode-map (kbd "C-c (") 'org-mode-reftex-search))
(add-hook 'org-mode-hook 'org-mode-reftex-setup)
#+END_SRC
The first line adds reftex-citations with /C-c [/, the rest sets some reftex-defaults and adds a menu which allows you to chose using \textbackslash citep{} instead of \textbackslash cite{} (this is what ACPD requires).
For nice Sourcecode highlighting, you should also install [[http://pygments.org/][Pygmentize]] and then add the following to your .emacs.d:
#+BEGIN_SRC elisp
(add-to-list 'org-latex-packages-alist '("" "minted"))
(add-to-list 'org-latex-packages-alist '("" "color"))
(setq org-latex-listings 'minted)
; add emacs lisp support for minted
(setq org-latex-custom-lang-environments
'((emacs-lisp "common-lispcode")))
#+END_SRC
** The working folder
As next step, unzip the [[http://www.atmospheric-chemistry-and-physics.net/Copernicus_LaTeX_Package_v_2_7.zip][copernicus latex package]] in the folder you want to use for writing your article (do use a dedicated folder for that: org-mode leaves around some files. And remember to use a version-tracking system like [[http://mercurial.selenic.com][Mercurial]], so you can always take snapshots of your current state.
This will give you the following files:
- authblk.sty
- copernicus.bst
- copernicus_discussions.cls
- natbib.sty
- pdfscreen.sty
- pdfscreencop.sty
Ensure that all of them are in your folder, not in a subfolder. If necessary copy them there.
Also get [[http://tug.ctan.org/tex-archive/macros/latex/contrib/lineno/lineno.sty][lineno.sty]] and copy it into your folder.
If you want to use unicode-symbols in your text, add [[http://wiki.neo-layout.org/attachment/ticket/317/uniinput.sty][uniinput.sty]], too.
* The org-mode document
Using the ACPD style requires some deviations from the standard org-mode export process. Luckily org-mode is flexible to adapt to them. Setup your document as follows:
#+Latex: \newpage
#+Latex: \tiny
#+caption: Minimal org-mode code for an ACPD paper.
#+BEGIN_EXAMPLE
,#+title: YOUR TITLE
,#+Options: toc:nil ^:nil
,#+BIND: org-latex-title-command ""
,#+Latex_Class: copernicus_discussions
,#+LaTeX_CLASS_OPTIONS: [acpd, hvmath, online]
# Nice code-blocks
,#+BEGIN_SRC elisp :noweb no-export :exports results
(setq org-latex-minted-options
'(("bgcolor" "mintedbg") ("frame" "single") ("framesep" "6pt")
("mathescape" "true") ("fontsize" "\\footnotesize")))
nil
,#+END_SRC
,#+BEGIN_ABSTRACT
Abstract
,#+END_ABSTRACT
,#+TOC: headlines 2
,#+Latex: \runningtitle{SHORT TITLE}
,#+Latex: \runningauthor{SHORT AUTHOR}
,#+Latex: \correspondence{AUTHOR NAME\\ EMAIL}
,#+Latex: \affil{YOUR UNIVERSITY}
,#+Latex: \author[2,*]{SECOND AUTHOR}
,#+Latex: \author[1]{THIRD AUTHOR SAME INSTITUTE}
,#+Latex: \affil[2]{SECOND UNIVERSITY}
,#+Latex: \affil[*]{now at: THIRD UNIVERSITY}
,#+Latex: \received{}
,#+Latex: \pubdiscuss{}
,#+Latex: \revised{}
,#+Latex: \accepted{}
,#+Latex: \published{}
,#+Latex: %% These dates will be inserted by ACPD
,#+Latex: \firstpage{1}
,#+Latex: \maketitle
,#+Latex: \introduction
# * Introduction
,* Second section
,* Discussion
,#+Latex: \conclusions
# * Conclusions
,#+Latex: \appendix
# use acknowledgements for multiple
,#+BEGIN_acknowledgement
Foo Bar Baz.
,#+END_acknowledgement
,#+Latex: \bibliographystyle{copernicus}
,#+Latex: \bibliography{ABSOLUTE_PATH_TO_YOUR_BIBTEX_FILE_WITHOUT_.bib_SUFFIX}{}
# Local Variables:
# org-confirm-babel-evaluate: nil
# org-export-allow-bind-keywords: t
# End:
#+END_EXAMPLE
#+Latex: \normalsize
Let’s look at this in more detail.
** Use the LaTeX class
As first step, we set the LaTeX class. In the options we select the journal (acpd) and such - you can find the detailed options in the [[http://www.atmospheric-chemistry-and-physics.net/submission/latex_instructions.html][latex-instructions]] from ACP.
#+BEGIN_EXAMPLE
,#+Latex_Class: copernicus_discussions
,#+LaTeX_CLASS_OPTIONS: [acpd, hvmath, online]
#+END_EXAMPLE
** Delayed table of contents
The table of contents is set to be shown after the Abstract by setting the /toc:nil/ option and later explicitely calling /#+TOC: headlines 2/. In org-mode this is really straightforward.
** Delayed maketitle
Delaying \textbackslash maketitle is a bit more convoluted than delaying the TOC. First we add the local variable /org-export-allow-bind-keywords: t/ at the bottom to allow file-local custom bindings for functions in the file, then we inactivate the title-command with /#+BIND: org-latex-title-command/ /""/ and finally we add \textbackslash maketitle where we need it.
** Define minted style
This defines the variables minted uses for beautiful code-blocks. Without this, your code-blocks will just look like inline text.
#+BEGIN_EXAMPLE
,#+BEGIN_SRC elisp :noweb no-export :exports results
(setq org-latex-minted-options
'(("bgcolor" "mintedbg") ("frame" "single") ("framesep" "6pt")
("mathescape" "true") ("fontsize" "\\footnotesize")))
nil
,#+END_SRC
#+END_EXAMPLE
** Intro and conclusions
The Introduction and the conclusions have their own commands in ACPD, because they use them to add bookmarks. You can also use he commands to specify another name.
We call the commands with /#+LaTeX:/ (just like some others) which allows us to explicitely add arbitrary LaTeX-code.
** Appendix
The appendix should be used sparingly. It changes the numbering of the pages.
#+BEGIN_EXAMPLE
,#+Latex: \appendix
#+END_EXAMPLE
** Bibliography
The bibliography allows referring to entries from your general bibtex-file. Ensure that you use the correct absolute path to that file. For more information, see [[http://orgmode.org/worg/org-tutorials/org-latex-export.html#sec-17-1][the org-tutorial page for biblatex]].
** Babel evaluate without confirmation
This allows us to just run all code snippets which we embedded in the document when we export the file. If we do not set this local variable, we have to acknowledge each source block before it runs (the block with local variables also contains the variable which allows binding functions on a per-file basis, as explained above).
#+BEGIN_EXAMPLE
# Local Variables:
# org-confirm-babel-evaluate: nil
# org-export-allow-bind-keywords: t
# End:
#+END_EXAMPLE
* Conclusion
With this setup, you can publish your paper with ACPD using org-mode for the actual writing, which has a much lower overhead than LaTeX and offers quite a few unique features for more efficient working - from easy referencing over inline math preview to planning and code-evaluation directly in your file.
#+Latex: \bibliographystyle{copernicus}
#+Latex: \bibliography{/home/arne/aufschriebe/ref}{}
# ,#+BIBLIOGRAPHY: /home/arne/aufschriebe/ref plain limit:t noabstract:t
* Footnotes
[fn:1] Research, or rather /science/ not only means to learn new things and to uncover secrets, but just as importantly to share what you learn. Fun fact: The German word for science is “Wissenschaft”, built from the words “wissen” (knowledge) and “schaft” (from schaffen: create), so it more exactly captures the essence of scientific work than the word “science”, that is based on the latin word “scientia” which just means knowledge. It isn’t enough to just learn. Creating knowledge requires telling it to others, so they can build upon it.
[fn:2] I chose ACPD as target for this article, because it is an Open Access journal, and because I want to publish in it (which makes it a rather natural choice for a tutorial).
[fn:3] General methods for using Emacs org-mode in scientific publishing have been described by \citet{SchulteEmacs2012}.