Doc updates part6

CHANGES.rst

@@ -88,6 +88,10 @@ By `@davidar <https://github.com/davidar>`_:
 ``mathics`` command line
 ++++++++++++++++++++++++
 
+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..
+
 WMA Compatibility
 -----------------
 

mathics/builtin/arithfns/basic.py

@@ -94,7 +94,7 @@ class CubeRoot(Builtin):
         ),
     }
 
-    summary_text = "cube root"
+    summary_text = "compute cube root of a number"
 
     def eval(self, n, evaluation):
         "CubeRoot[n_Complex]"
@@ -166,7 +166,7 @@ class Divide(InfixOperator):
         ),
     }
 
-    summary_text = "divide"
+    summary_text = "divide a number"
 
 
 class Minus(PrefixOperator):
@@ -209,7 +209,7 @@ class Minus(PrefixOperator):
         "Minus[x_]": "Times[-1, x]",
     }
 
-    summary_text = "arithmetic negate"
+    summary_text = "perform an arithmetic negation on a number"
 
     def eval_int(self, x: Integer, evaluation):
         "Minus[x_Integer]"
@@ -277,7 +277,7 @@ class Plus(InfixOperator, SympyFunction):
         None: "0",
     }
 
-    summary_text = "add"
+    summary_text = "add a number"
 
     # FIXME Note this is deprecated in 1.11
     # Remember to up sympy doc link when this is corrected
@@ -431,7 +431,7 @@ class Power(InfixOperator, MPMathFunction):
         "Power[x_]": "x",
     }
 
-    summary_text = "exponentiate"
+    summary_text = "exponentiate a number"
 
     # FIXME Note this is deprecated in 1.11
     # Remember to up sympy doc link when this is corrected
@@ -515,7 +515,7 @@ class Sqrt(SympyFunction):
         ),
     }
 
-    summary_text = "square root"
+    summary_text = "take the square root of a number"
 
 
 class Subtract(InfixOperator):
@@ -548,7 +548,7 @@ class Subtract(InfixOperator):
         "Subtract[x_, y_]": "Plus[x, Times[-1, y]]",
     }
 
-    summary_text = "subtract"
+    summary_text = "subtract from a number"
 
 
 class Times(InfixOperator, SympyFunction):
@@ -614,7 +614,7 @@ class Times(InfixOperator, SympyFunction):
     # Remember to up sympy doc link when this is corrected
     sympy_name = "Mul"
 
-    summary_text = "multiply"
+    summary_text = "multiply a number"
 
     def format_times(self, items, evaluation, op="\u2062"):
         "Times[items__]"

mathics/builtin/assignments/assign_binaryop.py

@@ -64,7 +64,7 @@ class AddTo(InfixOperator, InplaceInfixOperator):
 
     operator_symbol = SymbolPlus
     return_before_value: bool = True
-    summary_text = "add a value and assigns that returning the new value"
+    summary_text = "add a value and update; return the updated value"
 
     def eval(self, expr, increment, evaluation: Evaluation):
         """%(name)s[expr_, increment_]"""
@@ -123,7 +123,7 @@ class Decrement(InplaceInfixOperator, InfixOperator, PostfixOperator):
 
     returns_updated_value = False
     summary_text = (
-        "decreases the value by one and assigns that returning the original value"
+        "decreases a value by one and assign the value; return the original value"
     )
 
 
@@ -150,7 +150,7 @@ class DivideBy(InplaceInfixOperator, InfixOperator):
     rules = {
         "x_ /= dx_": "x = x / dx",
     }
-    summary_text = "divide a value and assigns that returning the new value"
+    summary_text = "divide by a value and update; return the new value"
 
 
 class Increment(InplaceInfixOperator, InfixOperator, PostfixOperator):
@@ -206,9 +206,7 @@ class Increment(InplaceInfixOperator, InfixOperator, PostfixOperator):
     increment_symbol = Integer1
     operator_symbol = SymbolPlus
     returns_updated_value: bool = False
-    summary_text = (
-        "increases the value by one and assigns that returning the original value"
-    )
+    summary_text = "increases the value by one and update; return the original value"
 
 
 class PreDecrement(InplaceInfixOperator, PrefixOperator):
@@ -243,7 +241,7 @@ class PreDecrement(InplaceInfixOperator, PrefixOperator):
     increment_symbol = IntegerM1
     operator_symbol = SymbolPlus
     returns_updated_value: bool = True
-    summary_text = "decrease the value by one and assigns that returning the new value"
+    summary_text = "decrease the value by one and update; return the new value"
 
 
 class PreIncrement(InplaceInfixOperator, PrefixOperator):
@@ -296,7 +294,7 @@ class PreIncrement(InplaceInfixOperator, PrefixOperator):
     operator_symbol = SymbolPlus
     return_before_value: bool = False
 
