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	results
Org-mode
	Library	org-library		Users/dk.emacs.d/src/org/lisp/org.el
	Version	org-version		6.36trans
Agenda
		chk-agenda-files		pass
LaTeX Export
	LaTeX classes	chk-ltx-cls		pass
		pkg-loaded	'org-latex	pass
HTML export
		pkg-loaded	'org-html	pass
Preview Latex
		chk-ext-cmd	"latex"	pass
		chk-sys-cmd	"latex"	pass
		chk-ext-cmd	"dvipng"	pass
		chk-sys-cmd	"dvipng"	pass
	latex-scale	chk-latex-scale		1.0
		pkg-loaded	'org-latex	pass
Make Pdfs
	latex	chk-ext-cmd	"latex"	pass
	latex-system	chk-sys-cmd	"latex"	pass
	latex-engine	chk-latex-engine		pdflatex
	engine-present	chk-engine-cmd		pass
Org-babel
	Org-babel	pkg-loaded	'org-babel	pass
	R language	chk-babel-lang	"R"	pass
		chk-ext-cmd	"R"	pass
		chk-sys-cmd	"R"	pass
		pkg-loaded	'org-babel-R	pass
	C language	chk-babel-lang	"C"	fail
		chk-ext-cmd	"cc"	pass
		chk-sys-cmd	"cc"	pass
		pkg-loaded	'org-babel-C	fail
	Clojure	chk-babel-lang	"clojure"	fail
		pkg-loaded	'org-babel-clojure	fail
	Ditaa	chk-babel-lang	"ditaa"	pass
		pkg-loaded	'org-babel-ditaa	pass
	CSS	chk-babel-lang	"css"	fail
		pkg-loaded	'org-babel-css	fail
	Gnuplot	chk-babel-lang	"gnuplot"	fail
		chk-ext-cmd	"gnuplot"	fail
		chk-sys-cmd	"gnuplot"	fail
		pkg-loaded	'org-babel-gnuplot	fail
	LaTeX	chk-babel-lang	"latex"	pass
		chk-ext-cmd	"latex"	pass
		chk-sys-cmd	"latex"	pass
		pkg-loaded	'org-babel-latex	pass
	MATLAB®	chk-babel-lang	"matlab"	fail
		chk-ext-cmd	"matlab"	fail
		chk-sys-cmd	"matlab"	fail
		pkg-loaded	'org-babel-matlab	fail
	Perl	chk-babel-lang	"perl"	fail
		chk-ext-cmd	"perl"	pass
		chk-sys-cmd	"perl"	pass
		pkg-loaded	'org-babel-perl	fail
	Python	chk-babel-lang	"python"	pass
		chk-ext-cmd	"python"	pass
		chk-sys-cmd	"python"	pass
		pkg-loaded	'org-babel-python	pass
	Ruby	chk-babel-lang	"ruby"	fail
		chk-ext-cmd	"ruby"	pass
		chk-sys-cmd	"ruby"	pass
		pkg-loaded	'org-babel-ruby	fail

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 <elisp:(progn (describe-variable 'org-export-latex-classes) (other-window 1))> has been set

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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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 <elisp:(progn (describe-variable 'exec-path) (other-window 1))> 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)

Package loaded

(if (featurep x) "pass" "fail")

Babel languages

Checks if a language can be tangled by Org-babel

(let ((z  (mapcar #'(lambda (y)
              (first y)) org-babel-tangle-langs )
)) (if (member x z) "pass" "fail") )

Check external commands

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

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 'org-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 <elisp:(progn (describe-variable 'org-agenda-files) (other-window 1))> variable is required for a number of optional, but useful, Org-mode commands
- <elisp:(progn (describe-function 'org-agenda) (other-window 1))>
- <elisp:(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 System Command

Check if x is present on the system path
If fail is returned, ensure that the executable is found on your system, then check that $PATH holds a path to the executable

if which $x > /dev/null;
then echo pass;
else echo fail;
fi

`check-latex-scale`

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

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

Learning Lisp (slowly)

Check LaTeX packages

if which kpsewhich > /dev/null;
then echo pass;
else echo fail;
fi

(if (string-equal x "pass") 
  (let* ((z (org-splice-latex-header org-format-latex-header
                                    org-export-latex-default-packages-alist
                                    org-export-latex-packages-alist nil))
        (d (mapcar #'(lambda (m) (if (listp m) (nth 1 m) m))
                   org-export-latex-default-packages-alist))
        (e (mapcar #'(lambda (f)
                       (position (concatenate 'string "{" f "}") z))d))
        )
   e ) "fail")

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