Ihor Radchenko <yanta...@posteo.net> writes: >> -(defcustom org-babel-ditaa-java-cmd "java" > >> +(defcustom org-ditaa-java-exec "java" >> + "Java executable to use when evaluating ditaa blocks using a JAR." >> + :group 'org-babel >> + :type 'string) > > We generally do not rename variables irreversibly. Please leave an > obsolete alias for `org-babel-ditaa-java-cmd' pointing to the new > variable name. Otherwise, the existing configs that were using the old > variable name will be broken.
Done. The variable is now set to become obsolete, tentatively in 9.7.34. >> +;;; small helper function returning file if it exists and signalling >> +;;; error otherwise >> +(defun org-ditaa-ensure-jar-file (file) >> + (if (file-exists-p file) >> + file >> + (error "could not find jar file %s" file))) > > Rather than writing what the function does in the comment, please do it > in the docstring. We might also make this function internal. Done and done. > Also, the error sounds very generic. It would be nicer to indicate to > the user that the problem is related to ob-ditaa. Done. >>>> + (png (cdr (assq :png params))) >>>> + (svg (cdr (assq :svg params))) >>>> (eps (cdr (assq :eps params))) >>> >>> I am wondering if we could instead deprecate the :png/:eps parameters >>> and instead use the :file extension to decide. >> >> This could be done, but I do not see much harm in providing an >> override. Note that the file extension is used by default. >> >> So, your choice: is it >> a) file extension only >> b) file extension with possibility to override with parameters? > > AFAIU, the current situation is not ideal: if we have something like > #+begin_src ditaa :pdf :file foo.eps, the results will be very strange. > > Moreover, we have API function `org-babel-graphical-output-file' (not > used by ob-ditaa) that makes use of :file-ext standard header argument > that is serving similar purpose with :eps/:pdf in ob-ditaa (see 16.5 > Evaluating Code Blocks section of the manual). > > So, I view these :ext options that are still used by several babel > backends as candidates for deprecation. Certainly, I do not want to make > them proliferate in the new features. Ok. I changed the patch so that it should now conform to the manual: 1. :file is the primary determinant of output file 2. `org-babel-graphical-output-file' is used secondarily; note that :file-ext is ignored quietly if :file is set 3. output file type is determined solely from file extension. This is a breaking change, since :png etc. parameters are now deprecated. There is no default output file type anymore (used to be png). >>>> + (message cmd) >>>> + (shell-command cmd) >>>> + (when pdf >>>> + (let ((pdf-cmd (concat "epstopdf" " " ditaa-out-file " " >>>> + "-o=" (org-babel-process-file-name out-file)))) >>>> + (message pdf-cmd) >>> >>> Why message? >> >> I was originally directed to ob-plantuml, which message's its >> command. During the testing of this patch I found messaging useful to >> observe what was happening. >> >> So, your choice: >> a) no messaging >> b) message always >> c) defcustom a toggle for messaging? > > I'd prefer no messaging as it serves no clear purpose to the user. Done. > For debugging purposes, one can always do M-x trace-function shell-command > >> And, finally, should I add myself as the maintainer? > > That would be great. Thanks! Done. > I assume that you already have access to savannah as you are listed as > the maintainer of ob-processing. Well, I do have - in my records - a username and a password, but those no longer work, and password recovery does not work either. I can reapply, or just send patches here, either one is fine by me. Please find the new version of the patch attached below. All the best, Jarmo
>From 612049b58aabfe76b7b07f70d21f2e2b9cc8de59 Mon Sep 17 00:00:00 2001 From: Jarmo Hurri <jarmo.hu...@iki.fi> Date: Fri, 1 Aug 2025 14:21:03 +0300 Subject: [PATCH] * lisp/ob-ditaa.el (org-babel-default-header-args:ditaa) Include new header arg `:encoding`. (org-ditaa-default-exec-mode): Define new customizable variable for controlling ditaa execution via jar or executable. (org-ditaa-exec): Define new customizable variable for controlling path to ditaa executable. (org-ditaa-java-exec): Rename old customizable variable to conform to ditaa variable naming (not containing word `babel`). Provide old variable as an obsolete alias. (org-ditaa-ensure-jar-file): Write a small helper function checking existence of jar file. (org-babel-execute:ditaa): Determine output file type correctly from header arguments. Add support for ditaa executable. Add support for SVG output. * doc/org-manual.org (List of contributors): Remove reference to non-existing location of ditaa.jar in org contrib, refer to ditaa github page instead. * etc/ORG-NEWS (=ob-ditaa=: output type control, ditaa executable, SVG output, and chararacter encoding): Document breaking change and new features. There was a mismatch between what ob-ditaa expected and what some operating systems provide. In particular, ob-ditaa expected a JAR executable via `java -jar`, while some operating systems provide a shell script which executes the JAR in a more complicated manner. Therefore support for executing ditaa source code blocks directly via an executable was added. Newer versions of ditaa can generate SVG output, which was not supported by ob-ditaa. This is now fixed. Output type is now deduced correctly as specified in Babel documentation (from header arguments `:file` or `:file-ext`). Character encoding of ditaa source code blocks was passed via Java, while the encoding can be specified directly as a parameter to ditaa. Character encoding is now passed directly to ditaa, with a corresponding header argument `:encoding`. --- doc/org-manual.org | 3 +- etc/ORG-NEWS | 22 ++++++ lisp/ob-ditaa.el | 165 +++++++++++++++++++++++++++++++-------------- 3 files changed, 138 insertions(+), 52 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index e4be10a3b..460b8be59 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -23275,7 +23275,8 @@ community and the code. literal examples, and remote highlighting for referenced code lines. - Stathis Sideris wrote the =ditaa.jar= ASCII to PNG converter that is - now packaged into the [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] repository. + that is available as a package in some operating systems or can be + downloaded from [[https://github.com/stathissideris/ditaa]]. - Daniel Sinder came up with the idea of internal archiving by locking subtrees. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 5b5908629..41dd57366 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -133,6 +133,28 @@ to your configuration. The new behaviour follows general babel backend rules (auto-detecting result type), but may affect the existing usage. +*** =ob-ditaa=: output type control, ditaa executable, SVG output, and chararacter encoding + +Output file type is determined as specified in Babel documentation: +the suffix of =:file= is the primary determinant, and =:file-ext= +secondary. There is no default type. Previously available header +arguments =:png=, =:eps= and =:pdf= are now deprecated. + +In order to use an executable instead of a JAR file, you can set +=org-ditaa-default-exec-mode= to ='ditaa=. The location of the +executable can be configured via =org-ditaa-exec=. + +SVG output can now be generated; note, however, that this requires a +ditaa version of at least 0.11.0. + +Character encoding is passed directly to ditaa (earlier to Java) and +can be controlled by new header argument =:encoding=. + +To align with other customizable variable names, which do not contain +the word =babel=, variable =org-babel-ditaa-java-cmd= has been renamed +to =org-ditaa-java-exec=. The old variable =org-babel-ditaa-java-cmd= +is still available as an obsolete alias. + ** New features # We list the most important features, and the features that may diff --git a/lisp/ob-ditaa.el b/lisp/ob-ditaa.el index 77eadd6c2..cbf5b2f7e 100644 --- a/lisp/ob-ditaa.el +++ b/lisp/ob-ditaa.el @@ -2,7 +2,8 @@ ;; Copyright (C) 2009-2025 Free Software Foundation, Inc. -;; Author: Eric Schulte +;; Authors: Eric Schulte, Jarmo Hurri +;; Maintainer: Jarmo Hurri <jarmo.hu...@iki.fi> ;; Keywords: literate programming, reproducible research ;; URL: https://orgmode.org @@ -25,15 +26,53 @@ ;; Org-Babel support for evaluating ditaa source code. ;; -;; This differs from most standard languages in that +;; Source code blocks of type ditaa have some special features: ;; -;; 1) there is no such thing as a "session" in ditaa +;; - there is no such thing as a "session" ;; -;; 2) we are generally only going to return results of type "file" +;; - there is no "output", so source code blocks always export "results" ;; -;; 3) we are adding the "file" and "cmdline" header arguments +;; - only results of type "file" are returned ;; -;; 4) there are no variables (at least for now) +;; - there are no variables +;; +;; - three different variants of "ditaa" exist: a ditaa executable +;; (shell script), ditaa.jar Java archive and DitaaEPS.jar Java +;; archive; the third one is a fork generating eps output, and is +;; also a prerequisite for producing pdf output; ob-ditaa supports +;; all three of these; if ditaa.jar or DitaaEPS.jar is used, paths +;; to file(s) must be set; the following table summarizes which +;; variant is used in which case; column mode refers to +;; `org-ditaa-default-exec-mode' +;; +;; | mode | output | command | +;; |----------------+----------+-----------------------------------------------------| +;; | `ditaa' | png, svg | `org-ditaa-exec' | +;; | `jar' | png, svg | `org-ditaa-java-exec' -jar `org-ditaa-jar-path' | +;; | `ditaa', `jar' | eps | `org-ditaa-java-exec' -jar `org-ditaa-eps-jar-path' | +;; | `ditaa', `jar' | pdf | `org-ditaa-java-exec' -jar `org-ditaa-eps-jar-path' | +;; +;; - the following header arguments are added: +;; "cmdline" : command line parameters passed to ditaa +;; "encoding" : character encoding (default UTF-8) +;; "java" : additional parameters passed to java if ditaa run via a jar +;; + +;;; Requirements: + +;; at least one of the following: +;; +;; ditaa (executable) +;; - packaged in some distributions +;; - configurable via `org-ditaa-exec' +;; +;; ditaa.jar | when exec mode is `jar' +;; - `org-ditaa-jar-path' must point to this jar file +;; - see https://github.com/stathissideris/ditaa +;; +;; DitaaEps.jar | when generating eps or pdf output +;; - `org-ditaa-eps-jar-path' must point to this jar file +;; - see https://sourceforge.net/projects/ditaa-addons/files/DitaaEps/ ;;; Code: @@ -46,9 +85,34 @@ (defvar org-babel-default-header-args:ditaa '((:results . "file") (:exports . "results") - (:java . "-Dfile.encoding=UTF-8")) + (:encoding . "UTF-8")) "Default arguments for evaluating a ditaa source block.") +(defcustom org-ditaa-default-exec-mode 'jar + "Method to use for ditaa diagram generation when generating png or svg output. +`jar' means to use java together with a JAR. +The JAR must be set via `org-ditaa-jar-path'. + +`ditaa' means to use the ditaa executable. +The executable can be configured via `org-ditaa-exec'." + + :group 'org-babel + :package-version '(Org . "9.8") + :type 'symbol + :options '(ditaa jar)) + +(defcustom org-ditaa-exec "ditaa" + "File name of the ditaa executable." + :group 'org-babel + :package-version '(Org . "9.8") + :type 'string) + +(define-obsolete-variable-alias org-babel-ditaa-java-cmd org-ditaa-java-exec "9.7.34") +(defcustom org-ditaa-java-exec "java" + "Java executable to use when evaluating ditaa blocks using a JAR." + :group 'org-babel + :type 'string) + (defcustom org-ditaa-jar-path (expand-file-name "ditaa.jar" (file-name-as-directory @@ -58,64 +122,63 @@ (expand-file-name "../contrib" (file-name-directory (org-find-library-dir "org"))))))) - "Path to the ditaa jar executable." - :group 'org-babel - :type 'string) - -(defcustom org-babel-ditaa-java-cmd "java" - "Java executable to use when evaluating ditaa blocks." + "Path to the ditaa.jar file." :group 'org-babel :type 'string) (defcustom org-ditaa-eps-jar-path (expand-file-name "DitaaEps.jar" (file-name-directory org-ditaa-jar-path)) - "Path to the DitaaEps.jar executable." + "Path to the DitaaEps.jar executable. +Used when generating eps or pdf output." :group 'org-babel :version "24.4" :package-version '(Org . "8.0") :type 'string) -(defcustom org-ditaa-jar-option "-jar" - "Option for the ditaa jar file. -Do not leave leading or trailing spaces in this string." - :group 'org-babel - :version "24.1" - :type 'string) +(defun ob-ditaa--ensure-jar-file (file) + "Small internal helper function returning file if it exists and signalling error otherwise." + (if (file-exists-p file) + file + (error "(ob-ditaa) Could not find jar file %s" file))) (defun org-babel-execute:ditaa (body params) - "Execute BODY of Ditaa code with org-babel according to PARAMS. + "Execute BODY of ditaa code with org-babel according to PARAMS. This function is called by `org-babel-execute-src-block'." (let* ((out-file (or (cdr (assq :file params)) - (error - "Ditaa code block requires :file header argument"))) - (cmdline (cdr (assq :cmdline params))) - (java (cdr (assq :java params))) - (in-file (org-babel-temp-file "ditaa-")) - (eps (cdr (assq :eps params))) - (eps-file (when eps - (org-babel-process-file-name (concat in-file ".eps")))) - (pdf-cmd (when (and (or (string= (file-name-extension out-file) "pdf") - (cdr (assq :pdf params)))) - (concat - "epstopdf" - " " eps-file - " -o=" (org-babel-process-file-name out-file)))) - (cmd (concat org-babel-ditaa-java-cmd - " " java " " org-ditaa-jar-option " " - (shell-quote-argument - (expand-file-name - (if eps org-ditaa-eps-jar-path org-ditaa-jar-path))) - " " cmdline - " " (org-babel-process-file-name in-file) - " " (if pdf-cmd - eps-file - (org-babel-process-file-name out-file))))) - (unless (file-exists-p org-ditaa-jar-path) - (error "Could not find ditaa.jar at %s" org-ditaa-jar-path)) - (with-temp-file in-file (insert body)) - (shell-command cmd) - (when pdf-cmd (shell-command pdf-cmd)) - nil)) ;; signal that output has already been written to file + (org-babel-graphical-output-file params))) + (out-file-suffix (file-name-extension out-file)) + (svg (string= out-file-suffix "svg")) + (eps (string= out-file-suffix "eps")) + (pdf (string= out-file-suffix "pdf")) + (png (string= out-file-suffix "png"))) + (when (not (or svg eps pdf png)) + (error "(ob-ditaa) Output file type can not be determined.")) + (let* ((ditaa-options (cdr (assq :cmdline params))) + (ditaa-encoding (cdr (assq :encoding params))) + (java-options (cdr (assq :java params))) + (use-eps-jar (or eps pdf)) + (exec-form (if (or (equal org-ditaa-default-exec-mode 'jar) use-eps-jar) + (concat org-ditaa-java-exec + (when java-options (concat " " java-options)) + " " "-jar" " " + (shell-quote-argument + (ob-ditaa--ensure-jar-file (if use-eps-jar org-ditaa-eps-jar-path + org-ditaa-jar-path)))) + org-ditaa-exec)) + (in-file (org-babel-temp-file "ditaa-")) + (ditaa-out-file (org-babel-process-file-name (if pdf (concat in-file ".eps") out-file))) + (cmd (concat exec-form + (when ditaa-options (concat " " ditaa-options)) + (when svg (concat " " "--svg")) + (when ditaa-encoding (concat " " "-e " ditaa-encoding)) + " " in-file " " ditaa-out-file))) + (with-temp-file in-file (insert body)) + (shell-command cmd) + (when pdf + (let ((pdf-cmd (concat "epstopdf" " " ditaa-out-file " " + "-o=" (org-babel-process-file-name out-file)))) + (shell-command pdf-cmd))) + nil))) ;; signal that output has already been written to file (defun org-babel-prep-session:ditaa (_session _params) "Return an error because ditaa does not support sessions." -- 2.50.1
