[PATCH] org-manual.org: $n$-th is not math

[PATCH] org-manual.org: $n$-th is not math

[Max Nikulin]

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

Hi,

yesterday an issue with $n$-th TeX markup was risen again. I think, the 
manual should not declare that it is supported. It is broken for a 
decade. So \(n\)-th should be suggested instead.

[-- Attachment #2: 0001-org-manual.org-n-th-is-not-math.patch --]
[-- Type: text/x-patch, Size: 2674 bytes --]

From 6feb228a1bcc485441bab707771e6d87a3d69671 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Wed, 15 Mar 2023 19:08:37 +0700
Subject: [PATCH] org-manual.org: $n$-th is not math
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/org-manual.org (LaTeX fragments): Do not state that dash is
allowed after single "$" math delimiter and recommend "\(...\)".

Detection of "$-" as closing math delimiters is broken since 2015 as a
side effect of using punctuation class in regular expressions while
dash is considered as a word constituent.  See commits
6779f8f424 and c0369a7984.  Bring the manual in accordance to the code
instead of allowing "($-2 change)" false positives.  Users who do not
like "\(...\)" constructs may use a helper for typing it and may change
how it is displayed to minimize visual noise by fontification, see

- Eric S Fraga to emacs-orgmode. Re: Depreciating TeX-style LaTeX
  fragments. Sun, 16 Jan 2022 12:10:30 +0000.
  <https://list.orgmode.org/87k0ezdgp5.fsf@ucl.ac.uk>
- Ihor Radchenko to emacs-orgmode. Re: [PATCH] Add support for $…$ latex
  fragments followed by a dash. Thu, 27 Jan 2022 16:28:10 +0800.
  <https://list.orgmode.org/87r18t7fc5.fsf@localhost>
---
 doc/org-manual.org | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 1c97d6aa8..7bb1ac637 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -11152,14 +11152,14 @@ *** LaTeX fragments
   =\begin= statement appears on a new line, preceded by only
   whitespace.
 
-- Text within the usual LaTeX math delimiters.  To avoid conflicts
-  with currency specifications, single =$= characters are only
-  recognized as math delimiters if the enclosed text contains at most
-  two line breaks, is directly attached to the =$= characters with no
-  whitespace in between, and if the closing =$= is followed by
-  whitespace, punctuation or a dash.  For the other delimiters, there
-  is no such restriction, so when in doubt, use =\(...\)= as inline
-  math delimiters.
+- Text within the usual LaTeX math delimiters.  Prefer =\(...\)= for
+  inline snippets.  The =$...$= alternative has some restrictions and
+  may be source of confusion.  To avoid conflicts with currency
+  specifications, single =$= characters are only recognized as math
+  delimiters if the enclosed text contains at most two line breaks, is
+  directly attached to the =$= characters with no whitespace in
+  between, and if the closing =$= is followed by whitespace or
+  punctuation (but not a dash).
 
 #+texinfo: @noindent
 For example:
-- 
2.25.1

Re: [PATCH] org-manual.org: $n$-th is not math

[Loris Bennett]

Max Nikulin <manikulin@gmail.com> writes:

[snip (17 lines)]

> Detection of "$-" as closing math delimiters is broken since 2015 as a

[snip (44 lines)]

Detection of "$-" as closing math delimiters has been broken since 2015 as a

-- 
This signature is currently under constuction.

Re: [PATCH] org-manual.org: $n$-th is not math

[Rudolf Adamkovič]

Bummer the dash will not be supported. :(

(I am super-happy with $...$, except for the dash case.)

Max Nikulin <manikulin@gmail.com> writes:

> Prefer =\(...\)= for + inline snippets.

Fragments, not snippets.  Right?

> The =$...$= alternative has some restrictions and may be source of confusion.

I am not a native speaker, but "may be a source of confusion" (note the "a")
sounds more correct.

Rudy
-- 
"It is no paradox to say that in our most theoretical moods we may be
nearest to our most practical applications."
-- Alfred North Whitehead, 1861-1947

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Max Nikulin]

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

Thanks to the reviewers.

On 16/03/2023 00:25, Rudolf Adamkovič wrote:
> Bummer the dash will not be supported. :(

You had an opportunity to submit an alternative patch fixing regexps.

I am neutral in respect to "$...$" vs. "\(...\)". The former is more 
prone to heuristics false positives.

What I do not like is that "$$...$$" and "\[...\]" are inline objects, 
not block level elements. However notion of paragraphs are different in 
Org and TeX.

>> Prefer =\(...\)= for + inline snippets.
> 
> Fragments, not snippets.  Right?

I agree with you that snippets are more related to export and fragments 
to LaTeX. See (info "(org) LaTeX math snippets")
https://orgmode.org/manual/LaTeX-math-snippets.html
though. It is about ODT however. Perhaps somebody should go through the 
manual to replace all LaTeX "snippets" to fragments for consistency.

[-- Attachment #2: v2-0001-org-manual.org-n-th-is-not-math.patch --]
[-- Type: text/x-patch, Size: 2686 bytes --]

From 6848a6fa844ceec20a3da7bad13f418ff3dae5d6 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Wed, 15 Mar 2023 19:08:37 +0700
Subject: [PATCH v2] org-manual.org: $n$-th is not math
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/org-manual.org (LaTeX fragments): Do not state that dash is
allowed after single "$" math delimiter and recommend "\(...\)".

Detection of "$-" as closing math delimiters has been broken since 2015
as a side effect of using punctuation class in regular expressions while
dash is considered as a word constituent.  See commits
6779f8f424 and c0369a7984.  Bring the manual in accordance to the code
instead of allowing "($-2 change)" false positives.  Users who do not
like "\(...\)" constructs may use a helper for typing it and may change
how it is displayed to minimize visual noise by fontification, see

- Eric S Fraga to emacs-orgmode. Re: Depreciating TeX-style LaTeX
  fragments. Sun, 16 Jan 2022 12:10:30 +0000.
  <https://list.orgmode.org/87k0ezdgp5.fsf@ucl.ac.uk>
- Ihor Radchenko to emacs-orgmode. Re: [PATCH] Add support for $…$ latex
  fragments followed by a dash. Thu, 27 Jan 2022 16:28:10 +0800.
  <https://list.orgmode.org/87r18t7fc5.fsf@localhost>
---
 doc/org-manual.org | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 1c97d6aa8..37fd3df14 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -11152,14 +11152,14 @@ *** LaTeX fragments
   =\begin= statement appears on a new line, preceded by only
   whitespace.
 
-- Text within the usual LaTeX math delimiters.  To avoid conflicts
-  with currency specifications, single =$= characters are only
-  recognized as math delimiters if the enclosed text contains at most
-  two line breaks, is directly attached to the =$= characters with no
-  whitespace in between, and if the closing =$= is followed by
-  whitespace, punctuation or a dash.  For the other delimiters, there
-  is no such restriction, so when in doubt, use =\(...\)= as inline
-  math delimiters.
+- Text within the usual LaTeX math delimiters.  Prefer =\(...\)= for
+  inline fragments.  The =$...$= alternative has some restrictions and
+  may be a source of confusion.  To avoid conflicts with currency
+  specifications, single =$= characters are only recognized as math
+  delimiters if the enclosed text contains at most two line breaks, is
+  directly attached to the =$= characters with no whitespace in
+  between, and if the closing =$= is followed by whitespace or
+  punctuation (but not a dash).
 
 #+texinfo: @noindent
 For example:
-- 
2.25.1

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> Subject: [PATCH v2] org-manual.org: $n$-th is not math

Applied, onto main.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Rudolf Adamkovič]

Max Nikulin <manikulin@gmail.com> writes:

>> Bummer the dash will not be supported. :(
>
> You had an opportunity to submit an alternative patch fixing regexps.

But why?  We have seen such attempts already, such as

  "[PATCH] Add support for $…$ latex fragments followed by a dash"

The attempts were always rejected.  So, just a "bummer".  :)

Rudy
-- 
"One can begin to reason only when a clear picture has been formed in
the imagination."
-- Walter Warwick Sawyer, Mathematician's Delight, 1943

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Ihor Radchenko]

Rudolf Adamkovič <salutis@me.com> writes:

> The attempts were always rejected.  So, just a "bummer".  :)

