Go over PDF generation and Manual part1... (#1048)

First part of going over PDF (via LaTeX)

* Makefile: clean target changed to track asymptote temp file
conventions
* {arithmetic,upvalue,symbols,color_operations}.py: regularize link
format
* numbers.py: we need a blank line in for LaTeX after </dl>
* 1-Manual.mdoc revise first sections. Use URLs more, reduce overfull
boxes
* mathics.tex:
   - add a full line between paragraphs.
- two-column (not three-column) minitoc handle long section names better

mathics/builtin/arithmetic.py

@@ -384,7 +384,7 @@ class Conjugate(MPMathFunction):
     """
     <url>:Complex Conjugate:
     https://en.wikipedia.org/wiki/Complex_conjugate</url> \
-    (<url>:WMA:https://reference.wolfram.com/language/ref/Conjugate.html</url>)
+    <url>:WMA link:https://reference.wolfram.com/language/ref/Conjugate.html</url>
 
     <dl>
       <dt>'Conjugate[$z$]'
@@ -539,7 +539,7 @@ def to_sympy(self, expr, **kwargs):
 class Element(Builtin):
     """
     <url>:Element of:https://en.wikipedia.org/wiki/Element_(mathematics)</url> \
-    (<url>:WMA:https://reference.wolfram.com/language/ref/Element.html</url>)
+    <url>:WMA link:https://reference.wolfram.com/language/ref/Element.html</url>
 
     <dl>
       <dt>'Element[$expr$, $domain$]'

mathics/builtin/assignments/upvalues.py

@@ -17,7 +17,7 @@
 # In Mathematica 5, this appears under "Types of Values".
 class UpValues(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/UpValues.html</url>
+    <url>:WMA link: https://reference.wolfram.com/language/ref/UpValues.html</url>
     <dl>
       <dt>'UpValues[$symbol$]'
       <dd>gives the list of transformation rules corresponding to upvalues \

mathics/builtin/atomic/numbers.py

@@ -152,6 +152,7 @@ class Accuracy(Builtin):
       <dd>examines the number of significant digits of $expr$ after the \
       decimal point in the number x.
     </dl>
+
     <i>Notice that the result could be slightly different than the obtained \
     in WMA, due to differencs in the internal representation of the real numbers.</i>
 
@@ -760,14 +761,15 @@ class Precision(Builtin):
     """
     <url>
     :Precision:
-    https://en.wikipedia.org/wiki/Accuracy_and_precision</url> (<url>
-    :WMA:
-    https://reference.wolfram.com/language/ref/Precision.html</url>)
+    https://en.wikipedia.org/wiki/Accuracy_and_precision</url> <url>
+    :WMA link:
+    https://reference.wolfram.com/language/ref/Precision.html</url>
 
     <dl>
       <dt>'Precision[$expr$]'
       <dd>examines the number of significant digits of $expr$.
     </dl>
+
     <i>Note that the result could be slightly different than the obtained \
     in WMA, due to differencs in the internal representation of the real numbers.</i>
 

mathics/builtin/atomic/symbols.py

@@ -95,7 +95,8 @@ def _get_usage_string(symbol, evaluation, is_long_form: bool, htmlout=False):
 
 class Context(Builtin):
     r"""
-    <url>:WMA: https://reference.wolfram.com/language/ref/Context.html</url>
+    <url>:WMA link:
+       https://reference.wolfram.com/language/ref/Context.html</url>
     <dl>
       <dt>'Context[$symbol$]'
       <dd>yields the name of the context where $symbol$ is defined in.
@@ -133,7 +134,8 @@ def eval(self, symbol, evaluation):
 
 class Definition(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/Definition.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/Definition.html</url>
     <dl>
       <dt>'Definition[$symbol$]'
       <dd>prints as the definitions given for $symbol$.
@@ -352,14 +354,14 @@ def format_definition_input(self, symbol, evaluation):
 # In Mathematica 5, this appears under "Types of Values".
 class DownValues(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/DownValues.html</url>
+    <url>:WMA link: https://reference.wolfram.com/language/ref/DownValues.html</url>
     <dl>
       <dt>'DownValues[$symbol$]'
       <dd>gives the list of downvalues associated with $symbol$.
     </dl>
 
     'DownValues' uses 'HoldPattern' and 'RuleDelayed' to protect the \
-    downvalues from being evaluated. Moreover, it has attribute \
+    downvalues from being evaluated, and it has attribute \
     'HoldAll' to get the specified symbol instead of its value.
 
     >> f[x_] := x ^ 2
@@ -408,7 +410,8 @@ def eval(self, symbol, evaluation):
 
 class Information(PrefixOperator):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/Information.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/Information.html</url>
     <dl>
       <dt>'Information[$symbol$]'
       <dd>Prints information about a $symbol$
@@ -562,7 +565,8 @@ def format_definition_input(self, symbol, evaluation: Evaluation, options: dict)
 
 class Names(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/Names.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/Names.html</url>
     <dl>
       <dt>'Names["$pattern$"]'
       <dd>returns the list of names matching $pattern$.
@@ -614,7 +618,8 @@ def eval(self, pattern, evaluation):
 # In Mathematica 5, this appears under "Types of Values".
 class OwnValues(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/OwnValues.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/OwnValues.html</url>
     <dl>
       <dt>'OwnValues[$symbol$]'
       <dd>gives the list of ownvalue associated with $symbol$.
@@ -647,7 +652,8 @@ def eval(self, symbol, evaluation):
 
 class Symbol_(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/Symbol.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/Symbol.html</url>
     <dl>
       <dt>'Symbol'
       <dd>is the head of symbols.
@@ -686,7 +692,8 @@ def eval(self, string, evaluation):
 
 class SymbolName(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/SymbolName.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/SymbolName.html</url>
     <dl>
       <dt>'SymbolName[$s$]'
       <dd>returns the name of the symbol $s$ (without any leading \
@@ -709,7 +716,8 @@ def eval(self, symbol, evaluation):
 
 class SymbolQ(Test):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/SymbolName.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/SymbolName.html</url>
     <dl>
       <dt>'SymbolQ[$x$]'
       <dd>is 'True' if $x$ is a symbol, or 'False' otherwise.
@@ -731,7 +739,8 @@ def test(self, expr) -> bool:
 
 class ValueQ(Builtin):
     """
-    <url>:WMA: https://reference.wolfram.com/language/ref/ValueQ.html</url>
+    <url>:WMA link:
+      https://reference.wolfram.com/language/ref/ValueQ.html</url>
     <dl>
       <dt>'ValueQ[$expr$]'
       <dd>returns 'True' if and only if $expr$ is defined.

mathics/builtin/colors/color_operations.py

@@ -205,7 +205,7 @@ def eval(self, input, colorspace, evaluation: Evaluation):
 class ColorNegate(Builtin):
     """
     Color Inversion (<url>
-    :WMA:
+    :WMA link:
     https://reference.wolfram.com/language/ref/ColorNegate.html</url>)
 
     <dl>

mathics/builtin/numbers/constants.py

@@ -246,7 +246,7 @@ class ComplexInfinity(_SympyConstant):
     is an infinite number in the complex plane whose complex argument \
     is unknown or undefined. (<url>
     :SymPy:
-    https://docs.sympy.org/latest/modules/core.html?highlight=zoo#complexinfinity</url>, <url>
+    https://docs.sympy.org/latest/modules/core.html#sympy.core.numbers.ComplexInfinity</url>, <url>
     :MathWorld:
     https://mathworld.wolfram.com/ComplexInfinity.html</url>, <url>
     :WMA:
@@ -257,10 +257,19 @@ class ComplexInfinity(_SympyConstant):
       <dd>represents an infinite complex quantity of undetermined direction.
     </dl>
 
+    ComplexInfinity can appear as the result of a computation such as dividing by zero:
+    >> 1 / 0
+     : Infinite expression 1 / 0 encountered.
+     = ComplexInfinity
+
+    But it can be used as an explicit value in an expression:
     >> 1 / ComplexInfinity
      = 0
+
     >> ComplexInfinity * Infinity
      = ComplexInfinity
+
+    ComplexInfinity though is a special case of DirectedInfinity:
     >> FullForm[ComplexInfinity]
      = DirectedInfinity[]
     """

mathics/doc/documentation/1-Manual.mdoc

@@ -1,15 +1,25 @@
 
 <chapter title="Introduction">
 
-\Mathics---to be pronounced like "Mathematics" without the "emat"---is a general-purpose computer algebra system (CAS). It is meant to be a free, open-source alternative to \Mathematica. It is free both as in "free beer" and as in "freedom". Mathics can be run \Mathics locally, and to facilitate installation of the vast amount of software need to run this, there is a <url>:docker image available on dockerhub: https://hub.docker.com/r/mathicsorg/mathics</url>.
+\Mathics---to be pronounced like "Mathematics" without the "emat"---is
+a <url>:computer algebra
+system:https://en.wikipedia.org/wiki/Computer_algebra_system</url>. It
+is a free, open-source alternative to \Mathematica or the \Wolfram
+Language. However, \Mathics builds around and on top of the Python
+ecosystem of libraries and tools. So in a sense, you can think of it
+as a WMA front-end to the Python ecosystem of tools.
 
-The programming language of \Mathics is meant to resemble the \Wolfram Language as much as possible. However, \Mathics is in no way affiliated or supported by \Wolfram. \Mathics will probably never have the power to compete with \Mathematica in industrial applications; it is an alternative though. It also invites community development at all levels.
+\Mathics is free both as in "free beer" but also, more importantly, as in "freedom". \Mathics can be run locally. But to facilitate installation of the vast amount of software need to run this, there is a <url>:docker image available on dockerhub: https://hub.docker.com/r/mathicsorg/mathics</url>.
+
+The programming language and built-in functions of \Mathics tries to match the \Wolfram Language, which is continually evolving changing.
+
+\Mathics is in no way affiliated or supported by \Wolfram. \Mathics will probably never have the power to compete with \Mathematica in industrial applications; it is a free alternative though. It also invites community development at all levels.
 
 See the <url>:installation instructions: https://mathics-development-guide.readthedocs.io/en/latest/installing/index.html</url> for the most recent instructions for installing from PyPI, or the source.
 
-For implementation details see <url>https://mathics-development-guide.readthedocs.io/en/latest/</url>.
+For implementation details, plrease refer to the <url>:Developers Guide:https://mathics-development-guide.readthedocs.io/en/latest/</url>.
 
-<section title="Why yet another CAS, one based on Mathematica?">
+<section title="Why a CAS based on Wolfram Language?">
 \Mathematica is great, but it a couple of disadvantages.
 
 <ul>
@@ -22,13 +32,13 @@ The second point some may find and advantage.
 
 However, even if you are willing to pay hundreds of dollars for the software, you would will not be able to see what\'s going on "inside" the program if that is your interest. That\'s what free, open-source, and community-supported software is for!
 
-\Mathics aims at combining the best of both worlds: the beauty of \Mathematica backed by a free, extensible Python core which includes a rich set of Python tools including:
+\Mathics combines the beauty of \Mathematica implemented in an open-source environment written in Python. The Python ecosystem includes libraries and toos like:
 
 <ul>
   <li><url>:mpmath: https://mpmath.org/</url> for floating-point arithmetic with arbitrary precision,
-  <li><url>:numpy: https://numpy.org/numpy</url> for numeric computation,
+  <li><url>:NumPy: https://numpy.org</url> for numeric computation,
   <li><url>:SymPy: https://sympy.org</url> for symbolic mathematics, and
-  <li>optionally <url>:SciPy: https://www.scipy.org/</url> for Scientific calculations.
+  <li><url>:SciPy: https://www.scipy.org/</url> for Scientific calculations.
 </ul>
 
 Performance of \Mathics is not, right now, practical in large-scale projects and calculations. However can be used as a tool for exploration and education.
@@ -37,16 +47,16 @@ Performance of \Mathics is not, right now, practical in large-scale projects and
 
 <section title="What does \Mathics offer?">
 
-Some of the features of \Mathics tries to be compatible with Wolfram-Language kernel within the confines of the Python ecosystem.
-
-Given this, it is a powerful functional programming language, driven by pattern matching and rule application.
+Because \Mathics is compatible with Wolfram-Language kernel within the
+confines of the Python ecosystem, it is a powerful functional
+programming language, driven by pattern matching and rule application.
 
 Primitive types include rationals, complex numbers, and arbitrary-precision numbers. Other primitive types such as images or graphs, or NLP come from the various Python libraries that \Mathics uses.
 
 Outside of the "core" \Mathics kernel (which has a only primitive command-line interface), in separate github projects, as add-ons, there is:
 
 <ul>
-  <li>a Django-based web server
+  <li>a <url>:Django-based web server:https://pypi.org/project/Mathics-Django/</url>
   <li>a command-line interface using either prompt-toolkit, or GNU Readline
   <li>a <url>:Mathics3 module for Graphs:https://pypi.org/project/pymathics-graph/</url> (via <url>:NetworkX:https://networkx.org/</url>),
   <li>a <url>:Mathics3 module for NLP:https://pypi.org/project/pymathics-natlang/</url> (via <url>:nltk:https://www.nltk.org/</url>, <url>:spacy:https://spacy.io/</url>, and others)
@@ -62,7 +72,7 @@ After that, Angus Griffith took over primary leadership and rewrote the parser t
 
 A <url>:docker image of the v.9 release: https://hub.docker.com/r/arkadi/mathics</url> can be found on dockerhub.
 
-Around 2017, the project was largely abandoned in its largely Python 2.7 state, with support for Python 3.2-3.5 via six.
+Around 2017, the project was largely abandoned in its largely Python 2.7 state, with some support for Python 3.2-3.5 via six.
 
 Subsequently, around mid 2020, it was picked up by the current developers. A list of authors and contributors can be found in the <url>
 :<con>AUTHORS.txt</con>:
@@ -94,7 +104,9 @@ See <url>:The Mathics3 Developer Guide:https://mathics-development-guide.readthe
 
 The following sections are introductions to the basic principles of the language of \Mathics. A few examples and functions are presented. Only their most common usages are listed; for a full description of a Symbols possible arguments, options, etc., see its entry in the Reference of Built-in Symbols.
 
-However if you google for "Mathematica Tutorials" you will find easily dozens of other tutorials which are applicable. Be warned though that \Mathics does not yet offer the full range and features and capabilities of \Mathematica.
+However if you google for "Mathematica Tutorials" you will find easily dozens of other tutorials which are applicable. For example, see <url>:An Elementary Introduction to the Wolfram Language:https://www.wolfram.com/language/elementary-introduction/</url>. In the <url>:docker image that we supply:https://hub.docker.com/r/mathicsorg/mathics</url>, you can load "workspaces" containing the examples described in the chapters of this introduction.
+
+Be warned though that \Mathics does not yet offer the full range and features and capabilities of \Mathematica.
 
 <section title="Basic calculations">
 \Mathics can be used to calculate basic stuff:
@@ -169,29 +181,41 @@ Of course, \Mathics has complex numbers:
   = 5
 
 \Mathics can operate with pretty huge numbers:
-  >> 100!
-  = 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000
+  >> 55! (* Also known as Factorial[55] *)
+  = 12696403353658275925965100847566516959580321051449436762275840000000000000
+
+We could easily increase use a number larger than 55, but the digits will just run off the page.
 
-('!' denotes the factorial function.)
 The precision of numerical evaluation can be set:
 
   >> N[Pi, 30]
   = 3.14159265358979323846264338328
 
-Division by zero is forbidden:
+Division by zero gives an error:
   >> 1 / 0
   : Infinite expression 1 / 0 encountered.
    = ComplexInfinity
 
-Other expressions involving 'Infinity' are evaluated:
+But zero division returns value <url>:'ComplexInfinity':/doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/mathematical-constants/complexinfinity</url> and that can be used as a value:
+
+  >> Cos[ComplexInfinity]
+   = Indeterminate
+
+'ComplexInfinity' is a shorthand though for 'DirectedInfinty[]'.
+
+Similarly, expressions using <url>:'Infinity':/doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/mathematical-constants/complexinfinity</url>  as a value are allowed and are evaluated:
   >> Infinity + 2 Infinity
   = Infinity
 
-In contrast to combinatorial belief, '0^0' is undefined:
+There is also the value, <url>:'Indeterminate':/doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/mathematical-constants/indeterminate</url>:
+
   >> 0 ^ 0
  : Indeterminate expression 0 ^ 0 encountered.
    = Indeterminate
 
+<!--
+TODO: Find some suitable place for the below. It does not belong here.
+
 The result of the previous query to \Mathics can be accessed by '%':
 
   >> 3 + 4
@@ -201,6 +225,8 @@ The result of the previous query to \Mathics can be accessed by '%':
   = 49
 
   ##
+-->
+
 </section>
 
 <section title="Precision and Accuracy">
@@ -228,14 +254,16 @@ While 3.1419 not the closest approximation to Pi in 4 digits after the decimal p
     >> Pi == 3.141987654321`3
      = True
 
-<url>The absolute accuracy of a number, is set by adding a two RawBackquotes '``' and the number digits.
+The absolute accuracy of a number, is set by adding a two RawBackquotes '``' and the number digits.
 
 For example:
 
   >> 13.1416``4
    = 13.142
 
-is a number having a absolute uncertainty of 10^-4. This number is numerically equivalent to '13.1413``4':
+is a number having an absolute uncertainty of $10^-4$.
+
+This number is numerically equivalent to '13.1413``4':
 
   >> 13.1416``4 == 13.1413``4
    = True
@@ -985,6 +1013,7 @@ Colors can be added in the list of graphics primitives to change the drawing col
   <dt>'GrayLevel[$l$]'
   <dd>specifies a color using a gray level.
 </dl>
+
 All components range from 0 to 1. Each color function can be supplied with an additional argument specifying the desired opacity ("alpha") of the color. There are many predefined colors, such as 'Black', 'White', 'Red', 'Green', 'Blue', etc.
 
   >> Graphics[{Red, Disk[]}]
@@ -1218,6 +1247,7 @@ We want to combine 'Dice' objects using the '+' operator:
   >> Dice[a___] + Dice[b___] ^:= Dice[Sequence @@ {a, b}]
 
 The '^:=' ('UpSetDelayed') tells \Mathics to associate this rule with 'Dice' instead of 'Plus'.
+
 'Plus' is protected---we would have to unprotect it first:
   >> Dice[a___] + Dice[b___] := Dice[Sequence @@ {a, b}]
   : Tag Plus in Dice[a___] + Dice[b___] is Protected.

mathics/doc/latex/1-Manual.mdoc

@@ -0,0 +1 @@
+../documentation/1-Manual.mdoc

mathics/doc/latex/Makefile

@@ -37,7 +37,7 @@ logo-heptatom.pdf logo-text-nodrop.pdf:
 	(cd .. && $(BASH) ./images.sh)
 
 #: The build of the documentation which is derived from docstrings in the Python code and doctest data
-documentation.tex: $(DOCTEST_LATEX_DATA_PCL)
+documentation.tex: $(DOCTEST_LATEX_DATA_PCL) 1-Manual.mdoc
 	$(PYTHON) ./doc2latex.py $(MATHICS3_MODULE_OPTION) && $(BASH) ./sed-hack.sh
 
 #: Same as mathics.pdf
@@ -48,7 +48,7 @@ clean:
 	rm -f mathics.asy mathics.aux mathics.idx mathics.log mathics.mtc mathics.mtc* mathics.out mathics.toc || true
 	rm -f test-mathics.aux test-mathics.idx test-mathics.log test-mathics.mtc test-mathics.mtc* test-mathics.out test-mathics.toc || true
 	rm -f mathics.fdb_latexmk mathics.ilg mathics.ind mathics.maf mathics.pre || true
-	rm -f mathics_*.* || true
+	rm -f mathics-*.* || true
 	rm -f mathics-test.asy mathics-test.aux mathics-test.idx mathics-test.log mathics-test.mtc mathicsest.mtc* mathics-test.out mathics-test.toc || true
 	rm -f documentation.tex $(DOCTEST_LATEX_DATA_PCL) || true
 	rm -f mathics.pdf mathics.dvi test-mathics.pdf test-mathics.dvi || true