[ox, patch] Add #+SUBTITLE

[ox, patch] Add #+SUBTITLE

[Rasmus]

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

Hi,

This patch adds #+SUBTITLE to a couple of backends.  This property is
already supported in ox-texinfo and e.g. beamer.cls has a subtitles macro,
but ox-beamer.el has no #+SUBTITLE.  I have used subtitles in
e.g. applications for research funds.

The value-added is twofold:

    - It adds a consistent way to have subtitle across backends.  I'm
      explicitly assuming this is nice, but perhaps this is false.
    - Currently, it is, I believe, impossible to hack-up a subtitle in at
      least ox-odt.el.

It's not documented yet as I want make sure that it's not an undesirable
feature before progressing further.

WDTY?

—Rasmus 

-- 
The right to be left alone is a human right

[-- 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: 17980 bytes --]

From 4b9ce6f4d260360847bf63f3bab9f98004bc7469 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 style for SUBTITLE.
---
 contrib/lisp/ox-deck.el |  2 ++
 contrib/lisp/ox-s5.el   |  2 ++
 lisp/ox-ascii.el        | 23 ++++++++++++++++++-----
 lisp/ox-beamer.el       | 10 +++++++++-
 lisp/ox-html.el         | 26 ++++++++++++++++++++------
 lisp/ox-latex.el        | 35 +++++++++++++++++++++++++++++++++--
 lisp/ox-odt.el          | 32 +++++++++++++++++++++++++++++---
 lisp/ox-org.el          |  9 +++++++--
 8 files changed, 120 insertions(+), 19 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/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 5711b53..4f6ecbe 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
