Re: [PATCH][ox-koma-letter] changed-in-buffer, subject, minor fixes

[Rasmus <rasmus@gmx.us>]

[-- Attachment #1: Type: text/plain, Size: 2378 bytes --]

Alan,

I finally had the time to fix these old patches.  Sorry about the
wait.

Alan Schmitt <alan.schmitt@polytechnique.org> writes:

> Hello,
>> Attached are a couple of changes to ox-koma-letter following a recent
>> bug report by James.
>>
>> 1. Minor fixes around.  The way subject-format was handled before was
>>    ugly.  Updated some docstrings etc.
>
> I'm afraid I'm not competent to talk about the subject handling (the
> elisp is beyond my level). I'm fine with the docstring update, with one
> nitpick: "e.g." should always be present as a parenthetical sentence:
> "..., e.g, ...".

Fixed.

>> 2. better test of whether values have changed in the buffer.  I think
>>    Alan added this first, but the previous implementation.  I think
>>    it's more robust now, and it hopefully addresses James' problems
>>    (please test).  Basically and x-aux variable is added for all
>>    variables x in :option-alist with a default value "unset".  The
>>    value can then be tested.
>
> Isn't "unset" a bit dangerous? Can we detect when we set something to
> "unset" (I don't know if it's a valid option for anything)? (By the way,
> the previous value of "nil", except for foldmarks, was much worse.) How
> about using "ox-koma-unset"?


Fixed.

>> 3. When studying the KOMA manual to answer James' second question I
>>    came across the komavar title which is currently not supported.  I
>>    have added support for a separate SUBJECT keyword.  The heuristic
>>    is something like this (i) if title and subject are be truthful to
>>    the name no matter what, (ii) if only title or subject is said let
>>    title be subject if org-koma-letter-title-is-subject-maybe is t
>>    otherwise be truthful to name.
>
> This sounds good. Once again, I'm not sure I'm competent enough to
> criticize the elisp code.

> [snip]


>> In 3. I would personally like to set
>> org-koma-letter-title-is-subject-maybe to nil by defaults, but this
>> would break backwards comparability for title keywords.
>
> I don't mind breaking backward compatibility at this point, if we make
> clear how to get back the previous output.

TITLE is now title and SUBJECT is now subject by default.

These new patches should apply against the master branch. 

–Rasmus

-- 
I almost cut my hair, it happened just the other day

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Minor-fixes-for-ox-koma-script.el.patch --]
[-- Type: text/x-diff, Size: 5838 bytes --]

From c4adcc44f08f4e92efba1b7aabb45807cffc5f1c Mon Sep 17 00:00:00 2001
From: Rasmus Pank Roulund <w530@pank.eu>
Date: Sun, 24 Nov 2013 17:57:37 +0100
Subject: [PATCH 1/3] Minor fixes for ox-koma-script.el

* ox-koma-letter.el (org-koma-letter-headline) (org-koma-letter-email)
(org-koma-letter-prefer-special-headings) (org-koma-letter-use-backaddress)
(org-koma-letter-headline-is-opening-maybe): Correct docstring.
(org-koma-letter-template): Insert subject before document start.
(org-koma-letter-headline): Fix spelling.
(org-koma-letter-template): Better subject handling.
---
 contrib/lisp/ox-koma-letter.el | 50 +++++++++++++++++++++++-------------------
 1 file changed, 27 insertions(+), 23 deletions(-)

diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index 240de29..3a0fa53 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -111,11 +111,15 @@
 ;;   \[EXTRA]"))
 ;;
 ;; Then, in your Org document, be sure to require the proper class
-;; with :
+;; with:
 ;;
 ;;    #+LATEX_CLASS: my-letter
 ;;
 ;; Or by setting `org-koma-letter-default-class'.
+;; You may possibly have to load (LaTeX) Babel as well e.g. by adding
+;; it to `org-latex-packages-alist',
+;;
+;;    (add-to-list 'org-latex-packages-alist '("AUTO" "babel" nil))
 
 ;;; Code:
 
