Re: [O] Extending org-koma-letter.el

[Nicolas Goaziou]

Hello,

Rasmus <address@hidden> writes:

> Thanks.  It's wonderful writing letters with the new latex exporter.
> You should consider adding it to org_contrib.

As you have noticed, it is not complete enough. Also, I haven't looked
at the documentation thoroughly and don't know what is possible to do.

On the other hand, I think that Org deserves a serious letter
package. If you want to maintain and improve it, I'm all for adding it
to contrib directory.

>> It's far from being complete. See it as a proof of concept. Feel free
>> to upgrade it.

> I need two further features to fully adopt org-koma-letter.el, but I am
> not sure how to proceed (I still haven't found too much [non-programmer]
> documentation on how to hack the new org-exporter).

If you have any question, just ask here.

> First, it should allow for contents after \closing{·}, e.g. \ps{·} and
> \encl{·}.  Second, it should allow for arbitrary LaTeX command
> \end{letter}, e.g. \includepdf{·}.

This is a reasonable suggestion, indeed.

> Thus, I basically want to extend org-koma-letter-template to include to
> extra content-like elements.
>
>    (defun org-koma-letter-template (contents info)
>    ...
>    ...
>    (format "\n\\closing{%s}\n\n" (plist-get info :closing))
>    ;; appendix in letter
>    appendix
>    ;; Letter ends.
>    "\\end{letter}\n"
>    after-letter
>    ;; Document ends.
>    "\\end{document}"
>
>
> I am not sure how to implement this.  I want it to operate on tags.  So
> I want
> #+begin_src
> * my-encl                                                    :appendix:
> #+latex:\encl{
>         - doc 1
>         - doc 2
> #+latex:}
> #+end_src

The #+latex: ... parts are ugly. You may implement
an #+attr_koma: :enclosure t syntax, for example.

> to /not/ be part of contents, but be recognized as appendix inserted
> after the signature.  Likewise headlines with tag :afterletter: should
> only be inserted after \end{letter}.
>
> Could anyone provide any hints as to how to archive this behavior.  (I
> can't really understand all the details by just reading the API...).

While in the template, you have to search for headlines with a certain
tag (you could also do the same with properties), and treat them the way
you want.

Parse tree is found in communication channel (INFO argument) via:

  (plist-get info :parse-tree)

You can skim through it and collect headlines matching a criteria with
`org-element-map'. Here, the criteria is that "appendix" has to be
a member of headline's tags. These tags are obtained with
`org-export-get-tags'. Hence:

#+begin_src emacs-lisp
(org-element-map
  (plist-get info :parse-tree) 'headline
  (lambda (h) 
    (and (member "appendix" (org-export-get-tags h info))
         h))
  info)
#+end_src

will return a list of all headlines with the "appendix" tag. Now, what
you want to do with them is up to you.  You may simply want to export
them right here, in the template. This is done with `org-export-data'.

#+begin_src emacs-liso
(mapconcat (lambda (h) (org-export-data h info))
           ;; List of "appendix" headlines
           (org-element-map
            (plist-get info :parse-tree) 'headline
            (lambda (h)
              (and (member "appendix" (org-export-get-tags h info))
                   h))
            info)
           "")
#+end_src

Though, if you transcode them outside of \begin{letter}...\end{letter},
you probably don't want to also see them within that environment. In
other words, you have to tell the function transcoding headlines,
`org-koma-letter-headline', to ignore (that is return a nil value)
headlines with an "appendix" tag when it sees one.

On the other hand, if the headline has no such tag, you may want to
delegate its transcoding to e-latex backend instead. You can use
something like the following:

#+begin_src emacs-lisp
(defun org-koma-letter-headline (headline contents info)
  "Transcode a HEADLINE element into KOMA Scrlttr2 code.
CONTENTS is nil.  INFO is a plist used as a communication
channel."
  (unless (member "appendix" (org-export-get-tags headline info))
    (funcall (cdr (assq 'headline org-e-latex-translate-alist))
             headline contents info)))
#+end_src

HTH,


Regards,

-- 
Nicolas Goaziou