org-element: OPTIONAL_TITLE becomes ALT_TITLE property

* lisp/org-element.el (org-element-headline-parser):
  Rename :optional-title into :alt-title.
* lisp/ox.el (org-export-get-alt-title): Renamed from
  `org-export-get-optional-title'.
* lisp/ox-ascii.el (org-ascii--build-title): Apply name change.
* lisp/ox-html.el (org-html--format-toc-headline): Apply name change.
* lisp/ox-latex.el (org-latex-headline): Apply name change.
* lisp/ox-texinfo.el (org-texinfo--get-node,
  org-texinfo--generate-menu-items): Apply name change.
* testing/lisp/test-ox.el: Update tests.
* doc/org.texi (Table of contents): Update documentation.

doc/org.texi

@@ -9187,11 +9187,11 @@ The same @code{TOC} keyword can also generate a list of all tables
 #+TOC: tables             (build a list of tables)
 @end example
 
-@cindex property, OPTIONAL_TITLE
+@cindex property, ALT_TITLE
 The headline's title usually determines its corresponding entry in a table of
 contents.  However, it is possible to specifify an alternative title by
-setting @code{OPTIONAL_TITLE} property accordingly.  It will then be used
-when building the table.
+setting @code{ALT_TITLE} property accordingly.  It will then be used when
+building the table.
 
 @node Lists, Paragraphs, Table of contents, Structural markup elements
 @subheading Lists

lisp/org-element.el

@@ -728,7 +728,7 @@ CONTENTS is the contents of the footnote-definition."
   "Parse a headline.
 
 Return a list whose CAR is `headline' and CDR is a plist
-containing `:raw-value', `:title', `:optional-title', `:begin',
+containing `:raw-value', `:title', `:alt-title', `:begin',
 `:end', `:pre-blank', `:hiddenp', `:contents-begin' and
 `:contents-end', `:level', `:priority', `:tags',
 `:todo-keyword',`:todo-type', `:scheduled', `:deadline',
@@ -847,13 +847,13 @@ Assume point is at beginning of the headline."
 			  :quotedp quotedp)
 		    time-props
 		    standard-props))))
-	(let ((opt-title (org-element-property :OPTIONAL_TITLE headline)))
-	  (when opt-title
+	(let ((alt-title (org-element-property :ALT_TITLE headline)))
+	  (when alt-title
 	    (org-element-put-property
-	     headline :optional-title
-	     (if raw-secondary-p opt-title
+	     headline :alt-title
+	     (if raw-secondary-p alt-title
 	       (org-element-parse-secondary-string
-		opt-title (org-element-restriction 'headline) headline)))))
+		alt-title (org-element-restriction 'headline) headline)))))
 	(org-element-put-property
 	 headline :title
 	 (if raw-secondary-p raw-value

lisp/ox-ascii.el

@@ -566,7 +566,7 @@ possible.  It doesn't apply to `inlinetask' elements."
 	 (text
 	  (org-trim
 	   (org-export-data
-	    (if (and toc headlinep) (org-export-get-optional-title element info)
+	    (if (and toc headlinep) (org-export-get-alt-title element info)
 	      (org-element-property :title element))
 	    info)))
 	 (todo

lisp/ox-html.el

@@ -1605,7 +1605,7 @@ INFO is a plist used as a communication channel."
 	    ;; Body.
 	    (concat section-number
 		    (org-export-data
-		     (org-export-get-optional-title headline info) info)
+		     (org-export-get-alt-title headline info) info)
 		    (and tags "   ") (org-html--tags tags)))))
 
 (defun org-html-list-of-listings (info)

lisp/ox-latex.el

@@ -1481,7 +1481,7 @@ holding contextual information."
 	       (funcall org-latex-format-headline-function
 			todo todo-type priority
 			(org-export-data
-			 (org-export-get-optional-title headline info) info)
+			 (org-export-get-alt-title headline info) info)
 			(and (eq (plist-get info :with-tags) t) tags))))
 	  (if (and opt-title (string-match "\\`\\\\\\(.*?[^*]\\){" section-fmt))
 	      (format (replace-match "\\1[%s]" nil nil section-fmt 1)

lisp/ox-texinfo.el

@@ -442,7 +442,7 @@ See `org-texinfo-text-markup-alist' for details."
 (defun org-texinfo--get-node (headline info)
   "Return node entry associated to HEADLINE.
 INFO is a plist used as a communication channel."
-  (let ((menu-title (org-export-get-optional-title headline info)))
+  (let ((menu-title (org-export-get-alt-title headline info)))
     (org-texinfo--sanitize-menu
      (replace-regexp-in-string
       "%" "%%"
@@ -576,7 +576,7 @@ menu using `org-texinfo--format-menu'."
   (loop for headline in items collect
 	(let* ((menu-title (org-texinfo--sanitize-menu
 			    (org-export-data
-			     (org-export-get-optional-title headline info)
+			     (org-export-get-alt-title headline info)
 			     info)))
 	       (title (org-texinfo--sanitize-menu
 		       (org-texinfo--sanitize-headline

lisp/ox.el

@@ -3419,6 +3419,10 @@ INFO is the plist used as a communication channel."
 ;; `org-export-get-tags', `org-export-get-category' and
 ;; `org-export-get-node-property' extract useful information from an
 ;; headline or a parent headline.  They all handle inheritance.
+;;
+;; `org-export-get-alt-title' tries to retrieve an alternative title,
+;; as a secondary string, suitable for table of contents.  It falls
+;; back onto default title.
 
 (defun org-export-get-relative-level (headline info)
   "Return HEADLINE relative level within current parsed tree.
@@ -3552,11 +3556,11 @@ fail, the fall-back value is \"???\"."
 	(and file (file-name-sans-extension (file-name-nondirectory file))))
       "???"))
 
-(defun org-export-get-optional-title (headline info)
-  "Return optional title for HEADLINE, as a secondary string.
+(defun org-export-get-alt-title (headline info)
+  "Return alternative title for HEADLINE, as a secondary string.
 INFO is a plist used as a communication channel.  If no optional
 title is defined, fall-back to the regular title."
-  (or (org-element-property :optional-title headline)
+  (or (org-element-property :alt-title headline)
       (org-element-property :title headline)))
 
 (defun org-export-first-sibling-p (headline info)

testing/lisp/test-ox.el

@@ -1046,20 +1046,20 @@ Paragraph[fn:1]"
   (should (equal (org-export-number-to-roman 1449) "MCDXLIX")))
 
 (ert-deftest test-org-export/get-optional-title ()
-  "Test `org-export-get-optional-title' specifications."
-  ;; If OPTIONAL_TITLE property is defined, use it.
+  "Test `org-export-get-alt-title' specifications."
+  ;; If ALT_TITLE property is defined, use it.
   (should
    (equal '("opt")
 	  (org-test-with-parsed-data
-	      "* Headline\n:PROPERTIES:\n:OPTIONAL_TITLE: opt\n:END:"
-	    (org-export-get-optional-title
+	      "* Headline\n:PROPERTIES:\n:ALT_TITLE: opt\n:END:"
+	    (org-export-get-alt-title
 	     (org-element-map tree 'headline 'identity info t)
 	     info))))
   ;; Otherwise, fall-back to regular title.
   (should
    (equal '("Headline")
 	  (org-test-with-parsed-data "* Headline"
-	    (org-export-get-optional-title
+	    (org-export-get-alt-title
 	     (org-element-map tree 'headline 'identity info t)
 	     info)))))