From e6fcc853c52d27d746e3ab985db2ac44e0f73453 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Wed, 11 Feb 2015 00:09:39 +0100
Subject: [PATCH] ox: Optional export of title

* ox.el (org-export-with-title): New variable.
* ox (org-export-options-alist),
  ox-ascii.el (org-ascii-template--document-title),
  ox-beamer.el (org-beamer-template), ox-html.el (org-html-template),
  ox-latex.el (org-latex-template), ox-man.el (org-man-template),
  ox-odt.el (org-odt-template), ox-org.el (org-org-template),
  ox-publish.el (org-publish-project-alist),
  ox-texinfo.el (org-texinfo-template),
  ox-groff.el (org-groff--mt-head): Use new variable.
* ox-koma-letter.el (org-koma-letter-use-title): Mark obsolete.
* test-ox.el (test-org-export/parse-option-keyword): Add :with-title.
* ORG-NEWS, org.texi: Mention org-export-with-title.

This is useful in e.g. ox-html where title can be set via
`org-html-preamble-template' or when using the {{{title}}}-macro.
---
 contrib/lisp/ox-groff.el       |  3 ++-
 contrib/lisp/ox-koma-letter.el | 14 +++-----------
 doc/org.texi                   |  5 +++++
 etc/ORG-NEWS                   |  6 ++++++
 lisp/ox-ascii.el               |  4 +++-
 lisp/ox-beamer.el              |  3 ++-
 lisp/ox-html.el                |  7 ++++---
 lisp/ox-latex.el               |  3 ++-
 lisp/ox-man.el                 |  3 ++-
 lisp/ox-odt.el                 |  3 ++-
 lisp/ox-org.el                 |  3 ++-
 lisp/ox-publish.el             |  3 ++-
 lisp/ox-texinfo.el             | 11 ++++++-----
 lisp/ox.el                     | 10 ++++++++++
 testing/lisp/test-ox.el        |  4 ++--
 15 files changed, 53 insertions(+), 29 deletions(-)

diff --git a/contrib/lisp/ox-groff.el b/contrib/lisp/ox-groff.el
index b618395cb..9f54f7167 100644
--- a/contrib/lisp/ox-groff.el
+++ b/contrib/lisp/ox-groff.el
@@ -563,7 +563,8 @@ See `org-groff-text-markup-alist' for details."
       (t (format ".AF \"%s\" \n" (or org-groff-organization "")))))
 
    ;; 2. Title