-    summary_text = "increase the value by one and assigns that returning the new value"
+    summary_text = "increase the value by one and updage; return the new value"
 
 
 class SubtractFrom(InfixOperator):
@@ -325,7 +323,7 @@ class SubtractFrom(InfixOperator):
     rules = {
         "x_ -= dx_": "x = x - dx",
     }
-    summary_text = "subtract a value and assins that returning the new value"
+    summary_text = "subtract a value and update; return the new value"
 
 
 class TimesBy(InfixOperator):
@@ -353,4 +351,4 @@ class TimesBy(InfixOperator):
     rules = {
         "x_ *= dx_": "x = x * dx",
     }
-    summary_text = "multiply a value and assigns that returning the new value"
+    summary_text = "multiply a value and update; return the new value"

mathics/builtin/directories/system_directories.py

@@ -89,7 +89,7 @@ class RootDirectory(Predefined):
     """
 
     name = "$RootDirectory"
-    summary_text = "system root directory"
+    summary_text = "get system root directory"
 
     def evaluate(self, evaluation):
         return String(SYS_ROOT_DIR)

mathics/builtin/files_io/filesystem.py

@@ -60,7 +60,7 @@ class AbsoluteFileName(Builtin):
         "fstr": ("File specification x is not a string of one or more characters."),
         "nffil": "File not found during `1`.",
     }
-    summary_text = "absolute path"
+    summary_text = "get absolute file path"
 
     def eval(self, name, evaluation):
         "AbsoluteFileName[name_]"

mathics/builtin/list/associations.py

@@ -52,7 +52,7 @@ class Association(Builtin):
 
     attributes = A_HOLD_ALL_COMPLETE | A_PROTECTED
 
-    summary_text = "an association between keys and values"
+    summary_text = "make an association between keys and values"
 
     def eval_makeboxes(self, rules, f, evaluation: Evaluation):
         """MakeBoxes[<|rules___|>,

mathics/builtin/numbers/calculus.py

@@ -902,9 +902,7 @@ class FindRoot(_BaseFinder):
     }
     messages = _BaseFinder.messages.copy()
     methods = {}
-    summary_text = (
-        "Looks for a root of an equation or a zero of a numerical expression."
-    )
+    summary_text = "look for a root of an equation or a zero of a numerical expression."
 
     try:
         from mathics.eval.numbers.calculus.optimizers import (
@@ -1642,7 +1640,7 @@ class Root(SympyFunction):
         "iidx": "Argument `1` at position 2 is out of bounds",
     }
 
-    summary_text = "the i-th root of a polynomial."
+    summary_text = "compute the i-th root of a polynomial."
     sympy_name = "CRootOf"
 
     def eval(self, f, i, evaluation: Evaluation):