+		       (or (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 (if utf8p "\n\n\n" "\n\n") author "\n" email))
diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el
index 7c42c74..193ed96 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)
@@ -798,7 +799,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
+		    (or (plist-get info :subtitle) "")
+		    (org-element-restriction 'keyword))
+		   info)))
     (concat
      ;; 1. Time-stamp.
      (and (plist-get info :time-stamp-file)
@@ -865,6 +871,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 92fe3d9..2e4692c 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)
@@ -271,7 +272,7 @@ for the JavaScript code in this tag.
 (defconst org-html-style-default
   "<style type=\"text/css\">
  <!--/*--><![CDATA[/*><!--*/
-  .title  { text-align: center; }
+  .title, .subtitle  { text-align: center; }
   .todo   { font-family: monospace; color: red; }
   .done   { font-family: monospace; color: green; }
   .priority { font-family: monospace; color: orange; }
@@ -1210,6 +1211,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.
@@ -1274,6 +1276,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.
@@ -1726,6 +1729,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
+			     (or (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)))
@@ -1866,10 +1873,17 @@ 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
+		      (or (plist-get info :subtitle) "")
+		      (org-element-restriction 'keyword))))
+       (when title
+	 (concat
+	  (format "<h1 class=\"title\">%s</h1>\n"
+		  (org-export-data title info))
+	  (when subtitle
+	    (format "<h2 class=\"subtitle\">%s</h2>\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 44435f4..e755e3d 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
@@ -1230,6 +1243,11 @@ INFO is a plist used as a communication channel."
 			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
+		   (or (plist-get info :subtitle) "")
+		   (org-element-restriction 'keyword))
+		  info) ""))
       (?k . ,(org-export-data (org-latex--wrap-latex-math-block
 			       (org-element-parse-secondary-string
 				(or (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
+	      (or (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 e32ca26..abc2358 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
+		    (or (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>"
+	 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
+			    (or (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\"/>"))))
 	  (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)
-- 
2.3.3

Re: [ox, patch] Add #+SUBTITLE

[Marcin Borkowski]

On 2015-03-21, at 00:23, Rasmus <rasmus@gmx.us> wrote:

> This patch adds #+SUBTITLE to a couple of backends.  This property is
>
> WDTY?

+1

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: [ox, patch] Add #+SUBTITLE

[Melanie Bacou]

Very nice, thanks!

On 3/20/2015 10:26 PM, Marcin Borkowski wrote:
>
> On 2015-03-21, at 00:23, Rasmus <rasmus@gmx.us> wrote:
>
>> This patch adds #+SUBTITLE to a couple of backends.  This property is
>>
>> WDTY?
>
> +1
>
> Best,
>

-- 
Melanie BACOU
International Food Policy Research Institute
Snr. Program Manager, HarvestChoice
E-mail m.bacou@cgiar.org
Visit www.harvestchoice.org

Re: [ox, patch] Add #+SUBTITLE

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> This patch adds #+SUBTITLE to a couple of backends.  This property is
> already supported in ox-texinfo and e.g. beamer.cls has a subtitles macro,
> but ox-beamer.el has no #+SUBTITLE.  I have used subtitles in
> e.g. applications for research funds.
>
> The value-added is twofold:
>
>     - It adds a consistent way to have subtitle across backends.  I'm
>       explicitly assuming this is nice, but perhaps this is false.
>     - Currently, it is, I believe, impossible to hack-up a subtitle in at
>       least ox-odt.el.
>
> It's not documented yet as I want make sure that it's not an undesirable
> feature before progressing further.
>
> WDTY?

Adding #+SUBTITLE to Beamer is a fine idea, since there's already
a dedicated macro for it. Thank you for taking care of it.

However, I think porting this feature to back-ends that do not support
it out of the box is pushing too hard. 

Back-ends developers should try hard to support features defined in
"ox.el" (in particular in `org-export-options-alist'). However, all
back-ends are free to implement their specific keywords without adding
burden on other libraries. "ox-texinfo" supports #+SUBAUTHOR, should we
add it everywhere? I don't think so.

This is why I suggested to move KEYWORD and DESCRIPTION outside of
"ox.el", as they cannot be ported to all back-ends without relying on
dubious markup.

Now, if SUBTITLE is a feature desperately needed everywhere, which can
be discussed, it should be moved to "ox.el" and probably
`org-element-document-keywords'. IMO, this is not necessary. SUBTITLE
should be kept for back-ends that can handle it.

As a side note, "ox-texinfo" doesn't parse SUBTITLE. You might want to
change it and update manual accordingly.

Regards,

-- 
Nicolas Goaziou

Re: [ox, patch] Add #+SUBTITLE

[Eric Abrahamsen]

Rasmus <rasmus@gmx.us> writes:

> Hi,
>
> This patch adds #+SUBTITLE to a couple of backends.  This property is
> already supported in ox-texinfo and e.g. beamer.cls has a subtitles macro,
> but ox-beamer.el has no #+SUBTITLE.  I have used subtitles in
> e.g. applications for research funds.
>
> The value-added is twofold:
>
>     - It adds a consistent way to have subtitle across backends.  I'm
>       explicitly assuming this is nice, but perhaps this is false.
>     - Currently, it is, I believe, impossible to hack-up a subtitle in at
>       least ox-odt.el.
>
> It's not documented yet as I want make sure that it's not an undesirable
> feature before progressing further.
>
> WDTY?

In ox-html, You might consider wrapping the title and subtitle in an
<hgroup> if :html5-fancy is t. Or maybe that's going too far! Either
way, I like this.

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Hi Nicolas,

I'm a bit confused by your message.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> However, I think porting this feature to back-ends that do not support
> it out of the box is pushing too hard. 

In the patch there's ox-latex where e.g. KOMA-Script has as
subtitle-macro.  ox-html, ox-ascii, ox-odt all are pretty liberate formats
in terms of what elements are supported.

> Back-ends developers should try hard to support features defined in
> "ox.el" (in particular in `org-export-options-alist'). However, all
> back-ends are free to implement their specific keywords without adding
> burden on other libraries. "ox-texinfo" supports #+SUBAUTHOR, should we
> add it everywhere? I don't think so.

OK.  ox and org-element shouldn't be touched by the patch.

> This is why I suggested to move KEYWORD and DESCRIPTION outside of
> "ox.el", as they cannot be ported to all back-ends without relying on
> dubious markup.

Yeah, I still have a patch for that...  I still have to do the
documentation changes.

> Now, if SUBTITLE is a feature desperately needed everywhere, which can
> be discussed, it should be moved to "ox.el" and probably
> `org-element-document-keywords'. IMO, this is not necessary. SUBTITLE
> should be kept for back-ends that can handle it.

IMO it is.  The only place where there's a "hack" is in ox-latex and
that's cause article is the default class.  If you prefer, it can just
output to the \subtitle{·} by default and say it's KOMA-script only.  That
seems harsh, though.

> As a side note, "ox-texinfo" doesn't parse SUBTITLE. You might want to
> change it and update manual accordingly.

The patch doesn't touch ox-texinfo.  I don't mind fixing that bug, though.

—Rasmus

-- 
Hvor meget poesi tror De kommer ud af et glas isvand?

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Rasmus <rasmus@gmx.us> writes:
>
> In ox-html, You might consider wrapping the title and subtitle in an
> <hgroup> if :html5-fancy is t. Or maybe that's going too far! Either
> way, I like this.

First result on my search engine says¹ :

    Update 16th April, 2013. hgroup has now been removed from the HTML5
    specification. We are working on an article to help guide authors on
    which markup patterns they should use instead.

    Update 4th April, 2013. Please note that following this decision,
    hgroup will be removed from the HTML5 specification. As such, we don’t
    endorse using it on production sites.

I don't know anything about html, though.  Is there another element you
had in mind?  Or is the html5doctor just wrong?

Thanks,
Rasmus


Footnotes: 
¹   http://html5doctor.com/the-hgroup-element/

-- 
Hvor meget poesi tror De kommer ud af et glas isvand?

Re: [ox, patch] Add #+SUBTITLE

[Marcin Borkowski]

On 2015-03-22, at 16:29, Rasmus <rasmus@gmx.us> wrote:

> IMO it is.  The only place where there's a "hack" is in ox-latex and
> that's cause article is the default class.  If you prefer, it can just
> output to the \subtitle{·} by default and say it's KOMA-script only.  That
> seems harsh, though.

Hi there,

being like a Pavlov's dog trained to dribble on seeing the word
LaTeX;-), let me add my 2 cents here.

[TL;DR: imho, the right way to do LaTeX export is to prepare a dedicated
package for Org-mode generated files (easy/medium), arrange for it to be
included in all major TeX distros (easy) and simplify the LaTeX exporter
to comply with it (easy).  This could greatly enhance the quality of
PDFs produced by Org-mode and make modifying their look easier on the
Org side.  I could do the LaTeX side of the work.  Now the question is:
does the community /want/ it.]

The (default) LaTeX markup sucks.  (It’s not about Org-mode-produced
LaTeX files, it’s about LaTeX itself.)  And I'm telling that as
a long-time TeX and LaTeX user and fan.  I would strongly suggest not
caring too much about “what does LaTeX support out-of-the-box” – in
fact, it supports almost nothing without a heap of packages.

What I really think Org-mode community should do is the following.

We (if I may use that pronoun here) should prepare a dedicated Org LaTeX
package, properly supporting all Org’s fancy stuff like tags,
timestamps, todo keywords etc., and allowing for parametrizing their
look-and-feel through a reasonable LaTeX interface.  I think it should
/not/ be a class, since then people would be free to use it with
article/amsart/koma-script/memoir/whatever.  This is not very difficult
nor time-consuming, and in fact I might be tempted to do it (more on
that below).  This would require (simple) changes in the LaTeX exporter
(generally, simplifying it); this I cannot do, since I don’t have the
FSF papers signed (and I don’t want to sign them).  OTOH, the package
does not have this problem, since LaTeX licensing is much more sane than
Emacs’; this package should be imho part of every TeX distro (which is
important, and in fact easy to arrange), so that we could send an
Org-generated LaTeX file to any TeX user.

The biggest advantage would be the possibility of exporting e.g. TODO
lists or agendas to LaTeX, and have them formatted as TODO lists and
agendas and not as “articles”.  Currently, LaTeX export is more or less
limited to scientific articles (unless you want to tweak it /a lot/ so
that it looks even remotely reasonable), where you don’t really care
about layout and design, since they are going to be changed by the
journal anyway.

Just think about the possibilities.  We could make a TODO list in Org,
and send it (as a pdf file) for non-Org-users to print, and it could
look like a TODO-list.  (I guess there are still lots of people who
depend on paper todo lists; I do, for sure, though I make them
manually.)  We could have an option (on Org side, which would translate
to a LaTeX one) to have more Word-like layout.  (You can say what you
want about Word – my personal opinion is that it is unsuitable for
documents larger/more complex than a piece of paper with an arrow
showing the direction to the restroom – but sometimes, especially for
short memos/notes, LaTeX’s extremely generic spacing can be annoying.
Of course, you could just load the savetrees package – but let me make
a short, informal and unscientific survey here: how many of you would
find it useful, but never thought that something like that exists?  If,
OTOH, there would be such option for the LaTeX exporter, it would be
right there, in Org-mode manual.  In fact, since not everyone might
follow this thread, let me start another one, with this very question in
a minute;-).)

The added benefit would be much cleaner structure of Org-generated LaTeX
files.  Currently, they have a huge preamble and a few hard-wired
things.

Summing up: as we know, there are many ways people use Org-mode, but the
current PDF exporter (through LaTeX’s article class, heavily biased
toward scientific material) is suboptimal for all but one of these ways.

As I said, if there is some consensus on whether something like that is
needed, I can start working on it.  (In fact, it might be a fun
side-project.)  I would estimate that I’d need a week or two to come up
with a proof-of-concept, sort-of-working thing, and something like two
months with a first production version.  (Though I don’t have time for
a project like this now, realistically I could start in August.)  (Let
me thank here for Org-mode clocking feature – the above estimate is due
to the fact that I did some work on coding a dedicated, quite complex
LaTeX class for a journal, and I know that it has taken me about 32
hours as of now.  Assuming an average pace of 2-4 hours a week, and
assuming about 16 hours for a first version of this one – it would be
a much simpler project – gives 1-2 months or so.  NB. Fun fact: the work
on the class for the journal I’m talking about includes coding some
Emacs Lisp to extract metadata from LaTeX (and aux) files and generate
XML files for uploading pdfs to the journal site.)

WDYT?

> —Rasmus

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: [ox, patch] Add #+SUBTITLE

[Thomas S. Dye]

Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:

> On 2015-03-22, at 16:29, Rasmus <rasmus@gmx.us> wrote:
>
>> IMO it is.  The only place where there's a "hack" is in ox-latex and
>> that's cause article is the default class.  If you prefer, it can just
>> output to the \subtitle{·} by default and say it's KOMA-script only.  That
>> seems harsh, though.
>
> Hi there,
>
> being like a Pavlov's dog trained to dribble on seeing the word
> LaTeX;-), let me add my 2 cents here.
>
> [TL;DR: imho, the right way to do LaTeX export is to prepare a dedicated
> package for Org-mode generated files (easy/medium), arrange for it to be
> included in all major TeX distros (easy) and simplify the LaTeX exporter
> to comply with it (easy).  This could greatly enhance the quality of
> PDFs produced by Org-mode and make modifying their look easier on the
> Org side.  I could do the LaTeX side of the work.  Now the question is:
> does the community /want/ it.]
>
> The (default) LaTeX markup sucks.  (It’s not about Org-mode-produced
> LaTeX files, it’s about LaTeX itself.)  And I'm telling that as
> a long-time TeX and LaTeX user and fan.  I would strongly suggest not
> caring too much about “what does LaTeX support out-of-the-box” – in
> fact, it supports almost nothing without a heap of packages.
>
> What I really think Org-mode community should do is the following.
>
> We (if I may use that pronoun here) should prepare a dedicated Org LaTeX
> package, properly supporting all Org’s fancy stuff like tags,
> timestamps, todo keywords etc., and allowing for parametrizing their
> look-and-feel through a reasonable LaTeX interface.  I think it should
> /not/ be a class, since then people would be free to use it with
> article/amsart/koma-script/memoir/whatever.  This is not very difficult
> nor time-consuming, and in fact I might be tempted to do it (more on
> that below).  This would require (simple) changes in the LaTeX exporter
> (generally, simplifying it); this I cannot do, since I don’t have the
> FSF papers signed (and I don’t want to sign them).  OTOH, the package
> does not have this problem, since LaTeX licensing is much more sane than
> Emacs’; this package should be imho part of every TeX distro (which is
> important, and in fact easy to arrange), so that we could send an
> Org-generated LaTeX file to any TeX user.
>
> The biggest advantage would be the possibility of exporting e.g. TODO
> lists or agendas to LaTeX, and have them formatted as TODO lists and
> agendas and not as “articles”.  Currently, LaTeX export is more or less
> limited to scientific articles (unless you want to tweak it /a lot/ so
> that it looks even remotely reasonable), where you don’t really care
> about layout and design, since they are going to be changed by the
> journal anyway.
>
> Just think about the possibilities.  We could make a TODO list in Org,
> and send it (as a pdf file) for non-Org-users to print, and it could
> look like a TODO-list.  (I guess there are still lots of people who
> depend on paper todo lists; I do, for sure, though I make them
> manually.)  We could have an option (on Org side, which would translate
> to a LaTeX one) to have more Word-like layout.  (You can say what you
> want about Word – my personal opinion is that it is unsuitable for
> documents larger/more complex than a piece of paper with an arrow
> showing the direction to the restroom – but sometimes, especially for
> short memos/notes, LaTeX’s extremely generic spacing can be annoying.
> Of course, you could just load the savetrees package – but let me make
> a short, informal and unscientific survey here: how many of you would
> find it useful, but never thought that something like that exists?  If,
> OTOH, there would be such option for the LaTeX exporter, it would be
> right there, in Org-mode manual.  In fact, since not everyone might
> follow this thread, let me start another one, with this very question in
> a minute;-).)
>
> The added benefit would be much cleaner structure of Org-generated LaTeX
> files.  Currently, they have a huge preamble and a few hard-wired
> things.
>
> Summing up: as we know, there are many ways people use Org-mode, but the
> current PDF exporter (through LaTeX’s article class, heavily biased
> toward scientific material) is suboptimal for all but one of these ways.
>
> As I said, if there is some consensus on whether something like that is
> needed, I can start working on it.  (In fact, it might be a fun
> side-project.)  I would estimate that I’d need a week or two to come up
> with a proof-of-concept, sort-of-working thing, and something like two
> months with a first production version.  (Though I don’t have time for
> a project like this now, realistically I could start in August.)  (Let
> me thank here for Org-mode clocking feature – the above estimate is due
> to the fact that I did some work on coding a dedicated, quite complex
> LaTeX class for a journal, and I know that it has taken me about 32
> hours as of now.  Assuming an average pace of 2-4 hours a week, and
> assuming about 16 hours for a first version of this one – it would be
> a much simpler project – gives 1-2 months or so.  NB. Fun fact: the work
> on the class for the journal I’m talking about includes coding some
> Emacs Lisp to extract metadata from LaTeX (and aux) files and generate
> XML files for uploading pdfs to the journal site.)
>
> WDYT?

+1

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

Re: [ox, patch] Add #+SUBTITLE

[John Williams]

I, for one, find your ideas exciting, Marcin.  If you're simply looking
for votes in order to start work on this: +1.

Thanks!

>>>>> Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:

    > On 2015-03-22, at 16:29, Rasmus <rasmus@gmx.us> wrote:

    >> IMO it is.  The only place where there's a "hack" is in ox-latex
    >> and that's cause article is the default class.  If you prefer, it
    >> can just output to the \subtitle{·} by default and say it's
    >> KOMA-script only.  That seems harsh, though.

    > Hi there,

    > being like a Pavlov's dog trained to dribble on seeing the word
    > LaTeX;-), let me add my 2 cents here.

    > [TL;DR: imho, the right way to do LaTeX export is to prepare a
    > dedicated package for Org-mode generated files (easy/medium),
    > arrange for it to be included in all major TeX distros (easy) and
    > simplify the LaTeX exporter to comply with it (easy).  This could
    > greatly enhance the quality of PDFs produced by Org-mode and make
    > modifying their look easier on the Org side.  I could do the LaTeX
    > side of the work.  Now the question is: does the community /want/
    > it.]

    > The (default) LaTeX markup sucks.  (It’s not about
    > Org-mode-produced LaTeX files, it’s about LaTeX itself.)  And I'm
    > telling that as a long-time TeX and LaTeX user and fan.  I would
    > strongly suggest not caring too much about “what does LaTeX
    > support out-of-the-box” – in fact, it supports almost nothing
    > without a heap of packages.

    > What I really think Org-mode community should do is the following.

    > We (if I may use that pronoun here) should prepare a dedicated Org
    > LaTeX package, properly supporting all Org’s fancy stuff like
    > tags, timestamps, todo keywords etc., and allowing for
    > parametrizing their look-and-feel through a reasonable LaTeX
    > interface.  I think it should /not/ be a class, since then people
    > would be free to use it with
    > article/amsart/koma-script/memoir/whatever.  This is not very
    > difficult nor time-consuming, and in fact I might be tempted to do
    > it (more on that below).  This would require (simple) changes in
    > the LaTeX exporter (generally, simplifying it); this I cannot do,
    > since I don’t have the FSF papers signed (and I don’t want to sign
    > them).  OTOH, the package does not have this problem, since LaTeX
    > licensing is much more sane than Emacs’; this package should be
    > imho part of every TeX distro (which is important, and in fact
    > easy to arrange), so that we could send an Org-generated LaTeX
    > file to any TeX user.

    > The biggest advantage would be the possibility of exporting
    > e.g. TODO lists or agendas to LaTeX, and have them formatted as
    > TODO lists and agendas and not as “articles”.  Currently, LaTeX
    > export is more or less limited to scientific articles (unless you
    > want to tweak it /a lot/ so that it looks even remotely
    > reasonable), where you don’t really care about layout and design,
    > since they are going to be changed by the journal anyway.

    > Just think about the possibilities.  We could make a TODO list in
    > Org, and send it (as a pdf file) for non-Org-users to print, and
    > it could look like a TODO-list.  (I guess there are still lots of
    > people who depend on paper todo lists; I do, for sure, though I
    > make them manually.)  We could have an option (on Org side, which
    > would translate to a LaTeX one) to have more Word-like layout.
    > (You can say what you want about Word – my personal opinion is
    > that it is unsuitable for documents larger/more complex than a
    > piece of paper with an arrow showing the direction to the restroom
    > – but sometimes, especially for short memos/notes, LaTeX’s
    > extremely generic spacing can be annoying.  Of course, you could
    > just load the savetrees package – but let me make a short,
    > informal and unscientific survey here: how many of you would find
    > it useful, but never thought that something like that exists?  If,
    > OTOH, there would be such option for the LaTeX exporter, it would
    > be right there, in Org-mode manual.  In fact, since not everyone
    > might follow this thread, let me start another one, with this very
    > question in a minute;-).)

    > The added benefit would be much cleaner structure of Org-generated
    > LaTeX files.  Currently, they have a huge preamble and a few
    > hard-wired things.

    > Summing up: as we know, there are many ways people use Org-mode,
    > but the current PDF exporter (through LaTeX’s article class,
    > heavily biased toward scientific material) is suboptimal for all
    > but one of these ways.

    > As I said, if there is some consensus on whether something like
    > that is needed, I can start working on it.  (In fact, it might be
    > a fun side-project.)  I would estimate that I’d need a week or two
    > to come up with a proof-of-concept, sort-of-working thing, and
    > something like two months with a first production version.
    > (Though I don’t have time for a project like this now,
    > realistically I could start in August.)  (Let me thank here for
    > Org-mode clocking feature – the above estimate is due to the fact
    > that I did some work on coding a dedicated, quite complex LaTeX
    > class for a journal, and I know that it has taken me about 32
    > hours as of now.  Assuming an average pace of 2-4 hours a week,
    > and assuming about 16 hours for a first version of this one – it
    > would be a much simpler project – gives 1-2 months or so.  NB. Fun
    > fact: the work on the class for the journal I’m talking about
    > includes coding some Emacs Lisp to extract metadata from LaTeX
    > (and aux) files and generate XML files for uploading pdfs to the
    > journal site.)

    > WDYT?

    >> —Rasmus

    > Best,

    > -- Marcin Borkowski http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
    > Faculty of Mathematics and Computer Science Adam Mickiewicz
    > University

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:

> [TL;DR: imho, the right way to do LaTeX export is to prepare a dedicated
> package for Org-mode generated files (easy/medium), arrange for it to be
> included in all major TeX distros (easy) and simplify the LaTeX exporter
> to comply with it (easy).  This could greatly enhance the quality of
> PDFs produced by Org-mode and make modifying their look easier on the
> Org side.  I could do the LaTeX side of the work.  Now the question is:
> does the community /want/ it.]

I have a couple of initial concerns that you could address if your
spin-off thread if you like.

- Sat you can envision better code for a particular piece of org syntax.
  Why is a better to have it in an external latex-package than directly in
  the org files?  If it lives somewhere else, I have to bug you when I
  want to change something.  What if you get bored of this?

- What happens when you cannot maintain it any longer?  Note also that the
  scope is somewhat different as a typical latex package solves a problem
  like "provide good tables" or "enhance itemize 2e" (ei2e).  Such
  packages are fairly easy to replace (e.g. sugfigure → subcaption).

- I don't want latex code generated by org to a "special flavor" like with
  LyX.

- Why can the issues you have in mind not be solved by a specialized
  derived backend?  Such as ox-beamer or ox-koma-letter.

Thanks,
Rasmus

-- 
Enough with the bla bla!

Re: [ox, patch] Add #+SUBTITLE

[Marcin Borkowski]

On 2015-03-22, at 23:43, Rasmus <rasmus@gmx.us> wrote:

> Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:
>
>> [TL;DR: imho, the right way to do LaTeX export is to prepare a dedicated
>> package for Org-mode generated files (easy/medium), arrange for it to be
>> included in all major TeX distros (easy) and simplify the LaTeX exporter
>> to comply with it (easy).  This could greatly enhance the quality of
>> PDFs produced by Org-mode and make modifying their look easier on the
>> Org side.  I could do the LaTeX side of the work.  Now the question is:
>> does the community /want/ it.]
>
> I have a couple of initial concerns that you could address if your
> spin-off thread if you like.

Good questions!

> - Sat you can envision better code for a particular piece of org syntax.
>   Why is a better to have it in an external latex-package than directly in
>   the org files?  If it lives somewhere else, I have to bug you when I
>   want to change something.  What if you get bored of this?

The point would be to provide user-level ways to change the look.
Currently e.g. tags are hardcoded into the section titles, which is ugly
both in the LaTeX source and in the LaTeX output.  (Also, see below.)

> - What happens when you cannot maintain it any longer?  Note also that the

Either the project dies, or someone takes it over.  The latter seems to
be quite common in the LaTeX community, so I wouldn't be very worried.

>   scope is somewhat different as a typical latex package solves a problem
>   like "provide good tables" or "enhance itemize 2e" (ei2e).  Such
>   packages are fairly easy to replace (e.g. sugfigure → subcaption).

Fair enough.  Not a problem imho, though.  A “package” has a very wide
definition in the LaTeX world, and I explained why a package would be
better than a class (even though doing it as a package would be a bit
more work with ensuring that it works with wide range of classes).

> - I don't want latex code generated by org to a "special flavor" like with
>   LyX.

But the whole point is to have LaTeX code which is human-readable (and
human-modifiable).  Also, currently you have "special flavor" anyway -
just look at the preamble of Org-generated LaTeX files.  In my vision,
the huge preamble is replaced by \usepackage{orglatex} or something like
this, and instead of, say,

: \section{{\bfseries\sffamily TODO} hello\hfill{}\textsc{world}}

(how is that not a “special flavor”?) you would have

: \section{\orgtodo{TODO}hello\orgtags{world}}

or, if we decide to do a major surgery on LaTeX’s sectioning mechanism
(which is debatable), even

: \section[orgtodo=TODO,orgtags=world]{hello}

or something like this.  Note that I assume that the package would be
included in all major TeX distros, so the average LaTeX user wouldn't
even notice any change, apart from better markup.

> - Why can the issues you have in mind not be solved by a specialized
>   derived backend?  Such as ox-beamer or ox-koma-letter.

This seems to bug you enough that you basically asked twice;-).

As I said, people use Org-mode in various ways.  For some people, the
LaTeX export is something they use to produce a PDF.  For other people,
Org may be a quick authoring tool (faster and more comfortable than
AUCTeX, possibly), but after e.g. making a draft in Org they continue
their work in LaTeX (because LaTeX is just more powerful than Org when
it comes to typesetting proper).  For them, human-readable (and
editable) LaTeX code is a nice thing.

Also, adding some options in a LaTeX package seems to have less friction
than in Org.  In the former, you just code it and make a pull request to
the package maintainer (or send a patch, or even just file a feature
request).  In the latter, you bug Nicolas, and he has to think about the
impact of your feature request for other backends (because Org is not
LaTeX-centric!).

Probably most importantly, Org-mode is much more about the content, and
delegates the presentation issues to backends.  In case of HTML, you
have CSS, and it seems that everyone agrees that generating a suitable
CSS is outside Org-mode’s scope.  What I’m proposing here is very much
analogous to the HTML/CSS division: let Org produce a somewhat generic
LaTeX markup (like HTML), and let a LaTeX package (like CSS) decide what
to do with that visually.  Currently, due to hard-coding of things like
in the above example, it is plainly impossible.  And while HTML has ways
of “extending itself” built-in (thanks to element classes and divs and
spans), LaTeX does not have anything like that.  What I’m proposing is
(more or less) filling this gap.

Also, due to (sorry to repeat that) insane licensing requirements of
Org, making changes is much more frictionless on the LaTeX side of
things.

>
> Thanks,
> Rasmus


-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Hi,

First: Please don't take me being critical as meaning I'm necessarily
negative about.  I'm just minimizing risk over the expectation.

Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:

>> - What happens when you cannot maintain it any longer?  Note also that the
>
> Either the project dies, or someone takes it over.  The latter seems to
> be quite common in the LaTeX community, so I wouldn't be very worried.

That does not seem like something you'd want to base Org on...

>>   scope is somewhat different as a typical latex package solves a problem
>>   like "provide good tables" or "enhance itemize 2e" (ei2e).  Such
>>   packages are fairly easy to replace (e.g. sugfigure → subcaption).
>
> Fair enough.  Not a problem imho, though.  A “package” has a very wide
> definition in the LaTeX world, and I explained why a package would be
> better than a class (even though doing it as a package would be a bit
> more work with ensuring that it works with wide range of classes).

I am talking about latex packages and the example mentions real latex
packages.  A class would be a sure route to failure.  A packages is fine.
But it's beside the point.  You argue, if I understand correctly, for
amending ox-latex to rely on a very specialized package, which we may or
may not easily be able to replace should it come to that.

>> - I don't want latex code generated by org to a "special flavor" like with
>>   LyX.

> In my vision, the huge preamble is replaced by \usepackage{orglatex} or
> something like this, and instead of, say,

OK.

> : \section{{\bfseries\sffamily TODO} hello\hfill{}\textsc{world}}
>
> (how is that not a “special flavor”?) you would have
>
> : \section{\orgtodo{TODO}hello\orgtags{world}}
>
> or, if we decide to do a major surgery on LaTeX’s sectioning mechanism
> (which is debatable), even
>
> : \section[orgtodo=TODO,orgtags=world]{hello}

Both are appealing.

>> - Why can the issues you have in mind not be solved by a specialized
>>   derived backend?  Such as ox-beamer or ox-koma-letter.
>
> This seems to bug you enough that you basically asked twice;-).

No.  Here is ask why you can't settle for another Org-mode backend, rather
than a new latex package.  This can even live in contrib without signing
the copyright agreement with FSF.

E.g. you could get a very similar result to what you are talking about by
defining the macros at export-level (e.g. write-out
\providecommand\orgtodo...)  and allowed writing a preamble or similar (if
you really mind long preambles).  That way anybody would also be able to
customize on the latex end, if they so desire.

> As I said, people use Org-mode in various ways. [...].  For other
> people, [they make] a draft in Org they continue their work in LaTeX
> (...).  For them, human-readable (and editable) LaTeX code is a nice
> thing.

Good point.

> Also, adding some options in a LaTeX package seems to have less friction
> than in Org.  In the former, you just code it and make a pull request to
> the package maintainer (or send a patch, or even just file a feature
> request).  In the latter, you bug Nicolas, and he has to think about the
> impact of your feature request for other backends (because Org is not
> LaTeX-centric!).

I don't see the difference.

—Rasmus

-- 
You people at the NSA are becoming my new best friends!

Re: [ox, patch] Add #+SUBTITLE

[Eric Abrahamsen]

Rasmus <rasmus@gmx.us> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> Rasmus <rasmus@gmx.us> writes:
>>
>> In ox-html, You might consider wrapping the title and subtitle in an
>> <hgroup> if :html5-fancy is t. Or maybe that's going too far! Either
>> way, I like this.
>
> First result on my search engine says¹ :
>
>     Update 16th April, 2013. hgroup has now been removed from the HTML5
>     specification. We are working on an article to help guide authors on
>     which markup patterns they should use instead.
>
>     Update 4th April, 2013. Please note that following this decision,
>     hgroup will be removed from the HTML5 specification. As such, we don’t
>     endorse using it on production sites.
>
> I don't know anything about html, though.  Is there another element you
> had in mind?  Or is the html5doctor just wrong?

Between me and html5doctor, I'd believe html5doctor. That's a shame
though! hgroup always made a lot of sense to me.

Re: [ox, patch] Add #+SUBTITLE

[Marcin Borkowski]

On 2015-03-23, at 01:05, Rasmus <rasmus@gmx.us> wrote:

> Hi,
>
> First: Please don't take me being critical as meaning I'm necessarily
> negative about.  I'm just minimizing risk over the expectation.

Of course, fine with me.  It’s the criticism which can make this project
better (or help decide it’s unnecessary, which would spare the unneeded
work;-)).  Also, you make me think more and refine my idea, so thanks
for the criticism!

> Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:
>
>>> - What happens when you cannot maintain it any longer?  Note also that the
>>
>> Either the project dies, or someone takes it over.  The latter seems to
>> be quite common in the LaTeX community, so I wouldn't be very worried.
>
> That does not seem like something you'd want to base Org on...

You might have misunderstood me.  I did not claim that it's often in the
TeX world that people abandon projects, but /if/ they do, it's common
that someone takes over the package.  (Though I don’t have any real
data, just my gut feeling.)

>>>   scope is somewhat different as a typical latex package solves a problem
>>>   like "provide good tables" or "enhance itemize 2e" (ei2e).  Such
>>>   packages are fairly easy to replace (e.g. sugfigure → subcaption).
>>
>> Fair enough.  Not a problem imho, though.  A “package” has a very wide
>> definition in the LaTeX world, and I explained why a package would be
>> better than a class (even though doing it as a package would be a bit
>> more work with ensuring that it works with wide range of classes).
>
> I am talking about latex packages and the example mentions real latex
> packages.  A class would be a sure route to failure.  A packages is fine.
> But it's beside the point.  You argue, if I understand correctly, for
> amending ox-latex to rely on a very specialized package, which we may or
> may not easily be able to replace should it come to that.

Well, currently it relies on 15 packages anyway, including marvosym and
wasysym which might not be present in every TeX installation, btw.
(They should /really/ be only included when actually needed!)  I don't
see much difference.

Besides, I'm not telling about /replacing/ the current exporter.  The
behavior I'm talking about could be optional, and turned on by an
option.  It would require changes to, say, maybe half of the transcoders
in ox-latex, and a new preamble – and that would be probably it.
Instead of replacing them, they might behave in two ways (“old” one and
“new” one) based on some option.

Finally, assuming that it gets stable after a few months, I don’t see
the need for “replacing” it.  I don’t think Org syntax is about to
change drastically.

I can see your concern, though.  If my proposal gets some traction, then
Org would indeed depend on something which is not under its control, and
it might be a real concern for some people.  OTOH, it /does/ depend on
a few third-party tools anyway – some LaTeX packages, too.  (Though they
are stable, and not tightly coupled with Org itself.)

But take, for instance, the current discussion about Org and
bibliographies (which I’m only aware of, I don’t follow it).  Assuming
Org gets some standard syntax for citations, there will be a need for
properly exporting them to LaTeX (probably using biblatex or optionally
amsrefs).  But these packages already exists, and are stable and
well-known, and it’s fine to call them, so it doesn’t seem a problem for
me.  Assuming we don’t want to clutter the exported file with
\usepackage’s, this would require adding /a few lines/ to the proposed
package (\RequirePackage{biblatex} and possibly some simple default
setup).

OTOH, the change in the proposed package /would/ be needed if something
is added to Org core (like TODO keywords, tags or timestamps), which is
not directly supported by LaTeX.  I wouldn’t expect that to happen very
often.

>>> - I don't want latex code generated by org to a "special flavor" like with
>>>   LyX.
>
>> In my vision, the huge preamble is replaced by \usepackage{orglatex} or
>> something like this, and instead of, say,
>
> OK.
>
>> : \section{{\bfseries\sffamily TODO} hello\hfill{}\textsc{world}}
>>
>> (how is that not a “special flavor”?) you would have
>>
>> : \section{\orgtodo{TODO}hello\orgtags{world}}
>>
>> or, if we decide to do a major surgery on LaTeX’s sectioning mechanism
>> (which is debatable), even
>>
>> : \section[orgtodo=TODO,orgtags=world]{hello}
>
> Both are appealing.
>
>>> - Why can the issues you have in mind not be solved by a specialized
>>>   derived backend?  Such as ox-beamer or ox-koma-letter.
>>
>> This seems to bug you enough that you basically asked twice;-).
>
> No.  Here is ask why you can't settle for another Org-mode backend, rather
> than a new latex package.  This can even live in contrib without signing
> the copyright agreement with FSF.

If it lives in contrib – which is fine for me personally – it would be
used by a lot less people.  If it’s official, Org would have better PDF
support /by default/.

Notice that there might be also Org options mapped to many of the
proposed package options, too, so that people wanting to change some
more “standard” things would not have to edit LaTeX directly.  But I’m
not sure that’s necessary, and it might be missing the point
altogether.  The point is (among others) to delegate typesetting to
LaTeX, including setting various options.  This way, both Org file is
cleaner (since it doesn’t contain lots of customizations for /one/
backend) and the LaTeX file is cleaner (since it doesn’t contain
hardwired things like the mentioned \bfseries, \sffamily or \hfill).
Let me repeat: Org-mode is not a typesetting engine, and should not be
imho, so typesetting/layout issues should be delegated to the tool which
does that.  Currently it’s not the case, and indeed Org exporter makes
some poor typographic decisions.

> E.g. you could get a very similar result to what you are talking about by
> defining the macros at export-level (e.g. write-out
> \providecommand\orgtodo...)  and allowed writing a preamble or similar (if
> you really mind long preambles).  That way anybody would also be able to
> customize on the latex end, if they so desire.

Of course.  Even now, extensive customization on the LaTeX level is
possible; some of my files have /a lot/ of #+LATEX_HEADER’s, for
instance.  But again: I consider this to be abusing Org to do what it
shouldn’t do.

>> As I said, people use Org-mode in various ways. [...].  For other
>> people, [they make] a draft in Org they continue their work in LaTeX
>> (...).  For them, human-readable (and editable) LaTeX code is a nice
>> thing.
>
> Good point.
>
>> Also, adding some options in a LaTeX package seems to have less friction
>> than in Org.  In the former, you just code it and make a pull request to
>> the package maintainer (or send a patch, or even just file a feature
>> request).  In the latter, you bug Nicolas, and he has to think about the
>> impact of your feature request for other backends (because Org is not
>> LaTeX-centric!).
>
> I don't see the difference.

For one, it /might/ be easier to find a TeX hacker (even for hire) to
change something than an Emacs hacker (though I don’t really know, both
Emacs and LaTeX are kind of niche).

Then, in case of LaTeX, basically /anyone/ can make a change; in case of
Org, you need those pesky FSF papers.

And, it might be a tad easier for a more casual user to tweak something
on the LaTeX side (though I might be biased) – quite a lot of LaTeX
tutorials mention \renewcommand and friends, and somehow people do it
(sometimes even too often, imo!); seemingly, people are much more scared
by Elisp.  You might argue that it’s stupid, because Elisp is way easier
to program in than (La)TeX – but that’s reality; moreover, in case of
LaTeX you often don’t really need “programming”, just replacing some
strings with others, without fancy stuff like loops, conditionals etc.,
hence the macro system TeX uses is often enough even for casual users.
You don’t need to be a programmer to understand

: \newcommand{\reals}{\mathbb{R}}

or even

: \newcommand{\abs}[1]{\lvert #1\rvert}  % btw, this is deprecated

while even a simple change in Org transcoders or filters requires some
knowledge of programming (and of Org exporter structure).

Finally, the LaTeX package might make use of the “template” mechanism of
LaTeX3, which is aimed at ease of customization of various constructs in
LaTeX (and is already usable, and in fact used by some packages).

> —Rasmus

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: [ox, patch] Add #+SUBTITLE

[Sebastien Vauban]

Marcin Borkowski wrote:
> On 2015-03-22, at 16:29, Rasmus <rasmus-0UDz38MK/Mo@public.gmane.org> wrote:
>
>> IMO it is.  The only place where there's a "hack" is in ox-latex and
>> that's cause article is the default class.  If you prefer, it can just
>> output to the \subtitle{·} by default and say it's KOMA-script only.  That
>> seems harsh, though.
>
> Hi there,
>
> being like a Pavlov's dog trained to dribble on seeing the word
> LaTeX;-), let me add my 2 cents here.
>
> [TL;DR: imho, the right way to do LaTeX export is to prepare a dedicated
> package for Org-mode generated files (easy/medium), arrange for it to be
> included in all major TeX distros (easy) and simplify the LaTeX exporter
> to comply with it (easy).  This could greatly enhance the quality of
> PDFs produced by Org-mode and make modifying their look easier on the
> Org side.  I could do the LaTeX side of the work.  Now the question is:
> does the community /want/ it.]
>
> The (default) LaTeX markup sucks.  (It’s not about Org-mode-produced
> LaTeX files, it’s about LaTeX itself.)  And I'm telling that as
> a long-time TeX and LaTeX user and fan.  I would strongly suggest not
> caring too much about “what does LaTeX support out-of-the-box” – in
> fact, it supports almost nothing without a heap of packages.
>
> What I really think Org-mode community should do is the following.
>
> We (if I may use that pronoun here) should prepare a dedicated Org LaTeX
> package, properly supporting all Org’s fancy stuff like tags,
> timestamps, todo keywords etc., and allowing for parametrizing their
> look-and-feel through a reasonable LaTeX interface.  I think it should
> /not/ be a class, since then people would be free to use it with
> article/amsart/koma-script/memoir/whatever.  This is not very difficult
> nor time-consuming, and in fact I might be tempted to do it (more on
> that below).  This would require (simple) changes in the LaTeX exporter
> (generally, simplifying it); this I cannot do, since I don’t have the
> FSF papers signed (and I don’t want to sign them).  OTOH, the package
> does not have this problem, since LaTeX licensing is much more sane than
> Emacs’; this package should be imho part of every TeX distro (which is
> important, and in fact easy to arrange), so that we could send an
> Org-generated LaTeX file to any TeX user.
>
> The biggest advantage would be the possibility of exporting e.g. TODO
> lists or agendas to LaTeX, and have them formatted as TODO lists and
> agendas and not as “articles”.  Currently, LaTeX export is more or less
> limited to scientific articles (unless you want to tweak it /a lot/ so
> that it looks even remotely reasonable), where you don’t really care
> about layout and design, since they are going to be changed by the
> journal anyway.
>
> Just think about the possibilities.  We could make a TODO list in Org,
> and send it (as a pdf file) for non-Org-users to print, and it could
> look like a TODO-list.  (I guess there are still lots of people who
> depend on paper todo lists; I do, for sure, though I make them
> manually.)  We could have an option (on Org side, which would translate
> to a LaTeX one) to have more Word-like layout.  (You can say what you
> want about Word – my personal opinion is that it is unsuitable for
> documents larger/more complex than a piece of paper with an arrow
> showing the direction to the restroom – but sometimes, especially for
> short memos/notes, LaTeX’s extremely generic spacing can be annoying.
> Of course, you could just load the savetrees package – but let me make
> a short, informal and unscientific survey here: how many of you would
> find it useful, but never thought that something like that exists?  If,
> OTOH, there would be such option for the LaTeX exporter, it would be
> right there, in Org-mode manual.  In fact, since not everyone might
> follow this thread, let me start another one, with this very question in
> a minute;-).)
>
> The added benefit would be much cleaner structure of Org-generated LaTeX
> files.  Currently, they have a huge preamble and a few hard-wired
> things.
>
> Summing up: as we know, there are many ways people use Org-mode, but the
> current PDF exporter (through LaTeX’s article class, heavily biased
> toward scientific material) is suboptimal for all but one of these ways.
>
> As I said, if there is some consensus on whether something like that is
> needed, I can start working on it.  (In fact, it might be a fun
> side-project.)  I would estimate that I’d need a week or two to come up
> with a proof-of-concept, sort-of-working thing, and something like two
> months with a first production version.  (Though I don’t have time for
> a project like this now, realistically I could start in August.)  (Let
> me thank here for Org-mode clocking feature – the above estimate is due
> to the fact that I did some work on coding a dedicated, quite complex
> LaTeX class for a journal, and I know that it has taken me about 32
> hours as of now.  Assuming an average pace of 2-4 hours a week, and
> assuming about 16 hours for a first version of this one – it would be
> a much simpler project – gives 1-2 months or so.  NB. Fun fact: the work
> on the class for the journal I’m talking about includes coding some
> Emacs Lisp to extract metadata from LaTeX (and aux) files and generate
> XML files for uploading pdfs to the journal site.)
>
> WDYT?

+1^{2} ;-)

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [ox, patch] Add #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> However, I think porting this feature to back-ends that do not support
>> it out of the box is pushing too hard. 
>
> In the patch there's ox-latex where e.g. KOMA-Script has as
> subtitle-macro.  ox-html, ox-ascii, ox-odt all are pretty liberate formats
> in terms of what elements are supported.

My concern is not technical. You can indeed tweak "ox-html", "ox-ascii"
and "ox-odt" to support many things.

I just don't want to make it too difficult for back-end developers, and
maintainers, to keep up with compatibility with other back-ends, while
still allowing existing back-ends to extend (almost) freely.

E.g., when creating a new export back-end, it is quite obvious that one
will need to handle TITLE, DATE, AUTHOR and EMAIL somehow. Now, if you
request handlers for SUBTITLE, KEYWORDS and DESCRIPTION, it becomes more
tedious to achieve the task.

This is not really about SUBTITLE, but, sooner or later, we will have to
draw a line between common features ensuring compatibility between
back-ends and specific ones. The cost of the former is some orders of
magnitude higher.

>> This is why I suggested to move KEYWORD and DESCRIPTION outside of
>> "ox.el", as they cannot be ported to all back-ends without relying on
>> dubious markup.
>
> Yeah, I still have a patch for that...  I still have to do the
> documentation changes.

Unless we decide that KEYWORD and DESCRIPTION should move to the "common
features" discussed above. In this case, they stay in "ox.el" and all
major back-ends are expected to handle them. WDYT?

>> Now, if SUBTITLE is a feature desperately needed everywhere, which can
>> be discussed, it should be moved to "ox.el" and probably
>> `org-element-document-keywords'. IMO, this is not necessary. SUBTITLE
>> should be kept for back-ends that can handle it.
>
> IMO it is.

See above. I don't mind much, as long as we eventually stop
compatibility hell at some point.

If you think it's important, then go ahead.

> The only place where there's a "hack" is in ox-latex and
> that's cause article is the default class.  If you prefer, it can just
> output to the \subtitle{·} by default and say it's KOMA-script only.  That
> seems harsh, though.

I agree it would be harsh.

>> As a side note, "ox-texinfo" doesn't parse SUBTITLE. You might want to
>> change it and update manual accordingly.
>
> The patch doesn't touch ox-texinfo.  I don't mind fixing that bug,
> though.

It isn't a bug at the moment, since that feature is documented in the
manual. However, it will become inconsistent if other back-ends parse
SUBTITLE.


Regards,

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> E.g., when creating a new export back-end, it is quite obvious that one
> will need to handle TITLE, DATE, AUTHOR and EMAIL somehow. Now, if you
> request handlers for SUBTITLE, KEYWORDS and DESCRIPTION, it becomes more
> tedious to achieve the task.

Isn't the point that you don't have to support those (e.g. markddown).
The current documentation is pretty specific about not having expectations
about KEYWORDS and DESCRIPTION working.  It would be the same for
SUBTITLE.

> This is not really about SUBTITLE, but, sooner or later, we will have to
> draw a line between common features ensuring compatibility between
> back-ends and specific ones. The cost of the former is some orders of
> magnitude higher.

This is why I proposed SUBTITLE as a feature of a few backends: ox-ascii,
ox-html, ox-odt, and ox-latex (and some derived backends).

>> Yeah, I still have a patch for that...  I still have to do the
>> documentation changes.
>
> Unless we decide that KEYWORD and DESCRIPTION should move to the "common
> features" discussed above. In this case, they stay in "ox.el" and all
> major back-ends are expected to handle them. WDYT?

I think it is fine either way.  But I have never used DESCRIPTION and I
don't use KEYWORDS regularly.

>>> Now, if SUBTITLE is a feature desperately needed everywhere, which can
>>> be discussed, it should be moved to "ox.el" and probably
>>> `org-element-document-keywords'. IMO, this is not necessary. SUBTITLE
>>> should be kept for back-ends that can handle it.
>>
>> IMO it is.
>
> See above. I don't mind much, as long as we eventually stop
> compatibility hell at some point.

I think I didn't understand the first quote above (prefixed with ">>>").
It should *not* be a common feature.  It should be a feature of the
backend where it makes sense, namely backends for text documents at large.

—Rasmus

-- 
Together we'll stand, divided we'll fall

Re: [ox, patch] Add #+SUBTITLE

[Melanie Bacou]

I would indeed go further and suggest adding the following once and for 
all as common ox features:

#+TITLE
#+SUBTITLE
#+DATE
#+AUTHORS (support multiple)
#+EMAILS (1 per author)
#+AFFILIATIONS (1 per author)
#+CLASSIFICATION (e.g. "ACM", "JEL", "Dublin Core", "your corporate 
classification", etc.)
#+KEYWORDS
#+DESCRIPTION
#+REVISION

This is not so much about what back-ends currently support (that's 
irrelevant in my view), it's about what minimum meta information is 
needed to publish and maintain meaningful documents. The use of these 
meta fields encourage good publishing practices, and all back-ends 
should eventually support all or a subset of these. Most LaTeX journal 
classes do. HTML would support these at least as <meta content=""> tags. 
ODT and DOCX can support all using templates.

--Mel.



On 3/24/2015 5:05 AM, Nicolas Goaziou wrote:
> Rasmus <rasmus@gmx.us> writes:
>
>> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>>
>>> However, I think porting this feature to back-ends that do not support
>>> it out of the box is pushing too hard.
>>
>> In the patch there's ox-latex where e.g. KOMA-Script has as
>> subtitle-macro.  ox-html, ox-ascii, ox-odt all are pretty liberate formats
>> in terms of what elements are supported.
>
> My concern is not technical. You can indeed tweak "ox-html", "ox-ascii"
> and "ox-odt" to support many things.
>
> I just don't want to make it too difficult for back-end developers, and
> maintainers, to keep up with compatibility with other back-ends, while
> still allowing existing back-ends to extend (almost) freely.
>
> E.g., when creating a new export back-end, it is quite obvious that one
> will need to handle TITLE, DATE, AUTHOR and EMAIL somehow. Now, if you
> request handlers for SUBTITLE, KEYWORDS and DESCRIPTION, it becomes more
> tedious to achieve the task.
>
> This is not really about SUBTITLE, but, sooner or later, we will have to
> draw a line between common features ensuring compatibility between
> back-ends and specific ones. The cost of the former is some orders of
> magnitude higher.
>
>>> This is why I suggested to move KEYWORD and DESCRIPTION outside of
>>> "ox.el", as they cannot be ported to all back-ends without relying on
>>> dubious markup.
>>
>> Yeah, I still have a patch for that...  I still have to do the
>> documentation changes.
>
> Unless we decide that KEYWORD and DESCRIPTION should move to the "common
> features" discussed above. In this case, they stay in "ox.el" and all
> major back-ends are expected to handle them. WDYT?
>
>>> Now, if SUBTITLE is a feature desperately needed everywhere, which can
>>> be discussed, it should be moved to "ox.el" and probably
>>> `org-element-document-keywords'. IMO, this is not necessary. SUBTITLE
>>> should be kept for back-ends that can handle it.
>>
>> IMO it is.
>
> See above. I don't mind much, as long as we eventually stop
> compatibility hell at some point.
>
> If you think it's important, then go ahead.
>
>> The only place where there's a "hack" is in ox-latex and
>> that's cause article is the default class.  If you prefer, it can just
>> output to the \subtitle{·} by default and say it's KOMA-script only.  That
>> seems harsh, though.
>
> I agree it would be harsh.
>
>>> As a side note, "ox-texinfo" doesn't parse SUBTITLE. You might want to
>>> change it and update manual accordingly.
>>
>> The patch doesn't touch ox-texinfo.  I don't mind fixing that bug,
>> though.
>
> It isn't a bug at the moment, since that feature is documented in the
> manual. However, it will become inconsistent if other back-ends parse
> SUBTITLE.
>
>
> Regards,
>
>

-- 
Melanie BACOU
International Food Policy Research Institute
Snr. Program Manager, HarvestChoice
E-mail m.bacou@cgiar.org
Visit www.harvestchoice.org

Re: [ox, patch] Add #+SUBTITLE

[Melanie Bacou]

I forgot:

#+COPYRIGHT


On 3/25/2015 10:36 PM, Melanie Bacou wrote:
> I would indeed go further and suggest adding the following once and for
> all as common ox features:
>
> #+TITLE
> #+SUBTITLE
> #+DATE
> #+AUTHORS (support multiple)
> #+EMAILS (1 per author)
> #+AFFILIATIONS (1 per author)
> #+CLASSIFICATION (e.g. "ACM", "JEL", "Dublin Core", "your corporate
> classification", etc.)
> #+KEYWORDS
> #+DESCRIPTION
> #+REVISION
>
> This is not so much about what back-ends currently support (that's
> irrelevant in my view), it's about what minimum meta information is
> needed to publish and maintain meaningful documents. The use of these
> meta fields encourage good publishing practices, and all back-ends
> should eventually support all or a subset of these. Most LaTeX journal
> classes do. HTML would support these at least as <meta content=""> tags.
> ODT and DOCX can support all using templates.
>
> --Mel.
>
>
>
> On 3/24/2015 5:05 AM, Nicolas Goaziou wrote:
>> Rasmus <rasmus@gmx.us> writes:
>>
>>> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>>>
>>>> However, I think porting this feature to back-ends that do not support
>>>> it out of the box is pushing too hard.
>>>
>>> In the patch there's ox-latex where e.g. KOMA-Script has as
>>> subtitle-macro.  ox-html, ox-ascii, ox-odt all are pretty liberate
>>> formats
>>> in terms of what elements are supported.
>>
>> My concern is not technical. You can indeed tweak "ox-html", "ox-ascii"
>> and "ox-odt" to support many things.
>>
>> I just don't want to make it too difficult for back-end developers, and
>> maintainers, to keep up with compatibility with other back-ends, while
>> still allowing existing back-ends to extend (almost) freely.
>>
>> E.g., when creating a new export back-end, it is quite obvious that one
>> will need to handle TITLE, DATE, AUTHOR and EMAIL somehow. Now, if you
>> request handlers for SUBTITLE, KEYWORDS and DESCRIPTION, it becomes more
>> tedious to achieve the task.
>>
>> This is not really about SUBTITLE, but, sooner or later, we will have to
>> draw a line between common features ensuring compatibility between
>> back-ends and specific ones. The cost of the former is some orders of
>> magnitude higher.
>>
>>>> This is why I suggested to move KEYWORD and DESCRIPTION outside of
>>>> "ox.el", as they cannot be ported to all back-ends without relying on
>>>> dubious markup.
>>>
>>> Yeah, I still have a patch for that...  I still have to do the
>>> documentation changes.
>>
>> Unless we decide that KEYWORD and DESCRIPTION should move to the "common
>> features" discussed above. In this case, they stay in "ox.el" and all
>> major back-ends are expected to handle them. WDYT?
>>
>>>> Now, if SUBTITLE is a feature desperately needed everywhere, which can
>>>> be discussed, it should be moved to "ox.el" and probably
>>>> `org-element-document-keywords'. IMO, this is not necessary. SUBTITLE
>>>> should be kept for back-ends that can handle it.
>>>
>>> IMO it is.
>>
>> See above. I don't mind much, as long as we eventually stop
>> compatibility hell at some point.
>>
>> If you think it's important, then go ahead.
>>
>>> The only place where there's a "hack" is in ox-latex and
>>> that's cause article is the default class.  If you prefer, it can just
>>> output to the \subtitle{·} by default and say it's KOMA-script only.
>>> That
>>> seems harsh, though.
>>
>> I agree it would be harsh.
>>
>>>> As a side note, "ox-texinfo" doesn't parse SUBTITLE. You might want to
>>>> change it and update manual accordingly.
>>>
>>> The patch doesn't touch ox-texinfo.  I don't mind fixing that bug,
>>> though.
>>
>> It isn't a bug at the moment, since that feature is documented in the
>> manual. However, it will become inconsistent if other back-ends parse
>> SUBTITLE.
>>
>>
>> Regards,
>>
>>
>

-- 
Melanie BACOU
International Food Policy Research Institute
Snr. Program Manager, HarvestChoice
E-mail m.bacou@cgiar.org
Visit www.harvestchoice.org

Re: [ox, patch] Add #+SUBTITLE

[Melanie Bacou]

Here is how titles and subtitles are supported in Bootstrap ("the most 
popular HTML/CSS/JS framework"):

<div class="page-header">
   <h1>This would be the title <small>and this the subtitle</small></h1>
</div>

ref: http://getbootstrap.com/components/#page-header

Another commonly seen approach is this (many web CMS use this pseudo 
standard):

<h1 class="title">My Title</h1>
<h2 class="subtitle">My Subtitle</h1>

--Mel.



On 3/22/2015 9:17 PM, Eric Abrahamsen wrote:
> Rasmus <rasmus@gmx.us> writes:
>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> Rasmus <rasmus@gmx.us> writes:
>>>
>>> In ox-html, You might consider wrapping the title and subtitle in an
>>> <hgroup> if :html5-fancy is t. Or maybe that's going too far! Either
>>> way, I like this.
>>
>> First result on my search engine says¹ :
>>
>>      Update 16th April, 2013. hgroup has now been removed from the HTML5
>>      specification. We are working on an article to help guide authors on
>>      which markup patterns they should use instead.
>>
>>      Update 4th April, 2013. Please note that following this decision,
>>      hgroup will be removed from the HTML5 specification. As such, we don’t
>>      endorse using it on production sites.
>>
>> I don't know anything about html, though.  Is there another element you
>> had in mind?  Or is the html5doctor just wrong?
>
> Between me and html5doctor, I'd believe html5doctor. That's a shame
> though! hgroup always made a lot of sense to me.
>
>
>

-- 
Melanie BACOU
International Food Policy Research Institute
Snr. Program Manager, HarvestChoice
E-mail m.bacou@cgiar.org
Visit www.harvestchoice.org

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Melanie Bacou <mel@mbacou.com> writes:

> Here is how titles and subtitles are supported in Bootstrap ("the most
> popular HTML/CSS/JS framework"):
>
> <div class="page-header">
>   <h1>This would be the title <small>and this the subtitle</small></h1>
> </div>
>
> ref: http://getbootstrap.com/components/#page-header

I don't know what bootstrap is.  I have softened on the whole JS thing,
but a side should still work (almost) perfectly without it.

Anyway, the example looks ugly (IMO) as there's no line break.  Is that a
feature?  The <small> tag seems handy though.

> Another commonly seen approach is this (many web CMS use this pseudo
> standard):
>
> <h1 class="title">My Title</h1>
> <h2 class="subtitle">My Subtitle</h1>

This is basically how it's handled.  I guess you could get the former by
writing a custom preamble and disabling title export.

Is that good enough?

—Rasmus

-- 
Hvor meget poesi tror De kommer ud af et glas isvand?

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Hi,

Melanie Bacou <mel@mbacou.com> writes:

> I would indeed go further and suggest adding the following once and
> for all as common ox features:

I don't think so.  Consider the ultra important ox-ical (it's important
'cause it keep my calendar in sync via org-caldav).  How should it handle
these fields?  I think markdown also ignores them.  I think it's better to
identify a subset of "text exporters" (ox-ascii, ox-html, ox-latex,
ox-odt) that support a larger set of keywords, but not through ox.el.
(Though having it in ox makes the backend code slightly cleaner).

> #+AUTHORS (support multiple)

This one is tough.  Recently I had to write a LaTeX title for two authors,
one institutions like

    Author 1            Author 2
            Institution

AFAIK, the \and does not work for this in LaTeX.  It's just very hard to
find a general solution.  How would you even write this?  How do I
associate authors and institution?  Previously we talked about supporting
footnotes in TITLE and AUTHOR which could maybe solve the email issue.

> #+EMAILS (1 per author)
> #+AFFILIATIONS (1 per author)

AFAIK this is supported in beamer, so we could add it there.  It's also in
KOMA-Script I believe.

> #+CLASSIFICATION (e.g. "ACM", "JEL", "Dublin Core", "your corporate
> classification", etc.)

I have no clue what this means.

> #+KEYWORDS
> #+DESCRIPTION

> #+REVISION
> #+COPYRIGHT

Are these fields standard?  In hyperref these are supported out of the
box:

pdftitle pdfauthor pdfsubject pdfcreator pdfproducer pdfkeywords
pdftrapped

New ones can be added via pdfinfo, though.


You have not specified any details about what is printed.  I guess
something like revision is like a subtitle, i.e. you'd want it printed?

> This is not so much about what back-ends currently support (that's
> irrelevant in my view), it's about what minimum meta information is
> needed to publish and maintain meaningful documents.

It also about having good support for our main backends.  E.g. we try to
support math equally well in latex and other backends.

> The use of these meta fields encourage good publishing practices, and
> all back-ends should eventually support all or a subset of these. Most
> LaTeX journal classes do.
        ^^^^^^^

But ox-latex assumes the default doc. classes.

> HTML would support these at least as <meta content=""> tags.

It would be great if you would concretely share examples with us, that
uses all of this stuff in a concrete manner.  At the very least more
details is needed.  You will also have to confirm whether you truly think
this is an ox.el issue in the light of my comments above (what is
COPYRIGHT to ical?).

> ODT and DOCX can support all using templates.

Org does not export to docx.

—Rasmus

-- 
. . . The proofs are technical in nature and provides no real understanding

Re: [ox, patch] Add #+SUBTITLE

[Rasmus]

Rasmus <rasmus@gmx.us> writes:

>> <div class="page-header">
>>   <h1>This would be the title <small>and this the subtitle</small></h1>
>> </div>
>>
>> ref: http://getbootstrap.com/components/#page-header

According to html5doctor.com:

    Note: Some have been advocating of the use of the small element to
    signify subtitles. This has been under discussion in the HTML working
    group, but no compelling arguments for its use have been
    made. Therefore it is not advised to use small to mark up subtitles.

That puts the nail in that coffin. . .

>> Another commonly seen approach is this (many web CMS use this pseudo
>> standard):
>>
>> <h1 class="title">My Title</h1>
>> <h2 class="subtitle">My Subtitle</h1>
>
> This is basically how it's handled.  I guess you could get the former by
> writing a custom preamble and disabling title export.

The same page as above leads to this interesting documents, which
unfortunately has draft in its name.

    http://www.w3.org/html/wg/drafts/html/master/semantics.html#sub-head

It suggests the following:

    <header>
    <h1>title</h1>
    <p>subtitle</p>
    </header>
   
I really like this one!  This is the HTML5 solution, it seems.  Then this
could be used for non-HTML5:

    <h1>Ramones <br>
    <span>Hey! Ho! Let's Go</span> 
    </h1>

WDYT?

—Rasmus

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

Re: [ox, patch] Add #+SUBTITLE

[Melanie Bacou]

See inline.

On 3/26/2015 6:42 AM, Rasmus wrote:
> Rasmus <rasmus@gmx.us> writes:
>
>>> <div class="page-header">
>>>    <h1>This would be the title <small>and this the subtitle</small></h1>
>>> </div>
>>>
>>> ref: http://getbootstrap.com/components/#page-header
>
> According to html5doctor.com:
>
>      Note: Some have been advocating of the use of the small element to
>      signify subtitles. This has been under discussion in the HTML working
>      group, but no compelling arguments for its use have been
>      made. Therefore it is not advised to use small to mark up subtitles.
>
> That puts the nail in that coffin. . .

Right, not saying Bootstrap's implementation is pretty. More on Twitter 
Bootstrap (TWBS) though, as this has become one of the easiest and most 
expandable CSS frameworks (due to many contributed plugins). There is an 
existing org export backend for TWBS at 
https://github.com/marsmining/ox-twbs defining a series of TWBS export 
options in `org-export-twbs`.

I found this package very useful because it allows:
- using TWBS default CSS theme, or any other CSS theme found for example 
at https://bootswatch.com/
- using any available TWBS JS plugin to add nifty features, like dynamic 
sidebar (useful for navigating long documents), menubar (when publishing 
more than 1 page), dynamic/sortable tables, etc.
- support code highlighting
- is mobile-ready

Just FYI, but if you use Org to maintain technical documents or publish 
entire websites, this is very useful.


>>> Another commonly seen approach is this (many web CMS use this pseudo
>>> standard):
>>>
>>> <h1 class="title">My Title</h1>
>>> <h2 class="subtitle">My Subtitle</h1>
>>
>> This is basically how it's handled.  I guess you could get the former by
>> writing a custom preamble and disabling title export.
>
> The same page as above leads to this interesting documents, which
> unfortunately has draft in its name.
>
>      http://www.w3.org/html/wg/drafts/html/master/semantics.html#sub-head
>
> It suggests the following:
>
>      <header>
>      <h1>title</h1>
>      <p>subtitle</p>
>      </header>
>
> I really like this one!  This is the HTML5 solution, it seems.  Then this
> could be used for non-HTML5:
>
>      <h1>Ramones <br>
>      <span>Hey! Ho! Let's Go</span>
>      </h1>
>
> WDYT?
>
> —Rasmus
>

I like the HTML5 solution as well, I'd vote for using this one as 
default in ox-html.

I also suggested in an earlier message adding (LaTeX, ODT, and HTML) 
support for the most common meta tags as well (all optional).

The multiple Authors, Emails, and Affiliation are required in quite a 
few LaTeX journal classes, but currently not supported in Org. I'd vote 
for using a similar markup approach as in YAML (with indented new 
lines), e.g.


#+TITLE:          Document Title
#+SUBTITLE:       Document Subtitle
#+DATE:           2015-03-28
#+AUTHOR:         Author 1
                   Author 2
#+EMAIL:          author1@email.com
                   author2@email.com
#+AFFILIATION:    Affiliation 1
                   Affiliation 2
#+CLASSIFICATION: JEL
#+KEYWORDS:       H00, H87, F2, F12
#+DESCRIPTION:    Document description
#+REVISION:       1.0
#+COPYRIGHT:      Right Owner, 2015. All rights reserved.

ox-html could use these extra tags as follows:

<head>
<title>Document Title</title>
<meta name="title" content="Document Title" />
<meta name="date" content="2015-03-28" />
<meta name="author" content="Author 1, Author 2" />
<meta name="keywords" content="JEL: H00, H87, F2, F12" />
<meta name="description" content="Document description" />
<meta name="classification" content="JEL" />
<meta name="copyright" content="Right Owner, 2015. All rights reserved."/>
<meta name="version" content="revision"/>

<meta name="citation_title" content="Document Title" />
<meta name="citation_publication_date" content="2015-03-28" />
<meta name="citation_author" content="Author 1" />
<meta name="citation_author" content="Author 2" />
</head>

<body>

<header>
<h1>Document Title</h1>
<p>Document Subtitle</p>
<p>Revision 1.0, <time datetime="2015-03-28">2015-03-28</time></p>
</header>

<address>
Author 1
<a href="mailto:author1@email.com">author1@email.com</a>
Affiliation 1
</address>

<address>
Author 2
<a href="mailto:author2@email.com">author2@email.com</a>
Affiliation 2
</address>

<div class="classification"><label>Classification</label> JEL: H00, H87, 
F2, F12</div>
<div class="copyright"><label>Copyright</label> Right Owner, 2015. All 
rights reserved.</div>
<div class="description"><label>Description</label> Document 
description</div>

<div class="abstract"><label>Abstract</label> Document abstract</div>

<div class="toc"><label>Contents</label> [TOC]</div>
<div class="toc"><label>Tables</label> [TOC:tables]</div>
<div class="toc"><label>Figures</label> [TOC:figures]</div>
<div class="toc"><label>Equations</label> [TOC:equations]</div>
<div class="toc"><label>Listings</label> [TOC:listings]</div>

[...]


<div class="bibliography">
<h2>References</h2>
[BIBLIOGRAPHY]
</div>

</body>

See ref:
- 
http://dev.w3.org/html5/spec-author-view/the-meta-element.html#the-meta-element
- https://scholar.google.com/intl/en/scholar/inclusion.html#indexing
- http://html5doctor.com/the-address-element/

I'm probably opening Pandora's box here, but in my long experience this 
is the information that's most commonly found or required in any type of 
publication or technical document.

Would be useful to hear others' opinions.

-- 
Melanie BACOU
International Food Policy Research Institute
Snr. Program Manager, HarvestChoice
E-mail m.bacou@cgiar.org
Visit www.harvestchoice.org

Re: [ox, patch] Add #+SUBTITLE

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> Isn't the point that you don't have to support those (e.g. markddown).
> The current documentation is pretty specific about not having expectations
> about KEYWORDS and DESCRIPTION working.  It would be the same for
> SUBTITLE.

OK, then SUBTITLE is expected to be out of "ox.el".

> I think it is fine either way.  But I have never used DESCRIPTION and I
> don't use KEYWORDS regularly.

Then let's put them in the same bag as SUBTITLE and document them per
back-end, whenever they are used.

> I think I didn't understand the first quote above (prefixed with ">>>").
> It should *not* be a common feature.  It should be a feature of the
> backend where it makes sense, namely backends for text documents at
> large.

Fair enough.

Regards,