Improve the docstring for 'org-html-mathjax-options'

Improve the docstring for 'org-html-mathjax-options'

[Rudolf Adamkovič]

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

Please, see the attached patch.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-incorrectly-documented-MathJax-options.patch --]
[-- Type: text/x-patch, Size: 1262 bytes --]

From e12a2bdd28b73661bbe89550409355ebdea7a082 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <salutis@me.com>
Date: Sun, 26 Jun 2022 08:04:40 +0200
Subject: [PATCH] Fix incorrectly documented MathJax options

* lisp/org/ox-html.el (org-html-mathjax-options): Fix some incorrect
choices for 'indent' and 'autonumber' in the docstring
---
 lisp/ox-html.el | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 32187f191..66d1c5c60 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -1185,10 +1185,9 @@ font          The font to use with HTML-CSS and SVG output.  As of MathJax 2.5
 linebreaks    Let MathJax perform automatic linebreaks.  Valid values
               are \"true\" and \"false\".
 indent        If align is not center, how far from the left/right side?
-              Valid values are \"left\" and \"right\"
 multlinewidth The width of the multline environment.
 autonumber    How to number equations.  Valid values are \"None\",
-              \"all\" and \"AMS Math\".
+              \"All\" and \"AMS\".
 tagindent     The amount tags are indented.
 tagside       Which side to show tags/labels on.  Valid values are
               \"left\" and \"right\"
-- 
2.36.1


