[PATCH] ox-koma-letter.el: Add support for section

[PATCH] ox-koma-letter.el: Add support for section

[Daniele Pizzolli]

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

Hello,

I was really surprised that headlines, that are so common in org-mode
are discarded by default in ox-koma-letter.

This patch tries to add the support for them.  It works for me but
requires some work to fit the coding and documentation convention that
are still unknown to me.

I will be happy to follow your suggestion or if somebody take this code
as a minimal implementation to start to work with.

Thanks in advance,
Daniele


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-ox-koma-letter.el-Add-support-for-section.patch --]
[-- Type: text/x-diff, Size: 1902 bytes --]

From 390d93afc95f6151e1bde43ef91b4e31f91ecd01 Mon Sep 17 00:00:00 2001
From: Daniele Pizzolli <dan@toel.it>
Date: Sat, 2 Jan 2016 11:48:24 +0100
Subject: [PATCH] ox-koma-letter.el: Add support for section

* contrib/lisp/ox-koma-letter.el (org-koma-letter-headline): Add
  support for section using the text of headline.

TINYCHANGE
---
 contrib/lisp/ox-koma-letter.el | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index 3231d34..aea5a9c 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -569,10 +569,34 @@ holding contextual information.
 Note that if a headline is tagged with a tag from
 `org-koma-letter-special-tags' it will not be exported, but
 stored in `org-koma-letter-special-contents' and included at the
-appropriate place."
+appropriate place.
+
+If the headline level is greater than one include the headline as
+section.  This allow to write letter with sections by using
+section.lco available at:
+<http://www.komascript.de/sections.lco>.
+
+Add [sections] to LATEX_CLASS_OPTIONS with:
+
+#+LATEX_CLASS_OPTIONS: [sections]
+
+If section.lco is unavaliable the section are exported in the tex
+source but not rendered in the final pdf.
+
+- TODO: add test
+- TODO: level n should become n-1, because there is no real
+        level 1 section
+- TODO: check if section are allowed inside other letter keywords
+"
   (let ((special-tag (org-koma-letter--special-tag headline info)))
     (if (not special-tag)
-	contents
+	(progn
+	  (if (= 1 (org-element-property :level headline))
+	      contents
+	    (progn
+	      ;; TODO find out how to decrease the level by one!
+	      (org-latex-headline headline contents info)
+	      )))
       (push (cons special-tag contents) org-koma-letter-special-contents)
       "")))
 
-- 
2.1.4

[PATCH] ox-koma-letter.el: Add support for section

[Daniele Pizzolli]

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

Hello,

I was really surprised that headlines, that are so common in org-mode
are discarded by default in ox-koma-letter.

This patch tries to add the support for them.  It works for me but
requires some work to fit the coding and documentation convention that
are still unknown to me.

I will be happy to follow your suggestion or if somebody take this code
as a minimal implementation to start to work with.

Thanks in advance,
Daniele


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-ox-koma-letter.el-Add-support-for-section.patch --]
[-- Type: text/x-diff, Size: 1902 bytes --]

From 390d93afc95f6151e1bde43ef91b4e31f91ecd01 Mon Sep 17 00:00:00 2001
From: Daniele Pizzolli <dan@toel.it>
Date: Sat, 2 Jan 2016 11:48:24 +0100
Subject: [PATCH] ox-koma-letter.el: Add support for section

* contrib/lisp/ox-koma-letter.el (org-koma-letter-headline): Add
  support for section using the text of headline.

TINYCHANGE
---
 contrib/lisp/ox-koma-letter.el | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index 3231d34..aea5a9c 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -569,10 +569,34 @@ holding contextual information.
 Note that if a headline is tagged with a tag from
 `org-koma-letter-special-tags' it will not be exported, but
 stored in `org-koma-letter-special-contents' and included at the
-appropriate place."
+appropriate place.
+
+If the headline level is greater than one include the headline as
+section.  This allow to write letter with sections by using
+section.lco available at:
+<http://www.komascript.de/sections.lco>.
+
+Add [sections] to LATEX_CLASS_OPTIONS with:
+
+#+LATEX_CLASS_OPTIONS: [sections]
+
+If section.lco is unavaliable the section are exported in the tex
+source but not rendered in the final pdf.
+
+- TODO: add test
+- TODO: level n should become n-1, because there is no real
+        level 1 section
+- TODO: check if section are allowed inside other letter keywords
+"
   (let ((special-tag (org-koma-letter--special-tag headline info)))
     (if (not special-tag)
-	contents
+	(progn
+	  (if (= 1 (org-element-property :level headline))
+	      contents
+	    (progn
+	      ;; TODO find out how to decrease the level by one!
+	      (org-latex-headline headline contents info)
+	      )))
       (push (cons special-tag contents) org-koma-letter-special-contents)
       "")))
 
-- 
2.1.4

Re: [PATCH] ox-koma-letter.el: Add support for section

[Rasmus]

Hi Daniele,

First, thanks for your patch.

Daniele Pizzolli <dan@toel.it> writes:

> I was really surprised that headlines, that are so common in org-mode
> are discarded by default in ox-koma-letter.

Why?  They are not supported by scrlttr2.cls, except if you download an
extra lco file, not distributed via CTAN.  As such, I don’t think it
should be supported by ox-koma-letter.el.

A general headline property that allows to insert arbitrary code right
before a headline (such as "@@latex:\clearpage@@") might be a more
fruitful approach.

> +Add [sections] to LATEX_CLASS_OPTIONS with:
> +
> +#+LATEX_CLASS_OPTIONS: [sections]
> +
> +If section.lco is unavaliable the section are exported in the tex
> +source but not rendered in the final pdf.

Whether section.lco is available or not is a complicated question.  You
first need to figure out what is the tex distribution (what if it’s not in
PATH) and whether section.lco is available via something like kpsewhich.
Note that e.g. TL also looks in the current path.

Regards,
Rasmus

-- 
Summon the Mothership!

Re: [PATCH] ox-koma-letter.el: Add support for section

[Daniele Pizzolli]

On Sat, Jan 02 2016, Rasmus  wrote:

> Hi Daniele,
>
> First, thanks for your patch.
>
> Daniele Pizzolli <dan@toel.it> writes:
>
>> I was really surprised that headlines, that are so common in org-mode
>> are discarded by default in ox-koma-letter.
>
> Why?  They are not supported by scrlttr2.cls, except if you download an
> extra lco file, not distributed via CTAN.  As such, I don’t think it
> should be supported by ox-koma-letter.el.

Hello Rasmus,

thanks for you comment.  I try to explain my point of view better.  Now
the export to letter silently discard the headings text in the exported
tex.  This is quite bad, even if documented.  As a user I want to change
quite easily the export backend (text, latex, beamer, ...)  while
retaining most of my work.  Every backend as it's own supported
features, but discarding the input provided by the user does not provide
the best user experience to me.

By the way this patch does not change the final output, if there is no
section.lco available.  So there should be no regression and only
improvements.

I really prefer something that instead of discarding the user input
rewrite it to fit the backend features (if there is no heading/section
support, use something like the start of paragraph, and support section
only if enabled by the user) but this is beyond my coding abilities in
elisp, so I sent the minimal working patch with the minimal impact on
existing behaviour.

> A general headline property that allows to insert arbitrary code right
> before a headline (such as "@@latex:\clearpage@@") might be a more
> fruitful approach.

I guess this is another story.

>> +Add [sections] to LATEX_CLASS_OPTIONS with:
>> +
>> +#+LATEX_CLASS_OPTIONS: [sections]
>> +
>> +If section.lco is unavaliable the section are exported in the tex
>> +source but not rendered in the final pdf.
>
> Whether section.lco is available or not is a complicated question.  You
> first need to figure out what is the tex distribution (what if it’s not in
> PATH) and whether section.lco is available via something like kpsewhich.
> Note that e.g. TL also looks in the current path.

I use org to touch as less latex as possible, I just downloaded the
section.lco and put in the same directory of my org file and everything
was working.  A little before I used apt-file search section.lco but
since nothing was found I quickly reverted to the manual download.  I
wish that everything is packaged as distro package, but I can survive
some manual work.

Best,
Daniele

Re: [PATCH] ox-koma-letter.el: Add support for section

[Rasmus]

Hi Daniele,

Daniele Pizzolli <dan@toel.it> writes:

> thanks for you comment.  I try to explain my point of view better.  Now
> the export to letter silently discard the headings text in the exported
> tex.  This is quite bad, even if documented.  As a user I want to change
> quite easily the export backend (text, latex, beamer, ...)  while
> retaining most of my work.  Every backend as it's own supported
> features, but discarding the input provided by the user does not provide
> the best user experience to me.

That's a fair point.  Nonetheless,

> By the way this patch does not change the final output, if there is no
> section.lco available.  So there should be no regression and only
> improvements.

> I really prefer something that instead of discarding the user input
> rewrite it to fit the backend features (if there is no heading/section
> support, use something like the start of paragraph, and support section
> only if enabled by the user) but this is beyond my coding abilities in
> elisp, so I sent the minimal working patch with the minimal impact on
> existing behaviour.


Whether sections.lco is available is nontrivial.  As I remember the patch,
it also imposed level two headings to be sections.

If you really think this is the right approach, perhaps the "H:" option
could be used to set the special heading level...  We’d need this since
you can specify the opening with a heading.

>>> +Add [sections] to LATEX_CLASS_OPTIONS with:
>>> +
>>> +#+LATEX_CLASS_OPTIONS: [sections]
>>> +
>>> +If section.lco is unavaliable the section are exported in the tex
>>> +source but not rendered in the final pdf.
>>
>> Whether section.lco is available or not is a complicated question.  You
>> first need to figure out what is the tex distribution (what if it’s not in
>> PATH) and whether section.lco is available via something like kpsewhich.
>> Note that e.g. TL also looks in the current path.
>
> I use org to touch as less latex as possible, I just downloaded the
> section.lco and put in the same directory of my org file and everything
> was working.  A little before I used apt-file search section.lco but
> since nothing was found I quickly reverted to the manual download.  I
> wish that everything is packaged as distro package, but I can survive
> some manual work.

This is because sections.lco is not part of KOMA-Script (like titlepage¹).
E.g. on my system with TL:

     $ kpsewhich sections.lco
     /home/rasmus/.texmf/tex/latex/koma-script/sections.lco

kpsewhich/tex also looks in the current directory, which is why you can
just place it in the same folder.

Cheers,
Rasmus

Footnotes: 
¹   http://www.komascript.de/titlepage

-- 
Warning: Everything saved will be lost

Re: [PATCH] ox-koma-letter.el: Add support for section

[Daniele Pizzolli]

On Mon, Jan 04 2016, Rasmus  wrote:

> Hi Daniele,
>
> Daniele Pizzolli <dan@toel.it> writes:
>
>> thanks for you comment.  I try to explain my point of view better.  Now
>> the export to letter silently discard the headings text in the exported
>> tex.  This is quite bad, even if documented.  As a user I want to change
>> quite easily the export backend (text, latex, beamer, ...)  while
>> retaining most of my work.  Every backend as it's own supported
>> features, but discarding the input provided by the user does not provide
>> the best user experience to me.
>
> That's a fair point.  Nonetheless,

Hi Rasmus,
thanks for recognizing it.

>> By the way this patch does not change the final output, if there is no
>> section.lco available.  So there should be no regression and only
>> improvements.
>
>> I really prefer something that instead of discarding the user input
>> rewrite it to fit the backend features (if there is no heading/section
>> support, use something like the start of paragraph, and support section
>> only if enabled by the user) but this is beyond my coding abilities in
>> elisp, so I sent the minimal working patch with the minimal impact on
>> existing behaviour.
>
>
> Whether sections.lco is available is nontrivial.  As I remember the patch,
> it also imposed level two headings to be sections.

Not really.  With the current patch, all the headings inside the main
content (that is the first not special tagged heading) are rendered with
a section level that is one level more than expected because the first
level is taken away by the main content (because the main content is not
a section).  So there should be some work to adjust the level by adding
+1.  The behaviour of one level headings is left unchanged because of
the way ox-koma-letter works, but this can be changed, if there is a
better approach.

> If you really think this is the right approach, perhaps the "H:" option
> could be used to set the special heading level...  We’d need this since
> you can specify the opening with a heading.

