Verify an Org-mode environment

Check an Org-mode environment.

warning: executing the table in this buffer will execute elisp and shell commands on your system. These commands are intended to check aspects of your environment for compatibility with Org-mode, however malicious people could tie arbitrary and/or malicious code blocks to this table.

don't be malicious, only put reasonable code into this buffer
don't be angry, you've been warned about the possible risks of using this buffer

In general Org-moders are very nice and will most likely keep this buffer both safe and useful.

Instructions

Download the file org-check.org
Calculate the table by putting point in the table and pressing C-u C-c *
Check the results column
- if you see all "pass" results, then your environment passes
- if you see "fail" or other unexpected results, then follow the link in the topic column for an explanation

task	topic	command	arg
Org-mode
	Library	org-library
	Version	org-version
Agenda
		chk-agenda-files
LaTeX Export
	LaTeX classes	chk-ltx-cls
		pkg-loaded	'org-latex
HTML export
		pkg-loaded	'org-html
Preview Latex
		chk-ext-cmd	"latex"
		chk-sys-cmd	"latex"
		chk-ext-cmd	"dvipng"
		chk-sys-cmd	"dvipng"
	latex-scale	chk-latex-scale
		pkg-loaded	'org-latex
Make Pdfs
	latex	chk-ext-cmd	"latex"
	latex-system	chk-sys-cmd	"latex"
	latex-engine	chk-latex-engine
	engine-present	chk-engine-cmd
Org-babel
	Org-babel	pkg-loaded	'org-babel

	R language	chk-babel-lang	"R"
		chk-ext-cmd	"R"
		chk-sys-cmd	"R"
		pkg-loaded	'org-babel-R

	C language	chk-babel-lang	"C"
		chk-ext-cmd	"cc"
		chk-sys-cmd	"cc"
		pkg-loaded	'org-babel-C

	Clojure	chk-babel-lang	"clojure"
		pkg-loaded	'org-babel-clojure

	Ditaa	chk-babel-lang	"ditaa"
		pkg-loaded	'org-babel-ditaa

	CSS	chk-babel-lang	"css"
		pkg-loaded	'org-babel-css

	Gnuplot	chk-babel-lang	"gnuplot"
		chk-ext-cmd	"gnuplot"
		chk-sys-cmd	"gnuplot"
		pkg-loaded	'org-babel-gnuplot

	LaTeX	chk-babel-lang	"latex"
		chk-ext-cmd	"latex"
		chk-sys-cmd	"latex"
		pkg-loaded	'org-babel-latex

	MATLAB®	chk-babel-lang	"matlab"
		chk-ext-cmd	"matlab"
		chk-sys-cmd	"matlab"
		pkg-loaded	'org-babel-matlab

	Perl	chk-babel-lang	"perl"
		chk-ext-cmd	"perl"
		chk-sys-cmd	"perl"
		pkg-loaded	'org-babel-perl

	Python	chk-babel-lang	"python"
		chk-ext-cmd	"python"
		chk-sys-cmd	"python"
		pkg-loaded	'org-babel-python

	Ruby	chk-babel-lang	"ruby"
		chk-ext-cmd	"ruby"
		chk-sys-cmd	"ruby"
		pkg-loaded	'org-babel-ruby

Tasks

Org Setup

It is sometimes the case that updating Org-mode seems to have no effect. This can arise when there are multiple Org-mode installations, or if Org-mode was compiled and then not recompiled after an update.

Org library

This is where emacs is finding the Org-mode installation

Org version

This is the hard-coded version number from org.el.

Export LaTeX

LaTeX Export Tutorial

Check `org-export-latex-classes`

Check that the variable org-export-latex-classes has been set: (progn (describe-variable 'org-export-latex-classes) (other-window 1))

Preview LaTeX

Previewing LaTeX in the Org-mode buffer requires:
- a working LaTeX installation, including the latex executable
- the dvipng executable
- paths to these executables on exec-path
If either latex-system or dvipng-system fails, then you probably need to install software
If latex-system passes and latex fails, then you need to modify the variable exec-path, so the path to the latex executable is included
If dvipng-system passes and dvipng fails, then you need to modify the variable exec-path, so the path to the dvipng executable is included
Image size can be scaled using the :scale property of the variable org-format-latex-options

Make pdf files

Pdf files are created for in-buffer preview and as the end-product of LaTeX export

Agenda

The agenda is key to using Org-mode effectively

Babel

Org-babel extends the very excellent Org-mode with the ability to execute code blocks
Org-babel configuration is a 5-step process that requires entries in .emacs

Org-babel provided

If this test fails, then Org-babel isn't loaded
You probably need something like this in .emacs

(require 'org-babel-init)

Org-babel installation is a 5-step process

R language configuration

R is a free software environment for statistical computing and graphics
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-R)

if chk-ext-cmd returns fail then you should check if there is a path to the R executable in exec-path : (progn (describe-variable 'exec-path) (other-window)) and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/R/executable")))

if chk-sys-cmd returns fail then you should check to see if R is installed on your system

C language configuration

C is a general-purpose computer programming language
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-C)

if chk-ext-cmd returns fail then you should check if there is a path to the cc executable in exec-path and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/cc/executable")))

if chk-sys-cmd returns fail then you should check to see if a C compiler is installed on your system and, if it is, what it is called other than cc

Clojure language configuration

Clojure is a dynamic programming language that targets the Java Virtual Machine
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-clojure)

Ditaa language configuration

Ditaa is a small command-line utility written in Java, that can convert diagrams drawn using ascii art into proper bitmap graphics
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-ditaa)

CSS configuration

Cascading Style Sheets (CSS) is a simple mechanism for adding style to Web documents
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-css)

