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

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

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"

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

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.

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

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)

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.

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

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

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

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)

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

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.

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

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