Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
504 lines (329 sloc) 25 KB

Writing technical documents in org-mode

\maketitle \tableofcontents

Basic principles

Org-mode is a simple, structured markup for information. You should keep it simple. If you find yourself writing a lot of LaTeX, you are probably doing something wrong, or using the wrong tool.

Our aim is to write technical documentation in org-mode, which can be exported to LaTeX for conversion to PDF. This is a conversion process. It is not a perfect process, so we will try to keep things as simple as possible.

Although org-mode is not LaTeX, you will find it helpful to be familiar with LaTeX. A pretty good reference is here http://en.wikibooks.org/wiki/LaTeX, especially for learning about equations.

It is not necessary to learn very many keyboard shortcuts to use org-mode. These only make you more efficient when you use org-mode a lot.

You can learn a lot about org-mode by reading the manual. There is a lot more there than needed for writing basic technical documents. This guide is not comprehensive, but rather designed to get you started quickly.

Basic markup

Basics

You can mark text as bold, italic, underlined, struck-through, verbatim, and code.

Paragraphs are separated by blank lines.

Subscripts and superscripts

Usually you use ^ for superscripts and _ for subscripts. The things super or subscripted should be in curly brackets. Here are some examples: NA is Avogadro’s number. U3d is the U parameter on the 3d orbitals. You should explicitly mark the content to be super or subscripted with curly brackets. This is controlled by this line in your org-file:

#+OPTIONS: ^:{}

Symbols

Org-mode recognizes many different symbols, including the greek letters, e.g. α, and Ω. You can make ° symbol and an Å symbol. These do not need to be contained in math environments. Some more of my favorites include ×, and →. You can toggle symbols over these commands with this command: elisp:org-toggle-pretty-entities or C-c C-x .

atoms_position

α x^2 x2

Chemical formulas

You should always enter chemical formulas like this: NH3. No other way is good. Here are some example formulas: CH4, ABO3-δ, FeO+1, H2SO4, Ca(NO3)2.

\ce{NH3} \ce{CH4} NH$_3$

Note this is org syntax not LaTeX syntax. You do not need the math-mode you need in LaTeX. Keep your org syntax clean and do not use math-mode like you do in LaTeX.

References to document sections

You are safest using a link to the headline text like this. See section *Chemical formulas. Note the * in the link, and the missing space after the *. This will get converted to the section number in your LaTeX file.

It is possible to create a “label” to a section. You must set a CUSTOM_ID property on the headline. You then refer to that section with this kind of link: see section #sec:headline-label

You should include the word “section” in front of the ref link in any case because the link is just converted to a number in LaTeX.

*** A headline with a custom id property
    :PROPERTIES:
    :CUSTOM_ID: sec:headline-label-test
    :END:

A headline with a custom id property

This section is intentionally empty.

An empty section label:sec:not-recommended

If you are used to section labels in LaTeX, you might put the label directly in the heading. This works, but is not recommended because it seems ugly. Nothing to see here in Section ref:sec:not-recommended. It does work though. For now.

Line spacing

The default is single spacing. It you want the document to come out double-spaced, use this

#+LATEX_HEADER: \usepackage{setspace}
\doublespace

Bibliography and citations

Specifying the bibliography files where citations come from

You specify the bibtex file(s) you will use with a bibliography link. This link should be where you want the bibliography to appear in the exported PDF, e.g. usually at the end of the document. The bibtex file should be in the same directory as your manuscript file. These links are clickable, and when you click on them, the file under your cursor should be opened.

Bibliography style

Depending on the type of document you are creating, you may need to specify a bibliography style. Use a bibliographystyle link for this. Some documents provide their own styles, others require you to specify them. See the examples.

Citing references

We use cite links to indicate a reference to an entry in the bibliography. Here is an example cite:akhade2012:surface. These links are clickable too. If everything is setup correctly, clicking on the link should give you a citation and a menu in the minibuffer. From this menu you can open the entry, the pdf if you have it, your notes, or the citation url.

You can insert citation links by pressing C-c ]. Type a few letters to search for what you want. Press enter to get a list of matches. Select the entries you want with m, and then press enter again. The link will be automatically entered. Multiple citations are separated by commas. If you need to add citations to an existing citation, just repeat the command with the cursor in the link, or at the end of the link.

