Note more of the many changes (#1310)

More edits in `CHANGES.rst`. Go over functions up to PolygonalNumber

CHANGES.rst

@@ -1,6 +1,9 @@
 CHANGES
 =======
 
+8.0.0
+-----
+
 This release is to get out some of the major changes that have gone on
 already in advance of redoing Boxing and Formatting.
 
@@ -20,33 +23,41 @@ And in the ``Mathics3-Trepan`` repository:
 * ``Debugger[]``, and
 * ``TraceActivate[]``
 
-This code is very much alpha quality, but it greatly improves the
-ability to debug problems in loading existing packages written from
-Mathematica. So packages ``BoolEval`` and ``CleanSlate`` were added to
-the repostiory.
+Option ``--post-mortem`` was added which goes into the `trepan3k debugger <https https://pypi.org/project/trepan3k/>`_ on an unrecoverable error. This option is  available on other front-ends..
+
+This debuggign code is very much alpha quality, but it greatly
+improves the ability to debug problems in loading existing packages
+written from Mathematica. So packages ``BoolEval`` and ``CleanSlate``
+were added to the repostiory.
 
 Also as a result of the improved ability to debug Mathics3, we now
 provide a version of Rubi 4.17 using git submodules . To use this you
 will need a patched version of ``stopit``.  Aravindh Krishnamoorthy
-led the initial port of Rubi.
+led the initial port of `Rubi <https://github.com/Mathics3/Mathics3-Rubi>`_.
 
 David A. Roberts worked on ensuring Mathics3 runs on pyodide and
 contributed a number of new Built-in Functions that are found in `The
-On-Line Encyclopedia of Integer Sequences (OEIS) <https://oeis.org/>`_
+On-Line Encyclopedia of Integer Sequences (OEIS) <https://oeis.org/>`_.
 
 
 New Builtins
 ++++++++++++
 
 * ``Between``
-* ``Breakpoint`` - forces a Python ``breakpoint()``
+* ``Breakpoint`` - (not WMA; forces a Python ``breakpoint()``
 * ``CheckAbort``
 * ``FileNameDrop``
 * ``FormatValues``
-* ``SetEnvironment``
+* ``ListStepPlot``
+* ``MapApply``
+* ``PythonCProfileEvaluation`` (not WMA; interface to Python cProfile)
+* ``RealValuedNumberQ``
 * ``SequenceForm``
+* ``SetEnvironment``
 * ``Stack``
+* ``SyntaxQ``
 * ``Trace``
+* ``UnitStep``
 
 By `@davidar <https://github.com/davidar>`_:
 
@@ -77,8 +88,6 @@ By `@davidar <https://github.com/davidar>`_:
 ``mathics`` command line
 ++++++++++++++++++++++++
 
-* ``--post-mortem`` option added which will go into the `trepan3k debugger <https https://pypi.org/project/trepan3k/>`_ on an unrecoverable error.
-
 WMA Compatibility
 -----------------
 
@@ -89,8 +98,10 @@ WMA Compatibility
 Internals
 ---------
 
-* Operator information has been gone over and is picked up from JSON
-tables produced from the Mathics Scanner project.
+* More of the on-OO evaluation code that forms what might be an
+  instruction evaluator has been moved out of module
+  ``mathics.builtins`` put in ``mathics.eval``. This includes code for
+  plotting, and making boxes.
 
 Performance
 -----------
@@ -111,7 +122,7 @@ API incompatibility
   To specify associated format in ``format_`` methods the
   docstring, the list of format must be wrapped in parenthesis, like
   ``(InputForm,): Definitions[...]`` instead of just ``InputForm: Definitions[...]``.
-
+* Character and Operator information that has been gone over in the Mathics Scanner project. The information in JSON tables, the keys, and values have thus change. Here, we read this information in and use that instead of previously hard-coded values.
 
 
 Bugs
@@ -132,7 +143,7 @@ Mathics3 Packages
 Mathics3 Modules
 ++++++++++++++++
 
-* Added preliminary Mathics3 debugger ("pymathics.trepan")
+* Added preliminary `Mathics3 debugger `Mathics3-Trepan <https://github.com/Mathics3/mathics3-trepan>`_.
 
 Python Package Updates
 +++++++++++++++++++++++

mathics/builtin/atomic/numbers.py

@@ -301,26 +301,37 @@ class NumberDigit(Builtin):
     https://reference.wolfram.com/language/ref/NumberDigit.html</url>
 
     <dl>
+      <dt>'NumberDigit[$x$, $n$]'
+      <dd>returns the digit coefficient of 10^$n$ for the real-valued number $x$.
+
       <dt>'NumberDigit[$x$, $n$, $b$]'
-      <dd>returns the coefficient of $b^n$ in the base-$b$ representation of $x$.
+      <dd>returns the coefficient of $b$^$n$ in the base-$b$ representation of $x$.
     </dl>
 
-    >> NumberDigit[123456, 2]
-     = 4
-    >> NumberDigit[12.3456, -1]
+    Get the 10^2 digit of a 210.345:
+    >> NumberDigit[210.345, 2]
+     = 2
+
+    Get the 10^-1 digit of a 210.345:
+    >> NumberDigit[210.345, -1]
      = 3
 
+    >> BaseForm[N[Pi], 2]
+     = 11.00100100001111110_2
+
+    Get the 2^0 bit of the Pi:
+     = 1
     """
 
     attributes = A_PROTECTED | A_READ_PROTECTED
 
-    summary_text = "digits of a real number"
-
     rules = {
         "NumberDigit[x_, n_Integer]": "NumberDigit[x, n, 10]",
         "NumberDigit[x_, n_Integer, b_Integer]": "RealDigits[x, b, 1, n][[1]][[1]]",
     }
 
+    summary_text = "get digits of a real number"
+
 
 class RealDigits(Builtin):
     """
@@ -776,7 +787,7 @@ class Precision(Builtin):
 
     summary_text = "find the precision of a number"
 
-    def eval(self, z, evaluation):
+    def eval(self, z, evaluation: Evaluation):
         """Precision[z_]"""
         if isinstance(z, MachineReal):
             return SymbolMachinePrecision

mathics/builtin/intfns/combinatorial.py

@@ -387,23 +387,39 @@ class PolygonalNumber(Builtin):
     :Polygonal number: https://en.wikipedia.org/wiki/Polygonal_number</url> (<url>
     :WMA: https://reference.wolfram.com/language/ref/PolygonalNumber.html</url>)
     <dl>
+      <dt>'PolygonalNumber[$n$]'
+      <dd>gives the $n$th triangular number.
+
       <dt>'PolygonalNumber[$r$, $n$]'
       <dd>gives the $n$th $r$-gonal number.
     </dl>
 
     >> Table[PolygonalNumber[n], {n, 10}]
      = {1, 3, 6, 10, 15, 21, 28, 36, 45, 55}
-    >> Table[PolygonalNumber[r, 10], {r, 3, 10}]
-     = {55, 100, 145, 190, 235, 280, 325, 370}
+
+    The sum of two consecutive Polygonal numbers is the square of the larger number:
+    >> Table[PolygonalNumber[n-1] + PolygonalNumber[n], {n, 10}]
+     = {1, 4, 9, 16, 25, 36, 49, 64, 81, 100}
+
+    'PolygonalNumber'[$r$, $n$] can be interpreted as the number of points arranged in the form of $n$-1 polygons of $r$ sides.
+
+    List the tenth $r-gonal number of regular polygons from 3 to 8:
+    >> Table[PolygonalNumber[r, 10], {r, 3, 8}]
+     = {55, 100, 145, 190, 235, 280}
+
+    See also <url>
+    :Binomial:
+    doc/reference-of-built-in-symbols/integer-functions/combinatorial-functions/binomial/</url>, and <url>
+    :RegularPolygon:
+    doc/reference-of-built-in-symbols/drawing-graphics/regularpolygon/</url>.
     """
 
     attributes = A_LISTABLE | A_NUMERIC_FUNCTION | A_PROTECTED | A_READ_PROTECTED
-    summary_text = "polygonal number"
-
     rules = {
         "PolygonalNumber[n_Integer]": "PolygonalNumber[3, n]",
         "PolygonalNumber[r_Integer, n_Integer]": "(1/2) n (n (r - 2) - r + 4)",
     }
+    summary_text = "get polygonal number"
 
 
 class RogersTanimotoDissimilarity(_BooleanDissimilarity):

mathics/builtin/intfns/recurrence.py

@@ -138,14 +138,13 @@ class StirlingS1(Builtin):
     """
     <url>
     :Stirling numbers of first kind:
-    https://en.wikipedia.org/wiki/Stirling_numbers_of_the_first_kind</url> \
-    (<url>
+    https://en.wikipedia.org/wiki/Stirling_numbers_of_the_first_kind</url> (<url>
     :WMA link:
     https://reference.wolfram.com/language/ref/StirlingS1.html</url>)
 
     <dl>
       <dt>'StirlingS1[$n$, $m$]'
-      <dd>gives the Stirling number of the first kind $ _n^m$.
+      <dd>gives the Stirling number of the first kind.
     </dl>
 
     Integer mathematical function, suitable for both symbolic and numerical manipulation.
@@ -173,18 +172,16 @@ class StirlingS2(Builtin):
     """
     <url>
     :Stirling numbers of second kind:
-    https://en.wikipedia.org/wiki/Stirling_numbers_of_the_second_kind</url> \
-    (<url>
-    :WMA link
-    :https://reference.wolfram.com/language/ref/StirlingS2.html</url>)
+    https://en.wikipedia.org/wiki/Stirling_numbers_of_the_second_kind</url> (<url>
+    :WMA link:
+    https://reference.wolfram.com/language/ref/StirlingS2.html</url>)
 
     <dl>
       <dt>'StirlingS2[$n$, $m$]'
-      <dd>gives the Stirling number of the second kind  _n^m.
+      <dd>gives the Stirling number of the second kind. Returns the number of ways \
+      of partitioning a set of $n$ elements into $m$ non empty subsets.
     </dl>
 
-    returns the number of ways of partitioning a set of $n$ elements into $m$ \
-    non empty subsets.
 
     >> Table[StirlingS2[10, m], {m, 10}]
     = {1, 511, 9330, 34105, 42525, 22827, 5880, 750, 45, 1}