Fixing Latex documentation. #1290

mmatera · 2025-01-14T04:27:01Z

Improving TeXForm to use name_character tables. Adjustments in docstrings.
DRY get_latex_operator. More adjustments

mmatera · 2025-01-14T04:28:13Z

mathics/builtin/no_meaning/infix_extra.py

@@ -31,7 +31,7 @@ class DirectedEdge(InfixOperator):
    >> DirectedEdge[x, y, z]
     = x → y → z

-    >> a \\[DirectedEdge] b
+    >> a -> b


Test expressions must be plane ASCII to work with the LaTeX documentation.

mmatera · 2025-01-14T04:29:43Z

mathics/builtin/numbers/numbertheory.py

    <url>
    :Divisor function: https://en.wikipedia.org/wiki/Divisor_function</url> (<url>
    :SymPy: https://docs.sympy.org/latest/modules/functions/combinatorial.html#sympy.functions.combinatorial.numbers.divisor_sigma</url>, <url>
    :WMA: https://reference.wolfram.com/language/ref/DivisorSigma.html</url>)

    <dl>
      <dt>'DivisorSigma[$k$, $n$]'
-      <dd>returns σ_$k$($n$)
+      <dd>returns $\sigma_k$($n$)


To make that the underscore be interpreted as a subindex, all must be enclosed by $...$. Also it is better to use the LaTeX command for $\sigma$.

This works for LaTeX but breaks Django.

This is how Django docstring looks in master:

This is not perfect either. I think we should handle this in the Mathics-Django side.

Mathics-Django uses Mathjax to render equations, so it is just a matter to call the render when the documentation is loaded. I will look how to do this later.

Ok - good. In the end I guess there will be improvement there as well.

Regarding this.

According the MathML documentation, and what we do in
https://github.com/Mathics3/mathics-django/blob/143195d67d3afd2e4cde94f1dde4a641a5fbdd0c/mathics_django/web/media/js/mathics.js#L310

it should be enough to add just bellow here:
https://github.com/Mathics3/mathics-django/blob/143195d67d3afd2e4cde94f1dde4a641a5fbdd0c/mathics_django/web/media/js/doc.js#L6
the line

MathJax.Hub.Queue(['Typeset', MathJax.Hub, doc]);

However, for some reason it does not do the trick. Any idea about why, or how to ask?

A guess is that this routine is hooked in from a path that processes evaluation output from Python which is distinct from the path that displays document output

Yes, it seems something like that happens, but I still could not figure out what/how.

mathics/core/convert/op.py

mmatera · 2025-01-14T04:31:15Z

mathics/core/convert/op.py

@@ -43,3 +96,34 @@ def ascii_op_to_unicode(ascii_op: str, encoding: str) -> str:
            ascii_op, ascii_op
        )
    return ascii_op
+
+
+def get_latex_operator(unicode_op: str) -> str:


This is used both in the documentation system and in the TeXForm formatter.

mmatera · 2025-01-14T04:32:17Z

mathics/doc/latex_doc.py

-        text += "\\test{%s}\n" % escape_latex_code(self.test)
+        test_str = self.test
+        # TODO: replace nonascii characters in test_str
+        text += "\\test{%s}\n" % escape_latex_code(test_str)


Here I copy the attribute into a variable, because eventually we would like to translate all the non-ascii characters into amslatex codes.

mmatera · 2025-01-14T04:34:00Z

mathics/doc/latex_doc.py

+        # character associated to the operator.
+        # At some point we would like to scan all the unicode characters
+        # and replace them according to the context.
+        if self.operator and not self.operator.isascii():


This replaces all the ocurrences of the operator in its unicode form, by its LaTeX form. Eventually we would like to translate any unicode character appearing in the docstring. Notice also that at this point, the documentation contains both the test cases and their results.

Eventually, we'd like to ditch all of this.

Eventually, we'd like to ditch all of this.

Even better!

mathics/doc/latex_doc.py

mathics/format/latex.py

adjust sed-hack for missing CapitalDifferentialD translation. Disable the use of the local amstex_operators dicctionary in translation

mathics/builtin/no_meaning/infix_extra.py

mmatera · 2025-01-15T00:10:02Z

mathics/format/latex.py

@@ -565,6 +556,7 @@ def graphics3dbox(self, elements=None, **options) -> str:
 \begin{{asy}}
 import three;
 import solids;
+import tube;


This seems to be required for TubeBox in asy.

rocky · 2025-01-15T01:44:07Z

mathics/doc/latex/sed-hack.sh

@@ -36,6 +36,7 @@ sed -i -e 's/⧦/\\\\Equiv/g' documentation.tex
 sed -i -e 's/⊻/xor/g' documentation.tex
 sed -i -e 's/∧/&&/g' documentation.tex
 sed -i -e 's/‖/||/g' documentation.tex
+sed -i -e 's/ⅅ/$\\mathbb{D}$/' documentation.tex


Good! Can the other sed's get removed?

I have to check which one of these can be removed.

rocky · 2025-01-15T01:45:26Z

If this can now build the documentation, then let's merge.

rocky · 2025-01-15T02:08:26Z

If this can now build the documentation, then let's merge.

I am not seeing that this fixes everything:

