[patch] ox-html.el: add html attribute (verse numbers) to verse blocks

[patch] ox-html.el: add html attribute (verse numbers) to verse blocks

[Juan Manuel Macías]

[-- Attachment #1: Type: text/plain, Size: 441 bytes --]

Hi all,

I believe that an html attribute to display marginal verse numbers in
sequence could be useful for certain content, as philological texts
(like here:
https://en.wikisource.org/wiki/The_Iliad_and_Odyssey_of_Homer_(Cowper)/Volume_2/The_Odyssey/Book_I)

The `lines' property must be a digit that is equivalent to the verse
numbers sequence:

#+ATTR_HTML: :lines 5
#+begin_verse
some verses...
#+end_verse

Best regards,

Juan Manuel 


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-html.el-add-verse-numbers-html-attribute-to-verse.patch --]
[-- Type: text/x-patch, Size: 3032 bytes --]

From 9f1bbef52989532e16873a1f75331af0c7b0401f Mon Sep 17 00:00:00 2001
From: Juan Manuel Macias <maciaschain@posteo.net>
Date: Sun, 3 Oct 2021 22:12:44 +0200
Subject: [PATCH] ox-html.el: add verse numbers html attribute to verse blocks

* lisp/ox-html.el (org-html-verse-block): add `lines' html attribute
---
 lisp/ox-html.el | 45 +++++++++++++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index a150b1fdb..4889bbe45 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -281,6 +281,7 @@ property on the headline itself.")
   .underline { text-decoration: underline; }
   #postamble p, #preamble p { font-size: 90%; margin: .2em; }
   p.verse { margin-left: 3%; }
+  .versenum {float:right;}
   pre {
     border: 1px solid #e6e6e6;
     border-radius: 3px;
@@ -3754,20 +3755,36 @@ information."
 
 ;;;; Verse Block
 
-(defun org-html-verse-block (_verse-block contents info)
-  "Transcode a VERSE-BLOCK element from Org to HTML.
-CONTENTS is verse block contents.  INFO is a plist holding
-contextual information."
-  (format "<p class=\"verse\">\n%s</p>"
-	  ;; Replace leading white spaces with non-breaking spaces.
-	  (replace-regexp-in-string
-	   "^[ \t]+" (lambda (m) (org-html--make-string (length m) "&#xa0;"))
-	   ;; Replace each newline character with line break.  Also
-	   ;; remove any trailing "br" close-tag so as to avoid
-	   ;; duplicates.
-	   (let* ((br (org-html-close-tag "br" nil info))
-		  (re (format "\\(?:%s\\)?[ \t]*\n" (regexp-quote br))))
-	     (replace-regexp-in-string re (concat br "\n") contents)))))
+(defun org-html-verse-block (verse-block contents info)
+    "Transcode a VERSE-BLOCK element from Org to HTML.
+    CONTENTS is verse block contents.  INFO is a plist holding
+    contextual information."
+    (let* ((lin (org-export-read-attribute :attr_html verse-block :lines))
+	   (versenum (if lin 0 ""))
+	   (seqverse (if lin (string-to-number lin) ""))
+	   (contents (if lin
+			 (with-temp-buffer
+			   (insert contents)
+			   (save-excursion
+			     (goto-char (point-min))
+			     (while (re-search-forward "^.+" nil t seqverse)
+			       (re-search-forward "$" nil t)
+			       (replace-match (concat "<span class=\"versenum\">"
+						      (number-to-string
+						       (setf versenum (+ versenum seqverse)))
+						      "</span>"))))
+			   (buffer-string))
+		       contents)))
+      (format "<p class=\"verse\">\n%s</p>"
+	      ;; Replace leading white spaces with non-breaking spaces.
+	      (replace-regexp-in-string
+	       "^[ \t]+" (lambda (m) (org-html--make-string (length m) "&#xa0;"))
+	       ;; Replace each newline character with line break.  Also
+	       ;; remove any trailing "br" close-tag so as to avoid
+	       ;; duplicates.
+	       (let* ((br (org-html-close-tag "br" nil info))
+		      (re (format "\\(?:%s\\)?[ \t]*\n" (regexp-quote br))))
+		 (replace-regexp-in-string re (concat br "\n") contents))))))
 
 \f
 ;;; Filter Functions
-- 
2.32.0

Re: [patch] ox-html.el: add html attribute (verse numbers) to verse blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> I believe that an html attribute to display marginal verse numbers in
> sequence could be useful for certain content, as philological texts
> (like here:
> https://en.wikisource.org/wiki/The_Iliad_and_Odyssey_of_Homer_(Cowper)/Volume_2/The_Odyssey/Book_I)
>
> The `lines' property must be a digit that is equivalent to the verse
> numbers sequence:
>
> #+ATTR_HTML: :lines 5
> #+begin_verse
> some verses...
> #+end_verse

Sounds reasonable. However, a more consistent way to handle line numbers
would be using switches, like what we do in EXAMPLE blocks. See
org-element-example-block-parser and 12.6 Literal Examples section of
the manual.

Similarly, line numbering support can be implemented across more
export backends.

Best,
Ihor

Re: [patch] ox-html.el: add html attribute (verse numbers) to verse blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> Sounds reasonable. However, a more consistent way to handle line numbers
> would be using switches, like what we do in EXAMPLE blocks. See
> org-element-example-block-parser and 12.6 Literal Examples section of
> the manual.

(I didn't remember that I had sent this patch...).

I'll take a look at the function you mention, when I have some time. In
any case, keep in mind that there are some conventions in verse
numbering: the white lines (separation between stanzas) are never
numbered and there is a sequence: 5 (first verse alwais remains
unnumbered) ... 10 ... 15 ..., which can be chosen using the :lines
attribute. :lines t defaults to a sequence of 5 verses. I chose this
syntax to follow the syntax of verse numbering with output to LaTeX
(another patch of mine that is already included in Org. In that case,
the 'verse' LaTeX package is used).

Verse numbering is a special case. In fact, a long time ago I wrote this
package: https://gitlab.com/maciaschain/org-verse-num

Best regards,

Juan Manuel 

Re: [patch] ox-html.el: add html attribute (verse numbers) to verse blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> Ihor Radchenko writes:
>
>> Sounds reasonable. However, a more consistent way to handle line numbers
>> would be using switches, like what we do in EXAMPLE blocks. See
>> org-element-example-block-parser and 12.6 Literal Examples section of
>> the manual.
>
> (I didn't remember that I had sent this patch...).
>
> I'll take a look at the function you mention, when I have some time. In
> any case, keep in mind that there are some conventions in verse
> numbering: the white lines (separation between stanzas) are never
> numbered and there is a sequence: 5 (first verse alwais remains
> unnumbered) ... 10 ... 15 ..., which can be chosen using the :lines
> attribute. :lines t defaults to a sequence of 5 verses. I chose this
> syntax to follow the syntax of verse numbering with output to LaTeX
> (another patch of mine that is already included in Org. In that case,
> the 'verse' LaTeX package is used).

The default switches syntax was originally designed for code block and
it generally supports continuous numbering across several subsequent
code blocks or starting the numbering from certain line. Will such
features be useful for verses?

Do you know if customizing :lines 5 to something other than 5 is often
needed? Maybe it can be an export option?

Best,
Ihor

Re: [patch] ox-html.el: add html attribute (verse numbers) to verse blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> The default switches syntax was originally designed for code block and
> it generally supports continuous numbering across several subsequent
> code blocks or starting the numbering from certain line. Will such
> features be useful for verses?
> [...]
> Do you know if customizing :lines 5 to something other than 5 is often
> needed? Maybe it can be an export option?

There are some differences between code numbering and verse numbering,
which is a convention used in Humanities and used by wikipedia and other
sites as well:

- The first verse is never numbered;

- White lines are not numbered;

- Numbering is added in a sequence, never continuously. The sequence is
  generally 5, but it is common to find sequences of 3, 10 or other
  digits (with that I answer your second question).

All of these features are performed in LaTeX by the 'verse' package, and
in the patch I submit for LaTeX I simply passed the options to these
package on LaTeX export. See:

(info (org)Verse blocks in LaTeX export)

The :lines attribute accepts any integer for the sequence: :lines 7
:lines 10, etc. :lines t defaults to 5. With this html patch I tried to
keep that same syntax. To format the verse numbering in html I was loosely
inspired by the way wikipedia does it.

I think line numbering is an idiosyncratic case and should not be
confused with standard line numbering as understood by Emacs linum-mode
or any other text editor. What I don't know is if the switches code
numbering could be reused in that peculiar case. An interesting
functionality could be to choose at which number the quoted fragment or
poem begins (because it is common to quote fragments of long poems. In
the LaTeX version this is obtained by :latexcode \setverselinenums{}{}

Nota bene: I understand that all these functionalities for verses are,
at the moment, a minority in Org, since Org has a small number of
Humanities users (here in Spain I try to gain followers among my
colleagues, but it is an arduous task). In any case, I think features
like this can attract more Humanities users...

Best regards,

Juan Manuel 

Re: [patch] ox-html.el: add html attribute (verse numbers) to verse blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> Nota bene: I understand that all these functionalities for verses are,
> at the moment, a minority in Org, since Org has a small number of
> Humanities users (here in Spain I try to gain followers among my
> colleagues, but it is an arduous task). In any case, I think features
> like this can attract more Humanities users...

I do like the proposed feature. However, I'd prefer if instead of
introducing a whole new functionality we could extend the existing one.
This approach generally leads to code that is easier to maintain.

> There are some differences between code numbering and verse numbering,
> which is a convention used in Humanities and used by wikipedia and other
> sites as well:
>
> - The first verse is never numbered;
>
> - White lines are not numbered;
>
> - Numbering is added in a sequence, never continuously. The sequence is
>   generally 5, but it is common to find sequences of 3, 10 or other
>   digits (with that I answer your second question).
> ...
> I think line numbering is an idiosyncratic case and should not be
> confused with standard line numbering as understood by Emacs linum-mode
> or any other text editor. What I don't know is if the switches code
> numbering could be reused in that peculiar case. An interesting
> functionality could be to choose at which number the quoted fragment or
> poem begins (because it is common to quote fragments of long poems. In
> the LaTeX version this is obtained by :latexcode \setverselinenums{}{}

From the above, the verse numbering looks simply like an extended line
numbering. Normal line numbering can be thought as a subset of the
proposed features.

Best,
Ihor