Verify an Org-mode environment

Table of Contents

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.

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    
  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

Check org-export-latex-classes

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)

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 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 '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

(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

Documentation from the http://orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.