Gnuplot language configuration

Gnuplot is a command-line driven graphing utility
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-gnuplot)

if chk-ext-cmd returns fail then you should check if there is a path to the gnuplot executable in exec-path and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/gnuplot/executable")))

if chk-sys-cmd returns fail then you should check to see if gnuplot is installed on your system

LaTeX language configuration

LaTeX is a TeX macro package that provides a document processing system
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-latex)

if chk-ext-cmd returns fail then you should check if there is a path to the latex executable in exec-path and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/latex/executable")))

if chk-sys-cmd returns fail then you should check to see if latex is installed on your system

MATLAB® language configuration

MATLAB® is a high-level language and interactive environment that enables you to perform computationally intensive tasks faster than with traditional programming languages such as C, C++, and Fortran
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-matlab)

if chk-ext-cmd returns fail then you should check if there is a path to the MATLAB® executable in exec-path and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/matlab/executable")))

if chk-sys-cmd returns fail then you should check to see if MATLAB® is installed on your system

Perl language configuration

Perl is a highly capable, feature-rich programming language with over 22 years of development
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-perl)

if chk-ext-cmd returns fail then you should check if there is a path to the Perl executable in exec-path and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/perl/executable")))

if chk-sys-cmd returns fail then you should check to see if Perl is installed on your system

Python language configuration

Python is a programming language that lets you work more quickly and integrate your systems more effectively
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-python)

if chk-ext-cmd returns fail then you should check if there is a path to the Python executable in exec-path and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/python/executable")))

if chk-sys-cmd returns fail then you should check to see if Python is installed on your system

Ruby language configuration

Ruby is a dynamic, open source programming language with a focus on simplicity and productivity
if chk-babel-lang returns fail then you should add this line to .emacs

(require 'org-babel-ruby)

if chk-ext-cmd returns fail then you should check if there is a path to the Ruby executable in exec-path and possibly add a line to .emacs

(setq exec-path (append exec-path '("/path/to/ruby/executable")))

if chk-sys-cmd returns fail then you should check to see if Ruby is installed on your system

HTML export

Commands

Org stuff

(let (
      (x (locate-library "org"))
      )
  (if (null x) "fail" x)
  )

(if (null org-version) "fail" org-version)

Export LaTeX classes

(if (null org-export-latex-classes) "fail" "pass")

LaTeX engine specified

Returns the first argument of the first entry in org-latex-to-pdf-process
This is typically a call to the LaTeX engine
If fail is returned, then the variable org-latex-to-pdf-process needs to be set

(require 'ox-latex)
(if (null org-latex-to-pdf-process)
    "fail"
  (substring (first org-latex-to-pdf-process) 0 (string-match "\\ " (first org-latex-to-pdf-process))))

LaTeX engine present

Checks if the LaTeX engine specified by org-latex-to-pdf-process can be found by Org-mode
Returns fail if chk-latex-engine returns fail
If fail is returned, then the variable exec-path probably needs to have the path to the LaTeX engine

(if (string-equal x "fail") x (if (org-check-external-command x "" t)
"pass" "fail"))

`org-agenda-files`

The org-agenda-files variable is required for a number of optional, but useful, Org-mode commands
- org-agenda
- org-export-icalendar-combine-agenda-files : (progn (describe-variable 'org-export-icalendar-combine-agenda-files) (other-window 1))
- others?
It is easy to set

(if (null org-agenda-files)
    "consider setting [[* org-agenda-files][org-agenda-files]]"
  "pass")

`check-latex-scale`

Report the scale setting for inline images. Default is 1.0.

(plist-get org-format-latex-options :scale)

Acknowledgments

Many thanks to the following people for their generous help:

Eric Schulte for setting up the original table and correcting code
Sebastian Rose for the pointer to (featurep FEATURE &optional SUBFEATURE)
Carsten Dominick for Org-mode Guide and his many other efforts to make Org-mode accessible to Lisp illiterates