doc

Author: arnog

docs/compute-engine/01-introduction.md

@@ -24,7 +24,7 @@ To use the Compute Engine, you must write JavaScript or TypeScript code. This
 guide assumes familiarity with one of these programming languages.
 :::
 
-<div style={{height:"2rem"}}></div>
+<div style={{height:"1rem"}}></div>
 
 ```live
 console.log("exp(i*pi) =", ce.parse("e^{i\\pi}").evaluate());
@@ -37,8 +37,8 @@ ce.box(["Expand", expr]).evaluate().print();
 
 
 ```live
-const lhs = ce.parse("2x^2 + 3x + 1");
-const rhs = ce.parse("1 + 2x + x + 2x^2");
+const lhs = ce.parse("1 + x(1 + 2x) + 2x");
+const rhs = ce.parse("2x^2 + 3x + 1");
 console.log(lhs, lhs.isEqual(rhs) ? "=" : "≠", rhs);
 ```
 
@@ -72,8 +72,13 @@ The Compute Engine can:
 In this guide, functions such as `ce.box()` and `ce.parse()` require a
 `ComputeEngine` instance which is denoted by the `ce.` prefix.
 
+**To create a new `ComputeEngine` instance:**, use `ce = new ComputeEngine()`
+
 Functions that apply to a boxed expression, such as `expr.simplify()` are denoted with the
 `expr.` prefix.
+
+**To create a new boxed expression:**, use `expr = ce.parse()` or `expr = ce.box()`
+
 :::
 
 
@@ -85,10 +90,13 @@ Try the **interactive demo** now<Icon name="chevron-right-bold" />
 ## Getting Started
 
 The easiest way to get started is to load the Compute Engine JavaScript module
-from a CDN, then instantiate a `ComputeEngine` object.
+from a CDN, then create a `ComputeEngine` instance.
 
 ### Using JavaScript Modules
 
+JavaScript modules are the modern way to load JavaScript code. You can load the
+Compute Engine module from a CDN using an `import` statement.
+
 ```html
 <script type="module">
   import { ComputeEngine } from 

docs/compute-engine/03-guide-expressions.md

@@ -44,45 +44,6 @@ The input of `ce.box()` can be:
 
 The result is an instance of a `BoxedExpression`.
 
