#+TITLE: Verify an Org-mode environment
#+OPTIONS: num:nil ^:nil
#+LaTeX_CLASS: normal
#+STARTUP: hideblocks
#+TODO: TODO | DONE

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 [[http://repo.or.cz/w/Worg.git/blob_plain/HEAD:/org-contrib/babel/examples/org-check.org][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%20Setup][Org-mode]]      |                |                  |                    |         |
|               | [[*Org%20library][Library]]        | org-library      |                    |         |
|               | [[*Org%20version][Version]]        | org-version      |                    |         |
|---------------+----------------+------------------+--------------------+---------|
| [[*Agenda][Agenda]]        |                |                  |                    |         |
|               |                | chk-agenda-files |                    |         |
|---------------+----------------+------------------+--------------------+---------|
| [[*Export%20LaTeX][LaTeX Export]]  |                |                  |                    |         |
|               | [[*%20org-export-latex-classes][LaTeX classes]]  | chk-ltx-cls      |                    |         |
|               |                | pkg-loaded       | 'org-latex         |         |
|---------------+----------------+------------------+--------------------+---------|
| [[*HTML%20export][HTML export]]   |                |                  |                    |         |
|               |                | pkg-loaded       | 'org-html          |         |
|---------------+----------------+------------------+--------------------+---------|
| [[*Preview%20LaTeX][Preview Latex]] |                |                  |                    |         |
|               |                | chk-ext-cmd      | "latex"            |         |
|               |                | chk-sys-cmd      | "latex"            |         |
|               |                | chk-ext-cmd      | "dvipng"           |         |
|               |                | chk-sys-cmd      | "dvipng"           |         |
|               | [[*chk-latex-scale][latex-scale]]    | chk-latex-scale  |                    |         |
|               |                | pkg-loaded       | 'org-latex         |         |
|---------------+----------------+------------------+--------------------+---------|
| [[*Make%20pdf%20files][Make Pdfs]]     |                |                  |                    |         |
|               | [[* latex][latex]]          | chk-ext-cmd      | "latex"            |         |
|               | [[* chk-latex-system][latex-system]]   | chk-sys-cmd      | "latex"            |         |
|               | [[*LaTeX%20engine][latex-engine]]   | chk-latex-engine |                    |         |
|               | [[*LaTeX%20engine%20present][engine-present]] | chk-engine-cmd   |                    |         |
|---------------+----------------+------------------+--------------------+---------|
| [[*Babel][Org-babel]]     |                |                  |                    |         |
|               | [[*Org%20babel%20provided][Org-babel]]      | pkg-loaded       | 'org-babel         |         |
|               |                |                  |                    |         |
|               | [[*R%20language%20configuration][R language]]     | chk-babel-lang   | "R"                |         |
|               |                | chk-ext-cmd      | "R"                |         |
|               |                | chk-sys-cmd      | "R"                |         |
|               |                | pkg-loaded       | 'org-babel-R       |         |
|               |                |                  |                    |         |
|               | [[*C%20language%20configuration][C language]]     | chk-babel-lang   | "C"                |         |
|               |                | chk-ext-cmd      | "cc"               |         |
|               |                | chk-sys-cmd      | "cc"               |         |
|               |                | pkg-loaded       | 'org-babel-C       |         |
|               |                |                  |                    |         |
|               | [[*Clojure%20language%20configuration][Clojure]]        | chk-babel-lang   | "clojure"          |         |
|               |                | pkg-loaded       | 'org-babel-clojure |         |
|               |                |                  |                    |         |
|               | [[*Ditaa%20language%20configuration][Ditaa]]          | chk-babel-lang   | "ditaa"            |         |
|               |                | pkg-loaded       | 'org-babel-ditaa   |         |
|               |                |                  |                    |         |
|               | [[*CSS%20configuration][CSS]]            | chk-babel-lang   | "css"              |         |
|               |                | pkg-loaded       | 'org-babel-css     |         |
|               |                |                  |                    |         |
|               | [[*Gnuplot%20language%20configuration][Gnuplot]]        | chk-babel-lang   | "gnuplot"          |         |
|               |                | chk-ext-cmd      | "gnuplot"          |         |
|               |                | chk-sys-cmd      | "gnuplot"          |         |
|               |                | pkg-loaded       | 'org-babel-gnuplot |         |
|               |                |                  |                    |         |
|               | [[*LaTeX%20language%20configuration][LaTeX]]          | chk-babel-lang   | "latex"            |         |
|               |                | chk-ext-cmd      | "latex"            |         |
|               |                | chk-sys-cmd      | "latex"            |         |
|               |                | pkg-loaded       | 'org-babel-latex   |         |
|               |                |                  |                    |         |
|               | [[*MATLAB%20language%20configuration][MATLAB®]]        | chk-babel-lang   | "matlab"           |         |
|               |                | chk-ext-cmd      | "matlab"           |         |
|               |                | chk-sys-cmd      | "matlab"           |         |
|               |                | pkg-loaded       | 'org-babel-matlab  |         |
|               |                |                  |                    |         |
|               | [[*Perl%20language%20configuration][Perl]]           | chk-babel-lang   | "perl"             |         |
|               |                | chk-ext-cmd      | "perl"             |         |
|               |                | chk-sys-cmd      | "perl"             |         |
|               |                | pkg-loaded       | 'org-babel-perl    |         |
|               |                |                  |                    |         |
|               | [[*Python%20language%20configuration][Python]]         | chk-babel-lang   | "python"           |         |
|               |                | chk-ext-cmd      | "python"           |         |
|               |                | chk-sys-cmd      | "python"           |         |
|               |                | pkg-loaded       | 'org-babel-python  |         |
|               |                |                  |                    |         |
|               | [[*Ruby%20language%20configuration][Ruby]]           | chk-babel-lang   | "ruby"             |         |
|               |                | chk-ext-cmd      | "ruby"             |         |
|               |                | chk-sys-cmd      | "ruby"             |         |
|               |                | pkg-loaded       | 'org-babel-ruby    |         |
|---------------+----------------+------------------+--------------------+---------|
#+TBLFM: 

* 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
   - [[http://orgmode.org/worg/org-tutorials/org-latex-export.html][LaTeX Export Tutorial]]
*** Check =org-export-latex-classes=
    - Check that the variable [[elisp:(progn (describe-variable 'org-export-latex-classes) (other-window 1))][org-export-latex-classes]] has been set

** Preview LaTeX
   - Previewing LaTeX in the Org-mode buffer requires: 
     - a working LaTeX installation, including the =latex= executable
     - the [[http://sourceforge.net/projects/dvipng/][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 [[http://orgmode.org/worg/org-tutorials/org-latex-export.html#sec-7][LaTeX export]]
** Agenda
   - The [[http://orgmode.org/manual/Agenda-Views.html#Agenda-Views][agenda]] is key to using Org-mode effectively
** Babel
   - [[http://orgmode.org/worg/org-contrib/babel/index.php][Org-babel]] extends the very excellent Org-mode with the ability to
     execute code blocks
   - [[http://orgmode.org/worg/org-contrib/babel/intro.php#getting-started][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=
#+begin_src emacs-lisp
  (require 'org-babel-init)
#+end_src
    - [[http://orgmode.org/worg/org-contrib/babel/intro.php#getting-started][Org-babel installation]] is a 5-step process

*** R language configuration
    - [[http://www.r-project.org/][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=
#+begin_src emacs-lisp
  (require 'org-babel-R)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the R executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to =.emacs=
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/R/executable")))
#+end_src
    - if =chk-sys-cmd= returns =fail= then you should check to see if
      R is installed on your system
*** C language configuration
    - [[http://en.wikipedia.org/wiki/C_%28programming_language%29][C]] is a general-purpose computer programming language
    - if =chk-babel-lang= returns =fail= then you should add this line
      to =.emacs=
#+begin_src emacs-lisp
  (require 'org-babel-C)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the cc executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to =.emacs=
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/cc/executable")))
#+end_src
    - 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
    - [[http://clojure.org/][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=
#+begin_src emacs-lisp
  (require 'org-babel-clojure)
#+end_src

*** Ditaa language configuration
    - [[http://ditaa.sourceforge.net/][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=
#+begin_src emacs-lisp
  (require 'org-babel-ditaa)
#+end_src

*** CSS configuration
    - [[http://www.w3.org/Style/CSS/][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=
#+begin_src emacs-lisp
  (require 'org-babel-css)
#+end_src

*** Gnuplot language configuration
    - [[http://www.gnuplot.info/][Gnuplot]] is a command-line driven graphing utility
    - if =chk-babel-lang= returns =fail= then you should add this line
      to .emacs
#+begin_src emacs-lisp
  (require 'org-babel-gnuplot)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the gnuplot executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to .emacs
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/gnuplot/executable")))
#+end_src
    - if =chk-sys-cmd= returns =fail= then you should check to see if
      gnuplot is installed on your system

*** LaTeX language configuration
    - [[http://www.tug.org/][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
#+begin_src emacs-lisp
  (require 'org-babel-latex)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the latex executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to .emacs
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/latex/executable")))
#+end_src
    - 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
#+begin_src emacs-lisp
  (require 'org-babel-matlab)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the MATLAB® executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to .emacs
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/matlab/executable")))
#+end_src
    - if =chk-sys-cmd= returns =fail= then you should check to see if
      MATLAB® is installed on your system

*** Perl language configuration
    - [[http://www.perl.org/][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=
#+begin_src emacs-lisp
  (require 'org-babel-perl)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the Perl executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to =.emacs=
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/perl/executable")))
#+end_src
    - if =chk-sys-cmd= returns =fail= then you should check to see if
      Perl is installed on your system

*** Python language configuration
    - [[http://www.python.org/][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=
#+begin_src emacs-lisp
  (require 'org-babel-python)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the Python executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to =.emacs=
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/python/executable")))
#+end_src
    - if =chk-sys-cmd= returns =fail= then you should check to see if
      Python is installed on your system

*** Ruby language configuration
    - [[http://www.ruby-lang.org/en/][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=
#+begin_src emacs-lisp
  (require 'org-babel-ruby)
#+end_src
    - if =chk-ext-cmd= returns =fail= then you should check if there
      is a path to the Ruby executable in [[elisp:(progn%20(describe-variable%20'exec-path)%20(other-window%201))][exec-path]] and possibly add a
      line to =.emacs=
#+begin_src emacs-lisp
   (setq exec-path (append exec-path '("/path/to/ruby/executable")))
#+end_src
    - if =chk-sys-cmd= returns =fail= then you should check to see if
      Ruby is installed on your system

** HTML export
* Commands
** Org stuff
#+srcname: org-library
#+begin_src emacs-lisp :results silent
  (let (
        (x (locate-library "org"))
        )
    (if (null x) "fail" x)
    )
#+end_src

#+srcname: org-version
#+begin_src emacs-lisp :results silent
(if (null org-version) "fail" org-version)  
#+end_src

** Package loaded
#+srcname: pkg-loaded(x)
#+begin_src emacs-lisp :results silent
  (if (featurep x) "pass" "fail")
#+end_src

** Babel languages
   - Checks if a language can be tangled by Org-babel
#+srcname: chk-babel-lang(x)
#+begin_src emacs-lisp :results silent
  (let ((z  (mapcar #'(lambda (y)
                (first y)) org-babel-tangle-langs )
  )) (if (member x z) "pass" "fail") )
#+end_src

** Check external commands
#+srcname: chk-ext-cmd(x)
#+begin_src emacs-lisp :results silent
    (if (org-check-external-command x "" t) "pass" "fail") 
#+end_src

** Export LaTeX classes
#+srcname: chk-ltx-cls
#+begin_src emacs-lisp :results silent
  (if (null org-export-latex-classes) "fail" "pass")
#+end_src

** 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
#+srcname: chk-latex-engine
#+begin_src emacs-lisp :results silent
  (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))) )
#+end_src

** 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
#+srcname: chk-engine-cmd
#+begin_src emacs-lisp :var x=chk-latex-engine :results silent
  (if (string-equal x "fail") x (if (org-check-external-command x "" t)
  "pass" "fail"))
#+end_src
   

** =org-agenda-files= 
   - The [[elisp:(progn (describe-variable 'org-agenda-files) (other-window 1))][org-agenda-files]] variable is required for a number of optional, but useful, Org-mode commands
        - [[elisp:(progn (describe-function 'org-agenda) (other-window 1))][org-agenda]]
        - [[elisp:(progn (describe-variable 'org-export-icalendar-combine-agenda-files) (other-window 1))][org-export-icalendar-combine-agenda-files]]
        - others?
   - It is [[http://orgmode.org/manual/Agenda-files.html#Agenda-files][easy to set]]
#+srcname: chk-agenda-files
#+begin_src emacs-lisp :results silent
  (if (null org-agenda-files)
      "consider setting [[* org-agenda-files][org-agenda-files]]"
    "pass")
#+end_src

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

#+srcname: chk-sys-cmd(x)
#+begin_src sh :results silent
    if which $x > /dev/null;
    then echo pass;
    else echo fail;
    fi
#+end_src


** =check-latex-scale=
Report the scale setting for inline images.  Default is 1.0.

#+srcname: chk-latex-scale
#+begin_src emacs-lisp :results silent
  (plist-get org-format-latex-options :scale)
#+end_src
* Learning Lisp (slowly)                                           :noexport:
** Check LaTeX packages
#+srcname: chk-kpse
#+begin_src sh :results silent
  if which kpsewhich > /dev/null;
  then echo pass;
  else echo fail;
  fi
#+end_src

#+srcname: chk-ltx-pkg
#+begin_src emacs-lisp :var x=chk-kpse() 
  (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")
#+end_src

#+results: chk-ltx-pkg

* 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 [[http://orgmode.org/guide/][Org-mode Guide]] and his many other efforts to
    make Org-mode accessible to Lisp illiterates

* Notes                                                            :noexport:
** DONE Provide a link to the org-check.org file in Instructions
** DONE Check, does Windows have something like which?
   - which is used in the shell scripts td wrote to check for latex
     and dvipng commands at the system level
** Source
#+srcname: copy-to-worg
#+begin_src sh :exports none :results output
  cd ~/org/Worg/
  git pull
  cp ~/org/org-check/org-check.org  ~/org/Worg/org-contrib/babel/examples/org-check.org
  git add org-contrib/babel/examples/org-check.org
  git commit -m "Additions to org-check.org"
  git push
#+end_src

#+results: copy-to-worg
#+begin_example
Already up-to-date.
[master 25fb17b] Additions to org-check.org
 1 files changed, 95 insertions(+), 66 deletions(-)
Counting objects: 11, done.
Delta compression using up to 2 threads.
Compressing objects:  16% (1/6)   
Compressing objects:  33% (2/6)   
Compressing objects:  50% (3/6)   
Compressing objects:  66% (4/6)   
Compressing objects:  83% (5/6)   
Compressing objects: 100% (6/6)   
Compressing objects: 100% (6/6), done.
Writing objects:  16% (1/6)   
Writing objects:  33% (2/6)   
Writing objects:  50% (3/6)   
Writing objects:  66% (4/6)   
Writing objects:  83% (5/6)   
Writing objects: 100% (6/6)   
Writing objects: 100% (6/6), 1.38 KiB, done.
Total 6 (delta 5), reused 0 (delta 0)
To git+ssh://repo.or.cz/srv/git/Worg.git
   108db30..25fb17b  master -> master
#+end_example