[BUG] Documentation errata [9.5.2 (release_9.5.2-25-gaf6f12 @ /usr/share/emacs/28.1/lisp/org/)]

[BUG] Documentation errata [9.5.2 (release_9.5.2-25-gaf6f12 @ /usr/share/emacs/28.1/lisp/org/)]

[Alessandro Bertulli]

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

Hi all,
this is not actually a bug regarding the code, but the documentation. In
the Manual, when talking about CDLaTeX mode (specifically at
https://orgmode.org/manual/CDLaTeX-mode.html), it is said, regarding the
single quote:
> Pressing the single-quote followed by another character modifies the
symbol before point with an accent or a font.

However, in my setup it's the other way around: first you digit a
character, and THEN you press the single quote. This is also reflected, for
what I saw, in the docstring of the function cdlatex-math-modify, which
says "Modify PREVIOUS char/group/macro with math accent/style." (my
emphasis).

I think this is a typo to be corrected in the Manual. Is this the right
place to make such a suggestion?

Thanks in advance to all and I apologize if this is not the right way to
submit an errata.

I post my configuration after my message.

Alessandro Bertulli

Emacs  : GNU Emacs 28.1 (build 1, x86_64-pc-linux-gnu, GTK+ Version
3.24.33, cairo version 1.17.6)
 of 2022-04-09
Package: Org mode version 9.5.2 (release_9.5.2-25-gaf6f12 @
/usr/share/emacs/28.1/lisp/org/)

current state:
==============
(setq
 org-link-elisp-confirm-function 'yes-or-no-p
 org-bibtex-headline-format-function #[257 "\300 \236A\207" [:title] 3
"\n\n(fn ENTRY)"]
 org-export-with-sub-superscripts '{}
 org-agenda-files '("~/agenda.org")
 org-capture-templates '(("c" "Comment" entry
 (file+headline "~/.notes" "Comments")
 "** Comment %t\n From: %a\n \"%i\"\n\n %?\n\n")
("f" "Fantasy Chronicles" entry
 (file+headline "~/FantasyChronicles/notes.org"
  "Note rapide")
 "** Capture %t\n  Da: %a\n  \"%i\"\n\n  %?\n\n")
("n" "Note" entry (file+headline "~/.notes" "Notes")
 "** Note %t\n  %?\n\n")
("N" "Titled note" entry
 (file+headline "~/.notes" "Notes") "** %? %t\n  \n")
("t" "Task" entry (file+headline "~/.notes" "Tasks")
 "* TODO %?\n  %i\n  %a")
("a" "Agenda task" entry
 (file+headline "~/agenda.org" "Agenda tasks")
 "* TODO %?\n  %i\n  %a")
)
 org-export-before-parsing-hook '(org-attach-expand-links)
 org-archive-hook '(org-attach-archive-delete-maybe)
 org-odt-format-inlinetask-function
'org-odt-format-inlinetask-default-function
 org-ascii-format-drawer-function #[771 " \207" [] 4 "\n\n(fn NAME CONTENTS
WIDTH)"]
 org-cycle-hook '(org-cycle-hide-archived-subtrees org-cycle-hide-drawers
 org-cycle-show-empty-lines
 org-optimize-window-after-visibility-change)
 org-mode-hook '(#[0 "\301\211 \207"
  [imenu-create-index-function org-imenu-get-tree] 2]
visual-line-mode
#[0 "\300\301\302\303\304$\207"
  [add-hook change-major-mode-hook org-show-all append local]
  5]
#[0 "\300\301\302\303\304$\207"
  [add-hook change-major-mode-hook org-babel-show-result-all
   append local]
  5]
org-babel-result-hide-spec org-babel-hide-all-hashes)
 org-highlight-links '(bracket plain radio tag date footnote)
 org-latex-format-drawer-function #[514 "\207" [] 3 "\n\n(fn _ CONTENTS)"]
 org-latex-format-headline-function
'org-latex-format-headline-default-function
 org-confirm-shell-link-function 'yes-or-no-p
 org-html-format-drawer-function #[514 "\207" [] 3 "\n\n(fn NAME CONTENTS)"]
 outline-isearch-open-invisible-function 'outline-isearch-open-invisible
 org-use-sub-superscripts '{}
 org-odt-format-headline-function 'org-odt-format-headline-default-function
 org-agenda-before-write-hook '(org-agenda-add-entry-text)
 org-src-mode-hook '(org-src-babel-configure-edit-buffer
    org-src-mode-configure-edit-buffer)
 org-confirm-elisp-link-function 'yes-or-no-p
 org-speed-command-hook '(org-speed-command-activate
 org-babel-speed-command-activate)
 org-html-format-inlinetask-function
