[ox, patch] #+SUBTITLE

[ox, patch] #+SUBTITLE

[Rasmus]

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

Hi,

I'm starting a new thread as the previous discussion attracted much
dissuasion not directly related to the patch in question.  Changes:

    - Html subtitles now follow the W3 recommendations, I think/hope.  It
      would be great if somebody who knows css would check the styling.
      
    - The texinfo subtitle is interpreted.

    - Documentation and NEWS is added.

Note: *the patch does not touch ox.el*.  SUBTITLE is *only* supported in a
tiny fraction of the backends, namely ox-latex, ox-ascii, ox-html, and
ox-odt.

—Rasmus

-- 
Er du tosset for noge' lårt!

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Add-SUBTITLE-property-in-some-backends.patch --]
[-- Type: text/x-diff, Size: 21269 bytes --]

From 6d4e46af0b9ef5623c1a638c4659997fb735350b Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@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 |  2 ++
 contrib/lisp/ox-s5.el   |  2 ++
 doc/org.texi            |  7 ++++++-
 etc/ORG-NEWS            |  3 +++
 lisp/ox-ascii.el        | 23 ++++++++++++++++++-----
 lisp/ox-beamer.el       | 10 +++++++++-
 lisp/ox-html.el         | 37 +++++++++++++++++++++++++++++++------
 lisp/ox-latex.el        | 41 ++++++++++++++++++++++++++++++++++++-----
 lisp/ox-odt.el          | 32 +++++++++++++++++++++++++++++---
 lisp/ox-org.el          |  9 +++++++--
 lisp/ox-texinfo.el      | 10 +++++++---
 11 files changed, 150 insertions(+), 26 deletions(-)

diff --git a/contrib/lisp/ox-deck.el b/contrib/lisp/ox-deck.el
index 0ebde41..a76384b 100644
--- a/contrib/lisp/ox-deck.el
+++ b/contrib/lisp/ox-deck.el
@@ -259,6 +259,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>"
@@ -446,6 +447,7 @@ holding export options."
       ;; title page
       (format "<%s id='title-slide' class='slide'>"
               (plist-get info :html-container))
+      ;; TODO: format-spec isn't great for missing details.
       (format-spec org-deck-title-slide-template (org-html-format-spec info))
       (format "</%s>" (plist-get info :html-container))
       ;; toc page
diff --git a/contrib/lisp/ox-s5.el b/contrib/lisp/ox-s5.el
index b003919..8b28692 100644
--- a/contrib/lisp/ox-s5.el
+++ b/contrib/lisp/ox-s5.el
@@ -174,6 +174,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>"
@@ -329,6 +330,7 @@ holding export options."
       ;; title page
       (format "<%s id='title-slide' class='slide'>"
 	      (plist-get info :html-container))
+      ;; TODO: format-spec isn't great for missing details.
       (format-spec org-s5-title-slide-template (org-html-format-spec info))
       (format "</%s>" (plist-get info :html-container))
       ;; table of contents.
diff --git a/doc/org.texi b/doc/org.texi
index 6b56c4a..64a34e5 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10711,6 +10711,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 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
@@ -13174,7 +13180,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
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 9c262f4..7f53123 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -323,6 +323,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 b7d8425..e9d5b55 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -121,7 +121,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)
@@ -969,9 +970,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)))))
@@ -1014,8 +1021,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
@@ -1027,6 +1038,8 @@ INFO is a plist used as a communication channel."
 	 (concat line "\n"
 		 (unless utf8p "\n")
 		 (upcase formatted-title)
+		 (when 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..7d69d45 100644
--- a/lisp/ox-beamer.el
+++ b/lisp/ox-beamer.el
@@ -233,6 +233,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)
+    (:latex-subtitle-format nil nil "\\subtitle{%s}")
     (: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 +811,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 +883,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)
+       (format (plist-get info :latex-subtitle-format) subtitle))
      ;; 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..6b0f757 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\">
  <!--/*--><![CDATA[/*><!--*/
-  .title  { text-align: center; }
+  .title  { text-align: center;
+             margin-bottom: .2em; }
+  .subtitle { text-align: center;
+              font-size: medium;
+              font-weight: bold;
+              margin-top:0; }
   .todo   { font-family: monospace; color: red; }
   .done   { font-family: monospace; color: green; }
   .priority { font-family: monospace; color: orange; }
@@ -1209,6 +1215,7 @@ The second element of each list is a format string to format the
 postamble itself.  This format string can contain these elements:
 
   %t stands for the title.
+  %s will be replaced by the export subtitle.
   %a stands for the author's name.
   %e stands for the author's email.
   %d stands for the date.
@@ -1273,6 +1280,7 @@ The second element of each list is a format string to format the
 preamble itself.  This format string can contain these elements:
 
   %t stands for the title.
+  %s will be replaced by the export subtitle.
   %a stands for the author's name.
   %e stands for the author's email.
   %d stands for the date.
@@ -1725,6 +1733,10 @@ INFO is a plist used as a communication channel."
   "Return format specification for elements that can be
 used in the preamble or postamble."
   `((?t . ,(org-export-data (plist-get info :title) info))
+    (?s . ,(org-export-data (org-element-parse-secondary-string
+			     (plist-get info :subtitle)
+			     (org-element-restriction 'keyword))
+			    info))
     (?d . ,(org-export-data (org-export-get-date info) info))
     (?T . ,(format-time-string
 	    (plist-get info :html-metadata-timestamp-format)))
@@ -1865,10 +1877,23 @@ holding export options."
      (format "<%s id=\"%s\">\n" (nth 1 div) (nth 2 div)))
    ;; Document title.
    (when (plist-get info :with-title)
-     (let ((title (org-export-data
-		   (or (plist-get info :title) "") info)))
-       (when (org-string-nw-p title)
-	 (format "<h1 class=\"title\">%s</h1>\n" title))))
+     (let ((title (plist-get info :title))
+	   (subtitle (org-element-parse-secondary-string
+		      (plist-get info :subtitle)
+		      (org-element-restriction 'keyword))))
+       (when title
+	 (format
+	  (if (plist-get info :html-html5-fancy)
+	      "<header>\n<h1 class=\"title\">%s</h1>\n%s</header>"
+	    "<h1 class=\"title\">%s%s</h1>\n")
+	  (org-export-data title info)
+	  (if subtitle
+	      (format
+	       (if (plist-get info :html-html5-fancy)
+		   "<p class=\"subtitle\">%s</p>\n"
+		 "\n<br>\n<span class=\"subtitle\">%s</span>\n")
+	       (org-export-data subtitle info))
+	    "")))))
    contents
    (format "</%s>\n" (nth 1 (assq 'content (plist-get info :html-divs))))
    ;; Postamble.
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 9e86863..b7acfcc 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -110,6 +110,7 @@
     (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
     (:latex-header "LATEX_HEADER" nil nil newline)
     (:latex-header-extra "LATEX_HEADER_EXTRA" nil nil newline)
+    (:subtitle "SUBTITLE" nil nil space)
     ;; Other variables.
     (:latex-active-timestamp-format nil nil org-latex-active-timestamp-format)
     (:latex-caption-above nil nil org-latex-caption-above)
@@ -135,6 +136,8 @@
     (:latex-listings-options nil nil org-latex-listings-options)
     (:latex-minted-langs nil nil org-latex-minted-langs)
     (:latex-minted-options nil nil org-latex-minted-options)
+    (:latex-subtitle-format nil nil org-latex-subtitle-format)
+    (:latex-subtitle-separate nil nil org-latex-subtitle-separate)
     (:latex-table-scientific-notation nil nil org-latex-table-scientific-notation)
     (:latex-tables-booktabs nil nil org-latex-tables-booktabs)
     (:latex-tables-centered nil nil org-latex-tables-centered)
@@ -388,6 +391,7 @@ This format string may contain these elements:
 
   %a for AUTHOR keyword
   %t for TITLE keyword
+  %s for SUBTITLE keyword
   %k for KEYWORDS line
   %d for DESCRIPTION line
   %c for CREATOR line
@@ -403,6 +407,14 @@ precedence over this variable."
   :group 'org-export-latex
   :type '(string :tag "Format string"))
 
+(defcustom org-latex-subtitle-format "\\\\\\smallskip\n\\large %s"
+  "Format string used for transcoded subtitle.
+The format string should have at most one \"%s\"-expression,
+which is replaced with the subtitle.")
+
+(defcustom org-latex-subtitle-separate nil
+  "Non-nil means the subtitle is not typeset as part of title.")
+
 (defcustom org-latex-toc-command "\\tableofcontents\n\n"
   "LaTeX command to set the table of contents, list of figures, etc.
 This command only applies to the table of contents generated with
@@ -419,6 +431,7 @@ This format string may contain these elements:
 
   %a for AUTHOR keyword
   %t for TITLE keyword
+  %s for SUBTITLE keyword
   %k for KEYWORDS line
   %d for DESCRIPTION line
   %c for CREATOR line
@@ -1227,9 +1240,14 @@ INFO is a plist used as a communication channel."
 			verbatim))
 	(language (let ((lang (plist-get info :language)))
 		    (or (cdr (assoc lang org-latex-babel-language-alist))
-			lang))))
-    `((?a . ,(org-export-data (plist-get info :author) info))
-      (?t . ,(org-export-data (plist-get info :title)  info))
+			lang ""))))
+    `((?a . ,(or (org-export-data (plist-get info :author) info) ""))
+      (?t . ,(or (org-export-data (plist-get info :title)  info) ""))
+      (?s . ,(or (org-export-data
+		  (org-element-parse-secondary-string
+		   (plist-get info :subtitle)
+		   (org-element-restriction 'keyword))
+		  info) ""))
       (?k . ,(org-export-data (org-latex--wrap-latex-math-block
 			       (org-element-parse-secondary-string
 				(plist-get info :keywords) objects)
@@ -1297,8 +1315,21 @@ holding export options."
      ;; Date.
      (let ((date (and (plist-get info :with-date) (org-export-get-date info))))
        (format "\\date{%s}\n" (org-export-data date info)))
-     ;; Title
-     (format "\\title{%s}\n" title)
+     ;; Title and subtitle.
+     (let* ((subtitle
+	     (org-element-parse-secondary-string
+	      (plist-get info :subtitle)
+	      (org-element-restriction 'keyword)))
+	    (formatted-subtitle
+	     (when subtitle
+	       (format (plist-get info :latex-subtitle-format)
+		       (org-export-data subtitle info))))
+	    (separate (plist-get info :latex-subtitle-separate)))
+       (concat
+	(format "\\title{%s%s}\n" title
+		(if separate "" formatted-subtitle))
+	(when (and separate subtitle) formatted-subtitle)))
+
      ;; Hyperref options.
      (let ((template (plist-get info :latex-hyperref-template)))
        (and (stringp template)
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index 02d3f44..5923d4a 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -96,7 +96,8 @@
 	      (if a (org-odt-export-to-odt t s v)
 		(org-open-file (org-odt-export-to-odt nil s v) 'system))))))
   :options-alist
-  '((:odt-styles-file "ODT_STYLES_FILE" nil nil t)
+  '((:subtitle "SUBTITLE" nil nil space)
+    (:odt-styles-file "ODT_STYLES_FILE" nil nil t)
     ;; Other variables.
     (:odt-content-template-file nil nil org-odt-content-template-file)
     (:odt-display-outline-level nil nil org-odt-display-outline-level)
@@ -1326,6 +1327,11 @@ CONTENTS is the transcoded contents string.  RAW-DATA is the
 original parsed data.  INFO is a plist holding export options."
   ;; Write meta file.
   (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))
 	(author (let ((author (plist-get info :author)))
 		  (if (not author) "" (org-export-data author info))))
 	(email (plist-get info :email))
@@ -1363,6 +1369,10 @@ original parsed data.  INFO is a plist holding export options."
       (format "<meta:keyword>%s</meta:keyword>\n" keywords)
       (format "<dc:subject>%s</dc:subject>\n" description)
       (format "<dc:title>%s</dc:title>\n" title)
+      (when (org-string-nw-p subtitle)
+	(format
+	 "<meta:user-defined meta:name=\"subtitle\">%s</meta:user-defined>"
+	 subtitle))
       "\n"
       "  </office:meta>\n" "</office:document-meta>")
      nil (concat org-odt-zip-dir "meta.xml"))
@@ -1508,6 +1518,12 @@ original parsed data.  INFO is a plist holding export options."
       (insert
        (let* ((title (and (plist-get info :with-title)
 			  (org-export-data (plist-get info :title) info)))
+	      (subtitle (when title
+			  (org-export-data
+			   (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)))))
@@ -1519,10 +1535,20 @@ original parsed data.  INFO is a plist holding export options."
 	  ;; Title.
 	  (when (org-string-nw-p title)
 	    (concat
-	     (format "\n<text:p text:style-name=\"%s\">%s</text:p>"
+	     (format "\n<text:p text:style-name=\"%s\">%s</text:p>\n"
 		     "OrgTitle" (format "\n<text:title>%s</text:title>" title))
 	     ;; Separator.
-	     "\n<text:p text:style-name=\"OrgTitle\"/>"))
+	     "\n<text:p text:style-name=\"OrgTitle\"/>\n"
+	     ;; Subtitle.
+	     (when (org-string-nw-p subtitle)
+	       (concat
+		(format "<text:p text:style-name=\"OrgSubtitle\">\n%s\n</text:p>\n"
+			(concat
+			 "<text:user-defined style:data-style-name=\"N0\" text:name=\"subtitle\">\n"
+			 subtitle
+			 "</text:user-defined>\n"))
+		;; Separator.
+		"<text:p text:style-name=\"OrgSubtitle\"/>"))))
 	  (cond
 	   ((and author (not email))
 	    ;; Author only.
diff --git a/lisp/ox-org.el b/lisp/ox-org.el
index b0eb279..21824ff 100644
--- a/lisp/ox-org.el
+++ b/lisp/ox-org.el
@@ -102,6 +102,7 @@ setting of `org-html-htmlize-output-type' is 'css."
     (underline . org-org-identity)
     (verbatim . org-org-identity)
     (verse-block . org-org-identity))