@@ -1699,29 +1697,31 @@ def to_sympy(self, expr, **kwargs):
 
 class RootSum(SympyFunction):
     """
-    <url>:WMA link: https://reference.wolfram.com/language/ref/RootSum.html</url>
-
-    <dl>
-      <dt>'RootSum[$f$, $form$]'
-      <dd>sums $form$[$x$] for all roots of the polynomial $f$[$x$].
-    </dl>
-
-    >> Integrate[1/(x^5 + 11 x + 1), {x, 1, 3}]
-     = RootSum[-1 - 212960 #1 ^ 3 - 9680 #1 ^ 2 - 165 #1 + 41232181 #1 ^ 5&, (Log[3749971 - 3512322106304 #1 ^ 4 + 453522741 #1 + 16326568676 #1 ^ 2 + 79825502416 #1 ^ 3] - 4 Log[5]) #1&] - RootSum[-1 - 212960 #1 ^ 3 - 9680 #1 ^ 2 - 165 #1 + 41232181 #1 ^ 5&, (Log[3748721 - 3512322106304 #1 ^ 4 + 453522741 #1 + 16326568676 #1 ^ 2 + 79825502416 #1 ^ 3] - 4 Log[5]) #1&]
-    >> N[%, 50]
-     = 0.051278805184286949884270940103072421286139857550894
-
-    >> RootSum[#^5 - 11 # + 1 &, (#^2 - 1)/(#^3 - 2 # + c) &]
-     = (538 - 88 c + 396 c ^ 2 + 5 c ^ 3 - 5 c ^ 4) / (97 - 529 c - 53 c ^ 2 + 88 c ^ 3 + c ^ 5)
-
-    >> RootSum[#^5 - 3 # - 7 &, Sin] //N//Chop
-     = 0.292188
-
-    Use 'Normal' to expand 'RootSum':
-    >> RootSum[1+#+#^2+#^3+#^4 &, Log[x + #] &]
-     = RootSum[1 + #1 ^ 2 + #1 ^ 3 + #1 ^ 4 + #1&, Log[x + #1]&]
-    >> %//Normal
-     = Log[-1 / 4 - Sqrt[5] / 4 - I Sqrt[5 / 8 - Sqrt[5] / 8] + x] + Log[-1 / 4 - Sqrt[5] / 4 + I Sqrt[5 / 8 - Sqrt[5] / 8] + x] + Log[-1 / 4 - I Sqrt[5 / 8 + Sqrt[5] / 8] + Sqrt[5] / 4 + x] + Log[-1 / 4 + I Sqrt[5 / 8 + Sqrt[5] / 8] + Sqrt[5] / 4 + x]
+     <url>:WMA link: https://reference.wolfram.com/language/ref/RootSum.html</url>
+
+     <dl>
+       <dt>'RootSum[$f$, $form$]'
+       <dd>sums $form$[$x$] for all roots of the polynomial $f$[$x$].
+     </dl>
+
+    Integrating a rational function of any order:
+     >> Integrate[1/(x^5 + 11 x + 1), {x, 1, 3}]
+      = RootSum[-1 - 212960 #1 ^ 3 - 9680 #1 ^ 2 - 165 #1 + 41232181 #1 ^ 5&, (Log[3749971 - 3512322106304 #1 ^ 4 + 453522741 #1 + 16326568676 #1 ^ 2 + 79825502416 #1 ^ 3] - 4 Log[5]) #1&] - RootSum[-1 - 212960 #1 ^ 3 - 9680 #1 ^ 2 - 165 #1 + 41232181 #1 ^ 5&, (Log[3748721 - 3512322106304 #1 ^ 4 + 453522741 #1 + 16326568676 #1 ^ 2 + 79825502416 #1 ^ 3] - 4 Log[5]) #1&]
+     >> N[%, 50]
+      = 0.051278805184286949884270940103072421286139857550894
+
+     Simplification of 'RootSum' expression
+     >> RootSum[#^5 - 11 # + 1 &, (#^2 - 1)/(#^3 - 2 # + c) &]
+      = (538 - 88 c + 396 c ^ 2 + 5 c ^ 3 - 5 c ^ 4) / (97 - 529 c - 53 c ^ 2 + 88 c ^ 3 + c ^ 5)
+
+     >> RootSum[#^5 - 3 # - 7 &, Sin] //N//Chop
+      = 0.292188
+
+     Use 'Normal' to expand 'RootSum':
+     >> RootSum[1+#+#^2+#^3+#^4 &, Log[x + #] &]
+      = RootSum[1 + #1 ^ 2 + #1 ^ 3 + #1 ^ 4 + #1&, Log[x + #1]&]
+     >> %//Normal
+      = Log[-1 / 4 - Sqrt[5] / 4 - I Sqrt[5 / 8 - Sqrt[5] / 8] + x] + Log[-1 / 4 - Sqrt[5] / 4 + I Sqrt[5 / 8 - Sqrt[5] / 8] + x] + Log[-1 / 4 - I Sqrt[5 / 8 + Sqrt[5] / 8] + Sqrt[5] / 4 + x] + Log[-1 / 4 + I Sqrt[5 / 8 + Sqrt[5] / 8] + Sqrt[5] / 4 + x]
     """
 
     summary_text = "sum polynomial roots"

mathics/builtin/numbers/integer.py

@@ -227,11 +227,12 @@ class FromDigits(Builtin):
 
     <dl>
       <dt>'FromDigits[$l$]'
-      <dd>returns the integer corresponding to the decimal representation given by $l$. $l$ can be a list of
-        digits or a string.
+      <dd>returns the integer corresponding to the decimal representation given by $l$. $l$ can \
+          be a list of digits or a string.
+
       <dt>'FromDigits[$l$, $b$]'
-      <dd>returns the integer corresponding to the base $b$ representation given by $l$. $l$ can be a list of
-        digits or a string.
+      <dd>returns the integer corresponding to the base $b$ representation given by $l$. $l$ can \
+          be a list of digits or a string.
     </dl>
 
     >> FromDigits["123"]