-### String Representation
-
-The `expr.toString()` method returns a [AsciiMath](https://asciimath.org/) string representation of the expression.
-
-```live
-let expr = ce.parse("3x^2+\\sqrt{2}");
-console.log(expr.toString());
-```
-
-When used in a context where a string is expected, the `expr.toString()` method
-is called automatically.
-
-```live
-let expr = ce.parse("3x^2+\\sqrt{2}");
-console.log(expr);
-```
-
-**To output an AsciiMath representation of the expressio to the console** use
-`expr.print()`.
-
-```live
-let expr = ce.parse("3x^2+\\sqrt{2}");
-expr.print();
-```
-
-**To obtain a LaTeX representation of the expression** use `expr.latex` or
-`expr.toLatex()` for additional formatting options.
-
-```live
-let expr = ce.parse("3x^2+\\sqrt{2}");
-console.log(expr.latex);
-```
-
-### Canonical Expressions
-
-By default, `ce.box()` returns a canonical expression. See
-[Canonical Expressions](#canonical) for more info.
-
-
 ```js
 let expr = ce.box(1.729e3);
 console.log(expr.re);
@@ -113,9 +74,6 @@ console.log(expr.json);
 // ➔ ["Add", 3, "x", "y"]
 ```
 
-By default, `ce.parse()` returns a canonical expression. See
-[Canonical Expressions](#canonical-expressions) for more info.
-
 **To get a Boxed Expression representing the content of a mathfield**
 use the `mf.expression` property:
 
@@ -127,42 +85,6 @@ console.log(expr.evaluate());
 // ➔ 2
 ```
 
-## Unboxing
-
-**To access the MathJSON expression of a boxed expression as plain JSON**, use
-the `expr.json` property. This property is an "unboxed" version of the
-expression.
-
-```js
-const expr = ce.box(["Add", 3, "x"]);
-console.log(expr.json);
-// ➔ ["Add", 3, "x"]
-```
-
-**To customize the format of the MathJSON expression returned by `expr.json`**
-use the `ce.toMathJson()` method.
-
-Use this option to control:
-
-- which metadata, if any, should be included
-- whether to use shorthand notation
-- to exclude some functions.
-
-See [JsonSerializationOptions](/compute-engine/api#jsonserializationoptions)
-for more info about the formatting options available.
-
-```live
-const expr = ce.parse("2 + \\frac{q}{p}");
-console.log("expr.json:", expr.json);
-
-console.log("expr.toMathJson():", expr.toMathJson({
-  exclude: ["Divide"], // Don't use `Divide` functions,
-  // use `Multiply`/`Power` instead
-  shorthands: [], // Don't use any shorthands
-}));
-```
-
-
 ## Canonical Expressions
 
 The **canonical form** of an expression is a conventional way of writing an
@@ -216,15 +138,20 @@ By default, `ce.box()` and `ce.parse()` produce a canonical expression.
 **To get a non-canonical expression instead**, use
 `ce.box(expr, {canonical: false})` or `ce.parse(latex, {canonical: false})`.
 
-The non-canonical form sticks closer to the original LaTeX input.
+When using `ce.parse()`, the non-canonical form sticks closer to the original 
+LaTeX input. When using `ce.box()`, the non-canonical form matches the
+input MathJSON.
 
 ```js
-const expr = "\\frac{30}{-50}";
+const latex = "\\frac{30}{-50}";
 
-ce.parse(expr);
+ce.parse(latex);
 // canonical form ➔ ["Rational", -3, 5]
 
-ce.parse(expr, { canonical: false });
+ce.parse(latex, { canonical: false });
+// non-canonical form ➔ ["Divide", 30, -50]
+
+ce.box(["Divide", 30, -50], { canonical: false });
 // non-canonical form ➔ ["Divide", 30, -50]
 ```
 
@@ -249,6 +176,85 @@ only possible syntax errors, but also semantic errors (incorrect number or
 type of arguments, etc...).
 
 
+
+
+## String Representation
+
+The `expr.toString()` method returns a [AsciiMath](https://asciimath.org/) string representation of the expression.
+
+```live
+let expr = ce.parse("3x^2+\\sqrt{2}");
+console.log(expr.toString());
+```
+
+When used in a context where a string is expected, the `expr.toString()` method
+is called automatically.
+
+```live
+let expr = ce.parse("3x^2+\\sqrt{2}");
+console.log(expr);
+```
+
+**To output an AsciiMath representation of the expression to the console** use
+`expr.print()`.
+
+```live
+let expr = ce.parse("\\frac{1+\\sqrt{5}}{2}");
+expr.print();
+```
+
+**To obtain a LaTeX representation of the expression** use `expr.latex` or
+`expr.toLatex()` for additional formatting options.
+
+```live
+let expr = ce.parse("3x^2+\\sqrt{2}");
+console.log(expr.latex);
+```
+
+
+
+
+
+
+
+## Unboxing
+
+**To access the MathJSON expression of a boxed expression as plain JSON**, use
+the `expr.json` property. This property is an "unboxed" version of the
+expression.
+
+```js
+const expr = ce.box(["Add", 3, "x"]);
+console.log(expr.json);
+// ➔ ["Add", 3, "x"]
+```
+
+**To customize the format of the MathJSON expression returned by `expr.json`**
+use the `ce.toMathJson()` method.
+
+Use this option to control:
+
+- which metadata, if any, should be included
+- whether to use shorthand notation
+- to exclude some functions.
+
+See [JsonSerializationOptions](/compute-engine/api#jsonserializationoptions)
+for more info about the formatting options available.
+
+```live
+const expr = ce.parse("2 + \\frac{q}{p}");
+console.log("expr.json:", expr.json);
+
+console.log("expr.toMathJson():", expr.toMathJson({
+  exclude: ["Divide"], // Don't use `Divide` functions,
+  // use `Multiply`/`Power` instead
+  shorthands: [], // Don't use any shorthands
+}));
+```
+
+
+
+
 ## Mutability
 
 Unless otherwise specified, expressions are immutable.