| blob | 4c150771ef55b6f5fd3c69aceb52731d800c09ce |
1 #+TITLE: Verify an Org-mode environment
2 #+OPTIONS: num:nil ^:nil
3 #+LaTeX_CLASS: normal
4 #+STARTUP: hideblocks
5 #+TODO: TODO | DONE
7 Check an Org-mode environment.
9 *warning*: executing the table in this buffer will execute elisp and
10 shell commands on your system. These commands are intended to check
11 aspects of your environment for compatibility with Org-mode, however
12 malicious people could tie arbitrary and/or malicious code blocks to
13 this table.
14 - don't be malicious, only put reasonable code into this buffer
15 - don't be angry, you've been warned about the possible risks of
16 using this buffer
18 In general Org-moders are very nice and will most likely keep this
19 buffer both safe and useful.
21 * Instructions
22 - Download the file [[https://git.sr.ht/~bzg/worg/tree/master/item/org-contrib/babel/examples/org-check.org][org-check.org]]
23 - Calculate the table by putting point in the table and pressing =C-u C-c *=
24 - Check the =results= column
25 - if you see all "pass" results, then your environment passes
26 - if you see "fail" or other unexpected results, then follow the
27 link in the =topic= column for an explanation
29 | task | topic | command | arg | results |
30 |---------------+----------------+------------------+--------------------+---------|
31 | [[*Org Setup][Org-mode]] | | | | |
32 | | [[*Org library][Library]] | org-library | | |
33 | | [[*Org version][Version]] | org-version | | |
34 |---------------+----------------+------------------+--------------------+---------|
35 | [[*Agenda][Agenda]] | | | | |
36 | | | chk-agenda-files | | |
37 |---------------+----------------+------------------+--------------------+---------|
38 | [[*Export LaTeX][LaTeX Export]] | | | | |
39 | | [[*Check =org-export-latex-classes=][LaTeX classes]] | chk-ltx-cls | | |
40 | | | pkg-loaded | 'org-latex | |
41 |---------------+----------------+------------------+--------------------+---------|
42 | [[*HTML export][HTML export]] | | | | |
43 | | | pkg-loaded | 'org-html | |
44 |---------------+----------------+------------------+--------------------+---------|
45 | [[*Preview LaTeX][Preview Latex]] | | | | |
46 | | | chk-ext-cmd | "latex" | |
47 | | | chk-sys-cmd | "latex" | |
48 | | | chk-ext-cmd | "dvipng" | |
49 | | | chk-sys-cmd | "dvipng" | |
50 | | [[*=check-latex-scale=][latex-scale]] | chk-latex-scale | | |
51 | | | pkg-loaded | 'org-latex | |
52 |---------------+----------------+------------------+--------------------+---------|
53 | [[*Make pdf files][Make Pdfs]] | | | | |
54 | | [[*LaTeX language configuration][latex]] | chk-ext-cmd | "latex" | |
55 | | [[*LaTeX language configuration][latex-system]] | chk-sys-cmd | "latex" | |
56 | | [[*LaTeX engine specified][latex-engine]] | chk-latex-engine | | |
57 | | [[*LaTeX engine present][engine-present]] | chk-engine-cmd | | |
58 |---------------+----------------+------------------+--------------------+---------|
59 | [[*Babel][Org-babel]] | | | | |
60 | | [[*Org-babel provided][Org-babel]] | pkg-loaded | 'org-babel | |
61 | | | | | |
62 | | [[*R language configuration][R language]] | chk-babel-lang | "R" | |
63 | | | chk-ext-cmd | "R" | |
64 | | | chk-sys-cmd | "R" | |
65 | | | pkg-loaded | 'org-babel-R | |
66 | | | | | |
67 | | [[*C language configuration][C language]] | chk-babel-lang | "C" | |
68 | | | chk-ext-cmd | "cc" | |
69 | | | chk-sys-cmd | "cc" | |
70 | | | pkg-loaded | 'org-babel-C | |
71 | | | | | |
72 | | [[*Clojure language configuration][Clojure]] | chk-babel-lang | "clojure" | |
73 | | | pkg-loaded | 'org-babel-clojure | |
74 | | | | | |
75 | | [[*Ditaa language configuration][Ditaa]] | chk-babel-lang | "ditaa" | |
76 | | | pkg-loaded | 'org-babel-ditaa | |
77 | | | | | |
78 | | [[*CSS configuration][CSS]] | chk-babel-lang | "css" | |
79 | | | pkg-loaded | 'org-babel-css | |
80 | | | | | |
81 | | [[*Gnuplot language configuration][Gnuplot]] | chk-babel-lang | "gnuplot" | |
82 | | | chk-ext-cmd | "gnuplot" | |
83 | | | chk-sys-cmd | "gnuplot" | |
84 | | | pkg-loaded | 'org-babel-gnuplot | |
85 | | | | | |
86 | | [[*LaTeX language configuration][LaTeX]] | chk-babel-lang | "latex" | |
87 | | | chk-ext-cmd | "latex" | |
88 | | | chk-sys-cmd | "latex" | |
89 | | | pkg-loaded | 'org-babel-latex | |
90 | | | | | |
91 | | [[*MATLAB® language configuration][MATLAB®]] | chk-babel-lang | "matlab" | |
92 | | | chk-ext-cmd | "matlab" | |
93 | | | chk-sys-cmd | "matlab" | |
94 | | | pkg-loaded | 'org-babel-matlab | |
95 | | | | | |
96 | | [[*Perl language configuration][Perl]] | chk-babel-lang | "perl" | |
97 | | | chk-ext-cmd | "perl" | |
98 | | | chk-sys-cmd | "perl" | |
99 | | | pkg-loaded | 'org-babel-perl | |
100 | | | | | |
101 | | [[*Python language configuration][Python]] | chk-babel-lang | "python" | |
102 | | | chk-ext-cmd | "python" | |
103 | | | chk-sys-cmd | "python" | |
104 | | | pkg-loaded | 'org-babel-python | |
105 | | | | | |
106 | | [[*Ruby language configuration][Ruby]] | chk-babel-lang | "ruby" | |
107 | | | chk-ext-cmd | "ruby" | |
108 | | | chk-sys-cmd | "ruby" | |
109 | | | pkg-loaded | 'org-babel-ruby | |
110 |---------------+----------------+------------------+--------------------+---------|
111 #+TBLFM:
113 * Tasks
114 ** Org Setup
115 - It is sometimes the case that updating Org-mode seems to have no
116 effect. This can arise when there are multiple Org-mode
117 installations, or if Org-mode was compiled and then not
118 recompiled after an update.
119 *** Org library
120 - This is where emacs is finding the Org-mode installation
121 *** Org version
122 - This is the hard-coded version number from org.el.
123 ** Export LaTeX
125 - [[https://orgmode.org/worg/org-tutorials/org-latex-export.html][LaTeX Export Tutorial]]
127 *** Check =org-export-latex-classes=
129 - Check that the variable =org-export-latex-classes= has been set: [[elisp:(progn (describe-variable 'org-export-latex-classes) (other-window 1))]]
131 ** Preview LaTeX
132 - Previewing LaTeX in the Org-mode buffer requires:
133 - a working LaTeX installation, including the =latex= executable
134 - the [[http://sourceforge.net/projects/dvipng/][dvipng]] executable
135 - paths to these executables on =exec-path=
136 - If either latex-system or dvipng-system fails, then you probably
137 need to install software
138 - If latex-system passes and latex fails, then you need to modify
139 the variable =exec-path=, so the path to the latex executable is
140 included
141 - If dvipng-system passes and dvipng fails, then you need to modify
142 the variable =exec-path=, so the path to the dvipng executable is
143 included
144 - Image size can be scaled using the =:scale= property of the
145 variable =org-format-latex-options=
146 ** Make pdf files
147 - Pdf files are created for in-buffer preview and as the
148 end-product of [[https://orgmode.org/worg/org-tutorials/org-latex-export.html#sec-7][LaTeX export]]
149 ** Agenda
150 - The [[https://orgmode.org/manual/Agenda-Views.html#Agenda-Views][agenda]] is key to using Org-mode effectively
151 ** Babel
152 - [[https://orgmode.org/worg/org-contrib/babel/index.php][Org-babel]] extends the very excellent Org-mode with the ability to
153 execute code blocks
154 - [[https://orgmode.org/worg/org-contrib/babel/intro.php#getting-started][Org-babel configuration]] is a 5-step process that requires entries
155 in =.emacs=
156 *** Org-babel provided
157 - If this test fails, then Org-babel isn't loaded
158 - You probably need something like this in =.emacs=
159 #+begin_src emacs-lisp
160 (require 'org-babel-init)
161 #+end_src
162 - [[https://orgmode.org/worg/org-contrib/babel/intro.php#getting-started][Org-babel installation]] is a 5-step process
164 *** R language configuration
165 - [[http://www.r-project.org/][R]] is a free software environment for statistical computing and graphics
166 - if =chk-babel-lang= returns =fail= then you should add this line
167 to =.emacs=
168 #+begin_src emacs-lisp
169 (require 'org-babel-R)
170 #+end_src
171 - if =chk-ext-cmd= returns =fail= then you should check if there
172 is a path to the R executable in =exec-path= : [[elisp:(progn (describe-variable 'exec-path) (other-window))]] and possibly add a line to =.emacs=
173 #+begin_src emacs-lisp
174 (setq exec-path (append exec-path '("/path/to/R/executable")))
175 #+end_src
176 - if =chk-sys-cmd= returns =fail= then you should check to see if
177 R is installed on your system
178 *** C language configuration
179 - [[https://en.wikipedia.org/wiki/C_%28programming_language%29][C]] is a general-purpose computer programming language
180 - if =chk-babel-lang= returns =fail= then you should add this line
181 to =.emacs=
182 #+begin_src emacs-lisp
183 (require 'org-babel-C)
184 #+end_src
185 - if =chk-ext-cmd= returns =fail= then you should check if there
186 is a path to the cc executable in [[elisp:(progn (describe-variable 'exec-path) (other-window 1))][exec-path]] and possibly add a
187 line to =.emacs=
188 #+begin_src emacs-lisp
189 (setq exec-path (append exec-path '("/path/to/cc/executable")))
190 #+end_src
191 - if =chk-sys-cmd= returns =fail= then you should check to see if
192 a C compiler is installed on your system and, if it is, what it
193 is called other than =cc=
194 *** Clojure language configuration
195 - [[http://clojure.org/][Clojure]] is a dynamic programming language that targets the Java Virtual Machine
196 - if =chk-babel-lang= returns =fail= then you should add this line
197 to =.emacs=
198 #+begin_src emacs-lisp
199 (require 'org-babel-clojure)
200 #+end_src
202 *** Ditaa language configuration
203 - [[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
204 - if =chk-babel-lang= returns =fail= then you should add this line
205 to =.emacs=
206 #+begin_src emacs-lisp
207 (require 'org-babel-ditaa)
208 #+end_src
210 *** CSS configuration
211 - [[http://www.w3.org/Style/CSS/][Cascading Style Sheets (CSS)]] is a simple mechanism for adding style to Web documents
212 - if =chk-babel-lang= returns =fail= then you should add this line
213 to =.emacs=
214 #+begin_src emacs-lisp
215 (require 'org-babel-css)
216 #+end_src
218 *** Gnuplot language configuration
219 - [[http://www.gnuplot.info/][Gnuplot]] is a command-line driven graphing utility
220 - if =chk-babel-lang= returns =fail= then you should add this line
221 to .emacs
222 #+begin_src emacs-lisp
223 (require 'org-babel-gnuplot)
224 #+end_src
225 - if =chk-ext-cmd= returns =fail= then you should check if there
226 is a path to the gnuplot executable in [[elisp:(progn (describe-variable 'exec-path) (other-window 1))][exec-path]] and possibly add a
227 line to .emacs
228 #+begin_src emacs-lisp
229 (setq exec-path (append exec-path '("/path/to/gnuplot/executable")))
230 #+end_src
231 - if =chk-sys-cmd= returns =fail= then you should check to see if
232 gnuplot is installed on your system
234 *** LaTeX language configuration
235 - [[http://www.tug.org/][LaTeX]] is a TeX macro package that provides a document processing system
236 - if =chk-babel-lang= returns =fail= then you should add this line
237 to .emacs
238 #+begin_src emacs-lisp
239 (require 'org-babel-latex)
240 #+end_src
241 - if =chk-ext-cmd= returns =fail= then you should check if there
242 is a path to the latex executable in [[elisp:(progn (describe-variable 'exec-path) (other-window 1))][exec-path]] and possibly add a
243 line to .emacs
244 #+begin_src emacs-lisp
245 (setq exec-path (append exec-path '("/path/to/latex/executable")))
246 #+end_src
247 - if =chk-sys-cmd= returns =fail= then you should check to see if
248 latex is installed on your system
250 *** MATLAB® language configuration
251 - MATLAB® is a high-level language and interactive environment
252 that enables you to perform computationally intensive tasks
253 faster than with traditional programming languages such as C,
254 C++, and Fortran
255 - if =chk-babel-lang= returns =fail= then you should add this line
256 to .emacs
257 #+begin_src emacs-lisp
258 (require 'org-babel-matlab)
259 #+end_src
260 - if =chk-ext-cmd= returns =fail= then you should check if there
261 is a path to the MATLAB® executable in [[elisp:(progn (describe-variable 'exec-path) (other-window 1))][exec-path]] and possibly add a
262 line to .emacs
263 #+begin_src emacs-lisp
264 (setq exec-path (append exec-path '("/path/to/matlab/executable")))
265 #+end_src
266 - if =chk-sys-cmd= returns =fail= then you should check to see if
267 MATLAB® is installed on your system
269 *** Perl language configuration
270 - [[http://www.perl.org/][Perl]] is a highly capable, feature-rich programming language with
271 over 22 years of development
272 - if =chk-babel-lang= returns =fail= then you should add this line
273 to =.emacs=
274 #+begin_src emacs-lisp
275 (require 'org-babel-perl)
276 #+end_src
277 - if =chk-ext-cmd= returns =fail= then you should check if there
278 is a path to the Perl executable in [[elisp:(progn (describe-variable 'exec-path) (other-window 1))][exec-path]] and possibly add a
279 line to =.emacs=
280 #+begin_src emacs-lisp
281 (setq exec-path (append exec-path '("/path/to/perl/executable")))
282 #+end_src
283 - if =chk-sys-cmd= returns =fail= then you should check to see if
284 Perl is installed on your system
286 *** Python language configuration
287 - [[http://www.python.org/][Python]] is a programming language that lets you work more quickly
288 and integrate your systems more effectively
289 - if =chk-babel-lang= returns =fail= then you should add this line
290 to =.emacs=
291 #+begin_src emacs-lisp
292 (require 'org-babel-python)
293 #+end_src
294 - if =chk-ext-cmd= returns =fail= then you should check if there
295 is a path to the Python executable in [[elisp:(progn (describe-variable 'exec-path) (other-window 1))][exec-path]] and possibly add a
296 line to =.emacs=
297 #+begin_src emacs-lisp
298 (setq exec-path (append exec-path '("/path/to/python/executable")))
299 #+end_src
300 - if =chk-sys-cmd= returns =fail= then you should check to see if
301 Python is installed on your system
303 *** Ruby language configuration
304 - [[http://www.ruby-lang.org/en/][Ruby]] is a dynamic, open source programming language with a focus
305 on simplicity and productivity
306 - if =chk-babel-lang= returns =fail= then you should add this line
307 to =.emacs=
308 #+begin_src emacs-lisp
309 (require 'org-babel-ruby)
310 #+end_src
311 - if =chk-ext-cmd= returns =fail= then you should check if there
312 is a path to the Ruby executable in [[elisp:(progn (describe-variable 'exec-path) (other-window 1))][exec-path]] and possibly add a
313 line to =.emacs=
314 #+begin_src emacs-lisp
315 (setq exec-path (append exec-path '("/path/to/ruby/executable")))
316 #+end_src
317 - if =chk-sys-cmd= returns =fail= then you should check to see if
318 Ruby is installed on your system
320 ** HTML export
321 * Commands
322 ** Org stuff
323 #+name: org-library
324 #+begin_src emacs-lisp :results silent
325 (let (
326 (x (locate-library "org"))
327 )
328 (if (null x) "fail" x)
329 )
330 #+end_src
332 #+name: org-version
333 #+begin_src emacs-lisp :results silent
334 (if (null org-version) "fail" org-version)
335 #+end_src
337 ** COMMENT Package loaded
339 FIXME: fix error "variable "pkg-loaded" in block "transpose-elisp" must be
340 assigned a default value"
342 #+name: pkg-loaded(x)
343 #+begin_src emacs-lisp :results silent
344 (if (featurep x) "pass" "fail")
345 #+end_src
347 ** COMMENT Babel languages
349 FIXME: "variable "chk-babel-lang" in block "transpose-elisp" must be
350 assigned a default value"
352 - Checks if a language can be tangled by Org-babel
353 #+name: chk-babel-lang(x)
354 #+begin_src emacs-lisp :results silent
355 (let ((z (mapcar #'(lambda (y)
356 (first y)) org-babel-tangle-langs )
357 )) (if (member x z) "pass" "fail") )
358 #+end_src
360 ** COMMENT Check external commands
361 #+name: chk-ext-cmd(x)
362 #+begin_src emacs-lisp :results silent
363 (if (org-check-external-command x "" t) "pass" "fail")
364 #+end_src
366 ** Export LaTeX classes
367 #+name: chk-ltx-cls
368 #+begin_src emacs-lisp :results silent
369 (if (null org-export-latex-classes) "fail" "pass")
370 #+end_src
372 ** LaTeX engine specified
373 - Returns the first argument of the first entry in =org-latex-to-pdf-process=
374 - This is typically a call to the LaTeX engine
375 - If =fail= is returned, then the variable =org-latex-to-pdf-process=
376 needs to be set
377 #+name: chk-latex-engine
378 #+begin_src emacs-lisp :results silent
379 (require 'org-latex)
380 (if (null org-latex-to-pdf-process) "fail" (substring (first org-latex-to-pdf-process) 0 (string-match "\\ " (first org-latex-to-pdf-process))) )
381 #+end_src
383 ** LaTeX engine present
384 - Checks if the LaTeX engine specified by
385 =org-latex-to-pdf-process= can be found by Org-mode
386 - Returns =fail= if =chk-latex-engine= returns =fail=
387 - If =fail= is returned, then the variable =exec-path= probably
388 needs to have the path to the LaTeX engine
389 #+name: chk-engine-cmd
390 #+begin_src emacs-lisp :var x=chk-latex-engine :results silent
391 (if (string-equal x "fail") x (if (org-check-external-command x "" t)
392 "pass" "fail"))
393 #+end_src
396 ** =org-agenda-files=
397 - 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
398 - [[elisp:(progn (describe-function 'org-agenda) (other-window 1))][org-agenda]]
399 - org-export-icalendar-combine-agenda-files : [[elisp:(progn (describe-variable 'org-export-icalendar-combine-agenda-files) (other-window 1))]]
400 - others?
401 - It is [[https://orgmode.org/manual/Agenda-files.html#Agenda-files][easy to set]]
402 #+name: chk-agenda-files
403 #+begin_src emacs-lisp :results silent
404 (if (null org-agenda-files)
405 "consider setting [[* org-agenda-files][org-agenda-files]]"
406 "pass")
407 #+end_src
409 ** COMMENT Check System Command
411 FIXME: "variable "chk-sys-cmd" in block "transpose-elisp" must be assigned
412 a default value"
414 - Check if x is present on the system path
415 - If =fail= is returned, ensure that the executable is found on
416 your system, then check that =$PATH= holds a path to the
417 executable
419 #+name: chk-sys-cmd(x)
420 #+begin_src sh :results silent
421 if which $x > /dev/null;
422 then echo pass;
423 else echo fail;
424 fi
425 #+end_src
428 ** =check-latex-scale=
429 Report the scale setting for inline images. Default is 1.0.
431 #+name: chk-latex-scale
432 #+begin_src emacs-lisp :results silent
433 (plist-get org-format-latex-options :scale)
434 #+end_src
435 * Learning Lisp (slowly) :noexport:
436 ** Check LaTeX packages
437 #+name: chk-kpse
438 #+begin_src sh :results silent
439 if which kpsewhich > /dev/null;
440 then echo pass;
441 else echo fail;
442 fi
443 #+end_src
445 #+name: chk-ltx-pkg
446 #+begin_src emacs-lisp :var x=chk-kpse()
447 (if (string-equal x "pass")
448 (let* ((z (org-splice-latex-header org-format-latex-header
449 org-export-latex-default-packages-alist
450 org-export-latex-packages-alist nil))
451 (d (mapcar #'(lambda (m) (if (listp m) (nth 1 m) m))
452 org-export-latex-default-packages-alist))
453 (e (mapcar #'(lambda (f)
454 (position (concatenate 'string "{" f "}") z))d))
455 )
456 e ) "fail")
457 #+end_src
459 #+results: chk-ltx-pkg
461 * Acknowledgments
462 Many thanks to the following people for their generous help:
463 - Eric Schulte for setting up the original table and correcting code
464 - Sebastian Rose for the pointer to (featurep FEATURE &optional SUBFEATURE)
465 - Carsten Dominick for [[https://orgmode.org/guide/][Org-mode Guide]] and his many other efforts to
466 make Org-mode accessible to Lisp illiterates
468 * Notes :noexport:
469 ** DONE Provide a link to the org-check.org file in Instructions
470 ** DONE Check, does Windows have something like which?
471 - which is used in the shell scripts td wrote to check for latex
472 and dvipng commands at the system level
473 ** Source
474 #+name: copy-to-worg
475 #+begin_src sh :exports none :results output
476 cd ~/org/worg/
477 git pull
478 cp ~/org/org-check/org-check.org ~/org/worg/org-contrib/babel/examples/org-check.org
479 git add org-contrib/babel/examples/org-check.org
480 git commit -m "Additions to org-check.org"
481 git push
482 #+end_src
484 #+results: copy-to-worg
485 #+begin_example
486 Already up-to-date.
487 [master 25fb17b] Additions to org-check.org
488 1 files changed, 95 insertions(+), 66 deletions(-)
489 Counting objects: 11, done.
490 Delta compression using up to 2 threads.
491 Compressing objects: 16% (1/6)
492 ...
493 To git@git.sr.ht:~bzg/worg
494 108db30..25fb17b master -> master
495 #+end_example