/ doc-org Public

org-mode + latex + docker = pdf

# doc-org/doc-org

Switch branches/tags
Nothing to show

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

## Files

Failed to load latest commit information.
Type
Name
Commit time

# Presentation

Doc-org generates pdf files by combining org-mode and latex.

Org mode is a markup language like markdown, but more powerful. Since it is very concise and readable, it is used to describe the body of your document. Emacs is used to export org mode to latex.

Latex is the best way to create awesome pdf files. It is used to describe how your document should look like.

Doc-org runs on docker, which means you don’t need to have latex or emacs installed on your machine and you can use it to generate documents with Continuous Integration.

# Install

## Install docker

Docker is a prerequisite. See official installation instructions.

## Install doc-org

In order to download doc-org run this command:

git clone https://github.com/doc-org/doc-org

In this directory there is the doc-org script, which is used to generate documents.

# Update

Inside the doc-org directory run:

git pull --rebase

# Usage

Run doc-org -h to get help and doc-org -v to get the software version.

\$ ./doc-org -h
doc-org 0.1.0
Generate pdf by combining org-mode and latex.

USAGE:
doc-org [document-dir]

FLAGS:
-h       Prints help information
-v       Prints version

ARGS:
[document-dir]


## Document directory

You can specify the directory of your document as the first argument. Otherwise, if you run doc-org without arguments it will use the current directory,

The directory should contain these files:

main.org
The first org file that will be compiled. In this file you can include other org or latex files.
The latex header, that contains document class, packages and so on (required if auto_latex: false).
config.json
Contains configuration parameters (optional).
init.el
Custom emacs configuration. Emacs sources this file before converting org to latex (optional).

# Configuration

config.json file and all of its fields are optional. This is an example of this file, where all parameters are present:

{
"pdf_filename": "my document",
"auto_latex": false,
"shell_escape": false
}

pdf_filename
Name of the output pdf file without extension.
auto_latex
If true org-mode creates the necessary latex code automatically. header.tex file is not used and doc-org does not modify the output of emacs. False by default.
shell_escape
Enable latex to run external commands. Useful when working with graphviz for example. False by default.

# Examples

See examples git repository. Github actions are used to automatically export to latex and pdf after each push to the repository.

# How it works

Doc-org uses emacs to convert the main.org org-mode file to the main.tex latex file. You can customize emacs export function with the init.el file. Then, latexmk is used to convert main.tex and header.tex to the final pdf.

+----------+   +---------+
| main.org |   | init.el |
+-----+----+   +----+----+
|             |
|             |
+------+------+
|
v
emacs
|
v
+-----+----+     +------------+
| main.tex |     | header.tex |
+-----+----+     +-----+------+
|                |
|                |
+-------+--------+
|
v
latexmk
|
v
+--+--+
| pdf |
+-----+


The main.tex file will look like this:

\input{header.tex}

\begin{document}
% contents of main.org translated into latex
\end{document}

# Who is it for

Doc-org is mainly for people who already have a latex template and want to use org-mode to write the body of their document. Anyway, if you are already happy with the default latex export function of org mode (i.e. you don’t want header.tex to be included automatically), you can set auto_latex: true in your config.json file.

With doc-org you have full control of the latex output, because Org mode supports embedded latex code, therefore you can use latex inside an org file when needed. Furthermore, emacs supports tons of different customization options, which can be set with the init.el file.

# Org mode to latex: useful links

org-mode + latex + docker = pdf

## Releases

No releases published

## Packages 0

No packages published