cite:calle-vallejo2013:outer,akhade2012:surface,chao2012:mesoporous,mao2013:emit

Equations

There are a few ways to enter equations. If your equation should be inline, e.g. \(e^x = 4\) use this format.

An alternative format that displays the equation on its own line is this: \[e^x = 4\]

You can also use the older LaTeX markup like this $e^x = 4$ for inline equations, or $$e^x=4$$ for display equations. These notations are more compact, but also more fragile when they are embedded in text.

References to equations

To make references to equations, you must label them. This can only be done by using a LaTeX equation environment. The label command must go at the end of the equation. Then you can use a ref link like this to refer to Equation ref:eq:1. Note you should write Equation before the link, so it will be clear what you refer to in the exported document.

\begin{equation} e^x = 4 \label{eq:1} \end{equation}

The ref link is clickable, and clicking on it moves the cursor to the corresponding label. You may prefer eqref:eq:1. This will render the number in parentheses on export. You need the amsmath LaTeX package for that. It is default in jmax.

Multiline formulas

If you have very long formulas that need to be broken over several lines, use the align environment. Mark the end of a line with \\. Use \nonumber for lines you do not want numbered.

\begin{align} &OVac\_FormE(cID) → OVac\_FormE(mID, mag, num\_atoms, \nonumber
&orientation, correction, calc\_quantity,\nonumber \ &calculator, figure) \label{eq:multiline} \end{align}

If you do not like the numbers use align*:

\begin{align*} &OVac\_FormE(cID) → OVac\_FormE(mID, mag, num\_atoms,
&orientation, correction, calc\_quantity, \ &calculator, figure) \end{align*}

Put the labels at the end of the equation, as in this example: eqref:eq:multiline.

Source code

One of the main reasons to use org-mode is the integration of source code.

import matplotlib.pyplot as plt
plt.plot([1,4,7,9])
plt.savefig('fig1.png')

By default all blocks will be rendered and included in the exported document. You control this in the source block header. Here is a block that is not exported, nor are the results.

Figures

Figures in org-mode are straightforward. You simply create a link to a figure that Emacs can render, and that can be included in a PDF file. That is usually a png file. You can, and should add captions and labels to the figure. Captions are descriptive, and labels allow you to refer to the figure in your document. Add a caption with a line like #+caption: some text. You have many options for labels. You can put a LaTeX label in the caption, or a line like #+label: labeltext. You can also use a label link in the caption.

By default images are shown with the jmax setup. You can toggle them off like this elisp:org-toggle-inline-images.

It is a good practice for the label to have a prefix on it of fig: so that later you can easily spot figure labels from table and equation labels.

./fig1.png

The default export behavior is not that nice at setting the width. You can set that the way you want like this:

./fig1.png

For more details on exporting, see info:org#Images in LaTeX export.

References to figures

Later, I can refer to Figure ref:fig:test-label. Figures tend to float around in LaTeX. Do not worry about it. If you need to specify the location of a figure, see this section Controlling placement of floats.

If you want help inserting the references, type M-x org-ref-insert-ref-link, and press tab. This should show you a list of labels in your document. It only shows labels defined as a link.

Controlling placement of floats

If it is essential to you to have a float in a specific place, you can set a LaTeX attribute that will probably make that happen. Here is an example.

Wrapping text around figures

You may be constrained for space and want your text to wrap around figures. You can use the wrapfig package and some attributes to make this happen. See http://orgmode.org/manual/LaTeX-specific-attributes.html. Note that the figure is wrapped into the paragraph after the figure.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec non elit purus. Maecenas id lectus luctus, ornare libero et, laoreet purus. In placerat, lectus eget rutrum vehicula, tortor odio tempor leo, eu pulvinar dolor ante vitae dui. Vivamus convallis interdum enim gravida molestie. Cras vulputate at neque at mollis. Curabitur lobortis gravida tellus, vitae sagittis nisl tempor ac. Cras vel porta urna. Pellentesque auctor, urna at vehicula rutrum, metus nunc dictum dui, at interdum diam libero vel ipsum. Donec euismod, felis nec dictum mattis, odio lorem tristique orci, in commodo purus nulla sed est. Nam quis molestie mauris. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.

