From 6424527dde6e487ce55dddae1260df3d84c2775e Mon Sep 17 00:00:00 2001 From: Leo Butler Date: Thu, 26 Oct 2023 20:49:41 -0500 Subject: [PATCH] * org-contrib/babel/languages/ob-doc-ditaa.org: update documentation * org-contrib/babel/languages/ob-doc-ditaa.org: Add a subsection that documents the four DEFCUSTOM variables. Modify the existing examples so that the org code that is exported also creates the code-blocks that are executed. Add a subsection that documents how to use those customization variables in order to run ditaa from a script, not necessarily as a jar file. * org-contrib/babel/languages/images/hello-world-from-script.png: This is a new file created by the new example. Ref: https://list.orgmode.org/ZTEML8zWrB6kQflk@toolbox/T/ --- .../images/hello-world-from-script.png | Bin 0 -> 3314 bytes org-contrib/babel/languages/ob-doc-ditaa.org | 86 ++++++++++++++++-- 2 files changed, 77 insertions(+), 9 deletions(-) create mode 100644 org-contrib/babel/languages/images/hello-world-from-script.png diff --git a/org-contrib/babel/languages/images/hello-world-from-script.png b/org-contrib/babel/languages/images/hello-world-from-script.png new file mode 100644 index 0000000000000000000000000000000000000000..8a039e1bad997ebd31d8906cc1d1f234e9159e09 GIT binary patch literal 3314 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 literal 0 HcmV?d00001 diff --git a/org-contrib/babel/languages/ob-doc-ditaa.org b/org-contrib/babel/languages/ob-doc-ditaa.org index 0ae949c2..66f7d4ad 100644 --- a/org-contrib/babel/languages/ob-doc-ditaa.org +++ b/org-contrib/babel/languages/ob-doc-ditaa.org @@ -57,6 +57,14 @@ Activate evaluation of =ditaa= source code blocks by adding =ditaa= to '((ditaa . t))) ; this line activates ditaa #+END_SRC +** Customization Options +Org needs to know a few things about =ditaa= and the =java= executable in order to function. The following is a list of variables that can be customized. + +- org-ditaa-jar-path :: The path to the =ditaa= jar file. +- org-babel-ditaa-java-cmd :: The name or path to the Java executable used to run the =ditaa= jar file. +- org-ditaa-eps-jar-path :: The path to the =ditaaeps= jar file. [[https://ditaa-addons.sourceforge.net/][DitaaEps]] is maintained as part of the [[https://ditaa-addons.sourceforge.net/][ditaa-addons]] project. +- org-ditaa-jar-option :: The prefix used before the =ditaa= jar path. The default is =-jar=. + * Babel Features for ditaa Code Blocks ** Header Arguments - file :: =ditaa= source code blocks require that an output file be specified @@ -67,8 +75,13 @@ Activate evaluation of =ditaa= source code blocks by adding =ditaa= to ** Result Types =Ditaa= source code blocks return a link to a [[http://www.libpng.org/pub/png/][png]] bitmap file. * Examples of Use +** Hello World The obligatory Hello World! example in =ditaa=: -#+BEGIN_EXAMPLE + +#+NAME: hello-world.org +#+BEGIN_SRC org :exports code :results replace +,#+NAME: hello-world +,#+HEADER: :exports results ,#+BEGIN_SRC ditaa :file images/hello-world.png +--------------+ | | @@ -76,9 +89,11 @@ The obligatory Hello World! example in =ditaa=: | | +--------------+ ,#+END_SRC -#+END_EXAMPLE +#+END_SRC -#+header: :exports results +#+RESULTS: hello-world.org +#+NAME: hello-world +#+HEADER: :exports results #+BEGIN_SRC ditaa :file images/hello-world.png +--------------+ | | @@ -87,23 +102,29 @@ The obligatory Hello World! example in =ditaa=: +--------------+ #+END_SRC -#+RESULTS: +#+RESULTS: hello-world [[file:images/hello-world.png]] +** Passing command-line options to =ditaa= Now, round all corners by passing =ditaa= the =-r,--round-corners= command line switch. -#+BEGIN_EXAMPLE -#+BEGIN_SRC ditaa :file images/hello-world-round.png :cmdline -r +#+NAME: hello-world-round.org +#+BEGIN_SRC org :exports code :results replace +,#+NAME: hello-world-round +,#+HEADER: :exports results +,#+BEGIN_SRC ditaa :file images/hello-world-round.png :cmdline -r +--------------+ | | | Hello World! | | | +--------------+ +,#+END_SRC #+END_SRC -#+END_EXAMPLE -#+header: :exports results +#+RESULTS: hello-world-round.org +#+NAME: hello-world-round +#+HEADER: :exports results #+BEGIN_SRC ditaa :file images/hello-world-round.png :cmdline -r +--------------+ | | @@ -112,6 +133,53 @@ command line switch. +--------------+ #+END_SRC -#+RESULTS: +#+RESULTS: hello-world-round [[file:images/hello-world-round.png]] +** Executing =ditaa= from a script + +Org assumes that =ditaa= is run as a java jar file. Users may need to +use a script to run =ditaa=. This example shows how. + +First, set ~org-babel-ditaa-java-cmd~ and ~org-ditaa-jar-option~ to +empty strings and ~org-ditaa-jar-path~ to the script's path; here, it +is =/usr/bin/ditaa=. This example uses ~setq-local~ to change only +the values in this buffer. + +#+NAME: hello-world-from-script.el.org +#+BEGIN_SRC org :exports code :results replace +,#+NAME: hello-world-from-script.el +,#+BEGIN_SRC emacs-lisp :exports none :results none +(setq-local org-babel-ditaa-java-cmd "" + org-ditaa-jar-option "" + org-ditaa-jar-path "/usr/bin/ditaa") +,#+END_SRC +#+END_SRC + +#+RESULTS: hello-world-from-script.el.org +#+NAME: hello-world-from-script.el +#+BEGIN_SRC emacs-lisp :exports none :results none +(setq-local org-babel-ditaa-java-cmd "" + org-ditaa-jar-option "" + org-ditaa-jar-path "/usr/bin/ditaa") +#+END_SRC + +Second, in the =ditaa= code-block, set the header argument =:java= to +the empty string =""=. The =:cmdline= header argument can be used to +pass command-line options to =ditaa= via the script. + +#+NAME: hello-world-from-script.org +#+BEGIN_SRC org :exports code :results replace +,#+name: hello-world-from-script +,#+begin_src ditaa :file images/hello-world-from-script.png :java "" :cmdline -r -e UTF-8 ++----------------+ +| | +| Hello World | +| from a script! | +| | ++----------------+ +,#+END_SRC +#+END_SRC + +#+RESULTS: hello-world-from-script +[[file:images/hello-world-from-script.png]] -- 2.42.0