-   (let ((subtitle1 (plist-get attr :subtitle1))
+   (let ((title (if (plist-get info :with-title) title ""))
+	 (subtitle1 (plist-get attr :subtitle1))
          (subtitle2 (plist-get attr :subtitle2)))
 
      (cond
diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index de40fe651..dd3a0eaaa 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -338,16 +338,6 @@ This option can also be set with the OPTIONS keyword, e.g.:
   :group 'org-export-koma-letter
   :type 'boolean)
 
-(defcustom org-koma-letter-use-title t
-  "Non-nil means use a title in the letter if present.
-This option can also be set with the OPTIONS keyword,
-e.g. \"title:nil\".
-
-See also `org-koma-letter-prefer-subject' for the handling of
-title versus subject."
-  :group 'org-export-koma-letter
-  :type 'boolean)
-
 (defcustom org-koma-letter-default-class "default-koma-letter"
   "Default class for `org-koma-letter'.
 The value must be a member of `org-latex-classes'."
@@ -383,6 +373,9 @@ was not present."
 (defvar org-koma-letter-special-contents nil
   "Holds special content temporarily.")
 
+(make-obsolete-variable 'org-koma-letter-use-title
+			'org-export-with-title
+			"25.1" 'set)
 
 
 ;;; Define Back-End
@@ -418,7 +411,6 @@ was not present."
     (:with-phone nil "phone" org-koma-letter-use-phone)
     (:with-place nil "place" org-koma-letter-use-place)
     (:with-subject nil "subject" org-koma-letter-subject-format)
-    (:with-title nil "title" org-koma-letter-use-title)
     (:with-title-as-subject nil "title-subject" org-koma-letter-prefer-subject)
     ;; Special properties non-nil when a setting happened in buffer.
     ;; They are used to prioritize in-buffer settings over "lco"
diff --git a/doc/org.texi b/doc/org.texi
index dfb00afc3..406579b97 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10820,6 +10820,11 @@ Toggle inclusion of TODO keywords into exported text
 Toggle inclusion of tables (@code{org-export-with-tables}).
 @end table
 
+@item title:
+@vindex org-export-with-titles
+Toggle inclusion of title (@code{org-export-with-title}).
+@end table
+
 When exporting only a subtree, each of the previous keywords@footnote{With
 the exception of @samp{SETUPFILE}.} can be overridden locally by special node
 properties.  These begin with @samp{EXPORT_}, followed by the name of the
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 103828b46..03fcfb219 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -106,6 +106,8 @@ anymore.  The chosen hard coded quoting style conforms to POSIX.
 Setting this option to anything else that the default value (nil)
 would create invalid planning info.  This dangerous option is now
 removed.
+*** Removed option ~org-koma-letter-use-title~
+Use org-export-with-title instead.  See also below.
 ** New features
 *** Additional markup with =#+INCLUDE= keyword
 The content of the included file can now be optionally marked up, for
@@ -202,6 +204,10 @@ displayed as the sole window of the current frame.
 *** ~{{{date}}}~ macro supports optional formatting argument
 It is now possible to supply and optional formatting argument to
 ~{{{date}}}~. See manual for details.
+*** New option ~org-export-with-title~
+It is possible to suppress the title insertion with ~#+OPTIONS:
+title:nil~ or globally using the variable ~org-export-with-title~.
+
 ** 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 f7bc31918..c4b34cbbf 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -969,7 +969,9 @@ 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 (org-export-data (plist-get info :title) info))
+	 (title (if (plist-get info :with-title)
+		    (org-export-data (plist-get info :title) info)
+		  ""))
 	 (author (and (plist-get info :with-author)
 		      (let ((auth (plist-get info :author)))
 			(and auth (org-export-data auth info)))))
diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el
index f53b35972..a9ae39742 100644
--- a/lisp/ox-beamer.el
+++ b/lisp/ox-beamer.el
@@ -877,7 +877,8 @@ holding export options."
      "\\begin{document}\n\n"
      ;; 10. Title command.
      (org-element-normalize-string
-      (cond ((string= "" title) nil)
+      (cond ((not (plist-get info :with-title)) nil)
+	    ((string= "" title) nil)
 	    ((not (stringp org-latex-title-command)) nil)
 	    ((string-match "\\(?:[^%]\\|^\\)%s"
 			   org-latex-title-command)
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 3733319cb..50df52094 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -1848,9 +1848,10 @@ holding export options."
    (let ((div (assq 'content (plist-get info :html-divs))))
      (format "<%s id=\"%s\">\n" (nth 1 div) (nth 2 div)))
    ;; Document title.
-   (let ((title (plist-get info :title)))
-     (format "<h1 class=\"title\">%s</h1>\n"
-	     (org-export-data (or title "") info)))
+   (when (plist-get info :with-title)
+       (let ((title (plist-get info :title)))
+	 (format "<h1 class=\"title\">%s</h1>\n"
+		 (org-export-data (or title "") 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 d7514aa32..dd0521cd8 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -1260,7 +1260,8 @@ holding export options."
      ;; Title command.
      (let ((command (plist-get info :latex-title-command)))
        (org-element-normalize-string
-	(cond ((string= "" title) nil)
+	(cond ((not (plist-get info :with-title)) nil)
+	      ((string= "" title) nil)
 	      ((not (stringp command)) nil)
 	      ((string-match "\\(?:[^%]\\|^\\)%s" command)
 	       (format command title))
diff --git a/lisp/ox-man.el b/lisp/ox-man.el
index 4f3991bd6..59d107f3e 100644
--- a/lisp/ox-man.el
+++ b/lisp/ox-man.el
@@ -311,7 +311,8 @@ This function shouldn't be used for floats.  See
   "Return complete document string after Man 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 (when (plist-get :with-title)
+		  (org-export-data (plist-get info :title) info)))
         (attr (read (format "(%s)"
                             (mapconcat
                              #'identity
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index af22ca03c..b23e5f7c7 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -1508,7 +1508,8 @@ original parsed data.  INFO is a plist holding export options."
 
       ;; Preamble - Title, Author, Date etc.
       (insert
-       (let* ((title (org-export-data (plist-get info :title) info))
+       (let* ((title (and (plist-get info :with-title)
+			  (org-export-data (plist-get info :title) info)))
 	      (author (and (plist-get info :with-author)
 			   (let ((auth (plist-get info :author)))
 			     (and auth (org-export-data auth info)))))
diff --git a/lisp/ox-org.el b/lisp/ox-org.el
index 5f2d12695..eb5ce1190 100644
--- a/lisp/ox-org.el
+++ b/lisp/ox-org.el
@@ -164,7 +164,8 @@ as a communication channel."
 			(concat "#+OPTIONS: "
 				(org-element-property :value k)))))
 	       "\n"))
-   (format "#+TITLE: %s\n" (org-export-data (plist-get info :title) info))
+   (and (plist-get info :with-title)
+	(format "#+TITLE: %s\n" (org-export-data (plist-get info :title) info)))
    (and (plist-get info :with-date)
 	(let ((date (org-export-data (org-export-get-date info) info)))
 	  (and (org-string-nw-p date)
diff --git a/lisp/ox-publish.el b/lisp/ox-publish.el
index 49b46b126..3cca0c958 100644
--- a/lisp/ox-publish.el
+++ b/lisp/ox-publish.el
@@ -175,6 +175,7 @@ included.  See the back-end documentation for more information.
   :with-footnotes           `org-export-with-footnotes'
   :with-inlinetasks         `org-export-with-inlinetasks'
   :with-latex               `org-export-with-latex'
+  :with-planning            `org-export-with-planning'
   :with-priority            `org-export-with-priority'
   :with-properties          `org-export-with-properties'
   :with-smart-quotes        `org-export-with-smart-quotes'
@@ -186,7 +187,7 @@ included.  See the back-end documentation for more information.
   :with-tags                `org-export-with-tags'
   :with-tasks               `org-export-with-tasks'
   :with-timestamps          `org-export-with-timestamps'
-  :with-planning            `org-export-with-planning'
+  :with-title               `org-export-with-title'
   :with-todo-keywords       `org-export-with-todo-keywords'
 
 The following properties may be used to control publishing of
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index 0e330080a..68ebd1908 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -568,11 +568,12 @@ holding export options."
      ;; Title
      "@finalout\n"
      "@titlepage\n"
-     (format "@title %s\n" (or (plist-get info :texinfo-printed-title) title))
-     (let ((subtitle (plist-get info :subtitle)))
-       (and subtitle
-	    (org-element-normalize-string
-	     (replace-regexp-in-string "^" "@subtitle " subtitle))))
+     (when (plist-get info :with-title)
+       (format "@title %s\n" (or (plist-get info :texinfo-printed-title) title))
+       (let ((subtitle (plist-get info :subtitle)))
+	 (and subtitle
+	      (org-element-normalize-string
+	       (replace-regexp-in-string "^" "@subtitle " subtitle)))))
      (when (plist-get info :with-author)
        (concat
 	;; Primary author.
diff --git a/lisp/ox.el b/lisp/ox.el
index cdfc8ed78..ac4fde971 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -137,6 +137,7 @@
     (:with-tags nil "tags" org-export-with-tags)
     (:with-tasks nil "tasks" org-export-with-tasks)
     (:with-timestamps nil "<" org-export-with-timestamps)
+    (:with-title nil "title" org-export-with-title)
     (:with-todo-keywords nil "todo" org-export-with-todo-keywords))
   "Alist between export properties and ways to set them.
 
@@ -743,6 +744,15 @@ e.g. \"tasks:nil\"."
 	  (repeat :tag "Specific TODO keywords"
 		  (string :tag "Keyword"))))
 
+(defcustom org-export-with-title t
+  "Non-nil means print title into the exported file.
+This option can also be set with the OPTIONS keyword,
+e.g. \"title:nil\"."
+  :group 'org-export-general
+  :version "25.1"
+  :package-version '(Org . 8.3)
+  :type 'boolean)
+
 (defcustom org-export-time-stamp-file t
   "Non-nil means insert a time stamp into the exported file.
 The time stamp shows when the file was created.  This option can
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 79b5c69b8..4a74ab3bb 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -111,7 +111,7 @@ variable, and communication channel under `info'."
     (org-export--parse-option-keyword
      "H:1 num:t \\n:t timestamp:t arch:t author:t creator:t d:t email:t
  *:t e:t ::t f:t pri:t -:t ^:t toc:t |:t tags:t tasks:t <:t todo:t inline:nil
- stat:t")
+ stat:t title:t")
     '(:headline-levels
       1 :preserve-breaks t :section-numbers t :time-stamp-file t
       :with-archived-trees t :with-author t :with-creator t :with-drawers t
@@ -119,7 +119,7 @@ variable, and communication channel under `info'."
       :with-footnotes t :with-inlinetasks nil :with-priority t
       :with-special-strings t :with-statistics-cookies t :with-sub-superscript t
       :with-toc t :with-tables t :with-tags t :with-tasks t :with-timestamps t
-      :with-todo-keywords t)))
+      :with-title t :with-todo-keywords t)))
   ;; Test some special values.
   (should
    (equal
-- 
2.11.4.GIT