[PATCH] Derive non-default start value for ordered list

[PATCH] Derive non-default start value for ordered list

[Jens Lechtenboerger]

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

Hi there,

currently, we have to write the following to continue an ordered
list from a value different from 1:

42. [@42] Answer
43. Question?

The requirement to type redundant information with the @-syntax
always struck me as odd.  For my export backend org-re-reveal, I
recently received a request to export lists without @-syntax to
their “correct” start values [1].

Before working on my backend, I’d like to ask for feedback: Why was
the @-syntax introduced?  Of what non-obvious effects should I be
aware?

What do you think about the attached patch that allows to omit the
@-syntax?  Controlled by the new variable
org-list-use-first-bullet-as-non-standard-counter, the code assigns
a counter value to the first list item from its bullet string if the
item
1. does not specify a counter itself,
2. has an alphanumeric bullet, and
3. does not have a default start value (1, a, A).

I hacked this as postprocessing step on the list’s struct.  Maybe an
Org expert could suggest how to do this in one pass?

Best wishes
Jens

P.S.  I did not work on documentation yet as I’m not sure that this
change is acceptable.

[1] https://gitlab.com/oer/org-re-reveal/merge_requests/27


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Use-bullet-as-non-standard-counter.patch --]
[-- Type: text/x-diff, Size: 4277 bytes --]

From 2eea43d84687259633f847bd17883e5fe578b6bc Mon Sep 17 00:00:00 2001
From: Jens Lechtenboerger <jens.lechtenboerger@fsfe.org>
Date: Sun, 1 Dec 2019 21:17:43 +0100
Subject: [PATCH] Use bullet as non-standard counter

* lisp/org-list.el: New variable
org-list-use-first-bullet-as-non-standard-counter and new function
org-list-struct-maybe-add-counters to assign counters from bullets
that indicate non-standard start values.
(org-list-struct): Use new variable and function.

* lisp/org-element.el (org-element-item-parser): Use new variable and
mirror behavior of org-list.el.
---
 lisp/org-element.el | 19 ++++++++++++++++++-
 lisp/org-list.el    | 33 ++++++++++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/lisp/org-element.el b/lisp/org-element.el
index 56b3cc413..80b7cab99 100644
--- a/lisp/org-element.el
+++ b/lisp/org-element.el
@@ -1269,6 +1269,8 @@ Assume point is at the beginning of the item."
     (beginning-of-line)
     (looking-at org-list-full-item-re)
     (let* ((begin (point))
+           (prevs (org-list-prevs-alist struct))
+           (prev-item (org-list-get-prev-item begin struct prevs))
 	   (bullet (match-string-no-properties 1))
 	   (checkbox (let ((box (match-string 3)))
 		       (cond ((equal "[ ]" box) 'off)
@@ -1277,7 +1279,22 @@ Assume point is at the beginning of the item."
 	   (counter (let ((c (match-string 2)))
 		      (save-match-data
 			(cond
-			 ((not c) nil)
+			 ((not c)
+			  (and
+			   org-list-use-first-bullet-as-non-standard-counter
+			   ;; As in org-list-struct-maybe-add-counters,
+			   ;; assign non-standard counter from bullet of
+			   ;; first list item.  To exclude "A", check range
+			   ;; from "B".
+                           (not prev-item)
+                           (or (and (string-match "[B-Zb-z]" bullet)
+				    (- (string-to-char
+					(upcase (match-string 0 bullet)))
+				       64))
+                               (and (string-match "[0-9]+" bullet)
+				    (string< "1" (match-string 0 bullet))
+                                    (string-to-number
+                                     (match-string 0 bullet))))))
 			 ((string-match "[A-Za-z]" c)
 			  (- (string-to-char (upcase (match-string 0 c)))
 			     64))
diff --git a/lisp/org-list.el b/lisp/org-list.el
index c4aef32fc..fe8742f42 100644
--- a/lisp/org-list.el
+++ b/lisp/org-list.el
@@ -336,6 +336,14 @@ clearly distinguish sub-items in a list."
   :version "24.1"
   :type 'integer)
 
+(defcustom org-list-use-first-bullet-as-non-standard-counter nil
+  "Non-nil means to use first bullet of an ordered list as counter.
+Then, you can start an ordered list with \"42. Answer\" instead of
+\"42. [@42] Answer\"."
+  :group 'org-plain-lists
+  :package-version '(Org . "9.3")
+  :type 'boolean)
+
 (defvar org-list-forbidden-blocks '("example" "verse" "src" "export")
   "Names of blocks where lists are not allowed.
 Names must be in lower case.")
@@ -731,7 +739,30 @@ Assume point is at an item."
       ;; 3. Associate each item to its end position.
       (org-list-struct-assoc-end struct end-lst)
       ;; 4. Return STRUCT
-      struct)))
+      (if org-list-use-first-bullet-as-non-standard-counter
+          (org-list-struct-maybe-add-counters struct)
+        struct))))
+
+(defun org-list-struct-maybe-add-counters (struct)
+  "Maybe add counters to first list items of STRUCT.
+For the first list items in STRUCT (those without previous item) that
+1. do not specify a counter,
+2. has an alphanumeric bullet, and
+3. do not have a default start value (1, a, A),
+set the counter to the item's bullet."
+  (let ((prevs (org-list-prevs-alist struct)))
+    (dolist (item struct)
+      (let ((prev-item (org-list-get-prev-item (nth 0 item) struct prevs)))
+        (unless prev-item
+          (let ((key (nth 0 item))
+                (fbullet (nth 2 item))
+                (fcounter (nth 3 item)))
+            (when (and (not fcounter)
+		       (string-match "[[:alnum:]]" fbullet))
+	      (let ((cand (match-string 0 fbullet)))
+		(unless (member cand '("1" "a" "A"))
+		  (org-list-set-nth 3 key struct cand))))))))
+    struct))
 
 (defun org-list-struct-assoc-end (struct end-list)
   "Associate proper ending point to items in STRUCT.
-- 
2.17.1

Re: [PATCH] Derive non-default start value for ordered list

[Samuel Wales]

i think it might be partlly a question of whether these numbers are
fixed things that refer to fixed items [like referring to sections in
a law that is not in the document] vs. being used to continue lists.

they are both legitimate uses.  in the first case, the @ syntax makes
sense to me, because it specifies a fixed alphanumber.  yes i made
that word up.

some exporters assume the numbers in the org source list don't matter
and start from 1 or the @ in the exported text.  so your solution
would be anomalous.

and i'm used to exporters doing that so it feels strange to me to rely
on the org text.  i view that as potentially changing.  what should
occur if you do something that renumbers it?


in the second case, the @ syntax and your solution both seem brittle
to me.  you might add to the first list.


i think there can be a third solution that would be less brittle.

just as a brainstorm, consider the common case of continued lists like

vvv
1.  asdf
2.  <<asdf-list-end>> asdf

a paragraph.

3.  [@asdf-list-end] asdf
^^^

this solution still fails if you have the first list in a separate
file.  therefore i propose org id to solve that.

for this, we could invoke the org id mechanism, or use id markers,
which is an old, unimplemented idea that can substitute for a bunch of
syntax with a consistent syntax.

but in any case the above illustrates a less brittle solution than @
numbers and using the existing number.

does that make any sense?

just a brainstorm, not to be taken too seriously if you think it's all wrong.


On 12/1/19, Jens Lechtenboerger <jens.lechtenboerger@fsfe.org> wrote:
> Hi there,
>
> currently, we have to write the following to continue an ordered
> list from a value different from 1:
>
> 42. [@42] Answer
> 43. Question?
>
> The requirement to type redundant information with the @-syntax
> always struck me as odd.  For my export backend org-re-reveal, I
> recently received a request to export lists without @-syntax to
> their “correct” start values [1].
>
> Before working on my backend, I’d like to ask for feedback: Why was
> the @-syntax introduced?  Of what non-obvious effects should I be
> aware?
>
> What do you think about the attached patch that allows to omit the
> @-syntax?  Controlled by the new variable
> org-list-use-first-bullet-as-non-standard-counter, the code assigns
> a counter value to the first list item from its bullet string if the
> item
> 1. does not specify a counter itself,
> 2. has an alphanumeric bullet, and
> 3. does not have a default start value (1, a, A).
>
> I hacked this as postprocessing step on the list’s struct.  Maybe an
> Org expert could suggest how to do this in one pass?
>
> Best wishes
> Jens
>
> P.S.  I did not work on documentation yet as I’m not sure that this
> change is acceptable.
>
> [1] https://gitlab.com/oer/org-re-reveal/merge_requests/27
>
>


-- 
The Kafka Pandemic

What is misopathy?
https://thekafkapandemic.blogspot.com/2013/10/why-some-diseases-are-wronged.html

The disease DOES progress. MANY people have died from it. And ANYBODY
can get it at any time.

Re: [PATCH] Derive non-default start value for ordered list

[Samuel Wales]

[note: id markers use org ids.]

On 12/1/19, Samuel Wales <samologist@gmail.com> wrote:
> i think it might be partlly a question of whether these numbers are
> fixed things that refer to fixed items [like referring to sections in
> a law that is not in the document] vs. being used to continue lists.
>
> they are both legitimate uses.  in the first case, the @ syntax makes
> sense to me, because it specifies a fixed alphanumber.  yes i made
> that word up.
>
> some exporters assume the numbers in the org source list don't matter
> and start from 1 or the @ in the exported text.  so your solution
> would be anomalous.
>
> and i'm used to exporters doing that so it feels strange to me to rely
> on the org text.  i view that as potentially changing.  what should
> occur if you do something that renumbers it?
>
>
> in the second case, the @ syntax and your solution both seem brittle
> to me.  you might add to the first list.
>
>
> i think there can be a third solution that would be less brittle.
>
> just as a brainstorm, consider the common case of continued lists like
>
> vvv
> 1.  asdf
> 2.  <<asdf-list-end>> asdf
>
> a paragraph.
>
> 3.  [@asdf-list-end] asdf
> ^^^
>
> this solution still fails if you have the first list in a separate
> file.  therefore i propose org id to solve that.
>
> for this, we could invoke the org id mechanism, or use id markers,
> which is an old, unimplemented idea that can substitute for a bunch of
> syntax with a consistent syntax.
>
> but in any case the above illustrates a less brittle solution than @
> numbers and using the existing number.
>
> does that make any sense?
>
> just a brainstorm, not to be taken too seriously if you think it's all
> wrong.
>
>
> On 12/1/19, Jens Lechtenboerger <jens.lechtenboerger@fsfe.org> wrote:
>> Hi there,
>>
>> currently, we have to write the following to continue an ordered
>> list from a value different from 1:
>>
>> 42. [@42] Answer
>> 43. Question?
>>
>> The requirement to type redundant information with the @-syntax
>> always struck me as odd.  For my export backend org-re-reveal, I
>> recently received a request to export lists without @-syntax to
>> their “correct” start values [1].
>>
>> Before working on my backend, I’d like to ask for feedback: Why was
>> the @-syntax introduced?  Of what non-obvious effects should I be
>> aware?
>>
>> What do you think about the attached patch that allows to omit the
>> @-syntax?  Controlled by the new variable
>> org-list-use-first-bullet-as-non-standard-counter, the code assigns
>> a counter value to the first list item from its bullet string if the
>> item
>> 1. does not specify a counter itself,
>> 2. has an alphanumeric bullet, and
>> 3. does not have a default start value (1, a, A).
>>
>> I hacked this as postprocessing step on the list’s struct.  Maybe an
>> Org expert could suggest how to do this in one pass?
>>
>> Best wishes
>> Jens
>>
>> P.S.  I did not work on documentation yet as I’m not sure that this
>> change is acceptable.
>>
>> [1] https://gitlab.com/oer/org-re-reveal/merge_requests/27
>>
>>
>
>
> --
> The Kafka Pandemic
>
> What is misopathy?
> https://thekafkapandemic.blogspot.com/2013/10/why-some-diseases-are-wronged.html
>
> The disease DOES progress. MANY people have died from it. And ANYBODY
> can get it at any time.
>


-- 
The Kafka Pandemic

What is misopathy?
https://thekafkapandemic.blogspot.com/2013/10/why-some-diseases-are-wronged.html

The disease DOES progress. MANY people have died from it. And ANYBODY
can get it at any time.

Re: [PATCH] Derive non-default start value for ordered list

[Nicolas Goaziou]

Hello,

Jens Lechtenboerger <jens.lechtenboerger@fsfe.org> writes:

> currently, we have to write the following to continue an ordered
> list from a value different from 1:
>
> 42. [@42] Answer
> 43. Question?
>
> The requirement to type redundant information with the @-syntax
> always struck me as odd.  For my export backend org-re-reveal, I
> recently received a request to export lists without @-syntax to
> their “correct” start values [1].
>
> Before working on my backend, I’d like to ask for feedback: Why was
> the @-syntax introduced?  Of what non-obvious effects should I be
> aware?
>
> What do you think about the attached patch that allows to omit the
> @-syntax?  Controlled by the new variable
> org-list-use-first-bullet-as-non-standard-counter, the code assigns
> a counter value to the first list item from its bullet string if the
> item
> 1. does not specify a counter itself,
> 2. has an alphanumeric bullet, and
> 3. does not have a default start value (1, a, A).

I think the current situation is better. It works, as advertised, and it
allows you to re-number any item in the list, not necessarily the first
one.

Of course, it may be less "elegant", but the overhead is negligible,
and, as a data point, I'd rather have continuation lists more visible
than not, as it could create confusion in the document.

I do not know about org-re-reveal, but included exporters do not display
the [@xxx] part. However, they use its value to start lists at an
appropriate number, if technically possible. I suggest org-re-reveal to
do the same if that's not the case.

Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Derive non-default start value for ordered list

[Jens Lechtenboerger]

On 2019-12-01, at 14:13, Samuel Wales wrote:

> i think it might be partlly a question of whether these numbers are
> fixed things that refer to fixed items [like referring to sections in
> a law that is not in the document] vs. being used to continue lists.
>
> they are both legitimate uses.  in the first case, the @ syntax makes
> sense to me, because it specifies a fixed alphanumber.  yes i made
> that word up.
>
> some exporters assume the numbers in the org source list don't matter
> and start from 1 or the @ in the exported text.

If I took the effort to type something, then that should not be
ignored by an exporter.

> so your solution would be anomalous.

But meet some users’ expectations.  Quite likely, those of new Org
users.

> and i'm used to exporters doing that so it feels strange to me to rely
> on the org text.

If text is ignored, I should not need to type it in the first
place.

> i view that as potentially changing.  what should
> occur if you do something that renumbers it?

If I renumber, then, of course, I want to see the new numbers after
export.

> in the second case, the @ syntax and your solution both seem brittle
> to me.  you might add to the first list.

I agree.

> i think there can be a third solution that would be less brittle.
>
> just as a brainstorm, consider the common case of continued lists like
>
> vvv
> 1.  asdf
> 2.  <<asdf-list-end>> asdf
>
> a paragraph.
>
> 3.  [@asdf-list-end] asdf
> ^^^

This would indeed be a cool solution.

Thanks
Jens

Re: [PATCH] Derive non-default start value for ordered list

[Jens Lechtenboerger]

On 2019-12-02, at 08:23, Nicolas Goaziou wrote:

> Jens Lechtenboerger <jens.lechtenboerger@fsfe.org> writes:
>
>> [...]
>> What do you think about the attached patch that allows to omit the
>> @-syntax?  Controlled by the new variable
>> org-list-use-first-bullet-as-non-standard-counter, the code assigns
>> a counter value to the first list item from its bullet string if the
>> item
>> 1. does not specify a counter itself,
>> 2. has an alphanumeric bullet, and
>> 3. does not have a default start value (1, a, A).
>
> I think the current situation is better. It works, as advertised, and it
> allows you to re-number any item in the list, not necessarily the first
> one.

One can still do this.

> Of course, it may be less "elegant", but the overhead is negligible,
> and, as a data point, I'd rather have continuation lists more visible
> than not, as it could create confusion in the document.

I understand.

> I do not know about org-re-reveal, but included exporters do not display
> the [@xxx] part. However, they use its value to start lists at an
> appropriate number, if technically possible. I suggest org-re-reveal to
> do the same if that's not the case.

My backend does this, but maybe the user did not know about the
@-syntax.  Also, he did not want to change all his preexisting
lists.

Thanks for your feedback
Jens