Greetings again. Ihor Radchenko <yanta...@posteo.net> writes:
> Jarmo Hurri <jarmo.hu...@iki.fi> writes: > >>> 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. > > Should be 9.8. We do not make breaking changes in bugfix releases. > See https://orgmode.org/worg/org-maintenance.html#branches Changed it to 9.8, although I think we will have no breaking changes after all your latest improvement ideas have been incorporated. >>> 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 > > Nope. `org-babel-graphical-output-file' relies on the fact that > ob-core pre-process :file argument in > `org-babel-generate-file-param'. So, you should simply call > `org-babel-graphical-output-file' without checking :file. Done. > Maybe it is also a good idea to add :results graphics to the default > header arguments. Done. >> 3. output file type is determined solely from file extension. >> >> This is a breaking change, since :png etc. parameters are now >> deprecated. > > Only :eps parameter is present in the current version of ob-ditaa. We > _should not_ remove it from the code to preserve > backwards-compatibility. Just remove it from the documentation and > mark as backwards-compatibility in code comments. Done. >> There is no default output file type anymore (used to be png). > > Why not? You can simply modify `org-babel-default-header-args:ditaa' to > have :file-ext "png" by default. Done. The default type is now determined explicitly in the code, but note that in the case of default png the value of the corresponding variable `png` need not be used after it is setq'd. There is a short comment about this in code. >>>> And, finally, should I add myself as the maintainer? >>> >>> That would be great. Thanks! >> >> Done. > > Please do it in a separate commit, so that different changes are not > intermixed. Maintainer info removed. I will provide a separate maintainer commit after this one has been approved. >>> 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. > > I just checked FSF records, and it does not look like you have an > active copyright assignment. Could you please check? I have signed one a long time ago. I will check the situation at some point. > The newlines are completely off in the commit message. Also, the > commit mesage does not have a short patch description on the first > line and does not conform to > https://orgmode.org/worg/org-contribute.html#commit-messages Not sure what happened there, weird end result of copy-pasting, amend and the like. Fixed in new version. >> -;; 2) we are generally only going to return results of type "file" >> +;; - there is no "output", so source code blocks always export "results" > > This is not true. If the user tries to set :exports output explicitly, > nothing will be exported. Just say that :exports results is the > default. Done. >> +;; - the following header arguments are added: >> +;; "cmdline" : command line parameters passed to ditaa > > You do not need to document standard header arguments in the babel > library headers. Just say that :cmdline is supported. I now mention that :cmdline is standard. I still explicitly state that it controls parameters passed to ditaa (because some parameters can also be passed to java). >> +(defun ob-ditaa--ensure-jar-file (file) >> + "Small internal helper function returning file if it exists and >> signalling error otherwise." > > Please shorten the first line of the docstring below 60 characters. > See D.6 Tips for Documentation Strings section of Eliso manual. Done. Thanks for the quality review of a subpar patch. Let us hope the one below fares better. All the best, Jarmo
>From fa83269db3630fba2b1c9b062aee2a3ad7e0bdb6 Mon Sep 17 00:00:00 2001 From: Jarmo Hurri <jarmo.hu...@iki.fi> Date: Mon, 4 Aug 2025 16:08:02 +0300 Subject: [PATCH] ob-ditaa.el: output type control, ditaa executable, SVG output, and chararacter encoding * lisp/ob-ditaa.el (org-babel-default-header-args:ditaa) Include new header arg `:encoding`. Add `graphics` to default value of `:results`. Add `png` as default value of header arg `:file-ext`. (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 an obsolete alias for backwards-compatibility. (org-ditaa-ensure-jar-file): Write a small helper function checking existence of jar file. (org-babel-execute:ditaa): Use standard `org-babel-graphical-output-file` to determine output file and type. Add support for ditaa executable. Add support for SVG output. Clarify code structure and local variable naming. * 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=: custom variable name, ditaa executable, SVG output, and chararacter encoding): Document 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 deduced automatically, and defaults to PNG. 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 | 173 +++++++++++++++++++++++++++++++-------------- 3 files changed, 144 insertions(+), 54 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index e4be10a3b..0af834e04 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. + 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 375a0c424..7b0d9663a 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -224,6 +224,28 @@ appropriate major mode is unavailable. When editing Dot source blocks, Org now uses Graphviz Dot mode, if installed. +*** =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. Header argument =:eps= is supported for backwards +compatibility. Default output type is still PNG. + +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 and changed options # Changes dealing with changing default values of customizations, diff --git a/lisp/ob-ditaa.el b/lisp/ob-ditaa.el index 77eadd6c2..92df56f29 100644 --- a/lisp/ob-ditaa.el +++ b/lisp/ob-ditaa.el @@ -2,7 +2,7 @@ ;; Copyright (C) 2009-2025 Free Software Foundation, Inc. -;; Author: Eric Schulte +;; Authors: Eric Schulte, Jarmo Hurri ;; Keywords: literate programming, reproducible research ;; URL: https://orgmode.org @@ -25,15 +25,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" +;; - :export results is the default ;; -;; 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' | +;; +;; - standard header argument "cmdline" controls command line parameters passed to ditaa +;; - the following header arguments are added: +;; "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: @@ -44,11 +82,37 @@ (require 'org-compat) (defvar org-babel-default-header-args:ditaa - '((:results . "file") + '((:results . "file graphics") (:exports . "results") - (:java . "-Dfile.encoding=UTF-8")) + (:encoding . "UTF-8") + (:file-ext . "png")) "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.8") +(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,67 @@ (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 + (let* ((out-file (org-babel-graphical-output-file params)) + (out-file-suffix (file-name-extension out-file)) + (svg (string= out-file-suffix "svg")) + (pdf (string= out-file-suffix "pdf")) + (png (string= out-file-suffix "png")) + (eps (or (string= out-file-suffix "eps") + ;; backwards-compatibility of :eps header argument + (and (not (or svg pdf png)) + (cdr (assq :eps params)))))) + ;; determine default png output; determined for clarity, but value + ;; of variable currently not used below + (setq png (or png (not (or svg pdf eps)))) + (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