Fusce bibendum sem turpis, at venenatis magna laoreet in. Sed convallis pretium leo, in aliquam massa lobortis quis. Fusce nec ornare mi. Nulla rutrum, tellus quis pretium varius, neque ligula facilisis urna, sit amet accumsan sem neque sit amet arcu. Aenean augue lacus, sodales a sem vitae, tincidunt rhoncus nibh. Donec venenatis dolor ut nulla bibendum tincidunt. Suspendisse facilisis, eros sed pharetra posuere, sem arcu viverra risus, eu aliquet orci est vitae ipsum. Integer scelerisque nisl et quam dapibus consequat. Integer pretium pharetra nisi, id consectetur dui ultricies ac. Vestibulum fermentum vulputate mauris nec tincidunt. Maecenas velit turpis, tempor porta tincidunt ac, venenatis eget tortor. Duis egestas odio venenatis adipiscing mattis.

./fig1.png

Mauris placerat faucibus scelerisque. Nunc interdum egestas nunc ut vestibulum. Maecenas commodo justo sit amet scelerisque auctor. Morbi lacinia sem sit amet lectus vehicula porttitor. Pellentesque at dictum metus, quis ornare arcu. Integer tellus turpis, rhoncus nec accumsan in, posuere sit amet arcu. Nullam tempus neque vel condimentum porttitor. Nullam vitae tincidunt felis. Nunc egestas, nunc sit amet tristique adipiscing, ante nulla imperdiet nisi, nec eleifend enim felis et urna. Sed sit amet erat scelerisque, sollicitudin nibh vitae, varius nunc. Mauris posuere scelerisque augue nec placerat. Morbi in elementum risus. Fusce quis condimentum turpis. Sed eleifend libero et diam consectetur, a rhoncus purus porta. Nulla consectetur blandit porta.

Tables

Tables are one of org-mode’s best features. They are easy to create, and customize. Read about them here info:org#Tables. Consider this table:

#+caption: The simplest kind of table. label:tab:example1
#+TBLNAME: tab:example1
| heading1 | heading2 |
|----------+----------|
|        1 |        8 |
|        4 |        5 |

The example above is a literal example so you can compare the table syntax with what is exported in LaTeX. Here is the actual table.

heading1heading2
18
45

We use #+tblname: to give the table a name we can reference later. Table ref:tab:example1 shows a simple table. We can add vertical lines by setting a LaTeX attribute :align; this attribute also specifies the alignment of each cell. In the next example, we specify vertical lines with |, make the first column centered, and the second column left aligned. You have to put a horizontal line everywhere you want it. We will also specify that the table be placed “Here”.

#+attr_latex: :placement [H] :align | c | l |
#+caption: The second simplest kind of table.
#+tblname: tab:example2
|----------+----------|
| heading1 | heading2 |
|----------+----------|
|        1 |        8 |
|----------+----------|
|        4 |        5 |
|----------+----------|

heading1heading2
18
45

You can see the result in Table ref:tab:example2.

For more details on exporting, see info:org#Tables in LaTeX export.

Including LaTex environments

You can include almost arbitrary environments from LaTeX, such as an array: \begin{equation} \begin{array}{llcr} a & 9 & sin (12x) & c
a + b & cos (x) & 7 & d \end{array} \end{equation}

or a verbatim environment:

\begin{verbatim} some verbatim text. \end{verbatim}

Just because you can does not mean you should… You should aim to keep this to a minimum, otherwise you might as well use LaTeX.

Miscellaneous document features

Table of contents

You can add a table of contents with \tableofcontents.

This is controlled by this option line:

#+OPTION: toc:nil

If you just want a convenient temporary table of contents use M-x speedbar.

elisp:speedbar

Preventing export of some headings

You can mark some headings with a tag that is listed in

#+EXPORT_EXCLUDE_TAGS: noexport

to mark it for noexport. Put your cursor on the headline, type C-c C-c and type in the tag name.

Attaching files to a pdf

You can use the attachfile link to embed files in a PDF. Like this: attachfile:technical-documents-in-org.org.

Your set of LaTeX packages must include the attachfile package. This is the default in jmax.

List of figures and tables

