Add markdownlint config and resolve existing issues

.github/workflows/cla_assistant.yml

@@ -13,7 +13,7 @@ jobs:
     steps:
       - name: "CLA Assistant"
         if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the Contributor License Agreement and I hereby accept the Terms.') || github.event_name == 'pull_request_target'
-        uses: cla-assistant/github-action@v2.1.3-beta
+        uses: cla-assistant/github-action@v2.3.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PERSONAL_ACCESS_TOKEN : ${{ secrets.CLA_BOT_ACCESS_TOKEN }}
@@ -26,4 +26,4 @@ jobs:
           custom-pr-sign-comment: 'I have read the Contributor License Agreement and I hereby accept the Terms.'
           allowlist: user1,bot*
           # edit the path below (if needed) to point to the document containing the CLA that a contributor agrees to
-          path-to-document: 'https://github.com/qir-alliance/qir-spec/blob/main/Contributor_License_Agreement.md' 
+          path-to-document: 'https://github.com/qir-alliance/qir-spec/blob/main/Contributor_License_Agreement.md'

.github/workflows/link_and_spell_check.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     name: "Check spelling, linting and links"
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - run: |
         wget https://github.com/qir-alliance/.github/archive/refs/heads/main.zip -O clone.zip &&
         unzip clone.zip && mv .github-main out && rm clone.zip &&
@@ -38,7 +38,7 @@ jobs:
       if: ${{ success() || failure() }}
     - name: "Check spelling in changed files"
       # cspell:words streetsidesoftware
-      uses: streetsidesoftware/cspell-action@v1.2.4
+      uses: streetsidesoftware/cspell-action@v6
       with:
         inline: warning
         # Only warn on spelling errors, since there's likely a lot of false

.markdownlint.yaml

@@ -0,0 +1,25 @@
+# Reference: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+
+# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
+MD013:
+  # Number of characters
+  line_length: 80
+  # Number of characters for headings
+  heading_line_length: 80
+  # Number of characters for code blocks
+  code_block_line_length: 180
+  # Include code blocks
+  code_blocks: true
+  # Include tables
+  tables: false
+  # Include headings
+  headings: true
+  # Strict length checking
+  strict: false
+  # Stern length checking
+  stern: false
+
+# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md033.md
+MD033:
+  # Allowed elements
+  allowed_elements: ["br"]

README.md

@@ -18,8 +18,8 @@ documentation to facilitate working with QIR.
 
 ### Asking and Answering Questions
 
-Have a question? This repository is great places to ask questions about QIR and
-the available tools to work with it. Your question will serve as resource to
+Have a question? This repository is a great place to ask questions about QIR and
+the available tools to work with it. Your question will serve as a resource to
 others searching for help. Please file an issue to ask your question
 [here](https://github.com/qir-alliance/qir-spec/issues/new).
 
@@ -51,7 +51,7 @@ have any questions or would like to revoke your consent, please contact
 [[email protected]](mailto:[email protected]).
 
 For more information about the development process for specifications under the
-QIR Alliance, please see the the governance policy available
+QIR Alliance, please see the governance policy available
 [here](https://github.com/qir-alliance/.github/blob/main/Governance.md).
 
 ### Contributing an Implementation
@@ -72,4 +72,4 @@ possible. Thank you for taking the time to contribute.
 This project has adopted the community specification [Code of
 Conduct](https://github.com/qir-alliance/.github/blob/main/Code_of_Conduct.md#contributor-covenant-code-of-conduct).
 Please contact [[email protected]](mailto:[email protected]) for Code of
-Conduct issues or inquires.
+Conduct issues or inquiries.

Resources.md

@@ -17,7 +17,7 @@ about:
 - [A quick introduction to
   LLVM](https://hub.packtpub.com/introducing-llvm-intermediate-representation/)
 - [Gitbook about LLVM-based
-  compilers](https://mapping-high-level-constructs-to-llvm-ir.readthedocs.io/en/latest/README.html)
+  compilers](https://mapping-high-level-constructs-to-llvm-ir.readthedocs.io/en/latest/)
 - [Language reference manual](https://llvm.org/docs/LangRef.html)
 - [Wikipedia entry](https://en.wikipedia.org/wiki/LLVM)
 - [Original publication](https://llvm.org/pubs/2004-01-30-CGO-LLVM.pdf)

specification/v0.1/1_Data_Types.md

@@ -68,8 +68,8 @@ with values of type `%Result*`:
 
 | Function                          | Signature                | Description |
 |-----------------------------------|--------------------------|-------------|
-| __quantum__rt__result_get_zero    | `%Result*()`             | Returns a constant representing a measurement result zero.
-| __quantum__rt__result_get_one     | `%Result*()`             | Returns a constant representing a measurement result one.
+| __quantum__rt__result_get_zero    | `%Result*()`             | Returns a constant representing a measurement result zero. |
+| __quantum__rt__result_get_one     | `%Result*()`             | Returns a constant representing a measurement result one.  |
 | __quantum__rt__result_equal       | `i1(%Result*, %Result*)` | Returns true if the two results are the same, and false if they are different. If a `%Result*` parameter is null, a runtime failure should occur. |
 | __quantum__rt__result_update_reference_count   | `void(%Result*, i32)` | Adds the given integer value to the reference count for the result. Deallocates the result if the reference count becomes 0. The behavior is undefined if the reference count becomes negative. The call should be ignored if the given `%Result*` is a null pointer. |
 
@@ -322,4 +322,4 @@ For all of these functions, if an `%Array*` pointer is null, a runtime failure
 should occur.
 
 ---
-_[Back to index](README.md)_
+*[Back to index](README.md)*

specification/v0.1/2_Callables.md

@@ -3,8 +3,8 @@
 We use the term _callable_ to mean a subroutine in the source language.
 Different source languages use different names for this concept.
 
-> *Note:* <br/>
-The QIR specification permits the usage of subroutines as first class values,
+> [!NOTE]
+> The QIR specification permits the usage of subroutines as first class values,
 and includes the necessary expressiveness to e.g. provide runtime support for
 functor application. This introduces the need to define a common structure to
 represent callable values and their arguments. If the source language does not
@@ -389,4 +389,4 @@ callable values:
 | __quantum__rt__capture_update_alias_count | `void(%Callable*, i32)`                      | Invokes the function at index 1 in the memory management table of the callable with the capture tuple and the given 32-bit integer. Does nothing if the memory management table pointer or the function pointer at that index is null, or if the given `%Callable*` is a null pointer. |
 
 ---
-_[Back to index](README.md)_
+*[Back to index](README.md)*

specification/v0.1/3_Classical_Runtime.md

@@ -68,4 +68,4 @@ reference counts as hints or as simple no-ops.
   instance pointer and simply ignore the call if the pointer is null.
 
 ---
-_[Back to index](README.md)_
+*[Back to index](README.md)*

specification/v0.1/5_Metadata.md

@@ -75,4 +75,4 @@ marked with an LLVM "EntryPoint" attribute.
 >use.
 
 ---
-_[Back to index](README.md)_
+*[Back to index](README.md)*

specification/v0.1/7_Profiles.md

@@ -82,4 +82,4 @@ restrictions:
   appear as literals.
 
 ---
-_[Back to index](README.md)_
+*[Back to index](README.md)*

specification/v0.1/8_Library_Reference.md

@@ -62,8 +62,8 @@ This table lists all of the runtime functions specified by QIR:
 | __quantum__rt__qubit_to_string   | `%String*(%Qubit*)`  | Returns a string representation of the qubit. |
 | __quantum__rt__range_to_string   | `%String*(%Range)`   | Returns a string representation of the range. |
 | __quantum__rt__result_equal       | `i1(%Result*, %Result*)` | Returns true if the two results are the same, and false if they are different. If a `%Result*` parameter is null, a runtime failure should occur. |
-| __quantum__rt__result_get_one     | `%Result*()`             | Returns a constant representing a measurement result one.
-| __quantum__rt__result_get_zero    | `%Result*()`             | Returns a constant representing a measurement result zero.
+| __quantum__rt__result_get_one     | `%Result*()`             | Returns a constant representing a measurement result one.  |
+| __quantum__rt__result_get_zero    | `%Result*()`             | Returns a constant representing a measurement result zero. |
 | __quantum__rt__result_to_string  | `%String*(%Result*)` | Returns a string representation of the result. |
 | __quantum__rt__result_update_reference_count   | `void(%Result*, i32)` | Adds the given integer value to the reference count for the result. Deallocates the result if the reference count becomes 0. The behavior is undefined if the reference count becomes negative. The call should be ignored if the given `%Result*` is a null pointer. |
 | __quantum__rt__string_concatenate | `%String*(%String*, %String*)` | Creates a new string that is the concatenation of the two argument strings. If a `%String*` parameter is null, a runtime failure should occur. |
@@ -77,4 +77,4 @@ This table lists all of the runtime functions specified by QIR:
 | __quantum__rt__tuple_update_alias_count | `void(%Tuple*, i32)` | Adds the given integer value to the alias count for the tuple. Fails if the count becomes negative. The call should be ignored if the given `%Tuple*` is a null pointer. |
 | __quantum__rt__tuple_update_reference_count   | `void(%Tuple*, i32)` | Adds the given integer value to the reference count for the tuple. Deallocates the tuple if the reference count becomes 0. The behavior is undefined if the reference count becomes negative. The call should be ignored if the given `%Tuple*` is a null pointer. |
 ---
-_[Back to index](README.md)_
+*[Back to index](README.md)*