@@ -258,10 +259,9 @@ class FromDigits(Builtin):
      = 0
     """
 
-    summary_text = "integer from a list of digits"
-    rules = {"FromDigits[l_]": "FromDigits[l, 10]"}
-
     messages = {"nlst": "The input must be a string of digits or a list."}
+    rules = {"FromDigits[l_]": "FromDigits[l, 10]"}
+    summary_text = "get integer from a list of digits"
 
     @staticmethod
     def _parse_string(s, b):

mathics/builtin/numbers/numbertheory.py

@@ -831,10 +831,21 @@ class PowersRepresentations(Builtin):
       <dd>represent $n$ as a sum of $k$ non-negative integers raised to the power of $p$.
     </dl>
 
+    Get the ways licence plate number 1729 can be represented as the sum of two cubes:
     >> PowersRepresentations[1729, 2, 3]
      = {{1, 12}, {9, 10}}
-    >> PowersRepresentations[50, 3, 2]
-     = {{0, 1, 7}, {0, 5, 5}, {3, 4, 5}}
+
+    See <url>:1729:https://en.wikipedia.org/wiki/1729_(number)</url> for the full backstory.
+
+    Demonstrate the validity of the Pythagorian triple: 3^2 + 4^2 == 5^2
+    >> PowersRepresentations[25, 2, 2]
+     = {{0, 5}, {3, 4}}
+
+    Since 0 is allowed in the sum, 'PowersRepresentations[$n$, $k$+1, $p$]' is includes \
+   'PowersRepresentations[$n$, $k$, $p$]' with by inserting a zero element at the beginning:
+
+    >> PowersRepresentations[25, 3, 2]
+     = {{0, 0, 5}, {0, 3, 4}}
     """
 
     attributes = A_PROTECTED | A_READ_PROTECTED

mathics/builtin/numeric.py

@@ -114,7 +114,7 @@ class Abs(MPMathFunction):
     rules = {
         "Abs[Undefined]": "Undefined",
     }
-    summary_text = "absolute value of a number"
+    summary_text = "get absolute value of a number"
     sympy_name = "Abs"
 
     def eval(self, x, evaluation: Evaluation):
@@ -578,7 +578,7 @@ class RealAbs(Builtin):
         "Integrate[RealAbs[x_],x_]": "1/2 x RealAbs[x]",
         "Integrate[RealAbs[u_],{u_,a_,b_}]": "1/2 b RealAbs[b]-1/2 a RealAbs[a]",
     }
-    summary_text = "real absolute value"
+    summary_text = "get absolute value of a real number"
 
     def eval(self, x: Number, evaluation: Evaluation):
         """RealAbs[x_]"""

mathics/builtin/statistics/orderstats.py

@@ -279,10 +279,21 @@ class ReverseSort(Builtin):
 
     >> ReverseSort[{c, b, d, a}]
      = {d, c, b, a}
+
+    You can specify a binary comparison function:
+    >> ReverseSort[{1, 2, 0, 3}, Less]
+     = {3, 2, 1, 0}
+
+    Using 'Greater' for the above, reverses the reverse sort:
+    >> ReverseSort[{1, 2, 0, 3}, Greater]
+     = {0, 1, 2, 3}
+
+    See also <url>:Sort:
+    /doc/reference-of-built-in-symbols/descriptive-statistics/order-statistics/sort/</url>.
     """
 
     attributes = A_PROTECTED
-    summary_text = "reverse sort"
+    summary_text = "sort in reverse order"
 
     rules = {
         "ReverseSort[list_]": "Reverse[Sort[list]]",
@@ -318,10 +329,13 @@ class Sort(Builtin):
      = {2 + c_, 1 + b__}
     >> Sort[{x_ + n_*y_, x_ + y_}, PatternsOrderedQ]
      = {x_ + n_ y_, x_ + y_}
+
+    See also <url>:ReverseSort:
+    /doc/reference-of-built-in-symbols/descriptive-statistics/order-statistics/reversesort/</url>.
     """
 
     attributes = A_PROTECTED
-    summary_text = "sort lexicographically or with any comparison function"
+    summary_text = "sort lexicographically or with a comparison function"
 
     def eval(self, list, evaluation: Evaluation):
         "Sort[list_]"

mathics/builtin/system.py

@@ -229,8 +229,8 @@ class Machine(Predefined):
      = ...
     """
 
-    summary_text = "the type of computer system over with Mathics is running"
     name = "$Machine"
+    summary_text = "get the OS platform of the system running Mathics3"
 
     def evaluate(self, evaluation: Evaluation) -> String:
         return String(sys.platform)
@@ -428,8 +428,8 @@ class ParentProcessID(Predefined):
 
     """
 
-    summary_text = "id of the process that invoked Mathics"
     name = "$ParentProcessID"
+    summary_text = "get process id of the process that invoked Mathics3"
 
     def evaluate(self, evaluation: Evaluation) -> Integer:
         return Integer(os.getppid())
@@ -449,8 +449,8 @@ class ProcessID(Predefined):
      = ...
     """
 
-    summary_text = "id of the Mathics process"
     name = "$ProcessID"
+    summary_text = "get process id of the Mathics process"
 
     def evaluate(self, evaluation: Evaluation) -> Integer:
         return Integer(os.getpid())