You can create a list of figures link like this: list-of-figures:lof. You can click on it and get a new buffer with a list of figures in it. Or run elisp:org-ref-list-of-figures

Similarly, you get a list of tables with list-of-tables:lot, or by running elisp:org-ref-list-of-tables.

Exporting to LaTeX and PDF

org-mode is not LaTeX, and it cannot do everything LaTeX does. It can do a lot though. To get LaTeX, we have to provide org-mode with the required packages, and tell it what kind of document to export. The default type is an article. We provide some additional document types:

  • cmu-article is like an article, but with one-inch margins

Those types use what we define as the default LaTeX packages to include. The order of these is important, and changing it can result in LaTeX errors. If you need additional packages for your document, you need to tell org-mode about them like this:

#+LATEX_HEADER: \usepackage[options]{xyz}

You can learn more about exporting here info:org#Exporting, and about LaTeX and PDF exporting here info:org#LaTeX and PDF export. There are many settings you may one day need to modify. Learn about them here info:org#Export settings.

Here is a brief description of these packages (Thanks to Jake Boes).

[AUTO] inputenc

This package translates various standard and other input-encodings into a ‘LaTeX internal language’. i.e. typing in non-ASCII characters into the document will be translated into a character number ‘228’.The character number that inputenc assigns is specified by the editor setup ‘AUTO’. TeX then reads the character number and inputenc returns a properly formatted LaTeX string ‘"a’ for character number ‘228’. This package is often used in conjunction with fontenc.

http://www.ctan.org/pkg/inputenc

[T1] fontenc

This package contains information regarding know latex functions such as ‘"’ and knows to turn these commands into the appropriate accent over a proceeding character.i.e. ‘"a’ would be represented as an a with a double dot accent above.fontenc then translates this into a statement like ‘print character 228’ where editor setup ‘T1’ determines the character number to be printed.

http://www.ctan.org/pkg/fontenc

fixltx2e

LaTeX tries to keep things the same between updates so that older documents won’t have their typesettings altered when you update to a newer version of LaTeX. The fixltx2e package contains patches that alter some of these typesettings in favor of fixing certain bugs. This way LaTeX updates remain backwards compatible and bugs can be patched as well. A full list of correction can be found at the following link:

http://www.ctan.org/pkg/fixltx2e

graphicx

This package provides an extension to the regular set of graphics commands provided in LaTeX. A more detailed outline of what can be done with this graphics tool is outlined here:http://ctan.mirrors.hoobly.com/macros/latex/required/graphics/grfguide.pdf

http://ctan.org/pkg/graphicx

longtable

Allows for tables to continue onto the next page of a document. The widths of this table will be kept constant between pages.

http://www.ctan.org/pkg/longtable

float

This package provides LaTeX with the concept of a floating figure or table. Such floating objects can be placed moved about to make appropriate spacing for text and other obstructions. This package also allows for the [H] setting to be used which dictates that the figure or table be positioned exactly where you specified in the text.

http://www.ctan.org/pkg/float

wrapfig

This package allows text to wrap around figures and tables. This is useful for inserting smaller images into large paragraphs.

http://www.ctan.org/pkg/wrapfig

rotating

The rotating package will rotate complete sets of figures and table any way you choose.

http://www.ctan.org/pkg/rotating

[normalem] ulem

This is a fancy underlining package which will underline through word breaks, unlike the standard method. [normalem] prevents ulem from replacing italics with underlines when using the \emph command.

http://www.ctan.org/pkg/ulem

amsmath

amsmath is the recommended package for serious mathematical typesetting in LaTeX. This package unlocks a plethora of functionality which is documented here: http://ctan.sharelatex.com/tex-archive/macros/latex/required/amslatex/math/amsldoc.pdf

http://www.ctan.org/pkg/amsmath

textcomp

textcomp provides support for many miscellaneous font symbols.

http://www.ctan.org/pkg/textcomp

marvosym

The Martin Vogel’s symbols package contains support for an unusual list of symbols as well as some potentially useful mathematically notations. The full list of provided fonts can be found here: http://mirror.utexas.edu/ctan/fonts/marvosym/doc/fonts/marvosym/marvodoc.pdf

http://www.ctan.org/pkg/marvosym

wasysym

More support for various symbols including integrals which look useful for engineering documentation. A full list of symbols can be found here: http://ctan.mirrors.hoobly.com/macros/latex/contrib/wasysym/wasysym.pdf

http://www.ctan.org/pkg/wasysym

amssymb

Support for symbols used by the American Mathematical Society. A complete list of symbols can be found here: http://www.rpi.edu/dept/arc/training/latex/amssymblist.pdf

http://www.ctan.org/tex-archive/fonts/amsfonts

[version=3] mhchem

A typeset package for chemical formulae and equations. More information on proper implementation can be found here: http://ctan.mirrorcatalogs.com/macros/latex/contrib/mhchem/mhchem.pdf

http://www.ctan.org/pkg/mhchem

natbib

A package which provides basic bibliography support. This package includes author-year and numbered references and support for a large variety of different bibliography formats.

http://www.ctan.org/pkg/natbib

url

Allows for the incorporation of URLs into TeX documentation. These URLs are interactive so that users can follow the links in the TeX document.

http://www.ctan.org/pkg/url

minted

This package provides formatting for source code in LaTeX from multiple different programming languages. This package is useful for representing source code as one would expect to see it in its typical format. There is also support for numbering lines of code and many other useful tricks. A full description of the uses can be found here: http://bay.uchicago.edu/tex-archive/macros/latex/contrib/minted/minted.pdf

http://www.ctan.org/pkg/minted

underscore

This package controls some aspects of how inserting underscores work i.e. ‘\_’. Normally connecting two words with and underscore prevents automatic hyphenation of the word. More importantly, this package also prevents the underscore command from interfering in mathematical notation.

http://www.ctan.org/pkg/underscore

[linktocpage,pdfstartview=FitH,colorlinks,linkcolor=blue,anchorcolor=blue,citecolor=blue,filecolor=blue,menucolor=blue,urlcolor=blue] hyperref

This package controls all aspects of cross-reference commands and how they are exported to PDF. This includes, but is not limited to, all of the bookmarks, links in table of contents, and URLs used in the document. [linktocpage] sets the page number as the link on the table of contents as opposed to the text. [pdfstartview=FitH] specifies that the PDF should open in the fit to screen view. [colorlinks] colors all of the links as specified in the following commands above.

http://www.ctan.org/pkg/hyperref

attachfile

This package allows files to be attached an arbitrary file into an exported PDF. This file is embedded into the PDF so that is can be easily transported along with the document.

http://www.ctan.org/pkg/attachfile

Exporting to a PDF

You can type C-c C-e j o to build and open a pdf file. This is most often what you want to do, if you just need a pdf.

M-x ox-manuscript-export-and-build-and-open

Exporting a manuscript for submission

Most journals do not want your bibtex file, nor do they use pdflatex. They want a standalone LaTeX file that contains the bibliography and which typically uses eps graphics. We create that file from the org-file with C-c C-e j m.

M-x ox-manuscript-build-submission-manuscript-and-open

The resulting tex file will have no extensions on the included graphics, so that LaTeX can choose the appropriate file. You need to provide the eps or pdf graphics. The bibliography will be embedded at the end of the file.

CMU Qualifier

see cmu-qualifier/cmu-qualifier.org

CMU MS report

see cmu-ms-report/project-report.org

CMU Dissertation

cmu-phd-dissertation/dissertation.org

ACS journals

The achemso LaTeX package is used. See the documentation here:

../texmf/doc/latex/achemso/achemso.pdf

I&ECR

see ./achemso/I&ECR/manuscript.org

Applied Interfaces and Materials

see achemso/aamick/manuscript.org

ACS Catalysis

see ./achemso/accacs/manuscript.org

Analytical Chemistry

APS journals

The revtex4-1 package is used. See the documentation here:

file:../texmf/doc/latex/revtex/auguide/auguide4-1.pdf

Physical Review Letters

See revtex4-1/PRL/manuscript.org.

Physical Review B

See revtex4-1/PRB/manuscript.org.

Elsevier journals

documentation

file:../texmf/doc/latex/elsarticle/elsdoc.pdf

see elsarticle/manuscript.org for an example.

Springer journals

see ./svjour3/manuscript.org

Bibliography

bibliographystyle:unsrt

bibliography:kitchin.bib