I am lost here.  H: should work as expected.  We have the inverse
problem (go up to the level with sections).

>>>> +Add [sections] to LATEX_CLASS_OPTIONS with:
>>>> +
>>>> +#+LATEX_CLASS_OPTIONS: [sections]
>>>> +
>>>> +If section.lco is unavaliable the section are exported in the tex
>>>> +source but not rendered in the final pdf.
>>>
>>> Whether section.lco is available or not is a complicated question.  You
>>> first need to figure out what is the tex distribution (what if it’s not in
>>> PATH) and whether section.lco is available via something like kpsewhich.
>>> Note that e.g. TL also looks in the current path.
>>
>> I use org to touch as less latex as possible, I just downloaded the
>> section.lco and put in the same directory of my org file and everything
>> was working.  A little before I used apt-file search section.lco but
>> since nothing was found I quickly reverted to the manual download.  I
>> wish that everything is packaged as distro package, but I can survive
>> some manual work.
>
> This is because sections.lco is not part of KOMA-Script (like titlepage¹).
> E.g. on my system with TL:
>
>      $ kpsewhich sections.lco
>      /home/rasmus/.texmf/tex/latex/koma-script/sections.lco
>
> kpsewhich/tex also looks in the current directory, which is why you can
> just place it in the same folder.

Thanks for the info, I admit that LT and kpsewhich are unknown to me, as
I said I try to stay away from latex and tex as much as possible.  If
there is some agreement on the patch I will update the doc to add those
info.

Best,
Daniele

Re: [PATCH] ox-koma-letter.el: Add support for section

[Rasmus]

Ciao Daniele,

Daniele Pizzolli <dan@toel.it> writes:

>> Whether sections.lco is available is nontrivial.  As I remember the patch,
>> it also imposed level two headings to be sections.
>
> Not really.  With the current patch, all the headings inside the main
> content (that is the first not special tagged heading) are rendered with
> a section level that is one level more than expected because the first
> level is taken away by the main content (because the main content is not
> a section).

That’s fair.

> So there should be some work to adjust the level by adding
> +1.  The behaviour of one level headings is left unchanged because of
> the way ox-koma-letter works, but this can be changed, if there is a
> better approach.

Some notes which are probably obvious to you, but which at least I need to
think about the problem follows.

1. From above, I guess you can take the relative level of the opening
   headline plus one.

2. As I recall, there’s no limitation on the level of the opening in
   org-koma-letter--keyword-or-headline.  It simply takes the first
   headline without a special keyword.  It need not be top level.

It seems you’d have to implement the following:

  - The opening headline is at the relative top level.  /This breaks
    backward-comparability/.  So perhaps only if sections are requested,
    although ox-koma-letter already has WAY too many options and
    configurations.
  - Sections start at (1+ (or "the opening level" "the relative top level")).
  - Bonus: How to configure the mapping of levels to section, subsection
    etc.  E.g. what if I want to use \addsect in stead of sections?  (I
    don’t remember if this is supported by sections.lco; IMO it’s very
    reasonable to just take assumptions according to what is available in
    sections.lco)
  
Some people organizes letters like this with subtree export (re previous
posts to this list).  It must work in that case.

    * letter one
    ** to one :to:
    ** opening one,
       Letter 1 
    * letter two
    ** to two :to:
    ** opening two,
       Letter 1 


>> If you really think this is the right approach, perhaps the "H:" option
>> could be used to set the special heading level...  We’d need this since
>> you can specify the opening with a heading.
>
> I am lost here.  H: should work as expected.  We have the inverse
> problem (go up to the level with sections).

Compare

    #+options: H:2
    * section
    ** frame

and

    #+options: H:1
    * section
    ** frame

in ox-beamer.  Perhaps it’s an overkill for ox-koma-letter.

> Thanks for the info, I admit that LT and kpsewhich are unknown to me, as
> I said I try to stay away from latex and tex as much as possible.  If
> there is some agreement on the patch I will update the doc to add those
> info.

I think it’s best to add a switch (defcustom) either per document or at
least a global variable.  It defaults to nil.  E.g. #+options: sections:t

Thanks,
Rasmus

-- 
And I faced endless streams of vendor-approved Ikea furniture. . .