From fa6b7bf25cdba052f9388f8a646223ce6ccb580f Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Tue, 20 Jun 2017 09:17:37 +0200
Subject: [PATCH] ox-texinfo: Fix location of text before first headline

* doc/org.texi (Info directory file): Fix node name.
(Headings and sectioning structure): Document location of text before
  first headline.
(A Texinfo example): Update example.

* lisp/ox-texinfo.el (org-texinfo-template): Handle contents of very
  first section.
(org-texinfo-section): Ignore very first section.

According to Texinfo specifications, Top node contents should not
appear in printed output.  Move it near "@top" command, within
"@ifnottex".
---
 doc/org.texi       | 22 +++++++++++++++++++---
 lisp/ox-texinfo.el | 21 ++++++++++++++-------
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 3c6be045e..be02b9722 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13600,8 +13600,14 @@ Copyright information is printed on the back of the title page.
   Copyright \copy 2016 Free Software Foundation, Inc.
 @end example
 
-@node Texinfo @samp{Top} node
-@subsection Texinfo @samp{Top} node
+@node Info directory file
+@subsection Info directory file
+@cindex @samp{dir} file, in Texinfo export
+@cindex Texinfo export, @samp{dir} file
+@cindex Info directory file, in Texinfo export
+@cindex Texinfo export, Info directory file
+@cindex @code{install-info} parameters, in Texinfo export
+@cindex Texinfo export, @code{install-info} parameters
 
 @cindex #+TEXINFO_DIR_CATEGORY
 @cindex #+TEXINFO_DIR_TITLE
@@ -13612,7 +13618,7 @@ This Info file's metadata has variables for category, title, and description:
 @code{#+TEXINFO_DIR_DESC} that establish where in the Info hierarchy the file
 fits.
 
-Here's an example that writes to the @samp{Top} node:
+Here is an example that writes to the Info directory file:
 
 @example
 #+TEXINFO_DIR_CATEGORY: Emacs
@@ -13661,6 +13667,13 @@ entry:
   :END:
 @end example
 
+@cindex The Top node, in Texinfo export
+@cindex Texinfo export, Top node
+The text before the first headline belongs to the @samp{Top} node, i.e., the
+node in which a reader enters an Info manual.  As such, it is expected not to
+appear in printed output generated from the @file{.texi} file.  @inforef{The
+Top Node,,texinfo}, for more information.
+
 @node Indices
 @subsection Indices
 
@@ -13825,6 +13838,9 @@ Texts,,texinfo} for an equivalent example using Texinfo code.
 
 #+TEXINFO_PRINTED_TITLE: GNU Sample
 
+This manual is for GNU Sample (version @{@{@{version@}@}@},
+@{@{@{updated@}@}@}).
+
 * Copying
   :PROPERTIES:
   :COPYING:  t
diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el
index cd926e2d8..3477baec9 100644
--- a/lisp/ox-texinfo.el
+++ b/lisp/ox-texinfo.el
@@ -624,7 +624,8 @@ holding export options."
      "@titlepage\n"
      (when (plist-get info :with-title)
        (concat
-	(format "@title %s\n" (or (plist-get info :texinfo-printed-title) title ""))
+	(format "@title %s\n"
+		(or (plist-get info :texinfo-printed-title) title ""))
 	(let ((subtitle (plist-get info :subtitle)))
 	  (when subtitle
 	    (format "@subtitle %s\n"
@@ -650,10 +651,17 @@ holding export options."
      "@end titlepage\n\n"
      ;; Table of contents.
      (and (plist-get info :with-toc) "@contents\n\n")
-     ;; Configure Top Node when not for Tex
+     ;; Configure Top Node when not for TeX.  Also include contents
+     ;; from the first section of the document.
      "@ifnottex\n"
      "@node Top\n"
      (format "@top %s\n" title)
+     (let* ((first-section
+	     (org-element-map (plist-get info :parse-tree) 'section
+	       #'identity info t '(headline)))
+	    (top-contents
+	     (org-export-data (org-element-contents first-section) info)))
+       (and (org-string-nw-p top-contents) (concat "\n" top-contents)))
      (and copying "@insertcopying\n")
      "@end ifnottex\n\n"
      ;; Menu.
@@ -1353,11 +1361,10 @@ contextual information."
   "Transcode a SECTION element from Org to Texinfo.
 CONTENTS holds the contents of the section.  INFO is a plist
 holding contextual information."
-  (org-trim
-   (concat contents
-	   "\n"
-	   (let ((parent (org-export-get-parent-headline section)))
-	     (and parent (org-texinfo-make-menu parent info))))))
+  (let ((parent (org-export-get-parent-headline section)))
+    (when parent			;ignore very first section
+      (org-trim
+       (concat contents "\n" (org-texinfo-make-menu parent info))))))
 
 ;;;; Special Block