@@ -148,7 +152,7 @@ string."
 		(const :tag "Do not export author" nil)))
 
 (defcustom org-koma-letter-email 'org-koma-letter-email
-  "The sender's email address.
+  "Sender's email address.
 
 This variable defaults to the value `org-koma-letter-email' which
 returns `user-mail-address'.  Alternatively a string, nil or a
@@ -189,7 +193,11 @@ t the value opening will be implicit set as the headline title."
   :type 'string)
 
 (defcustom org-koma-letter-prefer-special-headings nil
-  "If TO and/or FROM is specified using both a heading and a keyword the heading value will be preferred if the variable is t."
+  "Prefer special headings in letters.
+
+If TO and/or FROM is specified using both a heading and a keyword
+the heading value will be preferred if this variable is non-nil.
+"
   :group 'org-export-koma-letter
   :type 'boolean)
 
@@ -211,7 +219,6 @@ At this time the following values are allowed:
  - titled: add title/description to subject.
  - underlined: set subject underlined.
  - untitled: do not add title/description to subject.
- - No-export: do no insert a subject even if present.
 
 Please refer to the KOMA-script manual (Table 4.16. in the
 English manual of 2012-07-22)."
@@ -233,7 +240,7 @@ English manual of 2012-07-22)."
 
 
 (defcustom org-koma-letter-use-backaddress nil
-  "Print return address in small line above to address."
+  "Print return address above the address."
   :group 'org-export-koma-letter
   :type 'boolean)
 
@@ -270,7 +277,8 @@ The value must be a member of `org-latex-classes'."
   :type 'string)
 
 (defcustom org-koma-letter-headline-is-opening-maybe t
-  "Whether a headline may be used as an opening.
+  "Let headlines be used as an opening if non-nil.
+
 A headline is only used if #+OPENING is not set.  See also
 `org-koma-letter-opening'."
   :group 'org-export-koma-letter
@@ -288,7 +296,6 @@ A headline is only used if #+OPENING is not set.  See also
 (defvar org-koma-letter-special-contents nil
   "Holds special content temporarily.")
 
-
 \f
 ;;; Define Back-End
 
@@ -516,7 +523,7 @@ appropriate place."
 CONTENTS is the transcoded contents string.  INFO is a plist
 holding export options."
   ;; FIXME: instead of setq'ing org-koma-letter-special-contents and
-  ;; callying varioues stuff it might be nice to put a big let* around the templace
+  ;; callying varioues stuff it might be nice to put a big let* around the template
   ;; as in org-groff...
   (concat
    ;; Time-stamp.
@@ -585,7 +592,7 @@ holding export options."
    (let ((with-backaddress (plist-get info :with-backaddress))
 	 (with-backaddress-set (plist-get info :with-backaddress-changed-in-buffer-p))
 	 (with-foldmarks (plist-get info :with-foldmarks))
-	 (with-foldmarks-set 
+	 (with-foldmarks-set
 	  (not (string-equal (plist-get info :with-foldmarks-changed-in-buffer-p)
 			     "foldmarks-not-set")))
 	 (with-phone (plist-get info :with-phone))
@@ -601,28 +608,25 @@ holding export options."
 	(format "\\KOMAoption{fromphone}{%s}\n" (if with-phone "true" "false")))
       (when with-email-set
 	(format "\\KOMAoption{fromemail}{%s}\n" (if with-email "true" "false")))))
-   ;; Document start
-   "\\begin{document}\n\n"
    ;; Subject
    (let* ((with-subject (plist-get info :with-subject))
-	  (subject-format (cond ((member with-subject '("true" "t" t)) nil)
-				((stringp with-subject) (list with-subject))
-				((symbolp with-subject)
-				 (list (symbol-name with-subject)))
-				(t with-subject)))
-	  (subject (org-export-data (plist-get info :title) info))
-	  (l (length subject-format))
-	  (y ""))
+	  ;; TODO: this is a bit ugly and assumes that with-subject is
+	  ;; (a list of) symbol(s) or string(s)...
+	  (subject-format (mapcar
+			   (lambda (elt) (if (and elt (symbolp elt)) (symbol-name elt) elt))
+			   (cond ((member with-subject '("true" "t" t)) nil)
+				 ((listp with-subject) with-subject)
+				 (t (list with-subject)))))
+	  (subject (org-export-data (plist-get info :title) info)))
      (concat
       (when (and with-subject subject-format)
 	(concat
 	 "\\KOMAoption{subject}{"
-	 (apply 'format
-		(dotimes (x l y)
-		  (setq y (concat (if (> x 0) "%s," "%s") y)))
-		subject-format) "}\n"))
+	 (mapconcat 'identity subject-format ",") "}\n" ))
       (when (and subject with-subject)
 	(format "\\setkomavar{subject}{%s}\n\n" subject))))
+   ;; Document start
+   "\\begin{document}\n\n"
    ;; Letter start
    (format "\\begin{letter}{%%\n%s}\n\n"
 	   (org-koma-letter--determine-to-and-from info 'to))
-- 
1.8.5.3


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-ox-koma-letter-test-with-auxiliary-variables.patch --]
[-- Type: text/x-diff, Size: 9130 bytes --]

From 74b9c1e1f039fefeb293a675845e127a63fac202 Mon Sep 17 00:00:00 2001
From: Rasmus Pank Roulund <w530@pank.eu>
Date: Sun, 24 Nov 2013 19:23:02 +0100
Subject: [PATCH 2/3] ox-koma-letter: test with auxiliary variables

* ox-koma-letter.el (org-koma-letter-aux-suffix): New variable
(org-koma-letter-unset-string): New variable.
(koma-letter-option-alist): Removed x-changed-in-buffer-p variables.
(org-koma-letter--make-aux-variables): Function to add aux variables.
(org-koma-letter--aux-name): Function returns an aux name.
(org-koma-letter--set-in-buffer): Function returns t if
variable is changed in buffer.
(org-koma-letter-template): Use new test for changed in buffer.

An aux variable is used to test wheter a variable has been changed in
buffer.  This commits makes this work consistently.
---
 contrib/lisp/ox-koma-letter.el | 79 +++++++++++++++++++++++++++++++++---------
 1 file changed, 62 insertions(+), 17 deletions(-)

diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index 3a0fa53..ef9f624 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -66,6 +66,10 @@
 ;;   - after-letter-order, as above, but after the end of the letter
 ;;     (see `org-koma-letter-special-tags-after-letter').
 ;;
+;; Note, some formatting depends on whether the variables has been set
+;; in the buffer.  For instance, the email is inserted after LCO
+;; files, if changed in the letter.
+;;
 ;; The following variables works differently from the main LaTeX class
 ;;   - "AUTHOR": default to user-full-name but may be disabled.  (see org-koma-letter-author),
 ;;   - "EMAIL": same as AUTHOR, (see org-koma-letter-email),
@@ -93,7 +97,7 @@
 ;;
 ;; to your init file.  This will add a sparse scrlttr2 class and
 ;; set it as the default `org-koma-latex-default-class'.  You can also
-;; add you own letter class.  For instace:
+;; add you own letter class.  For instance:
 ;;
 ;;   (add-to-list 'org-latex-classes
 ;;                '("my-letter"
@@ -116,7 +120,7 @@
 ;;    #+LATEX_CLASS: my-letter
 ;;
 ;; Or by setting `org-koma-letter-default-class'.
-;; You may possibly have to load (LaTeX) Babel as well e.g. by adding
+;; You may possibly have to load (LaTeX) Babel as well, e.g., by adding
 ;; it to `org-latex-packages-alist',
 ;;
 ;;    (add-to-list 'org-latex-packages-alist '("AUTO" "babel" nil))
@@ -179,6 +183,8 @@ function may be given.  Functions must return a string."
   :type 'string)
 
 (defcustom org-koma-letter-opening nil
+  ;; TODO: We should probably get rid of requirement (1) and just
+  ;; check if the value is set in the buffer.
   "Letter's opening, as a string.
 
 If (1) this value is nil; (2) the letter is started with a
@@ -296,6 +302,12 @@ A headline is only used if #+OPENING is not set.  See also
 (defvar org-koma-letter-special-contents nil
   "Holds special content temporarily.")
 
+(defconst org-koma-letter-unset-string "*ox-koma-unset*"
+  "Value for unset auxiliary variables in :option-alist.")
+
+(defconst org-koma-letter-aux-suffix "ox-koma-aux"
+  "Suffix for auxiliary variables used to test whether a variable has been set.")
+
 \f
 ;;; Define Back-End
 
@@ -306,11 +318,9 @@ A headline is only used if #+OPENING is not set.  See also
 					org-koma-letter-default-class
 					org-latex-default-class) t)
     (:author "AUTHOR" nil (org-koma-letter--get-value org-koma-letter-author) t)
-    (:author-changed-in-buffer-p "AUTHOR" nil nil t)
     (:from-address "FROM_ADDRESS" nil nil newline)
     (:phone-number "PHONE_NUMBER" nil org-koma-letter-phone-number)
     (:email "EMAIL" nil (org-koma-letter--get-value org-koma-letter-email) t)
-    (:email-changed-in-buffer-p "EMAIL" nil nil t)
     (:to-address "TO_ADDRESS" nil nil newline)
     (:place "PLACE" nil org-koma-letter-place)
     (:opening "OPENING" nil org-koma-letter-opening)
@@ -326,14 +336,10 @@ A headline is only used if #+OPENING is not set.  See also
 			 org-koma-letter-special-tags-after-closing)
     (:with-after-letter nil "after-letter-order"
 			org-koma-letter-special-tags-after-letter)
-    (:with-backaddress nil "backaddress" org-koma-letter-use-backaddress)
-    (:with-backaddress-changed-in-buffer-p nil "backaddress" nil)
+    (:with-backaddress nil "backaddress" org-koma-letter-use-backaddress )
     (:with-foldmarks nil "foldmarks" org-koma-letter-use-foldmarks)
-    (:with-foldmarks-changed-in-buffer-p nil "foldmarks" "foldmarks-not-set")
     (:with-phone nil "phone" org-koma-letter-use-phone)
-    (:with-phone-changed-in-buffer-p nil "phone" nil)
     (:with-email nil "email" org-koma-letter-use-email)
-    (:with-email-changed-in-buffer-p nil "email" nil)
     (:with-place nil "place" org-koma-letter-use-place)
     (:with-subject nil "subject" org-koma-letter-subject-format))
   :translate-alist '((export-block . org-koma-letter-export-block)
@@ -351,6 +357,10 @@ A headline is only used if #+OPENING is not set.  See also
 	      (if a (org-koma-letter-export-to-pdf t s v b)
 		(org-open-file (org-koma-letter-export-to-pdf nil s v b))))))))
 
+
+;; Make auxiliary values to check whether variables have been set
+(org-koma-letter--make-aux-variables 'koma-letter)
+
 \f
 ;;; Initialize class function
 
@@ -366,6 +376,23 @@ A headline is only used if #+OPENING is not set.  See also
 
 ;;; Helper functions
 
+(defun org-koma-letter--make-aux-variables (class)
+  "Append the option list of CLASS with aux values that test
+  whether they have been set in buffer."
+  ;; TODO: Is this the proper way to archive this?
+  (let* ((options (org-export-backend-options (org-export-get-backend class)))
+	 (defined (mapcar 'first options))
+	 (aux (mapcar (lambda (l)
+			(let ((name (first l))
+			      (r1 (subseq l 1 3)))
+			  (unless  (member (org-koma-letter--aux-name name) defined)
+			    (append (list (org-koma-letter--aux-name name)) r1
+			     (list 'org-koma-letter-unset-string t)))))
+		      options)))
+    (setf (org-export-backend-options (org-export-get-backend class))
+	  (append options (delq nil aux)))))
+
+
 (defun org-koma-letter-email ()
   "Return the current `user-mail-address'."
   user-mail-address)
@@ -452,6 +479,21 @@ are present return the preferred one as determined by
      "\n" "\\\\\\\\\n"
      (org-koma-letter--normalize-string adr)))))
 
+(defun org-koma-letter--aux-name (option)
+  "Return the auxiliary name of OPTION"
+  (let ((aux org-koma-letter-aux-suffix))
+    (intern (concat (replace-regexp-in-string aux "" (symbol-name option)) "-aux"))))
+
+(defun org-koma-letter--set-in-buffer (info option)
+  "Test whether an :option-alist value is set.  Return t or nil
+
+Values are \"primary\" values such as :email."
+  (let* ((opt (org-koma-letter--aux-name option))
+	 (value (if (plist-member info opt) (plist-get info opt)
+		  (warn (format "Checked whether %s was set. But no auxiliary value exists.  Returning nil"
+				option)))))
+    (not (equal (org-export-data value info) org-koma-letter-unset-string))))
+
 ;;; Transcode Functions
 
 ;;;; Export Block
@@ -553,11 +595,11 @@ holding export options."
 	info)))
    (let ((lco (plist-get info :lco))
 	 (author (plist-get info :author))
-	 (author-set (plist-get info :author-changed-in-buffer-p))
+	 (author-set (org-koma-letter--set-in-buffer info :author))
 	 (from-address (org-koma-letter--determine-to-and-from info 'from))
 	 (phone-number (plist-get info :phone-number))
 	 (email (plist-get info :email))
-	 (email-set (plist-get info :email-changed-in-buffer-p))
+	 (email-set (org-koma-letter--set-in-buffer info :email))
 	 (signature (plist-get info :signature)))
      (concat
       ;; author or email not set in file: may be overridden by lco
@@ -590,16 +632,19 @@ holding export options."
        (format "\\setkomavar{place}{%s}\n" (if with-place place ""))))
    ;; KOMA options
    (let ((with-backaddress (plist-get info :with-backaddress))
-	 (with-backaddress-set (plist-get info :with-backaddress-changed-in-buffer-p))
+	 (with-backaddress-set (org-koma-letter--set-in-buffer info :with-backaddress))
 	 (with-foldmarks (plist-get info :with-foldmarks))
-	 (with-foldmarks-set
-	  (not (string-equal (plist-get info :with-foldmarks-changed-in-buffer-p)
-			     "foldmarks-not-set")))
+	 (with-foldmarks-set (org-koma-letter--set-in-buffer info :with-foldmarks))
 	 (with-phone (plist-get info :with-phone))
-	 (with-phone-set (plist-get info :with-phone-changed-in-buffer-p))
+	 (with-phone-set (org-koma-letter--set-in-buffer info :with-phone))
+	 ;; TODO: email can now be set in two different places.  This
+	 ;; is handled in an inelegant manner.
 	 (with-email (plist-get info :with-email))
-	 (with-email-set (plist-get info :with-email-changed-in-buffer-p)))
+	 (with-email-set (org-koma-letter--set-in-buffer info :with-email)))
      (concat
+      ;; TODO: with the (with . .)-clauses the default values are
+      ;; basically obsolete as these variables are only set when
+      ;; changed in buffer...
       (when with-backaddress-set
 	(format "\\KOMAoption{backaddress}{%s}\n" (if with-backaddress "true" "false")))
       (when with-foldmarks-set
-- 
1.8.5.3


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #4: 0003-Allow-separate-subject-and-title-in-ox-koma-letter.patch --]
[-- Type: text/x-diff, Size: 4001 bytes --]

From 16fe81deb90bd7eca503a94bc3cd53b366a3259a Mon Sep 17 00:00:00 2001
From: Rasmus Pank Roulund <w530@pank.eu>
Date: Mon, 25 Nov 2013 00:23:09 +0100
Subject: [PATCH 3/3] Allow separate subject and title in ox-koma-letter

* ox-koma-letter.el (org-koma-letter-use-title): New variable.
(org-koma-letter-title-is-subject-maybe): New variable.
(koma-letter-template): Allow seperate subject and title.
(org-koma-letter-template): Allow seperate subject and title.

Depending on the variable `org-koma-letter-title-is-subject-maybe' the
komavar "subject" may be set either with the TITLE keyword or with the
SUBJECT keyword.  It is now possible to typeset komavar title.
---
 contrib/lisp/ox-koma-letter.el | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index ef9f624..4f3fc57 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -275,6 +275,13 @@ Use `foldmarks:true' to activate default fold marks or
   :group 'org-export-koma-letter
   :type 'boolean)
 
+(defcustom org-koma-letter-use-title t
+  "Use a title in the letter.
+
+See also `org-koma-letter-title-is-subject-maybe'."
+  :group 'org-export-koma-letter
+  :type 'boolean)
+
 (defcustom org-koma-letter-default-class nil
   "Default class for `org-koma-letter'.
 
@@ -290,6 +297,14 @@ A headline is only used if #+OPENING is not set.  See also
   :group 'org-export-koma-letter
   :type 'boolean)
 
+(defcustom org-koma-letter-title-is-subject-maybe nil
+  "Let TITLE keyword be interpreted as subject when no subject is present if non-nil.
+
+This may be useful for older documents where the SUBJECT keyword
+was not present."
+    :group 'org-export-koma-letter
+    :type 'boolean)
+
 (defconst org-koma-letter-special-tags-in-letter '(to from)
   "Header tags related to the letter itself.")
 
@@ -318,6 +333,7 @@ A headline is only used if #+OPENING is not set.  See also
 					org-koma-letter-default-class
 					org-latex-default-class) t)
     (:author "AUTHOR" nil (org-koma-letter--get-value org-koma-letter-author) t)
+    (:subject "SUBJECT" nil nil space)
     (:from-address "FROM_ADDRESS" nil nil newline)
     (:phone-number "PHONE_NUMBER" nil org-koma-letter-phone-number)
     (:email "EMAIL" nil (org-koma-letter--get-value org-koma-letter-email) t)
@@ -341,7 +357,9 @@ A headline is only used if #+OPENING is not set.  See also
     (:with-phone nil "phone" org-koma-letter-use-phone)
     (:with-email nil "email" org-koma-letter-use-email)
     (:with-place nil "place" org-koma-letter-use-place)
-    (:with-subject nil "subject" org-koma-letter-subject-format))
+    (:with-subject nil "subject" org-koma-letter-subject-format)
+    (:with-title nil "title" org-koma-letter-use-title)
+    )
   :translate-alist '((export-block . org-koma-letter-export-block)
 		     (export-snippet . org-koma-letter-export-snippet)
 		     (headline . org-koma-letter-headline)
@@ -662,14 +680,20 @@ holding export options."
 			   (cond ((member with-subject '("true" "t" t)) nil)
 				 ((listp with-subject) with-subject)
 				 (t (list with-subject)))))
-	  (subject (org-export-data (plist-get info :title) info)))
+	  (prefer-subject org-koma-letter-title-is-subject-maybe)
+	  (subject* (org-export-data (plist-get info :subject) info))
+	  (title* (org-export-data (plist-get info :title) info))
+	  (subject (if prefer-subject (or subject* title*) subject*))
+	  (title (if prefer-subject (and subject* title*) title*))
+	  )
      (concat
       (when (and with-subject subject-format)
 	(concat
 	 "\\KOMAoption{subject}{"
 	 (mapconcat 'identity subject-format ",") "}\n" ))
       (when (and subject with-subject)
-	(format "\\setkomavar{subject}{%s}\n\n" subject))))
+	(format "\\setkomavar{subject}{%s}\n\n" subject))
+      (when title (format "\\setkomavar{title}{%s}\n\n" title))))
    ;; Document start
    "\\begin{document}\n\n"
    ;; Letter start
-- 
1.8.5.3