Format format update docs

mathics/builtin/atomic/symbols.py

@@ -407,15 +407,19 @@ class FormatValues(Builtin):
     <url>:WMA link:https://reference.wolfram.com/language/tutorial/PatternsAndTransformationRules.html#6025</url>
     <dl>
       <dt>'FormatValues'[$symbol$]
-      <dd>gives the list of formatvalues associated with $symbol$.
+      <dd>gives the list of format rules associated with $symbol$.
     </dl>
 
+    First, use 'Format' to set a formatting rule for a form:
+
     >> Format[F[x_], OutputForm]:= Subscript[x, F]
+
+    Now, to see the rules, we can use 'FormatValues':
+
     >> FormatValues[F]
      = {HoldPattern[Subscript[x_, F]] :> Subscript[x, F]}
 
-    Notice that the pattern was formatted using the rule. To reveal \
-    the rules, use 'InputForm':
+    The replacment pattern on the right in the delayed rule is formatted according to the top-level form. To see the rule input, we can use 'InputForm':
     >> FormatValues[F]  //InputForm
      = {HoldPattern[Format[F[x_], OutputForm]] :> Subscript[x, F]}
     """

mathics/builtin/layout.py

@@ -40,12 +40,15 @@ class Format(Builtin):
 
     <dl>
       <dt>'Format'[$expr$]
-      <dd>holds values specifying how $expr$ should be printed.
+      <dd>used on the left-hand side of an assignment to specify how $expr$ should be printed.
     </dl>
 
-    Assign values to 'Format' to control how particular expressions
-    should be formatted when printed to the user.
+    First, we set up a 'Format' definition for 'f' to display its arguments as if it were equivalent to an infix operator "~":
+
     >> Format[f[x___]] := Infix[{x}, "~"]
+
+    Now, to see this format in use:
+
     >> f[1, 2, 3]
      = 1 ~ 2 ~ 3
     >> f[1]
@@ -74,7 +77,7 @@ class Format(Builtin):
     >> % //FullForm
      = Format[Sin[x], TeXForm]
 
-    If the second parameter is ommited, 'Format' is ignored:
+    If the second parameter is omitted, 'Format' is ignored:
     >> Format[F[x]]
      = F[x]
 
@@ -84,20 +87,21 @@ class Format(Builtin):
      : Value of option FormatType -> NoFormat is not valid.
      = F[x]
 
-    Notice that differently from WMA, 'Format' expressions are not \
-    formatted in 'InputForm':
-    >> Format[{a->Integrate[F[x], x]}, StandardForm]
-     = ...
+    Mathics3 'Format' output can differ slightly from WMA in what we hope \
+    is a more useful way.
+
+    Use 'InputForm' if you want to get a 'Format' definition that can be used as \
+    Mathics3 input:
+
     >> Format[{a->Integrate[F[x], x]}, StandardForm] //InputForm
      = Format[{a -> Integrate[F[x], x]}, StandardForm]
 
-    This choice is more consistent with the meaning of 'InputForm' \
-    in the sense it gives the text required to reproduce the expression.
-    Also, it allows to get a more clear expression that what would be \
-    get using 'FullForm':
+    In WMA, you might not get something that can be used as input.
+
+    Similarly, use 'Fullform' to get a valid FullForm equivalent expression:
+
     >> Format[{a->Integrate[F[x], x]}, StandardForm] //FullForm
      = Format[{Rule[a, Integrate[F[x], x]]}, StandardForm]
-
     """
 
     messages = {"fttp": "Format type `1` is not a symbol."}