chore: update markdown content to pass mdx v3 parser (#4478)

Building.md

@@ -125,17 +125,17 @@ If you want to update the portal documentation, typically to keep in sync with a
 ## Coverage report
 
 To build with coverage enabled, compile the binaries in `src/` with
-
-    make DUNE_OPTS="--instrument-with bisect_ppx"`
-
+```
+make DUNE_OPTS="--instrument-with bisect_ppx"`
+```
 and then use `bisect-ppx-report html` to produce a report.
 
 The full report can be built with
-
-    nix-build -A tests.coverage
-
+```
+nix-build -A tests.coverage
+```
 and the report for latest `master` can be viewed at
-<https://dfinity.github.io/motoko/coverage/>.
+\<https://dfinity.github.io/motoko/coverage/\>.
 
 ## Profile the compiler
 

CI.md

@@ -114,7 +114,7 @@ Hydra job status page, and the there is a stable link for the latest build of
 
 **Implementation (external):**
 The latest `master` version of the file is availble at
-<https://dfinity.github.io/motoko/>.
+\<https://dfinity.github.io/motoko/\>.
 The reports are calculated in PRs (so failures would be caught), but are not
 hosted anywhere.
 

design/DFX-Interface.md

@@ -48,14 +48,14 @@ Compiling Motoko Files to Wasm
 ------------------------------
 
 In order to compile a Motoko file, `dfx` invokes `moc` with
-
-    moc some/path/input.mo            \
-        -o another/path/output.wasm   \
-        { --package pkgname pkgpath } \
-        { --actor-alias alias url }   \
-        [ --actor-idl actorpath ]     \
-        { --public-metadata name }
-
+```
+moc some/path/input.mo            \
+    -o another/path/output.wasm   \
+    { --package pkgname pkgpath } \
+    { --actor-alias alias url }   \
+    [ --actor-idl actorpath ]     \
+    { --public-metadata name }
+```
 This _reads_ the following files
  * `some/path/input.mo`
  * any `.mo` file referenced by `some/path/input.mo`, either relatively, absolutely or via the provided package aliases
@@ -122,9 +122,9 @@ Checking stable type compatibility
 ----------------------------------
 
 The command
-
-    moc --stable-compatible old.most new.most
-
+```
+moc --stable-compatible old.most new.most
+```
 checks if the stable interface can evolve from `old.most` to `new.most` in
 a type safe way without unintentional data loss.
 
@@ -135,12 +135,12 @@ Invoking the IDE
 ----------------
 
 In order to start the language server, `dfx` invokes
-
-    mo-ide --canister-main some/path/main.mo \
-        { --package pkgname pkgpath }        \
-        { --actor-alias alias url }          \
-        [ --actor-idl actorpath ]
-
+```
+mo-ide --canister-main some/path/main.mo \
+    { --package pkgname pkgpath }        \
+    { --actor-alias alias url }          \
+    [ --actor-idl actorpath ]
+```
 with `stdin` and `stdout` connected to the LSP client.
 
 This may _read_ the same files as `moc` would.
@@ -149,21 +149,21 @@ Listing dependencies
 --------------------
 
 The command
-
-    moc --print-deps some/path/input.mo
-
+```
+moc --print-deps some/path/input.mo
+```
 prints to the standard output all URLs _directly_ imported by
 `some/path/input.mo`, one per line. Each line outputs the original
 URL, and optionally a full path if `moc` can resolve the URL, separated by a space.
 For example,
-
-    mo:base/List
-    mo:other_package/Some/Module
-    ic:em77e-bvlzu-aq
-    canister:alias
-    ./local_import some/path/local_import.mo
-    ./runtime some/path/runtime.wasm
-
+```
+mo:base/List
+mo:other_package/Some/Module
+ic:em77e-bvlzu-aq
+canister:alias
+./local_import some/path/local_import.mo
+./runtime some/path/runtime.wasm
+```
 This _reads_ only `some/path/input.mo`, and writes no files.
 
 By transitively exploring the dependency graph using this command (and
@@ -175,11 +175,11 @@ Generating documentation
 ------------------------
 
 In order to generate documentation for a given Motoko package `dfx` invokes
-
-    mo-doc
-        [ --source source_dir ]
-        [ --output output_dir ]
-        [ --format html|adoc ]
-
+```
+mo-doc
+    [ --source source_dir ]
+    [ --output output_dir ]
+    [ --format html|adoc ]
+```
 The default source directory is `src`, the default output is `docs`, and the default format is `html`.
 `mo-doc` will then generate documentation in the output directory mirroring the directory/file structure of the source directory.

design/Implementation.md

@@ -20,7 +20,7 @@
 
 ## Primitive types
 
-* Nat and Int compile to heap-allocated big nums; unboxed for small numbers <= 31 bit.
+* Nat and Int compile to heap-allocated big nums; unboxed for small numbers `<= 31` bit.
 
 * Nat8/16 compile to unboxed scalars; Nat32/64 are boxed.
   - May unbox locally.

design/StableMemory.md

@@ -176,7 +176,7 @@ Stable memory layout (during execution):
 
 During execution, stable variables aren't maintained in stable memory - they are on the Motoko heap.
 
-Stable memory layout (between upgrades), assuming stable variable encoding `v == {fs:vs}`, a record value of record type {fs:Ts}.
+Stable memory layout (between upgrades), assuming stable variable encoding `v == {fs:vs}`, a record value of record type `{fs:Ts}`.
 
 NOTE: A program with no stable variables still writes an empty record value `v = {}`.
 

design/StableRegions.md

@@ -166,7 +166,7 @@ stable memory state can fully describe the region objects that will be rebuilt w
  - A singleton, heap-allocated object with mutable fields.
  - While being heap-allocated, the object is also `stable` (can be stored in a `stable var`, etc).
  - `RegionObject { id_lower: u32, id_upper: u32; mut page_count: u32; mut vec_pages: Value }`
- - Fields id_lower (lower 32-bits)  and id_upper (upper 32-bits) gives the Region's numerical 64-bit (id = (id_upper << 32 | id_lower)).
+ - Fields id_lower (lower 32-bits)  and id_upper (upper 32-bits) gives the Region's numerical 64-bit (id = (id_upper \<\< 32 | id_lower)).
  - Field `page_count` gives the number of pages allocated to the Region.
  - Field `vec_pages` points at a heap-allocated `Blob` value, and it works with `page_count`
    to represent a growable vector that we call the region's **"access
@@ -191,7 +191,7 @@ In ordinary operation, the second feature is not required.  In the event of an u
 ### block-region table
 
  - purpose:
-   - relate a block ID ("page block ID") to its region (if any), its position (or rank) in that region (see `rebuild`) and its current size in (used) pages (<=128).
+   - relate a block ID ("page block ID") to its region (if any), its position (or rank) in that region (see `rebuild`) and its current size in (used) pages (`<=128`).
      All but the last block owned by a region should have all pages 128 allocated.
 
    - NB: The organization of this table is not useful for efficient

design/WhitePaper.md

@@ -56,7 +56,7 @@ Oftentimes, these goals are difficult to achieve fully or can be in conflict wit
 
 * *Modules.* Motoko also features a simple module system, where modules are essentially a restricted form of object that must be stateless. Modules can contain type definitions, but not (currently) abstract them, i.e., hide their implementation. A Motoko compilation unit is either a module, or a top-level actor or actor class definition that can be imported as if it was contained in a module.
 
-* *Canonical type system.* Motoko's type system, at its core, is a fairly canonical typed lambda calculus with primitive types, labeled products and sums (i.e., objects and variants), first-class function types, polymorphism (i.e., generics), and structural recursive subtyping with top and bottom types. Type theory experts will recognise the close similarity to (Kernel) System F<:. Type checking mostly follows a strict bidirectional discipline, with only a few exceptions regarding optional inference of polymorphic type instantiation, overloaded operators, and multiple passes to account for recursive declarations.
+* *Canonical type system.* Motoko's type system, at its core, is a fairly canonical typed lambda calculus with primitive types, labeled products and sums (i.e., objects and variants), first-class function types, polymorphism (i.e., generics), and structural recursive subtyping with top and bottom types. Type theory experts will recognise the close similarity to (Kernel) System F\<:. Type checking mostly follows a strict bidirectional discipline, with only a few exceptions regarding optional inference of polymorphic type instantiation, overloaded operators, and multiple passes to account for recursive declarations.
 
 * *Shared types.* Motoko distinguishes a subset of types that are "sharable". These are those types whose values can be serialised, compared, or otherwise be inspected transparently. They include primitive types, immutable aggregates (arrays, objects, variants) whose components are shared, and references to actors or shared functions.
 

design/scoped-await.md

@@ -361,7 +361,7 @@ is rejected because, once annotated:
   }
 ```
 
-since `$1 <> $` and `$2` <> `$`.
+since `$1 <> $` and `$2` \<\> `$`.
 
 ### Imperative deadlock
 

doc/README.md

@@ -9,7 +9,7 @@ python3 -m http.server --directory html
 ```
 
 CI pushes these docs for latest master to
-<https://hydra.dfinity.systems/job/dfinity-ci-build/motoko/docs/latest/download/1/overview-slides.html>.
+\<https://hydra.dfinity.systems/job/dfinity-ci-build/motoko/docs/latest/download/1/overview-slides.html\>.
 
 The local documentation is suboptimal and compiled with pandoc, not
 docusaurus so it doesn't understand or process remark-code-import file includes,

doc/md/compatibility.md

@@ -174,21 +174,22 @@ Motoko compiler (`moc`) now supports:
 -   `moc --stable-compatible <pre> <post>` checks two `.most` files for upgrade compatibility
 
 To upgrade from `cur.wasm` to `nxt.wasm` we need check both Candid interface and stable variables are "compatible"
-
-    didc check nxt.did cur.did  // nxt <: cur
-    moc --stable-compatible cur.most nxt.most  // cur <<: nxt
-
+```
+didc check nxt.did cur.did  // nxt <: cur
+moc --stable-compatible cur.most nxt.most  // cur <<: nxt
+```
 E.g. the upgrade from `v2` to `v3` fails this check:
-
-    > moc --stable-compatible v2.most v3.most
-    (unknown location): Compatibility error [M0170], stable variable state of previous type
-      var Int
-    cannot be consumed at new type
-      var Nat
+```
+> moc --stable-compatible v2.most v3.most
+(unknown location): Compatibility error [M0170], stable variable state of previous type
+  var Int
+cannot be consumed at new type
+  var Nat
+```
 
 ## Examples in the wild
 
-A common, real-world example of an incompatible upgrade can be found on the forum: <https://forum.dfinity.org/t/questions-about-data-structures-and-migrations/822/12?u=claudio>
+A common, real-world example of an incompatible upgrade can be found on the forum: \<https://forum.dfinity.org/t/questions-about-data-structures-and-migrations/822/12?u=claudio/\>
 
 In that example, a user was attempting to add a field to the record payload of an array, by upgrading from stable type interface:
 

doc/md/upgrades.md

@@ -13,7 +13,7 @@ For applications written in Motoko, the language provides high-level support for
 Utilizing stable storage depends on you — as the application programmer — anticipating and indicating the data you want to retain after an upgrade. Depending on the application, the data you decide to persist might be some, all, or none of a given actor’s state.
 
 <!--
-To enable {proglang} to migrate the current state of variables when a canister is upgraded, you must identify those variables as containing data that must be preserved.
+To enable \{proglang\} to migrate the current state of variables when a canister is upgraded, you must identify those variables as containing data that must be preserved.
 -->
 
 ## Declaring stable variables
@@ -26,7 +26,7 @@ More precisely, every `let` and `var` variable declaration in an actor can speci
 Concretely, you use the following syntax to declare stable or flexible variables in an actor:
 
 ....
-<dec-field> ::=
+\<dec-field\> ::=
   (public|private)? (stable|flexible)? dec
 ....
 -->
@@ -152,7 +152,7 @@ Upgrade safety does not guarantee that the upgrade process will succeed (it can
 
 :::tip
 
-You can check valid Candid subtyping between two services described in `.did` files, `cur.did` and `nxt.did` (containing Candid types), using the `didc` tool with argument `check nxt.did cur.did`. The `didc` tool is available at <https://github.com/dfinity/candid>.
+You can check valid Candid subtyping between two services described in `.did` files, `cur.did` and `nxt.did` (containing Candid types), using the `didc` tool with argument `check nxt.did cur.did`. The `didc` tool is available at \<https://github.com/dfinity/candid\>.
 
 :::
 

src/Notes.md

@@ -2,17 +2,17 @@
 
 - Address TBR and TBD comments in source.
 - Why does BinE not take two immediate sub-expressions.  Currently it only has one so the parser has to use TupE to create a tuple. A: this is a typo, make it binary.
-- Relational operators (=, <, etc.) are missing - just treat them as binops? Yes, or add another class of bool producing RelE operations
+- Relational operators (=, \<, etc.) are missing - just treat them as binops? Yes, or add another class of bool producing RelE operations
 - Lhs of AssignE ast node is too general - these should be *locations* - shall we encode this
   in the syntax or as a static check? Preferably as static check - note we should allow array locations and object fields as l-values too. Alternative: introduce second class address ypes, perhaps indexed by location type for type-directed compilation.
-- what syntax do we want for rotation operators - do we want to support JS >>> operator?
-  Andreas has seen something like <>> used in other languages.a
+- what syntax do we want for rotation operators - do we want to support JS \>\>\> operator?
+  Andreas has seen something like \<\>\> used in other languages.a
 - do we really want async as a firs-class value or should we
   syntactically restrict await to async function calls and immediate blocks?
   The former supports overlapped io, passing async's as values and the registration of multiple waiters on the same async value.
   The second dissallows overlapped calls and allows exactly one waiter to await an async call.
 - it looks like we want operator overloading, at least on primitive types. Is that correct? Yes
-- do we want conversion (eg. int32->iny64), both implicit and explicit. No, just use
+- do we want conversion (eg. int32-\>iny64), both implicit and explicit. No, just use
   functions for now.
 - the parser requires parens around the condition of a while (...) ...  and loop ... while (...) constructs. This appears to agree with JS. A: Andreas would like a more principled solution using expression based syntax, while atomic_exp atomic exp should do.
 - unary update (++i etc) NYI but should be - not sure about postfix variants

test/README.md

@@ -137,7 +137,7 @@ See `README.md` in the `random/` subdirectory.
 Performance regression testing
 ------------------------------
 
-The purpose of the `perf/` directory is to have a small (<20) set of test
+The purpose of the `perf/` directory is to have a small (\<20) set of test
 programs representative of real use of Motoko.
 
 For these tests the test suite records the following numbers: