[PATCH] ox.el: Define subtitle macro

[PATCH] ox.el: Define subtitle macro

[Jens Lechtenboerger]

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

Hi there,

the attached patch adds a subtitle macro with documentation.

Best wishes
Jens


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Define-and-document-subtitle-macro.patch --]
[-- Type: text/x-diff, Size: 2410 bytes --]

From 3f54f515847f1f3034274d79fff6cfd1f92c72a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Lechtenb=C3=B6rger?= <jens.lechtenboerger@fsfe.org>
Date: Thu, 16 Nov 2017 15:03:33 +0100
Subject: [PATCH] Define and document subtitle macro

* lisp/ox.el (org-export-as): Define macro for subtitle.

* lisp/org-macro.el: Mention new macro in comment among others.

* doc/org.texi: Document new macro.
---
 doc/org.texi      | 2 ++
 lisp/org-macro.el | 2 +-
 lisp/ox.el        | 6 ++++--
 3 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index e116a9b..3907eda 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11080,9 +11080,11 @@ Org comes with following pre-defined macros:
 
 @table @code
 @item @{@{@{title@}@}@}
+@item @{@{@{subtitle@}@}@}
 @itemx @{@{@{author@}@}@}
 @itemx @{@{@{email@}@}@}
 @cindex title, macro
+@cindex subtitle, macro
 @cindex author, macro
 @cindex email, macro
 Org replaces these macro references with available information at the time of
diff --git a/lisp/org-macro.el b/lisp/org-macro.el
index 1d2823e..c82bfd8 100644
--- a/lisp/org-macro.el
+++ b/lisp/org-macro.el
@@ -43,7 +43,7 @@
 ;;   {{{n(counter,action}}}.
 
 ;; Upon exporting, "ox.el" will also provide {{{author}}}, {{{date}}},
-;; {{{email}}} and {{{title}}} macros.
+;; {{{email}}}, {{{title}}}, and {{{subtitle}}} macros.
 
 ;;; Code:
 (require 'cl-lib)
diff --git a/lisp/ox.el b/lisp/ox.el
index cc3c48b..6feec3e 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -3083,8 +3083,8 @@ Return code as a string."
 	     (let ((result (funcall filter info backend-name)))
 	       (when result (setq info result)))))
 	 ;; Expand export-specific set of macros: {{{author}}},
-	 ;; {{{date(FORMAT)}}}, {{{email}}} and {{{title}}}.  It must
-	 ;; be done once regular macros have been expanded, since
+	 ;; {{{date(FORMAT)}}}, {{{email}}}, {{{title}}}, and {{{subtitle}}}.
+	 ;; It must be done once regular macros have been expanded, since
 	 ;; parsed keywords may contain one of them.
 	 (org-macro-replace-all
 	  (list
@@ -3102,6 +3102,8 @@ Return code as a string."
 		     value)))
 	   (cons "email" (org-element-interpret-data (plist-get info :email)))
 	   (cons "title" (org-element-interpret-data (plist-get info :title)))
+	   (cons "subtitle"
+		 (org-element-interpret-data (plist-get info :subtitle)))
 	   (cons "results" "$1"))
 	  'finalize
 	  parsed-keywords)
-- 
2.1.4

Re: [PATCH] ox.el: Define subtitle macro

[Rasmus]

Jens Lechtenboerger <lechten@wi.uni-muenster.de> writes:

> the attached patch adds a subtitle macro with documentation.

AFAIK it’s already added to the backends where it makes sense.  It’s not a
basic keyword like "#+author".  It should be documented under the relevant
backends that support it.

Rasmus

-- 
Governments should be afraid of their people

Re: [PATCH] ox.el: Define subtitle macro

[Jens Lechtenboerger]

On 2017-11-17, Rasmus wrote:

> Jens Lechtenboerger <lechten@wi.uni-muenster.de> writes:
>
>> the attached patch adds a subtitle macro with documentation.
>
> AFAIK it’s already added to the backends where it makes sense.  It’s not a
> basic keyword like "#+author".  It should be documented under the relevant
> backends that support it.

Sorry, I don't understand your suggestion.  I'm interested in
org-reveal [1], which is based on ox-html.el.  In ox-html.el,
subtitles are used at some hardcoded positions (preamble, postamble,
template), but I need access to the subtitle elsewhere.

What should I document where?

Best wishes
Jens

[1] https://github.com/lechten/org-reveal

Re: [PATCH] ox.el: Define subtitle macro