[-- Attachment #3: Type: text/plain, Size: 199 bytes --]


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: Improve the docstring for 'org-html-mathjax-options'

[Ihor Radchenko]

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

> Please, see the attached patch.
> ...
> Subject: [PATCH] Fix incorrectly documented MathJax options
>
> * lisp/org/ox-html.el (org-html-mathjax-options): Fix some incorrect
> choices for 'indent' and 'autonumber' in the docstring

Thanks!
Applied onto main via 15068ce30.

Bastien, AFAIK Rudolf has completed his FSF copyright assignment. Can
you please add him to the contributor list?

Best,
Ihor

Re: Improve the docstring for 'org-html-mathjax-options'

[Ihor Radchenko]

Ihor Radchenko <yantar92@gmail.com> writes:

> Applied onto main via 15068ce30.

Forgot to mention that I amended the commit message adding the "." at
the end of the sentence and using the `symbol' quoting style for
symbols.

Best,
Ihor

Re: Improve the docstring for 'org-html-mathjax-options'

[Bastien Guerry]

Hi Ihor and Rudolf,

Ihor Radchenko <yantar92@gmail.com> writes:

> Bastien, AFAIK Rudolf has completed his FSF copyright assignment. 

I do confirm.

> Can you please add him to the contributor list?

Done, thanks,

-- 
 Bastien

Re: Improve the docstring for 'org-html-mathjax-options'

[Ihor Radchenko]

> Subject: [PATCH] Fix incorrectly documented MathJax options

I am going through some old bug reports and there was another related
report about this docstring.

Rudolf, since you are probably more familiar with MathJax, may you
please take a look at the report below and tell us if the suggestions
are sensible?

https://orgmode.org/list/m2lf0j77jh.fsf@ego.team
Y. E. via "General discussions about Org-mode." <emacs-orgmode@gnu.org> (2021-12-17) (2021 emacs-orgmode.gnu.org inbox maillist)
Subject: [BUG] org-html-mathjax-options docstring [9.5.1 (release_9.5.1-11-g96d91b @ /emacs-28.0.90/lisp/org/)]

It seems the docstring of org-html-mathjax-options may need to be
updated.

I tried setting 'autonumber' to "None", as the docstring suggests, but
only the lower-cased "none" worked fine.

Also, MathJax documentation for 2.7 (the version I've got HTML rendered
with by org-mode) mentions "AMS", not "AMS Math"
(http://docs.mathjax.org/en/v2.7-latest/tex.html).

Another option that needs attention is 'indent'. The docstring contains
the phrase 'Valid values are "left" and "right"'. This phrase should be
changed to something like 'An example of a valid value is "2em"' or
simply removed, I think.


-- 
Ihor Radchenko,
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: Improve the docstring for 'org-html-mathjax-options'

[Rudolf Adamkovič]

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

Ihor Radchenko <yantar92@gmail.com> writes:

> Rudolf, since you are probably more familiar with MathJax, may you
> please take a look at the report below and tell us if the suggestions
> are sensible?

Sure, see below.

> I tried setting 'autonumber' to "None", as the docstring suggests, but
> only the lower-cased "none" worked fine.

Oops!  I screwed this up (via 15068ce30).  I wanted to lowercase "None"
but instead I capitalized "All".  Please see the attached patch 0001.

> Also, MathJax documentation for 2.7 (the version I've got HTML
> rendered with by org-mode) mentions "AMS", not "AMS Math"
> (http://docs.mathjax.org/en/v2.7-latest/tex.html).

We have this fixed on main (via 15068ce30).

> Another option that needs attention is 'indent'. The docstring
> contains the phrase 'Valid values are "left" and "right"'.

We have this fixed on main (via 15068ce30).

> This phrase should be changed to something like 'An example of a valid
> value is "2em"' or simply removed, I think.

Good idea!  Please see the attached patch 0002.

Rudy


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-incorrectly-documented-auto-numbering-of-MathJax.patch --]
[-- Type: text/x-patch, Size: 1218 bytes --]

From c9b82b85515c7a7f334976aa90bd59bac8932461 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <salutis@me.com>
Date: Wed, 31 Aug 2022 16:03:38 +0200
Subject: [PATCH 1/2] Fix incorrectly documented auto-numbering of MathJax
 equations

* lisp/org/ox-html.el (org-html-mathjax-options): Fix incorrect
choices for the 'autonumber' MathJax option in the docstring.
---
 lisp/ox-html.el | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 9e8740754..65b550603 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -1186,8 +1186,8 @@ linebreaks    Let MathJax perform automatic linebreaks.  Valid values
               are \"true\" and \"false\".
 indent        If align is not center, how far from the left/right side?
 multlinewidth The width of the multline environment.
-autonumber    How to number equations.  Valid values are \"None\",
-              \"All\" and \"AMS\".
+autonumber    How to number equations.  Valid values are \"none\",
+              \"all\" and \"AMS\".
 tagindent     The amount tags are indented.
 tagside       Which side to show tags/labels on.  Valid values are
               \"left\" and \"right\"
-- 
2.37.2


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-Fix-under-documented-MathJax-indentation-option.patch --]
[-- Type: text/x-patch, Size: 1193 bytes --]

From 003013f8e79ccc4570df5f7df89ccc3dfcb35e06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <salutis@me.com>
Date: Wed, 31 Aug 2022 16:05:04 +0200
Subject: [PATCH 2/2] Fix under-documented MathJax indentation option

* lisp/org/ox-html.el (org-html-mathjax-options): Add an example of a
valid value for the 'indent' MathJax option the docstring.
---
 lisp/ox-html.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 65b550603..68b35492d 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -1184,7 +1184,8 @@ font          The font to use with HTML-CSS and SVG output.  As of MathJax 2.5
               \"Gyre-Termes\", and \"Latin-Modern\".
 linebreaks    Let MathJax perform automatic linebreaks.  Valid values
               are \"true\" and \"false\".
-indent        If align is not center, how far from the left/right side?
+indent        If align is not center, how far from the left/right side?  For
+              example, \"1em\".
 multlinewidth The width of the multline environment.
 autonumber    How to number equations.  Valid values are \"none\",
               \"all\" and \"AMS\".
-- 
2.37.2


[-- Attachment #4: Type: text/plain, Size: 300 bytes --]

-- 
"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

Re: Improve the docstring for 'org-html-mathjax-options'

[Ihor Radchenko]

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

> Subject: [PATCH 1/2] Fix incorrectly documented auto-numbering of MathJax
>  equations
> Subject: [PATCH 2/2] Fix under-documented MathJax indentation option

Thanks!
Applied onto main via 710b6ca70 and 74d1a8c75.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=74d1a8c75814519f23fde077d91067b1be61d5eb
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=710b6ca70e1e6d1f9ddc285315543cc361d888d1

-- 
Ihor Radchenko,
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