Hi,
I've added a patch that address the code problems, but not the
documentation issues, as the solution is still unclear.
Nicolas Goaziou <m...@nicolasgoaziou.fr> writes:
>> But de facto KEYWORDS and DESCRIPTION were also only supported in some
>> backends. I think it's more convenient to have these type of keywords in
>> one place. But I don't feel strongly about this.
>
> I would like to keep a clear and somewhat future-proof rule about this:
>
> 1. A keyword a user can expect to find in all back-ends where it makes
> sense should be defined in "ox.el". To put it differently, it can be
> considered as a bug if a back-end could /simply/ support a keyword
> in this category but doesn't. Keywords in this category are to be
> documented in (info "(org)Export settings").
>
> 2. Other keywords are defined in their respective back-end, and
> documented in their respective chapter in the manual.
>
> As a non-trivial example, consider :email. You can expect it to produce
> something sensible in any back-end. Yet, "ox-icalendar" doesn't use it.
> It still belongs to first category.
>
> If we support SUBTITLE everywhere it makes sense, it might be worth
> adding it to the first category. Actually, considering the rule above,
> I even lean towards adding it to that category. WDYT?
I think it's hard to make a clear-cut rule. I think keywords that are
well-supported by Org-core should be there. From a user perspective, I
think it should be close to TITLE. Further, putting it there also signal
to external writers, e.g. ox-reveal, that they should now try to support
it. I think SUBTITLE, KEYWORD, and DESCRIPTION is within the same
category and should be treated the same.
We could add a subsection with "text document properties" which are
keywords that are supported by the set: {ox-html, ox-ascii, ox-odt,
ox-latex}. These would be sort of 1½ class citizens.
We can't support SUBTITLE everywhere, 'cause it simply does not make sense
(only in "text document producers" IMO).
The support of SUBTITLE is:
W/Emacs: support is 6/9
W/Contrib: support is 8/20
- BTW: ox-groff seems to have some support for subtitles, but
I'm not sure how this works, so I haven't tried to unify
it.
- I guess it could be added to ox-rss could support it. Atom
seems to support subtitle, but it does not seem rss 2.0 has
it in its definition... I don't know the details of RSS
well.
W/"the wild": for all I know the limit of the fraction is zero.
> Also, I'm going to implement the `parse-object' and `parse-element'
> behaviour we discussed in another thread, and remove
> `org-element-document-properties' (and the relative
> `org-export-document-properties') altogether. This will remove a useless
> distinction among keywords: two categories are enough.
I think this sounds very cool. It will allow us to remove a lot of
"low-level" details from file with additional parsed keywords.
> As a side-effect, however, `org-element-context' will not show objects
> when called on TITLE and al, but that might be a good thing actually
> (there are objects in there only during export and only if considered
> export back-end makes use of them).
As mentioned, it's fine with me and nobody else complained so I think
there's no need to worry.
>>> (and formatted-subtitle ...)
>>
>> Can you explain why (and ⋯) should be used here?
>
> It makes more obvious you are expecting a return value. `when' is
> preferred for side effects. However, this is not a hard rule, since
Thanks for the example.
—Rasmus
--
Don't panic!!!
>From 1c2241e4d39a619b6123cb4e69c60dcec42534ee Mon Sep 17 00:00:00 2001
From: Rasmus <ras...@gmx.us>
Date: Sun, 1 Mar 2015 22:09:19 +0100
Subject: [PATCH] ox: Add SUBTITLE property in some backends
* ox-ascii.el (org-ascii-template--document-title)
(org-ascii-template--document-title)
ox-deck.el (org-deck-title-slide-template)
ox-s5.el (org-s5-title-slide-template)
ox-html.el (org-html--build-meta-info, org-html-format-spec)
(org-html--build-meta-info, org-html-format-spec)
(org-html--build-meta-info, org-html-format-spec)
ox-org.el (org), (org-org-keyword): Use SUBTITLE.
* ox-beamer.el (org-beamer-template)
ox-html (org-html-template)
ox-latex.el (org-latex-template)
ox-org (org-org-template): Insert SUBTITLE.
* ox-html (org-html-preamble-format) (org-html-postamble-format):
Update docstring.
* ox-html (org-html-style-default): Add .subtitle style and
change .title style.
* ox-texinfo.el (org-texinfo-template): Interpret subtitle.
* org.texi (Export settings): Document SUBTITLE.
* ORG-NEWS: Add entry on SUBTITLE.
The patch adds a #+SUBTITLE keyword to ox-ascii, ox-latex, ox-html and
ox-odt.
---
contrib/lisp/ox-deck.el | 7 +++++++
contrib/lisp/ox-s5.el | 7 +++++++
doc/org.texi | 11 ++++++++++-
etc/ORG-NEWS | 3 +++
lisp/ox-ascii.el | 22 +++++++++++++++++-----
lisp/ox-beamer.el | 20 +++++++++++++++++++-
lisp/ox-html.el | 37 +++++++++++++++++++++++++++++++------
lisp/ox-latex.el | 49 ++++++++++++++++++++++++++++++++++++++++++++-----
lisp/ox-odt.el | 32 +++++++++++++++++++++++++++++---
lisp/ox-texinfo.el | 10 +++++++---
10 files changed, 174 insertions(+), 24 deletions(-)
diff --git a/contrib/lisp/ox-deck.el b/contrib/lisp/ox-deck.el
index 0ebde41..9dbd6ca 100644
--- a/contrib/lisp/ox-deck.el
+++ b/contrib/lisp/ox-deck.el
@@ -38,6 +38,12 @@
;; See ox.el and ox-html.el for more details on how this exporter
;; works (it is derived from ox-html.)
+;; TODOs
+;; ------
+;; The title page is formatted using format-spec. This is error prone
+;; when details are missing and may insert empty tags, like <h2></h2>,
+;; for missing values.
+
(require 'ox-html)
(eval-when-compile (require 'cl))
@@ -259,6 +265,7 @@ Defaults to styles for the title page."
(defcustom org-deck-title-slide-template
"<h1>%t</h1>
+<h2>%s</h2>
<h2>%a</h2>
<h2>%e</h2>
<h2>%d</h2>"
diff --git a/contrib/lisp/ox-s5.el b/contrib/lisp/ox-s5.el
index b003919..503bfd0 100644
--- a/contrib/lisp/ox-s5.el
+++ b/contrib/lisp/ox-s5.el
@@ -48,6 +48,12 @@
;; in an Org mode buffer. See ox.el and ox-html.el for more details
;; on how this exporter works.
+;; TODOs
+;; ------
+;; The title page is formatted using format-spec. This is error prone
+;; when details are missing and may insert empty tags, like <h2></h2>,
+;; for missing values.
+
(require 'ox-html)
(eval-when-compile (require 'cl))
@@ -174,6 +180,7 @@ or an empty string."
(defcustom org-s5-title-slide-template
"<h1>%t</h1>
+<h2>%s</h2>
<h2>%a</h2>
<h3>%e</h3>
<h4>%d</h4>"
diff --git a/doc/org.texi b/doc/org.texi
index 18e5169..1f14093 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10713,6 +10713,12 @@ default value is @code{:export:}. Within a subtree tagged with
below). When headlines are selectively exported with @code{:export:}
anywhere in a file, text before the first headline is ignored.
+@item SUBTITLE
+@cindex #+SUBTITLE
+The document subtitle. The keyword is supported by @LaTeX{}-backends,
+HTML backends, ASCII backends, the Texinfo backend, and the ODT backend. You
+can use several such keywords for long subtitles.
+
@item EXCLUDE_TAGS
@cindex #+EXCLUDE_TAGS
@vindex org-export-exclude-tags
@@ -11601,6 +11607,7 @@ p.author @r{author information, including email}
p.date @r{publishing date}
p.creator @r{creator info, about org mode version}
.title @r{document title}
+.subtitle @r{document subtitle}
.todo @r{TODO keywords, all not-done states}
.done @r{the DONE keywords, all states that count as done}
.WAITING @r{each TODO keyword also uses a class named after itself}
@@ -13176,7 +13183,6 @@ to define your own class in @code{org-texinfo-classes}, which see. Set
@subsubheading Title and copyright page
@cindex #+TEXINFO_PRINTED_TITLE
-@cindex #+SUBTITLE
The default template includes a title page for hard copy output. The title
and author displayed on this page are extracted from, respectively,
@code{#+TITLE} and @code{#+AUTHOR} keywords (@pxref{Export settings}). It is
@@ -13982,6 +13988,7 @@ however, override everything.
@item @code{:beamer-frame-default-options} @tab @code{org-beamer-frame-default-options}
@item @code{:beamer-outline-frame-options} @tab @code{org-beamer-outline-frame-options}
@item @code{:beamer-outline-frame-title} @tab @code{org-beamer-outline-frame-title}
+@item @code{:org-beamer-subtitle-format} @tab @code{org-beamer-subtitle-format}
@end multitable
@subsubheading HTML specific properties
@@ -14066,6 +14073,8 @@ however, override everything.
@item @code{:latex-listings} @tab @code{org-latex-listings}
@item @code{:latex-minted-langs} @tab @code{org-latex-minted-langs}
@item @code{:latex-minted-options} @tab @code{org-latex-minted-options}
+@item @code{:latex-subtitle-format} @tab @code{org-latex-subtitle-format}
+@item @code{:latex-subtitle-separate} @tab @code{org-latex-subtitle-separate}
@item @code{:latex-table-scientific-notation} @tab @code{org-latex-table-scientific-notation}
@item @code{:latex-tables-booktabs} @tab @code{org-latex-tables-booktabs}
@item @code{:latex-tables-centered} @tab @code{org-latex-tables-centered}
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 28e8394..b37650b 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -327,6 +327,9 @@ leading spaces within table cells.
*** New MathJax configuration options.
Org uses the MathJax CDN by default. See the manual and the docstring
of ~org-html-mathjax-options~ for details.
+*** New ~#+SUBTITLE~ keyword
+Org can now typeset a subtitle in some backends. See the manual for
+details.
** Miscellaneous
*** Strip all meta data from ITEM special property
ITEM special property does not contain TODO, priority or tags anymore.
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 42495e2..5f11485 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -119,7 +119,8 @@
org-ascii-filter-comment-spacing)
(:filter-section . org-ascii-filter-headline-blank-lines))
:options-alist
- '((:ascii-bullets nil nil org-ascii-bullets)
+ '((:subtitle "SUBTITLE" nil nil space)
+ (:ascii-bullets nil nil org-ascii-bullets)
(:ascii-caption-above nil nil org-ascii-caption-above)
(:ascii-charset nil nil org-ascii-charset)
(:ascii-global-margin nil nil org-ascii-global-margin)
@@ -967,9 +968,15 @@ INFO is a plist used as a communication channel."
;; Links in the title will not be resolved later, so we make
;; sure their path is located right after them.
(info (org-combine-plists info '(:ascii-links-to-notes nil)))
- (title (if (plist-get info :with-title)
- (org-export-data (plist-get info :title) info)
- ""))
+ (with-title (plist-get info :with-title))
+ (title (org-export-data
+ (when with-title (plist-get info :title)) info))
+ (subtitle (org-export-data
+ (when with-title
+ (org-element-parse-secondary-string
+ (plist-get info :subtitle)
+ (org-element-restriction 'keyword)))
+ info))
(author (and (plist-get info :with-author)
(let ((auth (plist-get info :author)))
(and auth (org-export-data auth info)))))
@@ -1012,8 +1019,12 @@ INFO is a plist used as a communication channel."
(let* ((utf8p (eq (plist-get info :ascii-charset) 'utf-8))
;; Format TITLE. It may be filled if it is too wide,
;; that is wider than the two thirds of the total width.
- (title-len (min (length title) (/ (* 2 text-width) 3)))
+ (title-len (min (max (length title)
+ (length subtitle))
+ (/ (* 2 text-width) 3)))
(formatted-title (org-ascii--fill-string title title-len info))
+ (formatted-subtitle (when (org-string-nw-p subtitle)
+ (org-ascii--fill-string subtitle title-len info)))
(line
(make-string
(min (+ (max title-len
@@ -1025,6 +1036,7 @@ INFO is a plist used as a communication channel."
(concat line "\n"
(unless utf8p "\n")
(upcase formatted-title)
+ (and formatted-subtitle (concat "\n" formatted-subtitle))
(cond
((and (org-string-nw-p author) (org-string-nw-p email))
(concat "\n\n" author "\n" email))
diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el
index 5d0b55d..b9b3e8c 100644
--- a/lisp/ox-beamer.el
+++ b/lisp/ox-beamer.el
@@ -133,6 +133,16 @@ You might want to put e.g. \"allowframebreaks=0.9\" here."
:type '(string :tag "Outline frame options"))
+(defcustom org-beamer-subtitle-format "\\subtitle{%s}"
+ "Format string used for transcoded subtitle.
+The format string should have at most one \"%s\"-expression,
+which is replaced with the subtitle."
+ :group 'org-export-beamer
+ :version "25.1"
+ :package-version '(Org . "8.3")
+ :type '(string :tag "Format string"))
+
+
;;; Internal Variables
@@ -233,6 +243,7 @@ Return overlay specification, as a string, or nil."
:options-alist
'((:headline-levels nil "H" org-beamer-frame-level)
(:latex-class "LATEX_CLASS" nil "beamer" t)
+ (:beamer-subtitle-format nil nil org-beamer-subtitle-format)
(:beamer-column-view-format "COLUMNS" nil org-beamer-column-view-format)
(:beamer-theme "BEAMER_THEME" nil org-beamer-theme)
(:beamer-color-theme "BEAMER_COLOR_THEME" nil nil t)
@@ -810,7 +821,12 @@ information."
"Return complete document string after Beamer conversion.
CONTENTS is the transcoded contents string. INFO is a plist
holding export options."
- (let ((title (org-export-data (plist-get info :title) info)))
+ (let ((title (org-export-data (plist-get info :title) info))
+ (subtitle (org-export-data
+ (org-element-parse-secondary-string
+ (plist-get info :subtitle)
+ (org-element-restriction 'keyword))
+ info)))
(concat
;; 1. Time-stamp.
(and (plist-get info :time-stamp-file)
@@ -877,6 +893,8 @@ holding export options."
(format "\\date{%s}\n" (org-export-data date info)))
;; 7. Title
(format "\\title{%s}\n" title)
+ (when (org-string-nw-p subtitle)
+ (concat (format (plist-get info :beamer-subtitle-format) subtitle) "\n"))
;; 8. Beamer-header
(let ((beamer-header (plist-get info :beamer-header)))
(when beamer-header
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 7ed73f6..29cf9a4 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -108,7 +108,8 @@
(if a (org-html-export-to-html t s v b)
(org-open-file (org-html-export-to-html nil s v b)))))))
:options-alist
- '((:html-doctype "HTML_DOCTYPE" nil org-html-doctype)
+ '((:subtitle "SUBTITLE" nil nil space)
+ (:html-doctype "HTML_DOCTYPE" nil org-html-doctype)
(:html-container "HTML_CONTAINER" nil org-html-container-element)
(:html-html5-fancy nil "html5-fancy" org-html-html5-fancy)
(:html-link-use-abs-url nil "html-link-use-abs-url" org-html-link-use-abs-url)
@@ -270,7 +271,12 @@ for the JavaScript code in this tag.
(defconst org-html-style-default
"<style type=\"text/css\">
<!--/*--><