[Nicolas Goaziou]

Hello,

Jens Lechtenboerger <lechten@wi.uni-muenster.de> writes:

> On 2017-11-17, Rasmus wrote:
>
>> Jens Lechtenboerger <lechten@wi.uni-muenster.de> writes:
>>
>>> the attached patch adds a subtitle macro with documentation.
>>
>> AFAIK it’s already added to the backends where it makes sense.  It’s not a
>> basic keyword like "#+author".  It should be documented under the relevant
>> backends that support it.
>
> Sorry, I don't understand your suggestion.  I'm interested in
> org-reveal [1], which is based on ox-html.el.  In ox-html.el,
> subtitles are used at some hardcoded positions (preamble, postamble,
> template), but I need access to the subtitle elsewhere.
>
> What should I document where?

SUBTITLE keyword may not be supported in every back-end. As
a consequence, supporting a global {{{subtitle}}} macro sounds
presumptuous.

Anyway, it begs for generalisation. The same problem is going to arise
for CREATOR, KEYWORDS, and WHATNOT. Instead of {{{subtitle}}}, we could
implement {{{option(KWD)}}}. Basically,

  {{{option(SUBTITLE)}}}  => (org-element-interpret-data (plist-get info :subtitle))

Options with a `split' behaviour would need a special treatment,
however.

WDYT? Do you want to have a stab at it?

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] ox.el: Define subtitle macro

[Jens Lechtenboerger]

On 2017-11-17, Nicolas Goaziou wrote:

> SUBTITLE keyword may not be supported in every back-end. As
> a consequence, supporting a global {{{subtitle}}} macro sounds
> presumptuous.
>
> Anyway, it begs for generalisation. The same problem is going to arise
> for CREATOR, KEYWORDS, and WHATNOT. Instead of {{{subtitle}}}, we could
> implement {{{option(KWD)}}}. Basically,
>
>   {{{option(SUBTITLE)}}} => (org-element-interpret-data (plist-get
> info :subtitle))
>
> Options with a `split' behaviour would need a special treatment,
> however.
>
> WDYT? Do you want to have a stab at it?

Thanks for your reply.  That would be great but goes way beyond my
current understanding of org internals.  I've never heard of `split'
behaviour.  Currently I don't have time to investigate this.

I'll stick with a local change for now.

Best wishes
Jens

Re: [PATCH] ox.el: Define subtitle macro

[Nicolas Goaziou]

Hello,

Jens Lechtenboerger <lechten@wi.uni-muenster.de> writes:

> Thanks for your reply.  That would be great but goes way beyond my
> current understanding of org internals.  I've never heard of `split'
> behaviour.  Currently I don't have time to investigate this.

For the record, I implemented a "keyword" macro (master branch).

Feedback welcome.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] ox.el: Define subtitle macro

[Jens Lechtenboerger]

On 2017-11-21, Nicolas Goaziou wrote:

> For the record, I implemented a "keyword" macro (master branch).

Excellent, that works for me. 

Many thanks
Jens

Re: [PATCH] ox.el: Define subtitle macro

[Jens Lechtenboerger]

Hi there,

On 2017-11-21, Nicolas Goaziou wrote:

> For the record, I implemented a "keyword" macro (master branch).

That has been in master for over a year now.  Are there plans for
inclusion in a release?  (Or did I overlook that?)

Best wishes
Jens

Re: [PATCH] ox.el: Define subtitle macro

[Nicolas Goaziou]

Hello,

Jens Lechtenboerger <lechten@wi.uni-muenster.de> writes:

> Hi there,
>
> On 2017-11-21, Nicolas Goaziou wrote:
>
>> For the record, I implemented a "keyword" macro (master branch).
>
> That has been in master for over a year now.  Are there plans for
> inclusion in a release?  (Or did I overlook that?)

master branch is meant to be released... at some point. For the record,
I cannot do it myself.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] ox.el: Define subtitle macro

[Kaushal Modi]

> master branch is meant to be released... at some point. For the record,
> I cannot do it myself.

+1 It would be great to have Org 9.2 released!

Re: [PATCH] ox.el: Define subtitle macro

[Bastien]

Hi Kaushal and all,

>> master branch is meant to be released... at some point. For the record,
>> I cannot do it myself.
>
> +1 It would be great to have Org 9.2 released!

I plan to release it on saturday 22nd, thanks for the heads up.

Also, I just signed a three-years contract in december, meaning that
I will have more time to become a contributor again.

All best,

-- 
 Bastien