As I said in the linked message, supporting "-" will not solve the basic
issue, which is with the Org syntax not being LaTeX. Intra-word markup,
including $...$, requires workarounds. It is the trade-off we have to
take.

https://list.orgmode.org/87r18t7fc5.fsf@localhost

>>>   The problem with parsing is more than just supporting $i$-th and
>>>   similar. For example, AMS style guide explicitly advises against using
>>>   $i$-th in favour of $i$th [1]:
>>>
>>>       Do not hyphenate “th” expressions: xth, not x-th or xth .
>>>
>>>   We can theoretically make a change to support "-", but then it will be
>>>   logical to support $i$th as well. (If we don't some users will still be
>>>   confused after trying to write $i$th and then not getting the expected
>>>   results). In this question, it would make sense to implement
>>>   all-or-everything approach. Otherwise, confusion (like raised in this
>>>   thread) will be inevitable.
>>>
>>>   However, from point of view of Org mode parser, supporting $i$th is a
>>>   nightmare.  Remember that Org mode is _not_ LaTeX and we have to support
>>>   a lot more frivolous syntax (even in LaTeX, runaway $ is often a source
>>>   of cryptic compilation errors). Currently, we _must_ rely on heuristics
>>>   to determine $$-style latex fragments. I do not know any way to support
>>>   $$ syntax without creating deviations from LaTeX. Extending the
>>>   heuristics will not resolve the underlying ambiguity of $$ syntax, just
>>>   hide it within even more obscure cases.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Max Nikulin]

On 19/03/2023 18:08, Rudolf Adamkovič wrote:
> Max Nikulin writes:
>> You had an opportunity to submit an alternative patch fixing regexps.
> 
> But why?  We have seen such attempts already, such as
> 
>    "[PATCH] Add support for $…$ latex fragments followed by a dash"

I am sorry, I missed that this patch changes the same lines as commits 
mentioned in the comment to my patch. Sébastien Miquel would had more 
chances to convince people if, instead of referencing the thread related 
to deprecation of "$...$", the manual was cited with the commit that 
broke described behavior. So partially it is a communication issue.

I do not have strong opinion if support of $n$th is tightly bound to 
recognizing $n$-th. On the other hand I would not object deprecation of 
"$...$".

Ihor, if https://updates.orgmode.org/ is still maintained, could you, 
please, remove the entry related to this patch and 3 ones for
https://list.orgmode.org/f0597d96-a287-2c48-7897-6b8737c95217@posteo.eu/

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Rudolf Adamkovič]

Max Nikulin <manikulin@gmail.com> writes:

> I do not have strong opinion if support of $n$th is tightly bound to
> recognizing $n$-th. On the other hand I would not object deprecation
> of "$...$".

Funny, I the exact opposite of you; I would pay many to see $...$th and
$...$-th special-cased (with tests, so that it would not break again).

Rudy
-- 
"The introduction of suitable abstractions is our only mental aid to
organize and master complexity."
-- Edsger Wybe Dijkstra, 1930-2002

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Max Nikulin]

On 21/03/2023 23:38, Rudolf Adamkovič wrote:
> 
> Funny, I the exact opposite of you; I would pay many to see $...$th and
> $...$-th special-cased (with tests, so that it would not break again).

I do not think it is realistic. It may require models for various 
natural languages and for math expressions. It would be necessary to 
carefully track modifications of text to avoid performance degradation.

Example of false positive:
Topi Mäenpää to emacs-orgmode. Bug report. Wed, 01 Jun 2022 07:53:21 
+0000. 
https://list.orgmode.org/icEsGOcGni6qhFgjvChMB6qVwr3XpnZv2tcVWApPXwOWkntHtLmKOBeQKB4LPTqeXcMHTeIkyHv9JurAqJzTgjLm4s-HTODJ6h6p4QDMydU=@protonmail.com

Till somebody will demonstrate reliable recognition of "$n$th" you may 
use zero-width space after "$" and an export filter that removes these 
separators.

Personally, I would prefer more strict syntax to avoid zero width spaces 
even if it will require more verbose markup.

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Timothy]

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

Hi Rudolf,

> Funny, I the exact opposite of you; I would pay many to see $…$th and
> $…$-th special-cased (with tests, so that it would not break again).

I feel the need to point out that this way lies madness.

The behaviour of $ in Org is /inherrently/ confusing. You’re confused by `$...$th'
and `$...$-th'. Say those were special-cased, somebody notices the work and then
try `$n$-dimensional' and now are /even more confused/ when it doesn’t work.

Ok, say we make `$...$' just apply in more cases, then we have somebody who
writing about prices who changed `$3 or =$5' to `$3-$5' and now “weird things are
happening”.

The root issue is the way that `$' tries to pull double-duty as both a literal `$'
and a delimiter. It’s all very well to say that “in LaTeX this is fine”, however
in LaTeX this /simply is not an issue/* as single dollars must be escaped as `\$'.

We can fiddle with the heuristics, but there is no perfect solution here …
other than to move away from `$' and prioritise `\( ... \)' in our documentation and
examples, even add a linter rule that raises warnings about the tendency of
dollar-math to misbehave when people use it.

All the best,
Timothy

* It’s still a pain/discouraged for other reasons.

-- 
Timothy (‘tecosaur’/‘TEC’), Org mode contributor.
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/tec>.

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Rudolf Adamkovič]

Timothy <orgmode@tec.tecosaur.net> writes:

> I feel the need to point out that this way lies madness.
>
> The behaviour [...] “weird things are happening”.

Thank you so much for taking the time to explain the problem to me; I
now understand it much better!  That said, if the heuristic is

  <SPACE> $ <NO-SPACE> ...MATH... <NO-SPACE> $- <NO-SPACE>

then `$3 or =$5' to `$3-$5' would not cause any troubles, right?  What
common, real-world use-case would trigger problems with this simple
heuristic?

Rudy
-- 
"Thinking is a momentary dismissal of irrelevancies."
-- Richard Buckminster Fuller, 1969

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Ihor Radchenko]

Rudolf Adamkovič <salutis@me.com> writes:

> Thank you so much for taking the time to explain the problem to me; I
> now understand it much better!  That said, if the heuristic is
>
>   <SPACE> $ <NO-SPACE> ...MATH... <NO-SPACE> $- <NO-SPACE>
>
> then `$3 or =$5' to `$3-$5' would not cause any troubles, right?  What
> common, real-world use-case would trigger problems with this simple
> heuristic?

$-based economy employs 25$-like prices.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [PATCH v2] org-manual.org: $n$-th is not math

[Rudolf Adamkovič]

Ihor Radchenko <yantar92@posteo.net> writes:

> $-based economy employs 25$-like prices.

Gotcha!  I think I am fully convinced now.  :)

Rudy
-- 
"Mathematics takes us still further from what is human into the region
of absolute necessity, to which not only the actual world, but every
possible world, must conform."
-- Bertrand Russell, 1902

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia