Apply Markdown lint (#43)

Just a small attempt to make all markdown files consistent and formatted
in line with the current best practices.

I've also added a lint GHA job to prevent drifting away from this
baseline in the future.

Author: bbatsov

.github/workflows/markdown-lint.yml

@@ -0,0 +1,21 @@
+name: Markdown Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: tj-actions/changed-files@v45
+      id: changed-files
+      with:
+        files: '**/*.md'
+        separator: ","
+    - uses: DavidAnson/markdownlint-cli2-action@v19
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-files.outputs.all_changed_files }}
+        separator: ","

.markdownlint-cli2.jsonc

@@ -0,0 +1,22 @@
+{
+  // Enable all rules by default
+  "default": true,
+
+  // Line length: increase default from 80
+  "MD013": {
+    "line_length": 100,
+    "code_blocks": false,
+    "tables": false
+  },
+
+  // Allow duplicate headers in different nested sections
+  "MD024": {
+    "allow_different_nesting": true
+  },
+
+  // Allow inline HTML
+  "MD033": false,
+
+  // First line in a file doesn't need to be a top-level header
+  "MD041": false,
+}

README.md

@@ -1,4 +1,5 @@
 # fslang-spec
+
 F# Language Specification
 
 ## Overview
@@ -8,6 +9,7 @@ This is an initiative to create a more complete and community-maintainable F# sp
 This will be no small task, but we believe it is worthwhile and we count on community contributions.
 
 We foresee three phases:
+
 1. Convert the [latest official spec](https://fsharp.org/specs/language-spec/4.1/FSharpSpec-4.1-latest.pdf) to markdown and create the structure and tools to make it community-maintainable. This is done.
 2. Add the post-4.1 features as documented in the [RFCs](https://github.com/fsharp/fslang-design/) to the spec. Our goal: a complete F# 10 spec.
 3. Make spec update part of new feature development so that an up-to-date spec can be released with every new major compiler release.
@@ -151,4 +153,3 @@ The sources are the markdown files for the chapters (clauses) in the `spec` dire
 Run `build` to create a new complete spec (including ToC and updated reference links) in your `artifacts` directory.
 
 At certain points, releases are created and published in the `releases` directory.
-

releases/FSharp-Spec-4.1.2024-10-02.md

@@ -22,28 +22,33 @@ active-pattern-op-name :=
     | | ident | ... | ident |
     | | ident | ... | ident | _ |
 ```
+
 In operator definitions, the operator name is placed in parentheses. For example:
 
 ```fsgrammar
 let (+++) x y = (x, y)
 ```
+
 This example defines the binary operator `+++`. The text `(+++)` is an `ident-or-op` that acts as an
 identifier with associated text `+++`. Likewise, for active pattern definitions (§ 7), the active pattern
 case names are placed in parentheses, as in the following example:
 
 ```fsgrammar
 let (|A|B|C|) x = if x < 0 then A elif x = 0 then B else C
 ```
+
 Because an `ident-or-op` acts as an identifier, such names can be used in expressions. For example:
 
 ```fsgrammar
 List.map ((+) 1) [ 1; 2; 3 ]
 ```
+
 The three character token `(*)` defines the `*` operator:
 
 ```fsgrammar
 let (*) x y = (x + y)
 ```
+
 To define other operators that begin with `*`, whitespace must follow the opening parenthesis;
 otherwise `(*` is interpreted as the start of a comment:
 
@@ -149,6 +154,7 @@ long-ident-or-op :=
     | long-ident '.' ident-or-op
     | ident-or-op
 ```
+
 ## Constants
 
 The constants in the following table may be used in patterns and expressions. The individual lexical
@@ -178,6 +184,7 @@ const :=
     | false | true          -- Boolean constant of type "bool"
     | '(' ')'               -- unit constant of type "unit"
 ```
+
 ## Operators and Precedence
 
 ### Categorization of Symbolic Operators
@@ -215,10 +222,12 @@ prefix operators include the `~` character:
 // To completely redefine the prefix + operator:
 let (~+) x = x
 ```
+
 ```fsgrammar
 // To completely redefine the infix + operator to be addition modulo- 7
 let (+) a b = (a + b) % 7
 ```
+
 ```fsgrammar
 // To define the operator on a type:
 type C(n:int) =
@@ -229,6 +238,7 @@ let n = n % 7
     static member (+) (x1:C,x2:C) = C(x1.N+x2.N)
     static member (-) (x1:C,x2:C) = C(x1.N-x2.N)
 ```
+
 The `::` operator is special. It represents the union case for the addition of an element to the head of
 an immutable linked list, and cannot be redefined, although it may be used to form infix expressions.
 It always accepts arguments in tupled form — as do all union cases — rather than in curried form.
@@ -284,7 +294,8 @@ For example, consider the following token stream:
 ```fsharp
 a + b * c
 ```
-In this expression, the `expr infix-op expr` rule for `b * c` takes precedence over the 
+
+In this expression, the `expr infix-op expr` rule for `b * c` takes precedence over the
 `expr infix-op expr` rule for `a + b`, because the `*` operator has higher precedence than the `+` operator. Thus, this
 expression can be pictured as follows:
 
@@ -293,18 +304,21 @@ expression can be pictured as follows:
 // _________
 //     _____
 ```
+
 rather than
 
 ```fsharp
    a + b * c
 // _________
 // _____
 ```
+
 Likewise, given the tokens
 
 ```fsharp
 a * b * c
 ```
+
 the left associativity of `*` means we can picture the resolution of the ambiguity as:
 
 ```fsharp

releases/FSharp-Spec-latest.md

@@ -25,6 +25,7 @@ attribute-target :=
     constructor
     event
 ```
+
 ## Custom Attributes
 
 CLI languages support the notion of _custom attributes_ which can be added to most declarations.
@@ -41,6 +42,7 @@ expressions. Attributes on parameters are given as follows:
 ```fsharp
 let foo([<SomeAttribute>] a) = a + 5
 ```
+
 If present, the arguments to a custom attribute must be _literal constant expressions_ , or arrays of the
 same.
 
@@ -60,6 +62,7 @@ type Foo1 [<System.Obsolete("don't use me")>] () =
 type Foo2 [<System.Obsolete("don't use me")>] private () =
     member x.Bar() = 1
 ```
+
 Custom attributes are mapped to compiled CLI metadata as follows:
 
 - Custom attributes map to the element that is specified by their target, if a target is given.
@@ -71,8 +74,8 @@ Custom attributes are mapped to compiled CLI metadata as follows:
     that is named `_F`.
 - A custom attribute on a union case `ABC` for a type `T` is compiled to a custom attribute on a static
     method on the CLI type definition `T`. This method is called:
-    - `get_ABC` if the union case takes no arguments
-    - `ABC` otherwise
+  - `get_ABC` if the union case takes no arguments
+  - `ABC` otherwise
 - Custom attributes on arguments are propagated only for arguments of member definitions, and
     not for “let”-bound function definitions.
 - Custom attributes on generic parameters are not propagated.
@@ -147,7 +150,6 @@ In addition:
     `System.Type` object, although the `System.Type` object is not accessible by using the `typeof`
     operator.
 
-
 However:
 
 - Internal and private function and value definitions are not guaranteed to be given corresponding
@@ -158,5 +160,3 @@ However:
     abbreviations and F# unit-of-measure annotations.
 - The definition of new units of measure results in corresponding compiled CLI type declarations
     with an associated `System.Type`.
-
-