+  :options-alist '((:subtitle "SUBTITLE" nil nil space))
   :menu-entry
   '(?O "Export to Org"
        ((?O "As Org buffer" org-org-export-as-org)
@@ -139,7 +140,7 @@ CONTENTS is nil.  INFO is ignored."
   (let ((key (org-element-property :key keyword)))
     (unless (member key
 		    '("AUTHOR" "CREATOR" "DATE" "DESCRIPTION" "EMAIL" "KEYWORDS"
-		      "OPTIONS" "TITLE"))
+		      "OPTIONS" "TITLE" "SUBTITLE"))
       (org-element-keyword-interpreter keyword nil))))
 
 (defun org-org-link (link contents info)
@@ -165,7 +166,11 @@ as a communication channel."
 				(org-element-property :value k)))))
 	       "\n"))
    (and (plist-get info :with-title)
-	(format "#+TITLE: %s\n" (org-export-data (plist-get info :title) info)))
+	(let ((title (org-string-nw-p (org-export-data (plist-get info :title) info)))
+	      (subtitle (org-string-nw-p (org-export-data (plist-get info :subtitle) info))))
+	  (concat
+	   (and title (format "#+TITLE: %s\n" title))
+	   (and subtitle (format "#+SUBTITLE: %s\n" subtitle)))))
    (and (plist-get info :with-date)
 	(let ((date (org-export-data (org-export-get-date info) info)))
 	  (and (org-string-nw-p date)
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index bdf0c83..c8ef480 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -572,9 +572,13 @@ holding export options."
        (concat
 	(format "@title %s\n" (or (plist-get info :texinfo-printed-title) title ""))
 	(let ((subtitle (plist-get info :subtitle)))
-	  (and subtitle
-	       (org-element-normalize-string
-		(replace-regexp-in-string "^" "@subtitle " subtitle))))))
+	  (when subtitle
+	    (format "@subtitle %s\n"
+		    (org-export-data
+		     (org-element-parse-secondary-string
+		      subtitle
+		      (org-element-restriction 'keyword))
+		     info))))))
      (when (plist-get info :with-author)
        (concat
 	;; Primary author.
-- 
2.3.4

Re: [ox, patch] #+SUBTITLE

[Andreas Leha]

Hi Rasmus,

Rasmus <rasmus@gmx.us> writes:
> Hi,
>
> I'm starting a new thread as the previous discussion attracted much
> dissuasion not directly related to the patch in question.  Changes:
>
>     - Html subtitles now follow the W3 recommendations, I think/hope.  It
>       would be great if somebody who knows css would check the styling.
>       
>     - The texinfo subtitle is interpreted.
>
>     - Documentation and NEWS is added.
>
> Note: *the patch does not touch ox.el*.  SUBTITLE is *only* supported in a
> tiny fraction of the backends, namely ox-latex, ox-ascii, ox-html, and
> ox-odt.
>
> —Rasmus
>

[... the patch ...]

I have not followed the discussion.  But I like a uniform subtitle
support across relevant backends.  So, my only question is: this patch
does not include ox-beamer, right?  This is where I include my own latex
subtitle most times....

Regards,
Andreas

Re: [ox, patch] #+SUBTITLE

[Rasmus]

Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:

> I have not followed the discussion.  But I like a uniform subtitle
> support across relevant backends.  So, my only question is: this patch
> does not include ox-beamer, right?  This is where I include my own latex
> subtitle most times....

Beamer is derived from ox-latex.  So it's supported.  Quoting the
changelog:

    * ox-beamer.el (org-beamer-template) [...]: Insert SUBTITLE.

—Rasmus

-- 
This space is left intentionally blank

Re: [ox, patch] #+SUBTITLE

[Andreas Leha]

Rasmus <rasmus@gmx.us> writes:
> Andreas Leha <andreas.leha@med.uni-goettingen.de> writes:
>
>> I have not followed the discussion.  But I like a uniform subtitle
>> support across relevant backends.  So, my only question is: this patch
>> does not include ox-beamer, right?  This is where I include my own latex
>> subtitle most times....
>
> Beamer is derived from ox-latex.  So it's supported.  Quoting the
> changelog:
>
>     * ox-beamer.el (org-beamer-template) [...]: Insert SUBTITLE.
>

Thanks!  Will be using this (or another patch providing this) a lot once
it is applied!

- Andreas

Re: [ox, patch] #+SUBTITLE

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> Note: *the patch does not touch ox.el*.  SUBTITLE is *only* supported in a
> tiny fraction of the backends, namely ox-latex, ox-ascii, ox-html, and
> ox-odt.

For some definition of "tiny".

> +      ;; TODO: format-spec isn't great for missing details.

Could you elaborate a bit in the comment?

> +@item SUBTITLE
> +@cindex #+SUBTITLE
> +The document subtitle.  The keyword is supported by by @LaTeX{}-backends,
                                                       ^^^
Typo.

> +HTML backends, ASCII backends, the texinfo backend, and the ODT
> backend.  You

"Texinfo"

> +can use several such keywords for long subtitles.

However this section is not for back-end specific keywords. It should be
moved within their own chapter.

> +		 (when formatted-subtitle
> +		   (concat "\n" formatted-subtitle))

Nitpick:

  (and formatted-subtitle ...)

> +    (:latex-subtitle-format nil nil "\\subtitle{%s}")

If it is meant to be changed it should be coupled to a defcustom.
Otherwise, you can hard-code it in `org-beamer-template'.

> @@ -1209,6 +1215,7 @@ The second element of each list is a format string to format the
>  postamble itself.  This format string can contain these elements:
>  
>    %t stands for the title.
> +  %s will be replaced by the export subtitle.

"stands for", for the sake of consistency.

>    %a stands for the author's name.
>    %e stands for the author's email.
>    %d stands for the date.
> @@ -1273,6 +1280,7 @@ The second element of each list is a format string to format the
>  preamble itself.  This format string can contain these elements:
>  
>    %t stands for the title.
> +  %s will be replaced by the export subtitle.

Ditto.

>      (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
>      (:latex-header "LATEX_HEADER" nil nil newline)
>      (:latex-header-extra "LATEX_HEADER_EXTRA" nil nil newline)
> +    (:subtitle "SUBTITLE" nil nil space)
>      ;; Other variables.
>      (:latex-active-timestamp-format nil nil org-latex-active-timestamp-format)
>      (:latex-caption-above nil nil org-latex-caption-above)
> @@ -135,6 +136,8 @@
>      (:latex-listings-options nil nil org-latex-listings-options)
>      (:latex-minted-langs nil nil org-latex-minted-langs)
>      (:latex-minted-options nil nil org-latex-minted-options)
> +    (:latex-subtitle-format nil nil org-latex-subtitle-format)
> +    (:latex-subtitle-separate nil nil org-latex-subtitle-separate)

They need to be added to Publishing options in manual.

> +(defcustom org-latex-subtitle-format "\\\\\\smallskip\n\\large %s"
> +  "Format string used for transcoded subtitle.
> +The format string should have at most one \"%s\"-expression,
> +which is replaced with the subtitle.")

Missing keywords: :version, :package-version, :type, :group

> +(defcustom org-latex-subtitle-separate nil
> +  "Non-nil means the subtitle is not typeset as part of title.")

Ditto.

> --- a/lisp/ox-org.el
> +++ b/lisp/ox-org.el
> @@ -102,6 +102,7 @@ setting of `org-html-htmlize-output-type' is 'css."
>      (underline . org-org-identity)
>      (verbatim . org-org-identity)
>      (verse-block . org-org-identity))
> +  :options-alist '((:subtitle "SUBTITLE" nil nil space))

I don't see a valid reason to treat #+SUBTITLE specially in `org'
back-end. It will appear anyway as a regular keyword. You can ignore
that part altogether.

Also, assuming you keep :subtitle instead of :BACKEND-subtitle, these
should also be documented in Publishing options.

Thank you.


Regards,

-- 
Nicolas Goaziou

Re: [ox, patch] #+SUBTITLE

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Could you elaborate a bit in the comment?

Consider if title is nil.  With format-spec I'll get an empty <h1></h1>.
As I remember, the W3 checker dislike these.  I have never used these
html5 slides, so I don't really know how to fix it.

>> +can use several such keywords for long subtitles.
>
> However this section is not for back-end specific keywords. It should be
> moved within their own chapter.

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.

>> +		 (when formatted-subtitle
>> +		   (concat "\n" formatted-subtitle))
>
> Nitpick:
>
>   (and formatted-subtitle ...)

Can you explain why (and ⋯) should be used here?

—Rasmus

-- 
Spil noget med Slayer!

Re: [ox, patch] #+SUBTITLE

[Thomas S. Dye]

Rasmus <rasmus@gmx.us> writes:

>>> +		 (when formatted-subtitle
>>> +		   (concat "\n" formatted-subtitle))
>>
>> Nitpick:
>>
>>   (and formatted-subtitle ...)
>
> Can you explain why (and ⋯) should be used here?

Possibly because you don't need the implicit progn?

,---------------------------------------------------
| (when test {form}+) ==  (and test (progn {form}+))
`---------------------------------------------------

hth,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: [ox, patch] #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

>> Could you elaborate a bit in the comment?
>
> Consider if title is nil.  With format-spec I'll get an empty <h1></h1>.
> As I remember, the W3 checker dislike these.  I have never used these
> html5 slides, so I don't really know how to fix it.

You probably should add this to the comments in the file.

> 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?

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.

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).

>> Nitpick:
>>
>>   (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

  (and test
       ... some very long computation)

is less clear than

  (when test
    ... some very long computation)

However, it doesn't apply in this case.

As I warned, this is all about nitpicking anyway.


Regards,

Re: [ox, patch] #+SUBTITLE

[Rasmus]

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

Hi,

I've added a patch that address the code problems, but not the
documentation issues, as the solution is still unclear.

Nicolas Goaziou <mail@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!!!

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Add-SUBTITLE-property-in-some-backends.patch --]
[-- Type: text/x-diff, Size: 22166 bytes --]

From 1c2241e4d39a619b6123cb4e69c60dcec42534ee Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@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"))
+
+
 \f
 ;;; 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\">
  <!--/*--><![CDATA[/*><!--*/
-  .title  { text-align: center; }
+  .title  { text-align: center;
+             margin-bottom: .2em; }
+  .subtitle { text-align: center;
+              font-size: medium;
+              font-weight: bold;
+              margin-top:0; }
   .todo   { font-family: monospace; color: red; }
   .done   { font-family: monospace; color: green; }
   .priority { font-family: monospace; color: orange; }
@@ -1209,6 +1215,7 @@ The second element of each list is a format string to format the
 postamble itself.  This format string can contain these elements:
 
   %t stands for the title.
+  %s stands for the subtitle.
   %a stands for the author's name.
   %e stands for the author's email.
   %d stands for the date.
@@ -1273,6 +1280,7 @@ The second element of each list is a format string to format the
 preamble itself.  This format string can contain these elements:
 
   %t stands for the title.
+  %s stands for the subtitle.
   %a stands for the author's name.
   %e stands for the author's email.
   %d stands for the date.
@@ -1725,6 +1733,10 @@ INFO is a plist used as a communication channel."
   "Return format specification for elements that can be
 used in the preamble or postamble."
   `((?t . ,(org-export-data (plist-get info :title) info))
+    (?s . ,(org-export-data (org-element-parse-secondary-string
+			     (plist-get info :subtitle)
+			     (org-element-restriction 'keyword))
+			    info))
     (?d . ,(org-export-data (org-export-get-date info) info))
     (?T . ,(format-time-string
 	    (plist-get info :html-metadata-timestamp-format)))
@@ -1865,10 +1877,23 @@ holding export options."
      (format "<%s id=\"%s\">\n" (nth 1 div) (nth 2 div)))
    ;; Document title.
    (when (plist-get info :with-title)
-     (let ((title (org-export-data
-		   (or (plist-get info :title) "") info)))
-       (when (org-string-nw-p title)
-	 (format "<h1 class=\"title\">%s</h1>\n" title))))
+     (let ((title (plist-get info :title))
+	   (subtitle (org-element-parse-secondary-string
+		      (plist-get info :subtitle)
+		      (org-element-restriction 'keyword))))
+       (when title
+	 (format
+	  (if (plist-get info :html-html5-fancy)
+	      "<header>\n<h1 class=\"title\">%s</h1>\n%s</header>"
+	    "<h1 class=\"title\">%s%s</h1>\n")
+	  (org-export-data title info)
+	  (if subtitle
+	      (format
+	       (if (plist-get info :html-html5-fancy)
+		   "<p class=\"subtitle\">%s</p>\n"
+		 "\n<br>\n<span class=\"subtitle\">%s</span>\n")
+	       (org-export-data subtitle info))
+	    "")))))
    contents
    (format "</%s>\n" (nth 1 (assq 'content (plist-get info :html-divs))))
    ;; Postamble.
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 51ba042..6b99162 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -108,6 +108,7 @@
     (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
     (:latex-header "LATEX_HEADER" nil nil newline)
     (:latex-header-extra "LATEX_HEADER_EXTRA" nil nil newline)
+    (:subtitle "SUBTITLE" nil nil space)
     ;; Other variables.
     (:latex-active-timestamp-format nil nil org-latex-active-timestamp-format)
     (:latex-caption-above nil nil org-latex-caption-above)
@@ -133,6 +134,8 @@
     (:latex-listings-options nil nil org-latex-listings-options)
     (:latex-minted-langs nil nil org-latex-minted-langs)
     (:latex-minted-options nil nil org-latex-minted-options)
+    (:latex-subtitle-format nil nil org-latex-subtitle-format)
+    (:latex-subtitle-separate nil nil org-latex-subtitle-separate)
     (:latex-table-scientific-notation nil nil org-latex-table-scientific-notation)
     (:latex-tables-booktabs nil nil org-latex-tables-booktabs)
     (:latex-tables-centered nil nil org-latex-tables-centered)
@@ -386,6 +389,7 @@ This format string may contain these elements:
 
   %a for AUTHOR keyword
   %t for TITLE keyword
+  %s for SUBTITLE keyword
   %k for KEYWORDS line
   %d for DESCRIPTION line
   %c for CREATOR line
@@ -401,6 +405,22 @@ precedence over this variable."
   :group 'org-export-latex
   :type '(string :tag "Format string"))
 
+(defcustom org-latex-subtitle-format "\\\\\\smallskip\n\\large %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-latex
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type '(string :tag "Format string"))
+
+(defcustom org-latex-subtitle-separate nil
+  "Non-nil means the subtitle is not typeset as part of title."
+  :group 'org-export-latex
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type 'boolean)
+
 (defcustom org-latex-toc-command "\\tableofcontents\n\n"
   "LaTeX command to set the table of contents, list of figures, etc.
 This command only applies to the table of contents generated with
@@ -417,6 +437,7 @@ This format string may contain these elements:
 
   %a for AUTHOR keyword
   %t for TITLE keyword
+  %s for SUBTITLE keyword
   %k for KEYWORDS line
   %d for DESCRIPTION line
   %c for CREATOR line
@@ -1225,9 +1246,14 @@ INFO is a plist used as a communication channel."
 			verbatim))
 	(language (let ((lang (plist-get info :language)))
 		    (or (cdr (assoc lang org-latex-babel-language-alist))
-			lang))))
-    `((?a . ,(org-export-data (plist-get info :author) info))
-      (?t . ,(org-export-data (plist-get info :title)  info))
+			lang ""))))
+    `((?a . ,(or (org-export-data (plist-get info :author) info) ""))
+      (?t . ,(or (org-export-data (plist-get info :title)  info) ""))
+      (?s . ,(or (org-export-data
+		  (org-element-parse-secondary-string
+		   (plist-get info :subtitle)
+		   (org-element-restriction 'keyword))
+		  info) ""))
       (?k . ,(org-export-data (org-latex--wrap-latex-math-block
 			       (org-element-parse-secondary-string
 				(plist-get info :keywords) objects)
@@ -1295,8 +1321,21 @@ holding export options."
      ;; Date.
      (let ((date (and (plist-get info :with-date) (org-export-get-date info))))
        (format "\\date{%s}\n" (org-export-data date info)))
-     ;; Title
-     (format "\\title{%s}\n" title)
+     ;; Title and subtitle.
+     (let* ((subtitle
+	     (org-element-parse-secondary-string
+	      (plist-get info :subtitle)
+	      (org-element-restriction 'keyword)))
+	    (formatted-subtitle
+	     (when subtitle
+	       (format (plist-get info :latex-subtitle-format)
+		       (org-export-data subtitle info))))
+	    (separate (plist-get info :latex-subtitle-separate)))
+       (concat
+	(format "\\title{%s%s}\n" title
+		(if separate "" formatted-subtitle))
+	(when (and separate subtitle) formatted-subtitle)))
+
      ;; Hyperref options.
      (let ((template (plist-get info :latex-hyperref-template)))
        (and (stringp template)
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index 02d3f44..5923d4a 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -96,7 +96,8 @@
 	      (if a (org-odt-export-to-odt t s v)
 		(org-open-file (org-odt-export-to-odt nil s v) 'system))))))
   :options-alist
-  '((:odt-styles-file "ODT_STYLES_FILE" nil nil t)
+  '((:subtitle "SUBTITLE" nil nil space)
+    (:odt-styles-file "ODT_STYLES_FILE" nil nil t)
     ;; Other variables.
     (:odt-content-template-file nil nil org-odt-content-template-file)
     (:odt-display-outline-level nil nil org-odt-display-outline-level)
@@ -1326,6 +1327,11 @@ CONTENTS is the transcoded contents string.  RAW-DATA is the
 original parsed data.  INFO is a plist holding export options."
   ;; Write meta file.
   (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))
 	(author (let ((author (plist-get info :author)))
 		  (if (not author) "" (org-export-data author info))))
 	(email (plist-get info :email))
@@ -1363,6 +1369,10 @@ original parsed data.  INFO is a plist holding export options."
       (format "<meta:keyword>%s</meta:keyword>\n" keywords)
       (format "<dc:subject>%s</dc:subject>\n" description)
       (format "<dc:title>%s</dc:title>\n" title)
+      (when (org-string-nw-p subtitle)
+	(format
+	 "<meta:user-defined meta:name=\"subtitle\">%s</meta:user-defined>"
+	 subtitle))
       "\n"
       "  </office:meta>\n" "</office:document-meta>")
      nil (concat org-odt-zip-dir "meta.xml"))
@@ -1508,6 +1518,12 @@ original parsed data.  INFO is a plist holding export options."
       (insert
        (let* ((title (and (plist-get info :with-title)
 			  (org-export-data (plist-get info :title) info)))
+	      (subtitle (when title
+			  (org-export-data
+			   (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)))))
@@ -1519,10 +1535,20 @@ original parsed data.  INFO is a plist holding export options."
 	  ;; Title.
 	  (when (org-string-nw-p title)
 	    (concat
-	     (format "\n<text:p text:style-name=\"%s\">%s</text:p>"
+	     (format "\n<text:p text:style-name=\"%s\">%s</text:p>\n"
 		     "OrgTitle" (format "\n<text:title>%s</text:title>" title))
 	     ;; Separator.
-	     "\n<text:p text:style-name=\"OrgTitle\"/>"))
+	     "\n<text:p text:style-name=\"OrgTitle\"/>\n"
+	     ;; Subtitle.
+	     (when (org-string-nw-p subtitle)
+	       (concat
+		(format "<text:p text:style-name=\"OrgSubtitle\">\n%s\n</text:p>\n"
+			(concat
+			 "<text:user-defined style:data-style-name=\"N0\" text:name=\"subtitle\">\n"
+			 subtitle
+			 "</text:user-defined>\n"))
+		;; Separator.
+		"<text:p text:style-name=\"OrgSubtitle\"/>"))))
 	  (cond
 	   ((and author (not email))
 	    ;; Author only.
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index 140e217..e2708c7 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -570,9 +570,13 @@ holding export options."
        (concat
 	(format "@title %s\n" (or (plist-get info :texinfo-printed-title) title ""))
 	(let ((subtitle (plist-get info :subtitle)))
-	  (and subtitle
-	       (org-element-normalize-string
-		(replace-regexp-in-string "^" "@subtitle " subtitle))))))
+	  (when subtitle
+	    (format "@subtitle %s\n"
+		    (org-export-data
+		     (org-element-parse-secondary-string
+		      subtitle
+		      (org-element-restriction 'keyword))
+		     info))))))
      (when (plist-get info :with-author)
        (concat
 	;; Primary author.
-- 
2.3.4

Re: [ox, patch] #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> 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").

I would add that, to be in that category, a keyword needs to be
supported by at least 3 major back-ends (among ASCII, HTML, ODT and
LaTeX).

>>  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.

The rule above is good enough to make a decision in most cases, IMO.

> I think keywords that are well-supported by Org-core should be there.

That doesn't contradict category 1.

> 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.

Do you mean KEYWORD and DESCRIPTION should also belong to category 1?
I'm not against it, but then, back-ends are required to support them
whenever possible.

> 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.

I don't want to create a third category (à la
`org-element-document-properties', which I'm trying to remove).

> We can't support SUBTITLE everywhere, 'cause it simply does not make sense
> (only in "text document producers" IMO).

That doesn't contradict category 1 either, as shown by EMAIL example.

> The support of SUBTITLE is:
>
>     W/Emacs: support is 6/9

That's fine as there is no simple way to support SUBTITLE in the
3 back-ends left. Also, the "big four" support it.

>     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.

We are not maintaining the former and have no control over the latter,
so it doesn't matter.


Regards,

Re: [ox, patch] #+SUBTITLE

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>>> 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").
>
> I would add that, to be in that category, a keyword needs to be
> supported by at least 3 major back-ends (among ASCII, HTML, ODT and
> LaTeX).

That's simple enough and easy to test.

>> 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.
>
> Do you mean KEYWORD and DESCRIPTION should also belong to category 1?
> I'm not against it, but then, back-ends are required to support them
> whenever possible.

At the moment they are.  They lack ascii support, but at least keywords
should be supported in ascii eventually IMO (but that's another thread).

So I would keep them.  The documentation explicitly states which backend
these keywords are supported by.

>> 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.
>
> I don't want to create a third category (à la
> `org-element-document-properties', which I'm trying to remove).

This category would not exists in the code.  It would simply be a
classification that exists in the manual.  I would be a hack to not
maintain "no. of backend that support SOME_KEYWORD" different places to
maintain documentation for SOME_KEYWORD.

Anyway, the above is fine so let's use that.

—Rasmus

-- 
Summon the Mothership!

Re: [ox, patch] #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> Do you mean KEYWORD and DESCRIPTION should also belong to category 1?
>> I'm not against it, but then, back-ends are required to support them
>> whenever possible.
>
> At the moment they are.  They lack ascii support, but at least keywords
> should be supported in ascii eventually IMO (but that's another thread).
>
> So I would keep them.  The documentation explicitly states which backend
> these keywords are supported by.

OK. Then DESCRIPTION and KEYWORD stay in "ox.el", and documented in
"Export settings". You need to revert your patch about it.

We will have to take care about support for missing back-ends. E.g.,
ASCII could treat DESCRIPTION as a quote box just below title.

>>> 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.
>>
>> I don't want to create a third category (à la
>> `org-element-document-properties', which I'm trying to remove).
>
> This category would not exists in the code.  It would simply be a
> classification that exists in the manual.  I would be a hack to not
> maintain "no. of backend that support SOME_KEYWORD" different places to
> maintain documentation for SOME_KEYWORD.

I don't think it is needed. Such "text document properties" are de facto
members of category 1 anyway.

Regards,

Re: [ox, patch] #+SUBTITLE

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> So I would keep them.  The documentation explicitly states which backend
>> these keywords are supported by.
>
> OK. Then DESCRIPTION and KEYWORD stay in "ox.el", and documented in
> "Export settings". You need to revert your patch about it.

I thought we were just discussing criteria for being at a particular spot
in the manual, not in the code.

So should I also move the SUBTITLE to ox.el or keep it in files?  I think
it's OK to just define it in the files where it makes sense...

> We will have to take care about support for missing back-ends. E.g.,
> ASCII could treat DESCRIPTION as a quote box just below title.

Would that not be an abstract?  I'm not sure I think description should be
handled like that.

—Rasmus

-- 
El Rey ha muerto. ¡Larga vida al Rey!

Re: [ox, patch] #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>>> So I would keep them.  The documentation explicitly states which backend
>>> these keywords are supported by.
>>
>> OK. Then DESCRIPTION and KEYWORD stay in "ox.el", and documented in
>> "Export settings". You need to revert your patch about it.
>
> I thought we were just discussing criteria for being at a particular spot
> in the manual, not in the code.

As I explained, both are linked:

  - Anything defined in "ox.el" is documented in "Export settings" ;
  - Anything defined in "ox-backend.el" is documented in "Backend
    export".

This is a hard rule. Even if it means repeating documentation in three
different places, some back-end might use differently the same keyword
than others.

For the record, if the situation ever rises again, I think that
a keyword can be added to "ox.el" only if

  - it is supported at least in every major back-end (ASCII, HTML,
    LaTeX, ODT and Texinfo)
  - it comes with a toggle in the OPTIONS line e.g. keyword:nil

Even when these criteria are met, this move shouldn't be taken lightly
as it implies all back-ends should try hard to support it.

Again, keywords in this category are to be documented in 

  (info "(org)Export settings").

> So should I also move the SUBTITLE to ox.el or keep it in files?  I think
> it's OK to just define it in the files where it makes sense...

SUBTITLE, DESCRIPTION and KEYWORDS can be defined in the libraries where
they are used. Only the documentation needs to be adapted, per above.

Sorry for the confusion.

>> We will have to take care about support for missing back-ends. E.g.,
>> ASCII could treat DESCRIPTION as a quote box just below title.
>
> Would that not be an abstract?  I'm not sure I think description should be
> handled like that.

Forget about it. I'm not sure DESCRIPTION should be handled at all in
ASCII back-end.


Regards,

Re: [ox, patch] #+SUBTITLE

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> As I explained, both are linked:
>
>   - Anything defined in "ox.el" is documented in "Export settings" ;
>   - Anything defined in "ox-backend.el" is documented in "Backend
>     export".
>
> This is a hard rule.

OK.

> Even if it means repeating documentation in three
> different places, some back-end might use differently the same keyword
> than others.
>
> For the record, if the situation ever rises again, I think that
> a keyword can be added to "ox.el" only if
>
>   - it is supported at least in every major back-end (ASCII, HTML,
>     LaTeX, ODT and Texinfo)
>   - it comes with a toggle in the OPTIONS line e.g. keyword:nil

For subtitle I'm reusing :with-title.  If you think it necessary, I can
add a :with-subtitle, but I didn't think it was necessary.

>> So should I also move the SUBTITLE to ox.el or keep it in files?  I think
>> it's OK to just define it in the files where it makes sense...
>
> SUBTITLE, DESCRIPTION and KEYWORDS can be defined in the libraries where
> they are used. Only the documentation needs to be adapted, per above.
>
> Sorry for the confusion.

OK.  So with the above the in mind the game plan seems to be:

     - Remove DESCRIPTION/KEYWORD from it's current position in org.texi
       to backend descriptions and retain them in relevant backends.

       This imply some repetition, but also allows greater details,
       e.g. with latex we can point to the hyperref template.

     - In the subtitle patch documentation should be documented in the
       relevant backend sections.

>>> We will have to take care about support for missing back-ends. E.g.,
>>> ASCII could treat DESCRIPTION as a quote box just below title.
>>
>> Would that not be an abstract?  I'm not sure I think description should be
>> handled like that.
>
> Forget about it. I'm not sure DESCRIPTION should be handled at all in
> ASCII back-end.

OK.  If you want something like the above, I think we should just
recognize abstract blocks and reuse the quote formatting.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Let's erase my suggestion from the internet archives. Pretty please.

You can ask Lars to remove the post from gmane, at least . . . :)

—Rasmus

-- 
Dung makes an excellent fertilizer

Re: [ox, patch] #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

>> For the record, if the situation ever rises again, I think that
>> a keyword can be added to "ox.el" only if
>>
>>   - it is supported at least in every major back-end (ASCII, HTML,
>>     LaTeX, ODT and Texinfo)
>>   - it comes with a toggle in the OPTIONS line e.g. keyword:nil
>
> For subtitle I'm reusing :with-title.  If you think it necessary, I can
> add a :with-subtitle, but I didn't think it was necessary.

It doesn't apply here since SUBTITLE isn't defined in "ox.el". You can
do whatever you think is appropriate for SUBTITLE.

> OK.  So with the above the in mind the game plan seems to be:
>
>      - Remove DESCRIPTION/KEYWORD from it's current position in org.texi
>        to backend descriptions and retain them in relevant backends.

Correct.

>        This imply some repetition, but also allows greater details,
>        e.g. with latex we can point to the hyperref template.

Indeed.

>      - In the subtitle patch documentation should be documented in the
>        relevant backend sections.

Exactly.

Regards,

[org.texi] New keywords tables (was: [ox, patch] #+SUBTITLE)

[Rasmus]

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

Hi,

Following this discussion:

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
> Rasmus <rasmus@gmx.us> writes:

>> OK.  So with the above the in mind the game plan [for documentation]
>> seems to be:
>>
>>      - Remove DESCRIPTION/KEYWORD from it's current position in org.texi
>>        to backend descriptions and retain them in relevant backends.
>
> Correct.
>
>>        This imply some repetition, but also allows greater details,
>>        e.g. with latex we can point to the hyperref template.
>
> Indeed.

An example of a structure change is attached.  It introduces a table
similar to @ref{Export settings} in the beginning of most backend
chapters.

I have not (re)read it yet, but I want to make sure that we roughly agree
on the structure before I put more time into it.  It does not touch
texinfo (yet) 'cause it's complicated.

WDYT?

Also I would kill all backend specific keywords from the table in "@node
In-buffer settings":

    @itemx #+LATEX_HEADER:, #+LATEX_HEADER_EXTRA:,
    @itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
    @itemx #+ODT_STYLES_FILE:,

It does not contain all HTML KW or any Beamer KW.  IOW it's a mess and the
true picture here would be ugly.

WDYT?

—Rasmus

-- 
However beautiful the theory, you should occasionally look at the evidence

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-org.texi-Introduce-tables-for-backend-keywords.patch --]
[-- Type: text/x-diff, Size: 9391 bytes --]

From 406fec4af53607a78d56d278389a8821d9d91f1c Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Tue, 31 Mar 2015 17:37:48 +0200
Subject: [PATCH 2/2] org.texi: Introduce tables for backend keywords

---
 doc/org.texi | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 163 insertions(+), 13 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index ffaa281..1780b33 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -9707,7 +9707,7 @@ The title of the exported document is taken from the special line
 
 @cindex #+TITLE
 @example
-#+TITLE: This is the title of the document
+#+: This is the title of the document
 @end example
 
 @cindex property, EXPORT_TITLE
@@ -11092,21 +11092,49 @@ Beamer back-end is an extension of @LaTeX{} back-end.  As such, all @LaTeX{}
 specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is
 recognized.  See @ref{@LaTeX{} and PDF export} for more information.
 
+Beamer export introduces a number of keywords, similar to the general options
+settings described in @pxref{Export settings}.
+
+@table @samp
+@item BEAMER_THEME
 @cindex #+BEAMER_THEME
-@cindex #+BEAMER_COLOR_THEME
+@vindex org-beamer-theme
+The Beamer theme (@code{org-beamer-theme}).  See chapter 15 in the Beamer
+manual.
+
+@item BEAMER_FONT_THEME
 @cindex #+BEAMER_FONT_THEME
+The Beamer font theme.  See chapter 18 in the Beamer manual.
+
+@item BEAMER_INNER_THEME
 @cindex #+BEAMER_INNER_THEME
+The Beamer inner theme.  See chapter 16 in the Beamer manual.
+
+@item BEAMER_OUTER_THEME
 @cindex #+BEAMER_OUTER_THEME
-Beamer export introduces a number of keywords to insert code in the
-document's header.  Four control appearance of the presentation:
-@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
-@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
-@code{#+BEAMER_OUTER_THEME}.  All of them accept optional arguments within
-square brackets.  The last one, @code{#+BEAMER_HEADER}, is more generic and
-allows you to append any line of code in the header@footnote{Lines are
-appended at the end of the preamble, allowing for any final customization
-such as the inclusion of short titles.}.
+The Beamer outer theme.  See chapter 16 in the Beamer manual.
+
+@c This one is probably not needed
+@item BEAMER_HEADER
+@cindex #+BEAMER_HEADER
+Arbitrary lines appended to the end of the preamble of the document.
+
+@item DESCRIPTION
+@cindex #+DESCRIPTION (Beamer)
+The document description.  By default these are inserted as metadata using
+hyperref.  You can use several such keywords if the list is long.  See also
+@code{org-latex-hyperref-template} and @code{org-latex-title-command}.
 
+@item KEYWORDS
+@cindex #+KEYWORDS (Beamer)
+The keywords defining the contents of the document.  By default these are
+inserted as metadata using hyperref.  You can use several such keywords if
+the list is long.  See also @code{org-latex-hyperref-template} and
+@code{org-latex-title-command}.
+@end table
+
+This example illustrates how to change the theme.  Note that theme options
+can be specified in square brackets.
 @example
 #+BEAMER_THEME: Rochester [height=20pt]
 #+BEAMER_COLOR_THEME: spruce
@@ -11219,6 +11247,7 @@ HTML formatting, in ways similar to John Gruber's @emph{markdown}
 language, but with additional support for tables.
 
 @menu
+* HTML specific syntax::        Special keywords for HTML export.
 * HTML Export commands::        How to invoke HTML export
 * HTML doctypes::               Org can export to various (X)HTML flavors
 * HTML preamble and postamble::  How to insert a preamble and a postamble
@@ -11232,6 +11261,61 @@ language, but with additional support for tables.
 * JavaScript support::          Info and Folding in a web browser
 @end menu
 
+@node HTML specific syntax
+
+HTML export introduces a number of keywords, similar to the general options
+settings described in @pxref{Export settings}.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (HTML)
+The document description.  This description is inserted as a HTML meta tag.
+You can use several such keywords if the list is long.
+
+@item HTML_DOCTYPE
+@cindex #+HTML_DOCTYPE
+The document type (e.g. HTML5) (@code{org-html-doctype}).
+
+@item HTML_CONTAINER
+@cindex #+HTML_CONTAINER
+The contrainer used to wrap element (@code{org-html-container-element}).
+
+@item HTML_LINK_HOME
+@cindex #+HTML_LINK_HOME
+The URL of the home link (@code{org-html-link-home}).
+
+@item HTML_LINK_UP
+@cindex #+HTML_LINK_UP
+The URL of the up link (@code{org-html-link-up}).
+
+@item HTML_MATHJAX
+@cindex #+HTML_MATHJAX
+Options for MathJax (@code{org-html-mathjax-options}).  See also
+@code{org-html-mathjax-template}.
+
+@item HTML_HEAD
+@cindex #+HTML_HEAD
+Arbitrary lines appended to the end of the header of the document
+(@code{org-html-head}).
+
+@item HTML_HEAD_EXTRA
+@cindex #+HTML_HEAD_EXTRA
+Arbitrary lines appended to the end of the header of the document
+(@code{org-html-head-extra}).
+
+@item KEYWORDS
+@cindex #+KEYWORDS (HTML)
+The keywords defining the contents of the document.  This description is
+inserted as a HTML meta tag.  You can use several such keywords if the list
+is long.
+
+@item LATEX_HEADER
+@cindex #+LATEX_HEADER (HTML)
+used when transcoding e.g. math formulas to images.
+@end table
+
+These keywords are treated in details in the following sections.
+
 @node HTML Export commands
 @subsection HTML export commands
 
@@ -11755,12 +11839,54 @@ nested footnotes, footnotes in tables and footnotes in a list item's
 description.
 
 @menu
+* @LaTeX{} specific syntax::    Special keywords for @LaTeX{} export
 * @LaTeX{} export commands::    How to export to LaTeX and PDF
 * Header and sectioning::       Setting up the export file structure
 * Quoting @LaTeX{} code::       Incorporating literal @LaTeX{} code
 * @LaTeX{} specific attributes::  Controlling @LaTeX{} output
 @end menu
 
+@subsection @LaTeX{} specific syntax
+The @LaTeX{} exporter introduces a number of keywords, similar to the general
+options settings described in @pxref{Export settings}.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (@LaTeX)
+The document description.  By default these are inserted as metadata using
+hyperref.  You can use several such keywords if the list is long.  See also
+@code{org-latex-hyperref-template} and @code{org-latex-title-command}.
+
+@item LATEX_CLASS
+@cindex #+LATEX_CLASS
+The predefined preamble to use (@code{org-latex-default-class}).  The
+preamble must be an element in @code{org-latex-classes}.
+
+@item LATEX_CLASS_OPTIONS
+@cindex #+LATEX_CLASS_OPTIONS
+Options given to the @LaTeX{} document class.
+
+@item LATEX_HEADER
+@cindex #+LATEX_HEADER
+Arbitrary lines added to the preamble of the document, before the hyperref
+settings.  See also @code{org-latex-classes}.
+
+@item LATEX_HEADER_EXTRA
+@cindex #+LATEX_HEADER_EXTRA
+Arbitrary lines added to the preamble of the document, before the hyperref
+settings.  See also @code{org-latex-classes}.
+
+@item KEYWORDS
+@cindex #+KEYWORDS (@LaTeX)
+The keywords defining the contents of the document.  By default these are
+inserted as metadata using hyperref.  You can use several such keywords if
+the list is long.  See also @code{org-latex-hyperref-template} and
+@code{org-latex-title-command}.
+@end table
+
+These keywords are treated in details in the following sections.
+
+
 @node @LaTeX{} export commands
 @subsection @LaTeX{} export commands
 
@@ -12187,6 +12313,7 @@ are compatible with LibreOffice 3.4.
 
 @menu
 * Pre-requisites for ODT export::  What packages ODT exporter relies on
+* ODT specific syntax::         Specific keywords for ODT export
 * ODT export commands::         How to invoke ODT export
 * Extending ODT export::        How to produce @samp{doc}, @samp{pdf} files
 * Applying custom styles::      How to apply custom styles to the output
@@ -12199,6 +12326,29 @@ are compatible with LibreOffice 3.4.
 * Advanced topics in ODT export::  Read this if you are a power user
 @end menu
 
+@subsection ODT specific syntax
+The ODT exporter introduces a number of keywords, similar to the general
+options settings described in @pxref{Export settings}.  The keywords are
+treated in details in the following sections.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (ODT)
+The document description.  These are inserted as document metadata.  You can
+use several such keywords if the list is long.
+
+@item KEYWORDS
+@cindex #+KEYWORDS (ODT)
+The keywords defining the contents of the document.  These are inserted as
+document metadata.  You can use several such keywords if the list is long.
+
+@item ODT_STYLES_FILE
+@cindex ODT_STYLES_FILE
+The style file of the document (@code{org-odt-styles-file}).
+@end table
+
+These keywords are treated in details in the following sections.
+
 @node Pre-requisites for ODT export
 @subsection Pre-requisites for ODT export
 @cindex zip
@@ -12425,7 +12575,7 @@ desired image file with no link description.  For example, to embed
 [[file:img.png]]
 @end example
 
-@example
+@exampl
 [[./img.png]]
 @end example
 
@@ -13144,7 +13294,7 @@ including DocBook.}.
 @end table
 
 @node Document preamble
-@subsection Document preamble
+@subsection Texinfo specific syntax
 
 When processing a document, @samp{texinfo} back-end generates a minimal file
 header along with a title page, a copyright page, and a menu.  You control
-- 
2.3.4

Re: [org.texi] New keywords tables

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> An example of a structure change is attached.  It introduces a table
> similar to @ref{Export settings} in the beginning of most backend
> chapters.
>
> I have not (re)read it yet, but I want to make sure that we roughly agree
> on the structure before I put more time into it.  It does not touch
> texinfo (yet) 'cause it's complicated.

What is complicated? I find it quite clear. I'm biased, tho.

> WDYT?

Thanks. It is a good idea.

> Also I would kill all backend specific keywords from the table in "@node
> In-buffer settings":
>
>     @itemx #+LATEX_HEADER:, #+LATEX_HEADER_EXTRA:,
>     @itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
>     @itemx #+ODT_STYLES_FILE:,
>
> It does not contain all HTML KW or any Beamer KW.  IOW it's a mess and the
> true picture here would be ugly.
>
> WDYT?

Agreed.

> +#+TITLE: This is the title of the document
> +#+: This is the title of the document

Typo.

> +Beamer export introduces a number of keywords, similar to the general options
> +settings described in @pxref{Export settings}.
> +
> +@table @samp
> +@item BEAMER_THEME
>  @cindex #+BEAMER_THEME
> -@cindex #+BEAMER_COLOR_THEME
> +@vindex org-beamer-theme
> +The Beamer theme (@code{org-beamer-theme}).  See chapter 15 in the Beamer
> +manual.

I think the user can find references to Beamer's theme in the
appropriate manual by himself.  I suggest to remove the second sentence.

> +@item BEAMER_FONT_THEME
>  @cindex #+BEAMER_FONT_THEME
> +The Beamer font theme.  See chapter 18 in the Beamer manual.

Ditto.

> +@item BEAMER_INNER_THEME
>  @cindex #+BEAMER_INNER_THEME
> +The Beamer inner theme.  See chapter 16 in the Beamer manual.

Ditto.

> +@item BEAMER_OUTER_THEME
>  @cindex #+BEAMER_OUTER_THEME
> -Beamer export introduces a number of keywords to insert code in the
> -document's header.  Four control appearance of the presentation:
> -@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
> -@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
> -@code{#+BEAMER_OUTER_THEME}.  All of them accept optional arguments within
> -square brackets.  The last one, @code{#+BEAMER_HEADER}, is more generic and
> -allows you to append any line of code in the header@footnote{Lines are
> -appended at the end of the preamble, allowing for any final customization
> -such as the inclusion of short titles.}.
> +The Beamer outer theme.  See chapter 16 in the Beamer manual.

Ditto.

> +@c This one is probably not needed

Why this comment?

> +@item BEAMER_HEADER
> +@cindex #+BEAMER_HEADER
> +Arbitrary lines appended to the end of the preamble of the document.
> +
> +@item DESCRIPTION
> +@cindex #+DESCRIPTION (Beamer)
> +The document description.  By default these are inserted as metadata using
> +hyperref.  You can use several such keywords if the list is long.  See also
> +@code{org-latex-hyperref-template} and @code{org-latex-title-command}.

"See also" is a bit terse. Maybe

  By default these are inserted as metadata using @samp{hyperref}
  package@footnote{You can customize @code{org-latex-hyperref-template}
  to control what data is included in the document.} and can be used to
  build complex titles (see @code{org-latex-title-command} for details).
  You can use several such keywords if the description is long.

> +@item KEYWORDS
> +@cindex #+KEYWORDS (Beamer)
> +The keywords defining the contents of the document.  By default these are
> +inserted as metadata using hyperref.  You can use several such keywords if
> +the list is long.  See also @code{org-latex-hyperref-template} and
> +@code{org-latex-title-command}.
> +@end table
> +
> +This example illustrates how to change the theme.  Note that theme options
> +can be specified in square brackets.

Shouldn't the example be moved earlier, when BEAMER_THEME is discussed?

> +@cindex #+HTML_MATHJAX
> +Options for MathJax (@code{org-html-mathjax-options}).  See also
> +@code{org-html-mathjax-template}.

See above.

> +@item LATEX_HEADER
> +@cindex #+LATEX_HEADER (HTML)
> +used when transcoding e.g. math formulas to images.

Capital. This may be expanded a bit, i.e., how is it used?

> -@example
> +@exampl

Typo.

>  [[./img.png]]
>  @end example
>  
> @@ -13144,7 +13294,7 @@ including DocBook.}.
>  @end table
>  
>  @node Document preamble
> -@subsection Document preamble
> +@subsection Texinfo specific syntax

Typo?


Regards,

Re: [org.texi] New keywords tables

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> An example of a structure change is attached.  It introduces a table
>> similar to @ref{Export settings} in the beginning of most backend
>> chapters.
>>
>> I have not (re)read it yet, but I want to make sure that we roughly agree
>> on the structure before I put more time into it.  It does not touch
>> texinfo (yet) 'cause it's complicated.
>
> What is complicated? I find it quite clear. I'm biased, tho.

It's complicated 'cause it already "good quality" in the sense that it
already more structure (≡ using a table-like structure) than other
sections.  Thus, it's not simply a question of going through the backend
definitions, and copying in keywords.


>> Also I would kill all backend specific keywords from the table in "@node
>> In-buffer settings":
>>
>>     @itemx #+LATEX_HEADER:, #+LATEX_HEADER_EXTRA:,
>>     @itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:,
>> #+HTML_LINK_HOME:,
>>     @itemx #+ODT_STYLES_FILE:,
>>
>> It does not contain all HTML KW or any Beamer KW.  IOW it's a mess and the
>> true picture here would be ugly.
>>
>> WDYT?
>
> Agreed.

OK.

>> +#+TITLE: This is the title of the document
>> +#+: This is the title of the document
>
> Typo.

I was trying to suggest that I had not put much effort into this yet,
implying comments would be premature.  Anyway, thanks for the comments!

>> +Beamer export introduces a number of keywords, similar to the general options
>> +settings described in @pxref{Export settings}.
>> +
>> +@table @samp
>> +@item BEAMER_THEME
>>  @cindex #+BEAMER_THEME
>> -@cindex #+BEAMER_COLOR_THEME
>> +@vindex org-beamer-theme
>> +The Beamer theme (@code{org-beamer-theme}).  See chapter 15 in the Beamer
>> +manual.
>
> I think the user can find references to Beamer's theme in the
> appropriate manual by himself.  I suggest to remove the second sentence.

OK.

>> +@c This one is probably not needed
>
> Why this comment?

'Cause it's work in progress.  Anyway, I decided to just include any
keyword defined in the backend.  Thus, it should be included.

>> +@item BEAMER_HEADER
>> +@cindex #+BEAMER_HEADER
>> +Arbitrary lines appended to the end of the preamble of the document.
>> +
>> +@item DESCRIPTION
>> +@cindex #+DESCRIPTION (Beamer)
>> +The document description.  By default these are inserted as metadata using
>> +hyperref.  You can use several such keywords if the list is long.  See also
>> +@code{org-latex-hyperref-template} and @code{org-latex-title-command}.
>
> "See also" is a bit terse. Maybe
>
>   By default these are inserted as metadata using @samp{hyperref}
>   package@footnote{You can customize @code{org-latex-hyperref-template}
>   to control what data is included in the document.} and can be used to
>   build complex titles (see @code{org-latex-title-command} for details).
>   You can use several such keywords if the description is long.

I'm indifferent, but I know these keywords too well.

>> +@item KEYWORDS
>> +@cindex #+KEYWORDS (Beamer)
>> +The keywords defining the contents of the document.  By default these are
>> +inserted as metadata using hyperref.  You can use several such keywords if
>> +the list is long.  See also @code{org-latex-hyperref-template} and
>> +@code{org-latex-title-command}.
>> +@end table
>> +
>> +This example illustrates how to change the theme.  Note that theme options
>> +can be specified in square brackets.
>
> Shouldn't the example be moved earlier, when BEAMER_THEME is discussed?

No 'cause I want a clean view of the keywords.  I don't know what the
point is of that example (it was there before), but I learned about the
interpretation of square brackets...


>> +@item LATEX_HEADER
>> +@cindex #+LATEX_HEADER (HTML)
>> +used when transcoding e.g. math formulas to images.
>
> Capital. This may be expanded a bit, i.e., how is it used?

Good question.

>>  [[./img.png]]
>>  @end example
>>  
>> @@ -13144,7 +13294,7 @@ including DocBook.}.
>>  @end table
>>  
>>  @node Document preamble
>> -@subsection Document preamble
>> +@subsection Texinfo specific syntax
>
> Typo?

No, I would like to have consistent headings for each backend.  But see my
note above on the Texinfo chapter being more structured.

—Rasmus

-- 
And when I’m finished thinking, I have to die a lot

Re: [org.texi] New keywords tables

[Rasmus]

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

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> An example of a structure change is attached.  It introduces a table
>> similar to @ref{Export settings} in the beginning of most backend
>> chapters.
>>
>> I have not (re)read it yet, but I want to make sure that we roughly agree
>> on the structure before I put more time into it.  It does not touch
>> texinfo (yet) 'cause it's complicated.
>
> What is complicated? I find it quite clear. I'm biased, tho.
>
>> WDYT?
>
> Thanks. It is a good idea.

This time I read through the patches.

If there's no disagreements I would like to push the following patches.
After that I will update the doc changes of the SUBTITLE patch and push
that.

—Rasmus

-- 
To err is human. To screw up 10⁶ times per second, you need a computer

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org.texi-Subsections-in-Beamer-export.patch --]
[-- Type: text/x-diff, Size: 2719 bytes --]

From b4bd95c7c0078f8c58fab3e6ed5a6a5ddee66872 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Wed, 1 Apr 2015 13:10:57 +0200
Subject: [PATCH 1/5] org.texi: Subsections in Beamer export

* org.texi (Beamer export): Add menu and change subheading to
subsection.
---
 doc/org.texi | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 780bf6f..222a9d9 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11005,7 +11005,17 @@ The @LaTeX{} class @emph{Beamer} allows production of high quality
 presentations using @LaTeX{} and pdf processing.  Org mode has special
 support for turning an Org mode file or tree into a Beamer presentation.
 
-@subheading Beamer export commands
+@menu
+* Beamer specific export settings:: Export settings for Beamer export.
+* Beamer export commands:: How to export Beamer documents.
+* Sectioning Frames and Blocks in Beamer:: Blocks and sections in Beamer.
+* Beamer specific syntax:: Syntax specific to Beamer.
+* Editing support:: Helper functions for Org Beamer export.
+* A Beamer Example:: An complete Beamer example.
+@end menu
+
+@node Beamer export commands
+@subsection Beamer export commands
 
 @table @kbd
 @orgcmd{C-c C-e l b,org-beamer-export-to-latex}
@@ -11020,7 +11030,8 @@ Export as @LaTeX{} and then process to PDF.
 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
 @end table
 
-@subheading Sectioning, Frames and Blocks
+@node Sectioning Frames and Blocks in Beamer
+@subsection Sectioning, Frames and Blocks in Beamer
 
 Any tree with not-too-deep level nesting should in principle be exportable as
 a Beamer presentation.  Headlines fall into three categories: sectioning
@@ -11111,6 +11122,8 @@ such as the inclusion of short titles.}.
 #+BEAMER_THEME: Rochester [height=20pt]
 #+BEAMER_COLOR_THEME: spruce
 @end example
+@node Beamer specific syntax
+@subsection Beamer specific syntax
 
 Table of contents generated from @code{toc:t} @code{OPTION} keyword are
 wrapped within a @code{frame} environment.  Those generated from a @code{TOC}
@@ -11157,7 +11170,8 @@ the last one inserts optional arguments in current list environment.
 - item 2
 @end example
 
-@subheading Editing support
+@node Editing support
+@subsection Editing support
 
 You can turn on a special minor mode @code{org-beamer-mode} for faster
 editing with:
@@ -11172,7 +11186,8 @@ In @code{org-beamer-mode}, this key offers fast selection of a Beamer
 environment or the @code{BEAMER_COL} property.
 @end table
 
-@subheading An example
+@node A Beamer Example
+@subsection A Beamer example
 
 Here is a simple example Org document that is intended for Beamer export.
 
-- 
2.3.4


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-org.texi-Change-beamer-example-to-example.patch --]
[-- Type: text/x-diff, Size: 972 bytes --]

From 7cbab3d413c9d0950817eac81cd54f4f798a1597 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Wed, 1 Apr 2015 13:12:20 +0200
Subject: [PATCH 2/5] org.texi: Change beamer example to @example

* org.texi (A Beamer Example): Change to @example.
---
 doc/org.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 222a9d9..f8599bb 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11191,7 +11191,7 @@ environment or the @code{BEAMER_COL} property.
 
 Here is a simple example Org document that is intended for Beamer export.
 
-@smallexample
+@example
 #+TITLE: Example Presentation
 #+AUTHOR: Carsten Dominik
 #+OPTIONS: H:2 toc:t num:t
@@ -11223,7 +11223,7 @@ Here is a simple example Org document that is intended for Beamer export.
 ** Frame 2 (where we will not use columns)
 *** Request
     Please test this stuff!
-@end smallexample
+@end example
 
 @node HTML export
 @section HTML export
-- 
2.3.4


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #4: 0003-Manuals-Remove-DESCRIPTION-and-KEYWORDS.patch --]
[-- Type: text/x-diff, Size: 2262 bytes --]

From 8a37299acb5397e6f3e7c2693d7f1d6a312e2c97 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Wed, 1 Apr 2015 13:13:55 +0200
Subject: [PATCH 3/5] Manuals: Remove DESCRIPTION and KEYWORDS

* org.texi (Export settings)
  orgguide.texi (Export options): Remove DESCRIPTION and KEYWORDS.
---
 doc/org.texi      | 15 ---------------
 doc/orgguide.texi |  2 --
 2 files changed, 17 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index f8599bb..905d80b 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10679,26 +10679,11 @@ A date or a time-stamp@footnote{The variable
 @code{org-export-date-timestamp-format} defines how this time-stamp will be
 exported.}.
 
-@item DESCRIPTION
-@cindex #+DESCRIPTION
-The document description.  Back-ends handle it as they see fit (e.g., for the
-XHTML meta tag), if at all.  The keyword is supported by @LaTeX{} back-ends,
-HTML back-ends, ASCII back-ends, the Texinfo back-end, and the ODT back-end.  You
-can use several such keywords for long descriptions.
-
 @item EMAIL
 @cindex #+EMAIL
 @vindex user-mail-address
 The email address (@code{user-mail-address}).
 
-@item KEYWORDS
-@cindex #+KEYWORDS
-The keywords defining the contents of the document.  Back-ends handle it as
-they see fit (e.g., for the XHTML meta tag), if at all.  The keyword is
-supported by @LaTeX{} back-ends, HTML back-ends, ASCII back-ends, the Texinfo
-back-end, and the ODT back-end.  You can use several such keywords if the list
-is long.
-
 @item LANGUAGE
 @cindex #+LANGUAGE
 @vindex org-export-default-language
diff --git a/doc/orgguide.texi b/doc/orgguide.texi
index c3341b0..12d3a51 100644
--- a/doc/orgguide.texi
+++ b/doc/orgguide.texi
@@ -2350,8 +2350,6 @@ Insert template with export options, see example below.
 #+AUTHOR:      the author (default taken from @code{user-full-name})
 #+DATE:        a date, fixed, or an Org timestamp
 #+EMAIL:       his/her email address (default from @code{user-mail-address})
-#+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
-#+KEYWORDS:    the page keywords, e.g.@: for the XHTML meta tag
 #+LANGUAGE:    language, e.g.@: @samp{en} (@code{org-export-default-language})
 #+OPTIONS:     H:2 num:t toc:t \n:nil ::t |:t ^:t f:t tex:t ...
 @end smallexample
-- 
2.3.4


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #5: 0004-org.texi-New-export-keywords-sections.patch --]
[-- Type: text/x-diff, Size: 13866 bytes --]

From 09401fe35008ffa6a2f13fc888ccd9a7fb0fdd5c Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Wed, 1 Apr 2015 13:34:27 +0200
Subject: [PATCH 4/5] org.texi: New export keywords sections

* org.texi (Beamer specific export settings)
  (HTML Specific export settings)
  (@LaTeX{} specific export settings)
  (ODT specific export settings)
  (Texinfo specific export settings): New sections.
  (Beamer specific syntax): Removed some text.
---
 doc/org.texi | 275 +++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 250 insertions(+), 25 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 905d80b..67efe28 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10991,8 +10991,8 @@ presentations using @LaTeX{} and pdf processing.  Org mode has special
 support for turning an Org mode file or tree into a Beamer presentation.
 
 @menu
-* Beamer specific export settings:: Export settings for Beamer export.
 * Beamer export commands:: How to export Beamer documents.
+* Beamer specific export settings:: Export settings for Beamer export.
 * Sectioning Frames and Blocks in Beamer:: Blocks and sections in Beamer.
 * Beamer specific syntax:: Syntax specific to Beamer.
 * Editing support:: Helper functions for Org Beamer export.
@@ -11015,6 +11015,56 @@ Export as @LaTeX{} and then process to PDF.
 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
 @end table
 
+@node Beamer specific export settings
+@subsection Beamer specific export settings
+
+Beamer export introduces a number of keywords, similar to the general options
+settings described in @ref{Export settings}.
+
+@table @samp
+@item BEAMER_THEME
+@cindex #+BEAMER_THEME
+@vindex org-beamer-theme
+The Beamer theme (@code{org-beamer-theme}).  Options can be specified via
+brackets, for example:
+@smallexample
+#+BEAMER_THEME: Rochester [height=20pt]
+@end smallexample
+
+@item BEAMER_FONT_THEME
+@cindex #+BEAMER_FONT_THEME
+The Beamer font theme.
+
+@item BEAMER_INNER_THEME
+@cindex #+BEAMER_INNER_THEME
+The Beamer inner theme.
+
+@item BEAMER_OUTER_THEME
+@cindex #+BEAMER_OUTER_THEME
+The Beamer outer theme.
+
+@item BEAMER_HEADER
+@cindex #+BEAMER_HEADER
+Arbitrary lines inserted into the preamble, just before the @samp{hyperref}
+settings.
+
+@item DESCRIPTION
+@cindex #+DESCRIPTION (Beamer)
+The document description.  By default these are inserted as metadata using
+@samp{hyperref}.  Document metadata can be configured via
+@code{org-latex-hyperref-template}.  Description can also be typeset as part
+of the front matter via @code{org-latex-title-command}.  You can use several
+@code{#+DESCRIPTION} keywords if the description is is long.
+
+@item KEYWORDS
+@cindex #+KEYWORDS (Beamer)
+The keywords defining the contents of the document.  By default these are
+inserted as metadata using @samp{hyperref}.  Document metadata can be
+configured via @code{org-latex-hyperref-template}.  Description can also be
+typeset as part of the front matter via @code{org-latex-title-command}.  You
+can use several @code{#+KEYWORDS} if the description is is long.
+@end table
+
 @node Sectioning Frames and Blocks in Beamer
 @subsection Sectioning, Frames and Blocks in Beamer
 
@@ -11082,34 +11132,13 @@ Although, it can also be explicitly created, with a special @code{columns}
 value for @code{BEAMER_ENV} property (if it needs to be set up with some
 specific options, for example).
 
-@subheading Beamer specific syntax
+@node Beamer specific syntax
+@subsection Beamer specific syntax
 
-Beamer back-end is an extension of @LaTeX{} back-end.  As such, all @LaTeX{}
+The Beamer back-end is an extension of the @LaTeX{} back-end.  As such, all @LaTeX{}
 specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is
 recognized.  See @ref{@LaTeX{} and PDF export} for more information.
 
-@cindex #+BEAMER_THEME
-@cindex #+BEAMER_COLOR_THEME
-@cindex #+BEAMER_FONT_THEME
-@cindex #+BEAMER_INNER_THEME
-@cindex #+BEAMER_OUTER_THEME
-Beamer export introduces a number of keywords to insert code in the
-document's header.  Four control appearance of the presentation:
-@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
-@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
-@code{#+BEAMER_OUTER_THEME}.  All of them accept optional arguments within
-square brackets.  The last one, @code{#+BEAMER_HEADER}, is more generic and
-allows you to append any line of code in the header@footnote{Lines are
-appended at the end of the preamble, allowing for any final customization
-such as the inclusion of short titles.}.
-
-@example
-#+BEAMER_THEME: Rochester [height=20pt]
-#+BEAMER_COLOR_THEME: spruce
-@end example
-@node Beamer specific syntax
-@subsection Beamer specific syntax
-
 Table of contents generated from @code{toc:t} @code{OPTION} keyword are
 wrapped within a @code{frame} environment.  Those generated from a @code{TOC}
 keyword (@pxref{Table of contents}) are not.  In that case, it is also
@@ -11220,6 +11249,7 @@ language, but with additional support for tables.
 
 @menu
 * HTML Export commands::        How to invoke HTML export
+* HTML Specific export settings:: Export settings for HTML export.
 * HTML doctypes::               Org can export to various (X)HTML flavors
 * HTML preamble and postamble::  How to insert a preamble and a postamble
 * Quoting HTML tags::           Using direct HTML in Org mode
@@ -11232,6 +11262,7 @@ language, but with additional support for tables.
 * JavaScript support::          Info and Folding in a web browser
 @end menu
 
+
 @node HTML Export commands
 @subsection HTML export commands
 
@@ -11260,6 +11291,71 @@ Export to a temporary buffer.  Do not create a file.
 @c @noindent
 @c creates two levels of headings and does the rest as items.
 
+@node HTML Specific export settings
+@subsection HTML Specific export settings
+HTML export introduces a number of keywords, similar to the general options
+settings described in @ref{Export settings}.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (HTML)
+The document description.  This description is inserted as a HTML meta tag.
+You can use several such keywords if the list is long.
+
+@item HTML_DOCTYPE
+@cindex #+HTML_DOCTYPE
+@vindex org-html-doctype
+The document type, e.g. HTML5, (@code{org-html-doctype}).
+
+@item HTML_CONTAINER
+@cindex #+HTML_CONTAINER
+@vindex org-html-container-element
+The container, e.g. @samp{div}, used to wrap sections and elements
+(@code{org-html-container-element}).
+
+@item HTML_LINK_HOME
+@cindex #+HTML_LINK_HOME
+@vindex org-html-link-home
+The home link URL (@code{org-html-link-home}).
+
+@item HTML_LINK_UP
+@cindex #+HTML_LINK_UP
+@vindex org-html-link-up
+The up link URL (@code{org-html-link-up}).
+
+@item HTML_MATHJAX
+@cindex #+HTML_MATHJAX
+@vindex org-html-mathjax-options
+Options for the MathJax (@code{org-html-mathjax-options}).  MathJax is used
+to typeset @LaTeX{} math in HTML documents.  @ref{Math formatting in HTML
+export} contains an example.
+
+@item HTML_HEAD
+@cindex #+HTML_HEAD
+@vindex org-html-head
+Arbitrary lines appended to the end of the head of the document
+(@code{org-html-head}).
+
+@item HTML_HEAD_EXTRA
+@cindex #+HTML_HEAD_EXTRA
+@vindex org-html-head-extra
+Arbitrary lines appended to the end of the header of the document
+(@code{org-html-head-extra}).
+
+@item KEYWORDS
+@cindex #+KEYWORDS (HTML)
+The keywords defining the contents of the document.  This description is
+inserted as a HTML meta tag.  You can use several such keywords if the list
+is long.
+
+@item LATEX_HEADER
+@cindex #+LATEX_HEADER (HTML)
+Arbitrary lines appended to the preamble used when transcoding @LaTeX{}
+fragments to images.  See @ref{Math formatting in HTML export} for details.
+@end table
+
+These keywords are treated in details in the following sections.
+
 @node HTML doctypes
 @subsection HTML doctypes
 @vindex org-html-doctype
@@ -11756,6 +11852,7 @@ description.
 
 @menu
 * @LaTeX{} export commands::    How to export to LaTeX and PDF
+* @LaTeX{} specific export settings::  Export settings for @LaTeX{}
 * Header and sectioning::       Setting up the export file structure
 * Quoting @LaTeX{} code::       Incorporating literal @LaTeX{} code
 * @LaTeX{} specific attributes::  Controlling @LaTeX{} output
@@ -11777,6 +11874,57 @@ Export as @LaTeX{} and then process to PDF.
 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
 @end table
 
+@node @LaTeX{} specific export settings
+@subsection @LaTeX{} specific export settings
+The @LaTeX{} exporter introduces a number of keywords, similar to the general
+options settings described in @ref{Export settings}.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (@LaTeX{})
+The document description.  By default these are inserted as metadata using
+@samp{hyperref}.  Document metadata can be configured via
+@code{org-latex-hyperref-template}.  Description can also be typeset as part
+of the front matter via @code{org-latex-title-command}.  You can use several
+@code{#+DESCRIPTION} keywords if the description is is long.
+
+@item LATEX_CLASS
+@cindex #+LATEX_CLASS
+@vindex org-latex-default-class
+@vindex org-latex-classes
+The predefined preamble and headline level mapping to use
+(@code{org-latex-default-class}).  Must be an element in
+@code{org-latex-classes}.
+
+@item LATEX_CLASS_OPTIONS
+@cindex #+LATEX_CLASS_OPTIONS
+Options given to the @LaTeX{} document class.
+
+@item LATEX_HEADER
+@cindex #+LATEX_HEADER
+@vindex org-latex-classes
+Arbitrary lines added to the preamble of the document, before the
+@samp{hyperref} settings.  The location can be controlled via
+@code{org-latex-classes}.
+
+@item LATEX_HEADER_EXTRA
+@cindex #+LATEX_HEADER_EXTRA
+@vindex org-latex-classes
+Arbitrary lines added to the preamble of the document, before the
+@samp{hyperref} settings.  The location can be controlled via
+@code{org-latex-classes}.
+
+@item KEYWORDS
+@cindex #+KEYWORDS (@LaTeX{})
+The keywords defining the contents of the document.  By default these are
+inserted as metadata using @samp{hyperref}.  Document metadata can be
+configured via @code{org-latex-hyperref-template}.  Description can also be
+typeset as part of the front matter via @code{org-latex-title-command}.  You
+can use several @code{#+KEYWORDS} if the description is is long.
+@end table
+
+These keywords are treated in details in the following sections.
+
 @node Header and sectioning
 @subsection Header and sectioning structure
 @cindex @LaTeX{} class
@@ -12188,6 +12336,7 @@ are compatible with LibreOffice 3.4.
 @menu
 * Pre-requisites for ODT export::  What packages ODT exporter relies on
 * ODT export commands::         How to invoke ODT export
+* ODT specific export settings:: Export settings for ODT
 * Extending ODT export::        How to produce @samp{doc}, @samp{pdf} files
 * Applying custom styles::      How to apply custom styles to the output
 * Links in ODT export::         How links will be interpreted and formatted
@@ -12243,6 +12392,29 @@ file instead.  @xref{x-export-to-other-formats, , Automatically exporting to
 other formats}.
 @end table
 
+@node ODT specific export settings
+@subsection ODT specific export settings
+The ODT exporter introduces a number of keywords, similar to the general
+options settings described in @ref{Export settings}.
+
+@table @samp
+@item DESCRIPTION
+@cindex #+DESCRIPTION (ODT)
+The document description.  These are inserted as document metadata.  You can
+use several such keywords if the list is long.
+
+@item KEYWORDS
+@cindex #+KEYWORDS (ODT)
+The keywords defining the contents of the document.  These are inserted as
+document metadata.  You can use several such keywords if the list is long.
+
+@item ODT_STYLES_FILE
+@cindex ODT_STYLES_FILE
+@vindex org-odt-styles-file
+The style file of the document (@code{org-odt-styles-file}).  See
+@ref{Applying custom styles} for details.
+@end table
+
 @node Extending ODT export
 @subsection Extending ODT export
 
@@ -13120,6 +13292,7 @@ an Info file.
 
 @menu
 * Texinfo export commands::     How to invoke Texinfo export
+* Texinfo specific export settings:: Export settings for Texinfo
 * Document preamble::           File header, title and copyright page
 * Headings and sectioning structure:: Building document structure
 * Indices::                     Creating indices
@@ -13143,6 +13316,58 @@ Export to Texinfo and then process to an Info file@footnote{By setting
 including DocBook.}.
 @end table
 
+@node Texinfo specific export settings
+@subsection Texinfo specific export settings
+The Texinfo exporter introduces a number of keywords, similar to the general
+options settings described in @ref{Export settings}.
+
+@table @samp
+
+@item SUBTITLE
+@cindex #+SUBTITLE
+The document subtitle.
+
+@item SUBAUTHOR
+@cindex #+SUBAUTHOR
+The document subauthor.
+
+@item TEXINFO_FILENAME
+@cindex #+TEXINFO_FILENAME
+The Texinfo filename.
+
+@item TEXINFO_CLASS
+@cindex #+TEXINFO_CLASS
+@vindex org-texinfo-default-class
+The class of the document (@code{org-texinfo-default-class}).  This must be a
+member of @code{org-texinfo-classes}.
+
+@item TEXINFO_HEADER
+@cindex #+TEXINFO_HEADER
+Arbitrary lines inserted at the end of the preamble.
+
+@item TEXINFO_POST_HEADER
+@cindex #+TEXINFO_POST_HEADER
+Arbitrary lines inserted at the end of the preamble.
+
+@item TEXINFO_DIR_CATEGORY
+@cindex #+TEXINFO_DIR_CATEGORY
+The directory category of the document.
+
+@item TEXINFO_DIR_TITLE
+@cindex #+TEXINFO_DIR_TITLE
+The directory title of the document.
+
+@item TEXINFO_DIR_DESC
+@cindex #+TEXINFO_DIR_DESC
+The directory description of the document.
+
+@item TEXINFO_PRINTED_TITLE
+@cindex #+TEXINFO_PRINTED_TITLE
+The printed title of the document.
+@end table
+
+These keywords are treated in details in the following sections.
+
 @node Document preamble
 @subsection Document preamble
 
-- 
2.3.4


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #6: 0005-org.texi-Changes-to-In-buffer-settings.patch --]
[-- Type: text/x-diff, Size: 958 bytes --]

From 1cf5123a01903eb6da20a77058b4d136e66bc049 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Wed, 1 Apr 2015 00:27:07 +0200
Subject: [PATCH 5/5] org.texi: Changes to In-buffer settings

* org.texi (In-buffer settings): Remove keywords not defined in ox.el
---
 doc/org.texi | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 67efe28..0342c07 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -17134,10 +17134,6 @@ multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
 
 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
 @itemx #+OPTIONS:, #+BIND:,
-@itemx #+DESCRIPTION:, #+KEYWORDS:,
-@itemx #+LATEX_HEADER:, #+LATEX_HEADER_EXTRA:,
-@itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
-@itemx #+ODT_STYLES_FILE:,
 @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
 These lines provide settings for exporting files.  For more details see
 @ref{Export settings}.
-- 
2.3.4

Re: [org.texi] New keywords tables

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> If there's no disagreements I would like to push the following patches.
> After that I will update the doc changes of the SUBTITLE patch and push
> that.

It looks good. Thank you.

Regards,

Re: [org.texi] New keywords tables

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> It looks good. Thank you.

Pushed.

-- 
Bang bang

Re: [ox, patch] #+SUBTITLE

[Rasmus]

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

Hi,

>>> For the record, if the situation ever rises again, I think that
>>> a keyword can be added to "ox.el" only if
>>>
>>>   - it is supported at least in every major back-end (ASCII, HTML,
>>>     LaTeX, ODT and Texinfo)
>>>   - it comes with a toggle in the OPTIONS line e.g. keyword:nil
>>
>> For subtitle I'm reusing :with-title.  If you think it necessary, I can
>> add a :with-subtitle, but I didn't think it was necessary.
>
> It doesn't apply here since SUBTITLE isn't defined in "ox.el". You can
> do whatever you think is appropriate for SUBTITLE.

I mainly changed documentation.

It would still be good if somebody who knows html and css would comment on
the implemented style in ox-html.

—Rasmus

-- 
I feel emotional landscapes they puzzle me

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Add-SUBTITLE-property-in-some-backends.patch --]
[-- Type: text/x-diff, Size: 26973 bytes --]

From 56af4153a12383de5b69f290d420f8f01b7b5f2a Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@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 (ASCII/Latin-1/UTF-8 export): New section.
  (Beamer specific export settings)
  (HTML Specific export settings)
  (@LaTeX{} specific export settings)
  (ODT specific export settings)
  (ASCII/Latin-1/UTF-8 export): 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            | 45 +++++++++++++++++++++++++++++++++++++++++++--
 etc/ORG-NEWS            | 33 ++++-----------------------------
 lisp/ox-ascii.el        | 22 +++++++++++++++++-----
 lisp/ox-beamer.el       | 20 +++++++++++++++++++-
 lisp/ox-html.el         | 37 +++++++++++++++++++++++++++++++------
 lisp/ox-latex.el        | 49 ++++++++++++++++++++++++++++++++++++++++++++-----
 lisp/ox-odt.el          | 30 ++++++++++++++++++++++++++++--
 lisp/ox-texinfo.el      | 10 +++++++---
 10 files changed, 207 insertions(+), 53 deletions(-)

diff --git a/contrib/lisp/ox-deck.el b/contrib/lisp/ox-deck.el
index 7155863..915373f 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))
 
@@ -261,6 +267,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 2ab1bfe..6401399 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10926,6 +10926,17 @@ When the original file is @file{myfile.txt}, the resulting file becomes
 Export to a temporary buffer.  Do not create a file.
 @end table
 
+@subheading ASCII specific export settings
+
+ASCII export introduces a single of keywords, similar to the general options
+settings described in @ref{Export settings}.
+
+@table @samp
+@item SUBTITLE
+@cindex #+SUBTITLE (ASCII)
+The document subtitle.
+@end table
+
 @subheading Header and sectioning structure
 
 In the exported version, the first three outline levels become headlines,
@@ -11063,6 +11074,14 @@ inserted as metadata using @samp{hyperref}.  Document metadata can be
 configured via @code{org-latex-hyperref-template}.  Description can also be
 typeset as part of the front matter via @code{org-latex-title-command}.  You
 can use several @code{#+KEYWORDS} if the description is is long.
+
+@item SUBTITLE
+@cindex #+SUBTITLE (Beamer)
+@vindex org-beamer-subtitle-format
+The document subtitle.  This is typeset using the format string
+@code{org-beamer-subtitle-format}.  It can also access via
+@code{org-latex-hyperref-template} or typeset as part of the front
+matter via @code{org-latex-title-command}.
 @end table
 
 @node Sectioning Frames and Blocks in Beamer
@@ -11352,6 +11371,11 @@ is long.
 @cindex #+LATEX_HEADER (HTML)
 Arbitrary lines appended to the preamble used when transcoding @LaTeX{}
 fragments to images.  See @ref{Math formatting in HTML export} for details.
+
+@item SUBTITLE
+@cindex #+SUBTILE (HTML)
+The document subtitle.  The formatting depends on whether HTML5 in used
+and on the @samp{subtitle} CSS class.
 @end table
 
 These keywords are treated in details in the following sections.
@@ -11700,6 +11724,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}
@@ -11921,6 +11946,16 @@ inserted as metadata using @samp{hyperref}.  Document metadata can be
 configured via @code{org-latex-hyperref-template}.  Description can also be
 typeset as part of the front matter via @code{org-latex-title-command}.  You
 can use several @code{#+KEYWORDS} if the description is is long.
+
+@item SUBTITLE
+@cindex #+SUBTITLE (@LaTeX{})
+@vindex org-latex-subtitle-separate
+@vindex org-latex-subtitle-format
+The document subtitle.  This is typeset according to
+@code{org-latex-subtitle-format}.  If @code{org-latex-subtitle-separate}
+is non-@code{nil} it is typed as part of the @samp{\title}-macro.  It
+can also access via @code{org-latex-hyperref-template} or typeset as
+part of the front matter via @code{org-latex-title-command}.
 @end table
 
 These keywords are treated in details in the following sections.
@@ -12410,6 +12445,10 @@ document metadata.  You can use several such keywords if the list is long.
 @vindex org-odt-styles-file
 The style file of the document (@code{org-odt-styles-file}).  See
 @ref{Applying custom styles} for details.
+
+@item SUBTITLE
+@cindex SUBTITLE (ODT)
+The document subtitle.
 @end table
 
 @node Extending ODT export
@@ -13321,7 +13360,7 @@ options settings described in @ref{Export settings}.
 @table @samp
 
 @item SUBTITLE
-@cindex #+SUBTITLE
+@cindex #+SUBTITLE (Texinfo)
 The document subtitle.
 
 @item SUBAUTHOR
@@ -13401,7 +13440,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
@@ -14207,6 +14245,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
@@ -14291,6 +14330,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..a531de5 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -327,34 +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.
-** Miscellaneous
-*** Strip all meta data from ITEM special property
-ITEM special property does not contain TODO, priority or tags anymore.
-*** File names in links accept are now compatible with URI syntax
-Absolute file names can now start with =///= in addition to =/=. E.g.,
-=[[file:///home/me/unicorn.jpg]]=.
-*** Footnotes in included files are now local to the file
-As a consequence, it is possible to include multiple Org files with
-footnotes in a master document without being concerned about footnote
-labels colliding.
-*** Mailto links now use regular URI syntax
-This change deprecates old Org syntax for mailto links:
-=mailto:user@domain::Subject=.
-*** =QUOTE= keywords do not exist anymore
-=QUOTE= keywords have been deprecated since Org 8.2.
-*** Select tests to perform with the build system
-The build system has been enhanced to allow test selection with a
-regular expression by defining =BTEST_RE= during the test invocation.
-This is especially useful during bisection to find just when a
-particular test failure was introduced.
-*** Exact heading search for external links ignore spaces and cookies
-Exact heading search for links now ignore spaces and cookies. This is
-the case for links of the form ~file:projects.org::*task title~, as
-well as links of the form ~file:projects.org::some words~
-when ~org-link-search-must-match-exact-headline~ is not nil.
-*** ~org-latex-hyperref-template~, ~org-latex-title-command~ formatting
-New formatting keys are supported.  See the respective docstrings.
-Note, ~org-latex-hyperref-template~ has a new default value.
+*** New ~#+SUBTITLE~ export keyword
+Org can typeset a subtitle in some export backends.  See the manual
+for details.
 * Version 8.2
 
 ** Incompatible changes
@@ -1430,7 +1405,7 @@ See http://orgmode.org/elpa/
    | =C-c C-x E=     | =E=    | [[doc::org-inc-effort][org-inc-effort]]              |
    |                 | =#=    | [[doc::org-toggle-comment][org-toggle-comment]]          |
    |                 | =:=    | [[doc::org-columns][org-columns]]                 |
-   |                 | =W=    | Set =APPT_WARNTIME=         |
+   |                 | =W=    | Set =APPT_WARNTIME=          |
    | =k=             |        | [[doc::org-agenda-capture][org-agenda-capture]]          |
    | C-c ,           | ,      | [[doc::org-priority][org-priority]]                |
 
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"))
+
+
 \f
 ;;; 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 8c6406b..87daa6a 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)
     (:description "DESCRIPTION" nil nil newline)
     (:keywords "KEYWORDS" nil nil space)
@@ -271,7 +272,12 @@ for the JavaScript code in this tag.
 (defconst org-html-style-default
   "<style type=\"text/css\">
  <!--/*--><![CDATA[/*><!--*/
-  .title  { text-align: center; }
+  .title  { text-align: center;
+             margin-bottom: .2em; }
+  .subtitle { text-align: center;
+              font-size: medium;
+              font-weight: bold;
+              margin-top:0; }
   .todo   { font-family: monospace; color: red; }
   .done   { font-family: monospace; color: green; }
   .priority { font-family: monospace; color: orange; }
@@ -1211,6 +1217,7 @@ The second element of each list is a format string to format the
 postamble itself.  This format string can contain these elements:
 
   %t stands for the title.
+  %s stands for the subtitle.
   %a stands for the author's name.
   %e stands for the author's email.
   %d stands for the date.
@@ -1275,6 +1282,7 @@ The second element of each list is a format string to format the
 preamble itself.  This format string can contain these elements:
 
   %t stands for the title.
+  %s stands for the subtitle.
   %a stands for the author's name.
   %e stands for the author's email.
   %d stands for the date.
@@ -1727,6 +1735,10 @@ INFO is a plist used as a communication channel."
   "Return format specification for elements that can be
 used in the preamble or postamble."
   `((?t . ,(org-export-data (plist-get info :title) info))
+    (?s . ,(org-export-data (org-element-parse-secondary-string
+			     (plist-get info :subtitle)
+			     (org-element-restriction 'keyword))
+			    info))
     (?d . ,(org-export-data (org-export-get-date info) info))
     (?T . ,(format-time-string
 	    (plist-get info :html-metadata-timestamp-format)))
@@ -1867,10 +1879,23 @@ holding export options."
      (format "<%s id=\"%s\">\n" (nth 1 div) (nth 2 div)))
    ;; Document title.
    (when (plist-get info :with-title)
-     (let ((title (org-export-data
-		   (or (plist-get info :title) "") info)))
-       (when (org-string-nw-p title)
-	 (format "<h1 class=\"title\">%s</h1>\n" title))))
+     (let ((title (plist-get info :title))
+	   (subtitle (org-element-parse-secondary-string
+		      (plist-get info :subtitle)
+		      (org-element-restriction 'keyword))))
+       (when title
+	 (format
+	  (if (plist-get info :html-html5-fancy)
+	      "<header>\n<h1 class=\"title\">%s</h1>\n%s</header>"
+	    "<h1 class=\"title\">%s%s</h1>\n")
+	  (org-export-data title info)
+	  (if subtitle
+	      (format
+	       (if (plist-get info :html-html5-fancy)
+		   "<p class=\"subtitle\">%s</p>\n"
+		 "\n<br>\n<span class=\"subtitle\">%s</span>\n")
+	       (org-export-data subtitle info))
+	    "")))))
    contents
    (format "</%s>\n" (nth 1 (assq 'content (plist-get info :html-divs))))
    ;; Postamble.
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index cfd1fdf..893496e 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -110,6 +110,7 @@
     (:latex-header-extra "LATEX_HEADER_EXTRA" nil nil newline)
     (:description "DESCRIPTION" nil nil newline)
     (:keywords "KEYWORDS" nil nil space)
+    (:subtitle "SUBTITLE" nil nil space)
     ;; Other variables.
     (:latex-active-timestamp-format nil nil org-latex-active-timestamp-format)
     (:latex-caption-above nil nil org-latex-caption-above)
@@ -135,6 +136,8 @@
     (:latex-listings-options nil nil org-latex-listings-options)
     (:latex-minted-langs nil nil org-latex-minted-langs)
     (:latex-minted-options nil nil org-latex-minted-options)
+    (:latex-subtitle-format nil nil org-latex-subtitle-format)
+    (:latex-subtitle-separate nil nil org-latex-subtitle-separate)
     (:latex-table-scientific-notation nil nil org-latex-table-scientific-notation)
     (:latex-tables-booktabs nil nil org-latex-tables-booktabs)
     (:latex-tables-centered nil nil org-latex-tables-centered)
@@ -388,6 +391,7 @@ This format string may contain these elements:
 
   %a for AUTHOR keyword
   %t for TITLE keyword
+  %s for SUBTITLE keyword
   %k for KEYWORDS line
   %d for DESCRIPTION line
   %c for CREATOR line
@@ -403,6 +407,22 @@ precedence over this variable."
   :group 'org-export-latex
   :type '(string :tag "Format string"))
 
+(defcustom org-latex-subtitle-format "\\\\\\medskip\n\\large %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-latex
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type '(string :tag "Format string"))
+
+(defcustom org-latex-subtitle-separate nil
+  "Non-nil means the subtitle is not typeset as part of title."
+  :group 'org-export-latex
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type 'boolean)
+
 (defcustom org-latex-toc-command "\\tableofcontents\n\n"
   "LaTeX command to set the table of contents, list of figures, etc.
 This command only applies to the table of contents generated with
@@ -419,6 +439,7 @@ This format string may contain these elements:
 
   %a for AUTHOR keyword
   %t for TITLE keyword
+  %s for SUBTITLE keyword
   %k for KEYWORDS line
   %d for DESCRIPTION line
   %c for CREATOR line
@@ -1227,9 +1248,14 @@ INFO is a plist used as a communication channel."
 			verbatim))
 	(language (let ((lang (plist-get info :language)))
 		    (or (cdr (assoc lang org-latex-babel-language-alist))
-			lang))))
-    `((?a . ,(org-export-data (plist-get info :author) info))
-      (?t . ,(org-export-data (plist-get info :title)  info))
+			lang ""))))
+    `((?a . ,(or (org-export-data (plist-get info :author) info) ""))
+      (?t . ,(or (org-export-data (plist-get info :title)  info) ""))
+      (?s . ,(or (org-export-data
+		  (org-element-parse-secondary-string
+		   (plist-get info :subtitle)
+		   (org-element-restriction 'keyword))
+		  info) ""))
       (?k . ,(org-export-data (org-latex--wrap-latex-math-block
 			       (org-element-parse-secondary-string
 				(plist-get info :keywords) objects)
@@ -1297,8 +1323,21 @@ holding export options."
      ;; Date.
      (let ((date (and (plist-get info :with-date) (org-export-get-date info))))
        (format "\\date{%s}\n" (org-export-data date info)))
-     ;; Title
-     (format "\\title{%s}\n" title)
+     ;; Title and subtitle.
+     (let* ((subtitle
+	     (org-element-parse-secondary-string
+	      (plist-get info :subtitle)
+	      (org-element-restriction 'keyword)))
+	    (formatted-subtitle
+	     (when subtitle
+	       (format (plist-get info :latex-subtitle-format)
+		       (org-export-data subtitle info))))
+	    (separate (plist-get info :latex-subtitle-separate)))
+       (concat
+	(format "\\title{%s%s}\n" title
+		(if separate "" formatted-subtitle))
+	(when (and separate subtitle)
+	  (concat formatted-subtitle "\n"))))
      ;; Hyperref options.
      (let ((template (plist-get info :latex-hyperref-template)))
        (and (stringp template)
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index d52a3ae..427a3c5 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -99,6 +99,7 @@
   '((:odt-styles-file "ODT_STYLES_FILE" nil nil t)
     (:description "DESCRIPTION" nil nil newline)
     (:keywords "KEYWORDS" nil nil space)
+    (:subtitle "SUBTITLE" nil nil space)
     ;; Other variables.
     (:odt-content-template-file nil nil org-odt-content-template-file)
     (:odt-display-outline-level nil nil org-odt-display-outline-level)
@@ -1328,6 +1329,11 @@ CONTENTS is the transcoded contents string.  RAW-DATA is the
 original parsed data.  INFO is a plist holding export options."
   ;; Write meta file.
   (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))
 	(author (let ((author (plist-get info :author)))
 		  (if (not author) "" (org-export-data author info))))
 	(email (plist-get info :email))
@@ -1365,6 +1371,10 @@ original parsed data.  INFO is a plist holding export options."
       (format "<meta:keyword>%s</meta:keyword>\n" keywords)
       (format "<dc:subject>%s</dc:subject>\n" description)
       (format "<dc:title>%s</dc:title>\n" title)
+      (when (org-string-nw-p subtitle)
+	(format
+	 "<meta:user-defined meta:name=\"subtitle\">%s</meta:user-defined>\n"
+	 subtitle))
       "\n"
       "  </office:meta>\n" "</office:document-meta>")
      nil (concat org-odt-zip-dir "meta.xml"))
@@ -1510,6 +1520,12 @@ original parsed data.  INFO is a plist holding export options."
       (insert
        (let* ((title (and (plist-get info :with-title)
 			  (org-export-data (plist-get info :title) info)))
+	      (subtitle (when title
+			  (org-export-data
+			   (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)))))
@@ -1521,10 +1537,20 @@ original parsed data.  INFO is a plist holding export options."
 	  ;; Title.
 	  (when (org-string-nw-p title)
 	    (concat
-	     (format "\n<text:p text:style-name=\"%s\">%s</text:p>"
+	     (format "\n<text:p text:style-name=\"%s\">%s</text:p>\n"
 		     "OrgTitle" (format "\n<text:title>%s</text:title>" title))
 	     ;; Separator.
-	     "\n<text:p text:style-name=\"OrgTitle\"/>"))
+	     "\n<text:p text:style-name=\"OrgTitle\"/>\n"
+	     ;; Subtitle.
+	     (when (org-string-nw-p subtitle)
+	       (concat
+		(format "<text:p text:style-name=\"OrgSubtitle\">\n%s\n</text:p>\n"
+			(concat
+			 "<text:user-defined style:data-style-name=\"N0\" text:name=\"subtitle\">\n"
+			 subtitle
+			 "</text:user-defined>\n"))
+		;; Separator.
+		"<text:p text:style-name=\"OrgSubtitle\"/>\n"))))
 	  (cond
 	   ((and author (not email))
 	    ;; Author only.
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index 140e217..e2708c7 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -570,9 +570,13 @@ holding export options."
        (concat
 	(format "@title %s\n" (or (plist-get info :texinfo-printed-title) title ""))
 	(let ((subtitle (plist-get info :subtitle)))
-	  (and subtitle
-	       (org-element-normalize-string
-		(replace-regexp-in-string "^" "@subtitle " subtitle))))))
+	  (when subtitle
+	    (format "@subtitle %s\n"
+		    (org-export-data
+		     (org-element-parse-secondary-string
+		      subtitle
+		      (org-element-restriction 'keyword))
+		     info))))))
      (when (plist-get info :with-author)
        (concat
 	;; Primary author.
-- 
2.3.4

Re: [ox, patch] #+SUBTITLE

[Rasmus]

Pushed in a780080fcf38ca6412658323eae9367a17a12bdf.
—Rasmus

-- 
Send from my Emacs

Re: [ox, patch] #+SUBTITLE

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Also, assuming you keep :subtitle instead of :BACKEND-subtitle, these
> should also be documented in Publishing options.

So I *still* don't see this.  I assume you want me to add something do you
want me to add lines like this:

     @item @code{:subtitle}   @tab ""

To the tables akin to the one in @subsubheading Beamer specific
properties?

Note that there's no mapping to a variable, only to an buffer-keyword.

Thanks,
Rasmus

-- 
Hooray!

Re: [ox, patch] #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Also, assuming you keep :subtitle instead of :BACKEND-subtitle, these
>> should also be documented in Publishing options.
>
> So I *still* don't see this.  I assume you want me to add something do you
> want me to add lines like this:
>
>      @item @code{:subtitle}   @tab ""
>
> To the tables akin to the one in @subsubheading Beamer specific
> properties?
>
> Note that there's no mapping to a variable, only to an buffer-keyword.

You're right, there's nothing to do.

Let's erase my suggestion from the internet archives. Pretty please.


Regards,