$ make clean && make mathics.pdf 
...
LaTeX Warning: Reference `reference-of-built-in-symbols/atomic-elements-of-expr
essions/representation-of-numbers/precision' on page 10 undefined on input line
 367.

[10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24]
[25] [26] [27] [28] [29] [30] [31] [32]
chapter 3.
[33] [34] [35] [36] [37]
chapter 4.
[38] [39] [40] [41] [42]
part II.
[43]
chapter 5.
! Missing \endgroup inserted.
<inserted text> 
                \endgroup 
l.4900 \begin{testresult}\frac{ $\pi$ }{4}
                                          \end{testresult}\end{testcase}%
Output written on mathics.pdf (43 pages).
Transcript written on mathics.log.

mmatera · 2025-01-15T02:16:51Z

If this can now build the documentation, then let's merge.

I am not seeing that this fixes everything:

$ make clean && make mathics.pdf 
...
LaTeX Warning: Reference `reference-of-built-in-symbols/atomic-elements-of-expr
essions/representation-of-numbers/precision' on page 10 undefined on input line
 367.

[10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24]
[25] [26] [27] [28] [29] [30] [31] [32]
chapter 3.
[33] [34] [35] [36] [37]
chapter 4.
[38] [39] [40] [41] [42]
part II.
[43]
chapter 5.
! Missing \endgroup inserted.
<inserted text> 
                \endgroup 
l.4900 \begin{testresult}\frac{ $\pi$ }{4}
                                          \end{testresult}\end{testcase}%
Output written on mathics.pdf (43 pages).
Transcript written on mathics.log.

Please, check if the mathics-scanner databases are updated to the current master.

rocky · 2025-01-15T02:20:10Z

If this can now build the documentation, then let's merge.

I am not seeing that this fixes everything:

$ make clean && make mathics.pdf 
...
LaTeX Warning: Reference `reference-of-built-in-symbols/atomic-elements-of-expr
essions/representation-of-numbers/precision' on page 10 undefined on input line
 367.

[10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24]
[25] [26] [27] [28] [29] [30] [31] [32]
chapter 3.
[33] [34] [35] [36] [37]
chapter 4.
[38] [39] [40] [41] [42]
part II.
[43]
chapter 5.
! Missing \endgroup inserted.
<inserted text> 
                \endgroup 
l.4900 \begin{testresult}\frac{ $\pi$ }{4}
                                          \end{testresult}\end{testcase}%
Output written on mathics.pdf (43 pages).
Transcript written on mathics.log.

Please, check if the mathics-scanner databases are updated to the current master.

I ran make-JSON-tables.sh, but I didn't pull latest master on mathics-scanner. Checking again now...

rocky · 2025-01-15T02:35:28Z

It works! Great work - thanks!

rocky · 2025-01-15T14:46:47Z

LGTM - merge when you are satisfied.

mmatera marked this pull request as draft January 14, 2025 04:27

mmatera commented Jan 14, 2025

View reviewed changes

mathics/core/convert/op.py Outdated Show resolved Hide resolved

mmatera commented Jan 14, 2025

View reviewed changes

rocky reviewed Jan 14, 2025

View reviewed changes

mathics/doc/latex_doc.py Outdated Show resolved Hide resolved

rocky reviewed Jan 14, 2025

View reviewed changes

mathics/format/latex.py Outdated Show resolved Hide resolved

Improving TeXForm to use name_character tables. Misc adjustments

26458ac

adjust sed-hack for missing CapitalDifferentialD translation. Disable the use of the local amstex_operators dicctionary in translation

mmatera force-pushed the fix_documentation branch from f7d1c15 to 26458ac Compare January 14, 2025 23:49

adjust docstrings and comments

c6aba76

mmatera marked this pull request as ready for review January 14, 2025 23:53

rocky reviewed Jan 15, 2025

View reviewed changes

mathics/builtin/no_meaning/infix_extra.py Outdated Show resolved Hide resolved

mmatera added 2 commits January 14, 2025 21:03

restore import tube in asymptote.

d174ccd

fix UndirectedEdge docstring

ccabce1

mmatera commented Jan 15, 2025

View reviewed changes

adjust tests

af0b3f4

rocky reviewed Jan 15, 2025

View reviewed changes

mmatera changed the title ~~Towards make the latex documentation works again.~~ Fixing Latex documentation. Jan 15, 2025

mmatera added 2 commits January 15, 2025 10:11

reducing sedhacks

d3fc5b5

fix GreaterEqual docstring and removing another sed hack

28ff6a6

mmatera merged commit a2c14ad into master Jan 15, 2025
14 checks passed

mmatera deleted the fix_documentation branch January 15, 2025 15:42

rocky mentioned this pull request Jan 18, 2025

FormatValues #1303

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fixing Latex documentation. #1290

Fixing Latex documentation. #1290

mmatera commented Jan 14, 2025

mmatera Jan 14, 2025

mmatera Jan 14, 2025

rocky Jan 15, 2025

mmatera Jan 15, 2025

rocky Jan 15, 2025

mmatera Jan 15, 2025

rocky Jan 15, 2025

mmatera Jan 18, 2025

rocky Jan 18, 2025

mmatera Jan 18, 2025

mmatera Jan 14, 2025

mmatera Jan 14, 2025

mmatera Jan 14, 2025

rocky Jan 15, 2025

mmatera Jan 15, 2025

mmatera Jan 15, 2025

rocky Jan 15, 2025

mmatera Jan 15, 2025

rocky commented Jan 15, 2025

rocky commented Jan 15, 2025

mmatera commented Jan 15, 2025

rocky commented Jan 15, 2025

rocky commented Jan 15, 2025

rocky commented Jan 15, 2025

Fixing Latex documentation. #1290

Fixing Latex documentation. #1290

Conversation

mmatera commented Jan 14, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rocky commented Jan 15, 2025

rocky commented Jan 15, 2025

mmatera commented Jan 15, 2025

rocky commented Jan 15, 2025

rocky commented Jan 15, 2025

rocky commented Jan 15, 2025