diff --git a/doc/org-manual.org b/doc/org-manual.org index b015b502c..fe21b5aca 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -13870,6 +13870,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. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 5e5f1954d..47e0ec40e 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -149,6 +149,19 @@ Example: A new =u= mode flag for Calc formulas in Org tables has been added to enable Calc units simplification mode. +*** LaTeX attributes for verse blocks + +The LaTeX export back-end now accepts four attributes for verse +blocks: + +- =:lines=, for marginal verse numbering; +- =:center= and =:versewidth=, for optical centering of the verses; +- =:latexcode=, for any arbitrary LaTeX code that can be included + within a LaTeX =verse= environment. + +The three first require the external LaTeX package =verse.sty=, wich +is an extension of the standard LaTeX environment. + ** Miscellaneous *** =org-goto-first-child= now works before first heading diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el index fb9fc3cd6..0931b7e9c 100644 --- a/lisp/ox-latex.el +++ b/lisp/ox-latex.el @@ -3506,6 +3506,17 @@ channel." "Transcode a VERSE-BLOCK element from Org to LaTeX. CONTENTS is verse block contents. INFO is a plist holding contextual information." + (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 @@ -3513,19 +3524,20 @@ contextual information." ;; 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}" + (format "%s\\begin{verse}%s\n%s\\end{verse}%s" + vwidth + attr (replace-regexp-in-string "^[ \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)) + 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))) - + (org-latex--delayed-footnotes-definitions verse-block info)))) ;;; End-user functions