From fb29d32ffcf0b09edf238c86f6d622da18e72feb Mon Sep 17 00:00:00 2001 From: "R. Bernstein" Date: Fri, 2 Aug 2024 21:31:16 -0400 Subject: [PATCH] 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 * 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 | 4 +- mathics/builtin/assignments/upvalues.py | 2 +- mathics/builtin/atomic/numbers.py | 8 ++- mathics/builtin/atomic/symbols.py | 31 ++++++---- mathics/builtin/colors/color_operations.py | 2 +- mathics/builtin/numbers/constants.py | 11 +++- mathics/doc/documentation/1-Manual.mdoc | 72 +++++++++++++++------- mathics/doc/latex/1-Manual.mdoc | 1 + mathics/doc/latex/Makefile | 4 +- mathics/doc/latex/mathics.tex | 20 +++--- 10 files changed, 106 insertions(+), 49 deletions(-) create mode 120000 mathics/doc/latex/1-Manual.mdoc diff --git a/mathics/builtin/arithmetic.py b/mathics/builtin/arithmetic.py index 3e21d877d..f73d0699f 100644 --- a/mathics/builtin/arithmetic.py +++ b/mathics/builtin/arithmetic.py @@ -384,7 +384,7 @@ class Conjugate(MPMathFunction): """ :Complex Conjugate: https://en.wikipedia.org/wiki/Complex_conjugate \ - (:WMA:https://reference.wolfram.com/language/ref/Conjugate.html) + :WMA link:https://reference.wolfram.com/language/ref/Conjugate.html
'Conjugate[$z$]' @@ -539,7 +539,7 @@ def to_sympy(self, expr, **kwargs): class Element(Builtin): """ :Element of:https://en.wikipedia.org/wiki/Element_(mathematics) \ - (:WMA:https://reference.wolfram.com/language/ref/Element.html) + :WMA link:https://reference.wolfram.com/language/ref/Element.html
'Element[$expr$, $domain$]' diff --git a/mathics/builtin/assignments/upvalues.py b/mathics/builtin/assignments/upvalues.py index 4d099c2da..7580aef7f 100644 --- a/mathics/builtin/assignments/upvalues.py +++ b/mathics/builtin/assignments/upvalues.py @@ -17,7 +17,7 @@ # In Mathematica 5, this appears under "Types of Values". class UpValues(Builtin): """ - :WMA: https://reference.wolfram.com/language/ref/UpValues.html + :WMA link: https://reference.wolfram.com/language/ref/UpValues.html
'UpValues[$symbol$]'
gives the list of transformation rules corresponding to upvalues \ diff --git a/mathics/builtin/atomic/numbers.py b/mathics/builtin/atomic/numbers.py index bf529591d..93b6c6807 100644 --- a/mathics/builtin/atomic/numbers.py +++ b/mathics/builtin/atomic/numbers.py @@ -152,6 +152,7 @@ class Accuracy(Builtin):
examines the number of significant digits of $expr$ after the \ decimal point in the number x.
+ Notice that the result could be slightly different than the obtained \ in WMA, due to differencs in the internal representation of the real numbers. @@ -760,14 +761,15 @@ class Precision(Builtin): """ :Precision: - https://en.wikipedia.org/wiki/Accuracy_and_precision ( - :WMA: - https://reference.wolfram.com/language/ref/Precision.html) + https://en.wikipedia.org/wiki/Accuracy_and_precision + :WMA link: + https://reference.wolfram.com/language/ref/Precision.html
'Precision[$expr$]'
examines the number of significant digits of $expr$.
+ Note that the result could be slightly different than the obtained \ in WMA, due to differencs in the internal representation of the real numbers. diff --git a/mathics/builtin/atomic/symbols.py b/mathics/builtin/atomic/symbols.py index f7301bcee..7c190e53f 100644 --- a/mathics/builtin/atomic/symbols.py +++ b/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""" - :WMA: https://reference.wolfram.com/language/ref/Context.html + :WMA link: + https://reference.wolfram.com/language/ref/Context.html
'Context[$symbol$]'
yields the name of the context where $symbol$ is defined in. @@ -133,7 +134,8 @@ def eval(self, symbol, evaluation): class Definition(Builtin): """ - :WMA: https://reference.wolfram.com/language/ref/Definition.html + :WMA link: + https://reference.wolfram.com/language/ref/Definition.html
'Definition[$symbol$]'
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): """ - :WMA: https://reference.wolfram.com/language/ref/DownValues.html + :WMA link: https://reference.wolfram.com/language/ref/DownValues.html
'DownValues[$symbol$]'
gives the list of downvalues associated with $symbol$.
'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): """ - :WMA: https://reference.wolfram.com/language/ref/Information.html + :WMA link: + https://reference.wolfram.com/language/ref/Information.html
'Information[$symbol$]'
Prints information about a $symbol$ @@ -562,7 +565,8 @@ def format_definition_input(self, symbol, evaluation: Evaluation, options: dict) class Names(Builtin): """ - :WMA: https://reference.wolfram.com/language/ref/Names.html + :WMA link: + https://reference.wolfram.com/language/ref/Names.html
'Names["$pattern$"]'
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): """ - :WMA: https://reference.wolfram.com/language/ref/OwnValues.html + :WMA link: + https://reference.wolfram.com/language/ref/OwnValues.html
'OwnValues[$symbol$]'
gives the list of ownvalue associated with $symbol$. @@ -647,7 +652,8 @@ def eval(self, symbol, evaluation): class Symbol_(Builtin): """ - :WMA: https://reference.wolfram.com/language/ref/Symbol.html + :WMA link: + https://reference.wolfram.com/language/ref/Symbol.html
'Symbol'
is the head of symbols. @@ -686,7 +692,8 @@ def eval(self, string, evaluation): class SymbolName(Builtin): """ - :WMA: https://reference.wolfram.com/language/ref/SymbolName.html + :WMA link: + https://reference.wolfram.com/language/ref/SymbolName.html
'SymbolName[$s$]'
returns the name of the symbol $s$ (without any leading \ @@ -709,7 +716,8 @@ def eval(self, symbol, evaluation): class SymbolQ(Test): """ - :WMA: https://reference.wolfram.com/language/ref/SymbolName.html + :WMA link: + https://reference.wolfram.com/language/ref/SymbolName.html
'SymbolQ[$x$]'
is 'True' if $x$ is a symbol, or 'False' otherwise. @@ -731,7 +739,8 @@ def test(self, expr) -> bool: class ValueQ(Builtin): """ - :WMA: https://reference.wolfram.com/language/ref/ValueQ.html + :WMA link: + https://reference.wolfram.com/language/ref/ValueQ.html
'ValueQ[$expr$]'
returns 'True' if and only if $expr$ is defined. diff --git a/mathics/builtin/colors/color_operations.py b/mathics/builtin/colors/color_operations.py index 4a3688cdc..76c374025 100644 --- a/mathics/builtin/colors/color_operations.py +++ b/mathics/builtin/colors/color_operations.py @@ -205,7 +205,7 @@ def eval(self, input, colorspace, evaluation: Evaluation): class ColorNegate(Builtin): """ Color Inversion ( - :WMA: + :WMA link: https://reference.wolfram.com/language/ref/ColorNegate.html)
diff --git a/mathics/builtin/numbers/constants.py b/mathics/builtin/numbers/constants.py index 26e39a974..119f94330 100644 --- a/mathics/builtin/numbers/constants.py +++ b/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. ( :SymPy: - https://docs.sympy.org/latest/modules/core.html?highlight=zoo#complexinfinity, + https://docs.sympy.org/latest/modules/core.html#sympy.core.numbers.ComplexInfinity, :MathWorld: https://mathworld.wolfram.com/ComplexInfinity.html, :WMA: @@ -257,10 +257,19 @@ class ComplexInfinity(_SympyConstant):
represents an infinite complex quantity of undetermined direction.
+ 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[] """ diff --git a/mathics/doc/documentation/1-Manual.mdoc b/mathics/doc/documentation/1-Manual.mdoc index efbe86776..f878f2660 100644 --- a/mathics/doc/documentation/1-Manual.mdoc +++ b/mathics/doc/documentation/1-Manual.mdoc @@ -1,15 +1,25 @@ -\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 :docker image available on dockerhub: https://hub.docker.com/r/mathicsorg/mathics. +\Mathics---to be pronounced like "Mathematics" without the "emat"---is +a :computer algebra +system:https://en.wikipedia.org/wiki/Computer_algebra_system. 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 :docker image available on dockerhub: https://hub.docker.com/r/mathicsorg/mathics. + +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 :installation instructions: https://mathics-development-guide.readthedocs.io/en/latest/installing/index.html for the most recent instructions for installing from PyPI, or the source. -For implementation details see https://mathics-development-guide.readthedocs.io/en/latest/. +For implementation details, plrease refer to the :Developers Guide:https://mathics-development-guide.readthedocs.io/en/latest/. -
+
\Mathematica is great, but it a couple of disadvantages.
    @@ -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:
    • :mpmath: https://mpmath.org/ for floating-point arithmetic with arbitrary precision, -
    • :numpy: https://numpy.org/numpy for numeric computation, +
    • :NumPy: https://numpy.org for numeric computation,
    • :SymPy: https://sympy.org for symbolic mathematics, and -
    • optionally :SciPy: https://www.scipy.org/ for Scientific calculations. +
    • :SciPy: https://www.scipy.org/ for Scientific calculations.
    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
    -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:
      -
    • a Django-based web server +
    • a :Django-based web server:https://pypi.org/project/Mathics-Django/
    • a command-line interface using either prompt-toolkit, or GNU Readline
    • a :Mathics3 module for Graphs:https://pypi.org/project/pymathics-graph/ (via :NetworkX:https://networkx.org/),
    • a :Mathics3 module for NLP:https://pypi.org/project/pymathics-natlang/ (via :nltk:https://www.nltk.org/, :spacy:https://spacy.io/, and others) @@ -62,7 +72,7 @@ After that, Angus Griffith took over primary leadership and rewrote the parser t A :docker image of the v.9 release: https://hub.docker.com/r/arkadi/mathics 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 :AUTHORS.txt: @@ -94,7 +104,9 @@ See :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 :An Elementary Introduction to the Wolfram Language:https://www.wolfram.com/language/elementary-introduction/. In the :docker image that we supply:https://hub.docker.com/r/mathicsorg/mathics, 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.
      \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 :'ComplexInfinity':/doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/mathematical-constants/complexinfinity and that can be used as a value: + + >> Cos[ComplexInfinity] + = Indeterminate + +'ComplexInfinity' is a shorthand though for 'DirectedInfinty[]'. + +Similarly, expressions using :'Infinity':/doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/mathematical-constants/complexinfinity 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, :'Indeterminate':/doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/mathematical-constants/indeterminate: + >> 0 ^ 0 : Indeterminate expression 0 ^ 0 encountered. = Indeterminate + +
      @@ -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 -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
      'GrayLevel[$l$]'
      specifies a color using a gray level.
+ 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. diff --git a/mathics/doc/latex/1-Manual.mdoc b/mathics/doc/latex/1-Manual.mdoc new file mode 120000 index 000000000..f23c9aa64 --- /dev/null +++ b/mathics/doc/latex/1-Manual.mdoc @@ -0,0 +1 @@ +../documentation/1-Manual.mdoc \ No newline at end of file diff --git a/mathics/doc/latex/Makefile b/mathics/doc/latex/Makefile index 82552c70f..26e5ac140 100644 --- a/mathics/doc/latex/Makefile +++ b/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 diff --git a/mathics/doc/latex/mathics.tex b/mathics/doc/latex/mathics.tex index 4a9bac44c..0462a6bc1 100644 --- a/mathics/doc/latex/mathics.tex +++ b/mathics/doc/latex/mathics.tex @@ -47,7 +47,7 @@ \usepackage[k-tight]{minitoc} \setlength{\mtcindent}{0pt} \mtcsetformat{minitoc}{tocrightmargin}{2.55em plus 1fil} -\newcommand{\multicolumnmtc}{3} +\newcommand{\multicolumnmtc}{2} \makeatletter \let\SV@mtc@verse\mtc@verse \let\SV@endmtc@verse\endmtc@verse @@ -69,10 +69,13 @@ \includegraphics[height=0.08125\linewidth]{logo-text-nodrop.pdf} \\[.5em] {\LARGE\color{subtitle}\textit{\textmd{A free, open-source alternative to Mathematica}}} - \par\textmd{\Large Mathics Core Version \MathicsCoreVersion} + \par\textmd{\Large Mathics3 Core Version \MathicsCoreVersion} } \author{The Mathics3 Team} +% Since we are using a XML input we have need to specify missed hyphenation +% in LaTeX sich as here: +\hyphenation{eco-system} % Fix unicode mappings for listings % http://tex.stackexchange.com/questions/39640/typesetting-utf8-listings-with-german-umlaute @@ -133,19 +136,21 @@ \newcommand{\chapterstart}{ } \newcommand{\chaptersections}{ - \minitoc - %\begin{multicols}{2} + \begin{sloppypar} + \minitoc + \end{sloppypar} } \newcommand{\chapterend}{ %\end{multicols} } \newcommand{\referencestart}{ -% \setcounter{chapter}{0} %\def\thechapter{\Roman{chapter}} \renewcommand{\chaptersections}{ - \minitoc + \begin{sloppypar} + \minitoc %\begin{multicols*}{2} + \end{sloppypar} } \renewcommand{\chapterend}{ %\end{multicols*} @@ -247,7 +252,7 @@ \newcommand{\console}[1]{\hbadness=10000{\ttfamily #1}} \setlength{\parindent}{0mm} -\setlength{\parskip}{1pt} +\setlength{\parskip}{10pt} \setlength{\mathindent}{0em} @@ -269,6 +274,7 @@ \setcounter{tocdepth}{0} \tableofcontents + \lstset{ % inputencoding=utf8, extendedchars=true,