'org-html-format-inlinetask-default-function
 org-ascii-format-inlinetask-function 'org-ascii-format-inlinetask-default
 org-odt-format-drawer-function #[514 "\207" [] 3 "\n\n(fn NAME CONTENTS)"]
 org-latex-format-inlinetask-function
'org-latex-format-inlinetask-default-function
 org-tab-first-hook '(org-babel-hide-result-toggle-maybe
     org-babel-header-arg-expand)
 org-link-shell-confirm-function 'yes-or-no-p
 org-babel-pre-tangle-hook '(save-buffer)
 org-agenda-loop-over-headlines-in-active-region nil
 org-occur-hook '(org-first-headline-recenter)
 org-metadown-hook '(org-babel-pop-to-session-maybe)
 org-link-parameters '(("attachment" :follow org-attach-follow :complete
org-attach-complete-link)
      ("id" :follow org-id-open)
      ("eww" :follow org-eww-open :store org-eww-store-link)
      ("rmail" :follow org-rmail-open :store
org-rmail-store-link)
      ("mhe" :follow org-mhe-open :store org-mhe-store-link)
      ("irc" :follow org-irc-visit :store org-irc-store-link
:export org-irc-export)
      ("info" :follow org-info-open :export org-info-export
:store org-info-store-link)
      ("gnus" :follow org-gnus-open :store org-gnus-store-link)
      ("docview" :follow org-docview-open :export
org-docview-export :store org-docview-store-link)
      ("bibtex" :follow org-bibtex-open :store
org-bibtex-store-link)
      ("bbdb" :follow org-bbdb-open :export org-bbdb-export
:complete org-bbdb-complete-link :store
org-bbdb-store-link)
      ("w3m" :store org-w3m-store-link)
      ("doi" :follow org-link-doi-open :export
org-link-doi-export)
      ("treemacs" :store treemacs-store-org-link) ("file+sys")
      ("file+emacs") ("shell" :follow org-link--open-shell)
      ("news" :follow
#[514 "\301\300\302 Q \"\207" ["news" browse-url ":"]
 6 "\n\n(fn URL ARG)"]
)
      ("mailto" :follow
#[514 "\301\300\302 Q \"\207"
 ["mailto" browse-url ":"] 6 "\n\n(fn URL ARG)"]
)
      ("https" :follow
#[514 "\301\300\302 Q \"\207"
 ["https" browse-url ":"] 6 "\n\n(fn URL ARG)"]
)
      ("http" :follow
#[514 "\301\300\302 Q \"\207" ["http" browse-url ":"]
 6 "\n\n(fn URL ARG)"]
)
      ("ftp" :follow
#[514 "\301\300\302 Q \"\207" ["ftp" browse-url ":"]
 6 "\n\n(fn URL ARG)"]
)
      ("help" :follow org-link--open-help :store
org-link--store-help)
      ("file" :complete org-link-complete-file)
      ("elisp" :follow org-link--open-elisp))
 org-html-format-headline-function
'org-html-format-headline-default-function
 org-metaup-hook '(org-babel-load-in-session-maybe)
 org-clock-sound "/home/alessandro/.emacs.d/AC_Bicycle-bell-1.au"
 )

