From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rasmus Subject: Re: [ox, patch] #+SUBTITLE Date: Sun, 29 Mar 2015 13:50:08 +0200 Message-ID: <87oanct43z.fsf@gmx.us> References: <87y4miv7y6.fsf@gmx.us> <87a8yxi0zf.fsf@nicolasgoaziou.fr> <87k2y1qfpi.fsf@gmx.us> <87d23sdtod.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:57434) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YcBjM-0007xf-Bz for emacs-orgmode@gnu.org; Sun, 29 Mar 2015 07:50:19 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YcBjI-0002JA-T8 for emacs-orgmode@gnu.org; Sun, 29 Mar 2015 07:50:16 -0400 Received: from mout.gmx.net ([212.227.15.15]:54338) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YcBjI-0002Hi-El for emacs-orgmode@gnu.org; Sun, 29 Mar 2015 07:50:12 -0400 Received: from W530 ([46.166.188.195]) by mail.gmx.com (mrgmx001) with ESMTPSA (Nemesis) id 0Lcj9b-1ZI5BN2wS7-00kBiT for ; Sun, 29 Mar 2015 13:50:11 +0200 In-Reply-To: <87d23sdtod.fsf@nicolasgoaziou.fr> (Nicolas Goaziou's message of "Sun, 29 Mar 2015 11:44:34 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi, I've added a patch that address the code problems, but not the documentation issues, as the solution is still unclear. Nicolas Goaziou writes: >> But de facto KEYWORDS and DESCRIPTION were also only supported in some >> backends. I think it's more convenient to have these type of keywords in >> one place. But I don't feel strongly about this. > > I would like to keep a clear and somewhat future-proof rule about this: > > 1. A keyword a user can expect to find in all back-ends where it makes > sense should be defined in "ox.el". To put it differently, it can be > considered as a bug if a back-end could /simply/ support a keyword > in this category but doesn't. Keywords in this category are to be > documented in (info "(org)Export settings"). > > 2. Other keywords are defined in their respective back-end, and > documented in their respective chapter in the manual. > > As a non-trivial example, consider :email. You can expect it to produce > something sensible in any back-end. Yet, "ox-icalendar" doesn't use it. > It still belongs to first category. > > If we support SUBTITLE everywhere it makes sense, it might be worth > adding it to the first category. Actually, considering the rule above, > I even lean towards adding it to that category. WDYT? I think it's hard to make a clear-cut rule. I think keywords that are well-supported by Org-core should be there. From a user perspective, I think it should be close to TITLE. Further, putting it there also signal to external writers, e.g. ox-reveal, that they should now try to support it. I think SUBTITLE, KEYWORD, and DESCRIPTION is within the same category and should be treated the same. We could add a subsection with "text document properties" which are keywords that are supported by the set: {ox-html, ox-ascii, ox-odt, ox-latex}. These would be sort of 1=C2=BD class citizens. We can't support SUBTITLE everywhere, 'cause it simply does not make sense (only in "text document producers" IMO). The support of SUBTITLE is: W/Emacs: support is 6/9 W/Contrib: support is 8/20 - BTW: ox-groff seems to have some support for subtitles, but I'm not sure how this works, so I haven't tried to unify it. - I guess it could be added to ox-rss could support it. Atom seems to support subtitle, but it does not seem rss 2.0 has it in its definition... I don't know the details of RSS well. W/"the wild": for all I know the limit of the fraction is zero. > Also, I'm going to implement the `parse-object' and `parse-element' > behaviour we discussed in another thread, and remove > `org-element-document-properties' (and the relative > `org-export-document-properties') altogether. This will remove a useless > distinction among keywords: two categories are enough. I think this sounds very cool. It will allow us to remove a lot of "low-level" details from file with additional parsed keywords. > As a side-effect, however, `org-element-context' will not show objects > when called on TITLE and al, but that might be a good thing actually > (there are objects in there only during export and only if considered > export back-end makes use of them). As mentioned, it's fine with me and nobody else complained so I think there's no need to worry. >>> (and formatted-subtitle ...) >> >> Can you explain why (and =E2=8B=AF) should be used here? > > It makes more obvious you are expecting a return value. `when' is > preferred for side effects. However, this is not a hard rule, since Thanks for the example. =E2=80=94Rasmus --=20 Don't panic!!! --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-ox-Add-SUBTITLE-property-in-some-backends.patch >From 1c2241e4d39a619b6123cb4e69c60dcec42534ee Mon Sep 17 00:00:00 2001 From: Rasmus Date: Sun, 1 Mar 2015 22:09:19 +0100 Subject: [PATCH] ox: Add SUBTITLE property in some backends * ox-ascii.el (org-ascii-template--document-title) (org-ascii-template--document-title) ox-deck.el (org-deck-title-slide-template) ox-s5.el (org-s5-title-slide-template) ox-html.el (org-html--build-meta-info, org-html-format-spec) (org-html--build-meta-info, org-html-format-spec) (org-html--build-meta-info, org-html-format-spec) ox-org.el (org), (org-org-keyword): Use SUBTITLE. * ox-beamer.el (org-beamer-template) ox-html (org-html-template) ox-latex.el (org-latex-template) ox-org (org-org-template): Insert SUBTITLE. * ox-html (org-html-preamble-format) (org-html-postamble-format): Update docstring. * ox-html (org-html-style-default): Add .subtitle style and change .title style. * ox-texinfo.el (org-texinfo-template): Interpret subtitle. * org.texi (Export settings): Document SUBTITLE. * ORG-NEWS: Add entry on SUBTITLE. The patch adds a #+SUBTITLE keyword to ox-ascii, ox-latex, ox-html and ox-odt. --- contrib/lisp/ox-deck.el | 7 +++++++ contrib/lisp/ox-s5.el | 7 +++++++ doc/org.texi | 11 ++++++++++- etc/ORG-NEWS | 3 +++ lisp/ox-ascii.el | 22 +++++++++++++++++----- lisp/ox-beamer.el | 20 +++++++++++++++++++- lisp/ox-html.el | 37 +++++++++++++++++++++++++++++++------ lisp/ox-latex.el | 49 ++++++++++++++++++++++++++++++++++++++++++++----- lisp/ox-odt.el | 32 +++++++++++++++++++++++++++++--- lisp/ox-texinfo.el | 10 +++++++--- 10 files changed, 174 insertions(+), 24 deletions(-) diff --git a/contrib/lisp/ox-deck.el b/contrib/lisp/ox-deck.el index 0ebde41..9dbd6ca 100644 --- a/contrib/lisp/ox-deck.el +++ b/contrib/lisp/ox-deck.el @@ -38,6 +38,12 @@ ;; See ox.el and ox-html.el for more details on how this exporter ;; works (it is derived from ox-html.) +;; TODOs +;; ------ +;; The title page is formatted using format-spec. This is error prone +;; when details are missing and may insert empty tags, like

, +;; for missing values. + (require 'ox-html) (eval-when-compile (require 'cl)) @@ -259,6 +265,7 @@ Defaults to styles for the title page." (defcustom org-deck-title-slide-template "

%t

+

%s

%a

%e

%d

" diff --git a/contrib/lisp/ox-s5.el b/contrib/lisp/ox-s5.el index b003919..503bfd0 100644 --- a/contrib/lisp/ox-s5.el +++ b/contrib/lisp/ox-s5.el @@ -48,6 +48,12 @@ ;; in an Org mode buffer. See ox.el and ox-html.el for more details ;; on how this exporter works. +;; TODOs +;; ------ +;; The title page is formatted using format-spec. This is error prone +;; when details are missing and may insert empty tags, like

, +;; for missing values. + (require 'ox-html) (eval-when-compile (require 'cl)) @@ -174,6 +180,7 @@ or an empty string." (defcustom org-s5-title-slide-template "

%t

+

%s

%a

%e

%d

" diff --git a/doc/org.texi b/doc/org.texi index 18e5169..1f14093 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10713,6 +10713,12 @@ default value is @code{:export:}. Within a subtree tagged with below). When headlines are selectively exported with @code{:export:} anywhere in a file, text before the first headline is ignored. +@item SUBTITLE +@cindex #+SUBTITLE +The document subtitle. The keyword is supported by @LaTeX{}-backends, +HTML backends, ASCII backends, the Texinfo backend, and the ODT backend. You +can use several such keywords for long subtitles. + @item EXCLUDE_TAGS @cindex #+EXCLUDE_TAGS @vindex org-export-exclude-tags @@ -11601,6 +11607,7 @@ p.author @r{author information, including email} p.date @r{publishing date} p.creator @r{creator info, about org mode version} .title @r{document title} +.subtitle @r{document subtitle} .todo @r{TODO keywords, all not-done states} .done @r{the DONE keywords, all states that count as done} .WAITING @r{each TODO keyword also uses a class named after itself} @@ -13176,7 +13183,6 @@ to define your own class in @code{org-texinfo-classes}, which see. Set @subsubheading Title and copyright page @cindex #+TEXINFO_PRINTED_TITLE -@cindex #+SUBTITLE The default template includes a title page for hard copy output. The title and author displayed on this page are extracted from, respectively, @code{#+TITLE} and @code{#+AUTHOR} keywords (@pxref{Export settings}). It is @@ -13982,6 +13988,7 @@ however, override everything. @item @code{:beamer-frame-default-options} @tab @code{org-beamer-frame-default-options} @item @code{:beamer-outline-frame-options} @tab @code{org-beamer-outline-frame-options} @item @code{:beamer-outline-frame-title} @tab @code{org-beamer-outline-frame-title} +@item @code{:org-beamer-subtitle-format} @tab @code{org-beamer-subtitle-format} @end multitable @subsubheading HTML specific properties @@ -14066,6 +14073,8 @@ however, override everything. @item @code{:latex-listings} @tab @code{org-latex-listings} @item @code{:latex-minted-langs} @tab @code{org-latex-minted-langs} @item @code{:latex-minted-options} @tab @code{org-latex-minted-options} +@item @code{:latex-subtitle-format} @tab @code{org-latex-subtitle-format} +@item @code{:latex-subtitle-separate} @tab @code{org-latex-subtitle-separate} @item @code{:latex-table-scientific-notation} @tab @code{org-latex-table-scientific-notation} @item @code{:latex-tables-booktabs} @tab @code{org-latex-tables-booktabs} @item @code{:latex-tables-centered} @tab @code{org-latex-tables-centered} diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 28e8394..b37650b 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -327,6 +327,9 @@ leading spaces within table cells. *** New MathJax configuration options. Org uses the MathJax CDN by default. See the manual and the docstring of ~org-html-mathjax-options~ for details. +*** New ~#+SUBTITLE~ keyword +Org can now typeset a subtitle in some backends. See the manual for +details. ** Miscellaneous *** Strip all meta data from ITEM special property ITEM special property does not contain TODO, priority or tags anymore. diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el index 42495e2..5f11485 100644 --- a/lisp/ox-ascii.el +++ b/lisp/ox-ascii.el @@ -119,7 +119,8 @@ org-ascii-filter-comment-spacing) (:filter-section . org-ascii-filter-headline-blank-lines)) :options-alist - '((:ascii-bullets nil nil org-ascii-bullets) + '((:subtitle "SUBTITLE" nil nil space) + (:ascii-bullets nil nil org-ascii-bullets) (:ascii-caption-above nil nil org-ascii-caption-above) (:ascii-charset nil nil org-ascii-charset) (:ascii-global-margin nil nil org-ascii-global-margin) @@ -967,9 +968,15 @@ INFO is a plist used as a communication channel." ;; Links in the title will not be resolved later, so we make ;; sure their path is located right after them. (info (org-combine-plists info '(:ascii-links-to-notes nil))) - (title (if (plist-get info :with-title) - (org-export-data (plist-get info :title) info) - "")) + (with-title (plist-get info :with-title)) + (title (org-export-data + (when with-title (plist-get info :title)) info)) + (subtitle (org-export-data + (when with-title + (org-element-parse-secondary-string + (plist-get info :subtitle) + (org-element-restriction 'keyword))) + info)) (author (and (plist-get info :with-author) (let ((auth (plist-get info :author))) (and auth (org-export-data auth info))))) @@ -1012,8 +1019,12 @@ INFO is a plist used as a communication channel." (let* ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)) ;; Format TITLE. It may be filled if it is too wide, ;; that is wider than the two thirds of the total width. - (title-len (min (length title) (/ (* 2 text-width) 3))) + (title-len (min (max (length title) + (length subtitle)) + (/ (* 2 text-width) 3))) (formatted-title (org-ascii--fill-string title title-len info)) + (formatted-subtitle (when (org-string-nw-p subtitle) + (org-ascii--fill-string subtitle title-len info))) (line (make-string (min (+ (max title-len @@ -1025,6 +1036,7 @@ INFO is a plist used as a communication channel." (concat line "\n" (unless utf8p "\n") (upcase formatted-title) + (and formatted-subtitle (concat "\n" formatted-subtitle)) (cond ((and (org-string-nw-p author) (org-string-nw-p email)) (concat "\n\n" author "\n" email)) diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el index 5d0b55d..b9b3e8c 100644 --- a/lisp/ox-beamer.el +++ b/lisp/ox-beamer.el @@ -133,6 +133,16 @@ You might want to put e.g. \"allowframebreaks=0.9\" here." :type '(string :tag "Outline frame options")) +(defcustom org-beamer-subtitle-format "\\subtitle{%s}" + "Format string used for transcoded subtitle. +The format string should have at most one \"%s\"-expression, +which is replaced with the subtitle." + :group 'org-export-beamer + :version "25.1" + :package-version '(Org . "8.3") + :type '(string :tag "Format string")) + + ;;; Internal Variables @@ -233,6 +243,7 @@ Return overlay specification, as a string, or nil." :options-alist '((:headline-levels nil "H" org-beamer-frame-level) (:latex-class "LATEX_CLASS" nil "beamer" t) + (:beamer-subtitle-format nil nil org-beamer-subtitle-format) (:beamer-column-view-format "COLUMNS" nil org-beamer-column-view-format) (:beamer-theme "BEAMER_THEME" nil org-beamer-theme) (:beamer-color-theme "BEAMER_COLOR_THEME" nil nil t) @@ -810,7 +821,12 @@ information." "Return complete document string after Beamer conversion. CONTENTS is the transcoded contents string. INFO is a plist holding export options." - (let ((title (org-export-data (plist-get info :title) info))) + (let ((title (org-export-data (plist-get info :title) info)) + (subtitle (org-export-data + (org-element-parse-secondary-string + (plist-get info :subtitle) + (org-element-restriction 'keyword)) + info))) (concat ;; 1. Time-stamp. (and (plist-get info :time-stamp-file) @@ -877,6 +893,8 @@ holding export options." (format "\\date{%s}\n" (org-export-data date info))) ;; 7. Title (format "\\title{%s}\n" title) + (when (org-string-nw-p subtitle) + (concat (format (plist-get info :beamer-subtitle-format) subtitle) "\n")) ;; 8. Beamer-header (let ((beamer-header (plist-get info :beamer-header))) (when beamer-header diff --git a/lisp/ox-html.el b/lisp/ox-html.el index 7ed73f6..29cf9a4 100644 --- a/lisp/ox-html.el +++ b/lisp/ox-html.el @@ -108,7 +108,8 @@ (if a (org-html-export-to-html t s v b) (org-open-file (org-html-export-to-html nil s v b))))))) :options-alist - '((:html-doctype "HTML_DOCTYPE" nil org-html-doctype) + '((:subtitle "SUBTITLE" nil nil space) + (:html-doctype "HTML_DOCTYPE" nil org-html-doctype) (:html-container "HTML_CONTAINER" nil org-html-container-element) (:html-html5-fancy nil "html5-fancy" org-html-html5-fancy) (:html-link-use-abs-url nil "html-link-use-abs-url" org-html-link-use-abs-url) @@ -270,7 +271,12 @@ for the JavaScript code in this tag. (defconst org-html-style-default "