\maketitle \tableofcontents
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.
You can mark text as bold, italic, underlined, struck-through, verbatim, and code.
Paragraphs are separated by blank lines.
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: ^:{}
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
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.
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:
This section is intentionally empty.
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.
The default is single spacing. It you want the document to come out double-spaced, use this
#+LATEX_HEADER: \usepackage{setspace}
\doublespace
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.
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.
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
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
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.
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.
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 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.
The default export behavior is not that nice at setting the width. You can set that the way you want like this:
For more details on exporting, see info:org#Images in LaTeX export.
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.
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.
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.
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 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.
| heading1 | heading2 |
|---|---|
| 1 | 8 |
| 4 | 5 |
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 | |----------+----------|
| heading1 | heading2 |
|---|---|
| 1 | 8 |
| 4 | 5 |
You can see the result in Table ref:tab:example2.
For more details on exporting, see info:org#Tables in LaTeX export.
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.
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
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.
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.
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.
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).
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
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
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
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
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
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.
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
The rotating package will rotate complete sets of figures and table any way you choose.
http://www.ctan.org/pkg/rotating
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.
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 provides support for many miscellaneous font symbols.
http://www.ctan.org/pkg/textcomp
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
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
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
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
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
Allows for the incorporation of URLs into TeX documentation. These URLs are interactive so that users can follow the links in the TeX document.
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
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
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
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
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.
see cmu-qualifier/cmu-qualifier.org
see cmu-ms-report/project-report.org
cmu-phd-dissertation/dissertation.org
The achemso LaTeX package is used. See the documentation here:
../texmf/doc/latex/achemso/achemso.pdf
see ./achemso/I&ECR/manuscript.org
see achemso/aamick/manuscript.org
see ./achemso/accacs/manuscript.org
The revtex4-1 package is used. See the documentation here:
file:../texmf/doc/latex/revtex/auguide/auguide4-1.pdf
See revtex4-1/PRL/manuscript.org.
See revtex4-1/PRB/manuscript.org.
documentation
file:../texmf/doc/latex/elsarticle/elsdoc.pdf
see elsarticle/manuscript.org for an example.
bibliographystyle:unsrt
bibliography:kitchin.bib