[-- Attachment #2: Type: text/html, Size: 8394 bytes --]

Re: [BUG] Documentation errata [9.5.2 (release_9.5.2-25-gaf6f12 @ /usr/share/emacs/28.1/lisp/org/)]

[Ihor Radchenko]

Alessandro Bertulli <alessandro.bertulli96@gmail.com> writes:

> I think this is a typo to be corrected in the Manual. Is this the right
> place to make such a suggestion?
>
> Thanks in advance to all and I apologize if this is not the right way to
> submit an errata.

Thanks for the suggestion! Emailing Org mailing list is the right way to
submit errata and other suggestions/questions.

> this is not actually a bug regarding the code, but the documentation. In
> the Manual, when talking about CDLaTeX mode (specifically at
> https://orgmode.org/manual/CDLaTeX-mode.html), it is said, regarding the
> single quote:
>> Pressing the single-quote followed by another character modifies the
>> symbol before point with an accent or a font.
>
> However, in my setup it's the other way around: first you digit a
> character, and THEN you press the single quote. This is also reflected, for
> what I saw, in the docstring of the function cdlatex-math-modify, which
> says "Modify PREVIOUS char/group/macro with math accent/style." (my
> emphasis).

You were clearly confused by the manual text, so you may certainly be
improved. However, I do not see any error in the text you pointed to.

To make use of org-cdlatex-math-modify (bound to "'") you generally do
the following:

1. Type a math symbol
2. Type ' followed by another character
3. org-cdlatex modifies the symbol from (1) according to the character
   you typed in (2).

Example:

1. \alpha
2. ' -
3. \bar{\alpha}

So, as the footnote suggests, you type the single-quote ' followed by
another character - to modify the symbol \alpha before quote.

"Modify PREVIOUS char/group/macro with math accent/style." does not
contradict the above.

If you have a suggestion how to improve the present text in the manual,
feel free to share it.

Best,
Ihor

Re: [BUG] Documentation errata [9.5.2 (release_9.5.2-25-gaf6f12 @ /usr/share/emacs/28.1/lisp/org/)]

[Alessandro Bertulli]

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

Thanks! You're right, I was confused. In the phrase "Pressing the
single-quote FOLLOWED by another character modifies the symbol BEFORE
POINT with an accent or a font.", I got tricked by the "followed". I
thought it meant: "press the single-quote, then the character YOU WANT
TO MODIFY". Of course, re-reading the sentence with your explanation
now makes sense.

I don't remember right now what I understood when I read it the first
time, but possibly I also interpreted the "symbol before point" as
"the symbol before point after you pressed the single-quote", hence my
confusion.

> "Modify PREVIOUS char/group/macro with math accent/style." does not
> contradict the above.

Indeed! that was my point. I got this docstring right, it was the
manual that I misread.

> You were clearly confused by the manual text, so you may certainly be
> improved.

> If you have a suggestion how to improve the present text in the manual,
> feel free to share it.

I don't know if it's worth changing it, but I may suggest to change
"modifies the symbol before point with an accent or a font."
with
"modifies the symbol before THE SINGLE-QUOTE with an accent or a font." ?

Thanks,
Alessandro

[-- Attachment #2: Type: text/html, Size: 1407 bytes --]

Re: [BUG] Documentation errata [9.5.2 (release_9.5.2-25-gaf6f12 @ /usr/share/emacs/28.1/lisp/org/)]

[Ihor Radchenko]

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

Alessandro Bertulli <alessandro.bertulli96@gmail.com> writes:

>> You were clearly confused by the manual text, so you may certainly be
>> improved.
>
>> If you have a suggestion how to improve the present text in the manual,
>> feel free to share it.
>
> I don't know if it's worth changing it, but I may suggest to change
> "modifies the symbol before point with an accent or a font."
> with
> "modifies the symbol before THE SINGLE-QUOTE with an accent or a font." ?

Hmm. Note that SINGLE-QUOTE is not actually typed, so your version is
also kind of confusing.

I propose an alternative as the attached.

Best,
Ihor


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-Using-CDLaTeX-to-enter-math-Clari.patch --]
[-- Type: text/x-patch, Size: 1170 bytes --]

From 961192fc0dec17b4f3a54519ac4a2289de514961 Mon Sep 17 00:00:00 2001
Message-Id: <961192fc0dec17b4f3a54519ac4a2289de514961.1651373883.git.yantar92@gmail.com>
From: Ihor Radchenko <yantar92@gmail.com>
Date: Sun, 1 May 2022 10:42:55 +0800
Subject: [PATCH] * doc/org-manual.org (Using CDLaTeX to enter math): Clarify '
 binding

See https://orgmode.org/list/CAJczNmB95tdWgYcb6gP-B4LH5+W0sBMyA+Z38Fh7Sy+ksfpmbw@mail.gmail.com
---
 doc/org-manual.org | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index c9c1c1298..c0bd853ca 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -11112,8 +11112,8 @@ *** Using CDLaTeX to enter math
   #+kindex: '
 
   Pressing the single-quote followed by another character modifies the
-  symbol before point with an accent or a font.  If you wait more than
-  1.5 seconds after the single-quote, a help window pops up.
+  LaTeX symbol before point with an accent or a font.  If you wait
+  more than 1.5 seconds after the single-quote, a help window pops up.
   Character modification works only inside LaTeX fragments; outside
   the quote is normal.
 
-- 
2.35.1

Re: [BUG] Documentation errata [9.5.2 (release_9.5.2-25-gaf6f12 @ /usr/share/emacs/28.1/lisp/org/)]

[Alessandro Bertulli]

I feel like it's still not completely clear, but I assume it's just a
problem of mine: if I have been the only one having the problem, then
it's on me, I suppose. Anyway, your patch is an improvement, and you
are certainly more expert than me in producing user documentation, so
green light for me!

In fact, thank you for your patience.

Best,
Alessandro

Re: [BUG] Documentation errata [9.5.2 (release_9.5.2-25-gaf6f12 @ /usr/share/emacs/28.1/lisp/org/)]

[Ihor Radchenko]

Ihor Radchenko <yantar92@gmail.com> writes:

> Hmm. Note that SINGLE-QUOTE is not actually typed, so your version is
> also kind of confusing.
>
> I propose an alternative as the attached.

Applied onto main via 79f0969cc.

Best,
Ihor