ox-latex.el: Support specific attributes for verse block

* lisp/ox-latex.el (org-latex-verse-block): Support verse-specific
attributes.

* doc/org-manual.org (Verse blocks in LaTeX export): New section.

Link: https://orgmode.org/list/874kfdn0k5.fsf@posteo.net/

doc/org-manual.org

@@ -13871,6 +13871,54 @@ The LaTeX export back-end converts horizontal rules by the specified
 -----
 #+end_example
 
+*** Verse blocks in LaTeX export
+:PROPERTIES:
+:DESCRIPTION: Attributes specific to special blocks.
+:END:
+
+#+cindex: verse blocks, in @LaTeX{} export
+#+cindex: @samp{ATTR_LATEX}, keyword
+
+The LaTeX export back-end accepts four attributes for verse blocks:
+=:lines=, =:center=, =:versewidth= and =:latexcode=. The three first
+require the external LaTeX package =verse.sty=, wich is an extension
+of the standard LaTeX environment. The purpose of these attributes is
+explained below.
+
+- =:lines= :: To add marginal verse numbering. Its value is an
+  integer, the sequence in which the verses should be numbered.
+- =:center= :: With value =t= all the verses on the page are optically
+  centered (a typographic convention for poetry), taking as a
+  reference the longest verse, which must be indicated by the
+  attribute =:versewidth=.
+- =:versewidth= :: Its value is a literal text string with the longest
+  verse.
+- =:latexcode= :: It accepts any arbitrary LaTeX code that can be
+  included within a LaTeX =verse= environment.
+
+A complete example with Shakespeare's first sonnet:
+
+#+begin_src org
+,#+ATTR_LaTeX: :center t :latexcode \color{red} :lines 5
+,#+ATTR_LaTeX: :versewidth Feed’st thy light’st flame with self-substantial fuel,
+,#+begin_verse
+From fairest creatures we desire increase,
+That thereby beauty’s rose might never die,
+But as the riper should by time decrease,
+His tender heir mught bear his memeory:
+But thou, contracted to thine own bright eyes,
+Feed’st thy light’st flame with self-substantial fuel,
+Making a famine where abundance lies,
+Thyself thy foe, to thy sweet self too cruel.
+Thou that art now the world’s fresh ornament
+And only herald to the gaudy spring,
+Within thine own bud buriest thy content
+And, tender churl, makest waste in niggarding.
+Pity the world, or else this glutton be,
+To eat the world’s due, by the grave and thee.
+,#+end_verse
+#+end_src
+
 ** Markdown Export
 :PROPERTIES:
 :DESCRIPTION: Exporting to Markdown.

lisp/ox-latex.el

@@ -3526,26 +3526,37 @@ channel."
   "Transcode a VERSE-BLOCK element from Org to LaTeX.
 CONTENTS is verse block contents.  INFO is a plist holding
 contextual information."
-  (concat
-   (org-latex--wrap-label
-    verse-block
-    ;; In a verse environment, add a line break to each newline
-    ;; character and change each white space at beginning of a line
-    ;; into a space of 1 em.  Also change each blank line with
-    ;; a vertical space of 1 em.
-    (format "\\begin{verse}\n%s\\end{verse}"
-	    (replace-regexp-in-string
-	     "^[ \t]+" (lambda (m) (format "\\hspace*{%dem}" (length m)))
-	     (replace-regexp-in-string
-	      "^[ \t]*\\\\\\\\$" "\\vspace*{1em}"
+  (let* ((lin (org-export-read-attribute :attr_latex verse-block :lines))
+         (latcode (org-export-read-attribute :attr_latex verse-block :latexcode))
+         (cent (org-export-read-attribute :attr_latex verse-block :center))
+         (attr (concat
+	        (if cent "[\\versewidth]" "")
+	        (if lin (format "\n\\poemlines{%s}" lin) "")
+	        (if latcode (format "\n%s" latcode) "")))
+         (versewidth (org-export-read-attribute :attr_latex verse-block :versewidth))
+         (vwidth (if versewidth (format "\\settowidth{\\versewidth}{%s}\n" versewidth) ""))
+         (linreset (if lin "\n\\poemlines{0}" "")))
+    (concat
+     (org-latex--wrap-label
+      verse-block
+      ;; In a verse environment, add a line break to each newline
+      ;; character and change each white space at beginning of a line
+      ;; into a space of 1 em.  Also change each blank line with
+      ;; a vertical space of 1 em.
+      (format "%s\\begin{verse}%s\n%s\\end{verse}%s"
+	      vwidth
+	      attr
 	      (replace-regexp-in-string
-	       "\\([ \t]*\\\\\\\\\\)?[ \t]*\n" "\\\\\n"
-	       contents nil t) nil t) nil t))
-    info)
-   ;; Insert footnote definitions, if any, after the environment, so
-   ;; the special formatting above is not applied to them.
-   (org-latex--delayed-footnotes-definitions verse-block info)))
-
+	       "^[ \t]+" (lambda (m) (format "\\hspace*{%dem}" (length m)))
+	       (replace-regexp-in-string
+	        "^[ \t]*\\\\\\\\$" "\\vspace*{1em}"
+	        (replace-regexp-in-string
+	         "\\([ \t]*\\\\\\\\\\)?[ \t]*\n" "\\\\\n"
+	         contents nil t) nil t) nil t) linreset)
+      info)
+     ;; Insert footnote definitions, if any, after the environment, so
+     ;; the special formatting above is not applied to them.
+     (org-latex--delayed-footnotes-definitions verse-block info))))
 
 
 ;;; End-user functions