Many minor fixes to the hs-bindgen manual

README.md

@@ -47,4 +47,3 @@ that can be extended by users for specific applications.
 
 You can find the (currently still very incomplete) manual in
 [manual/](manual/README.md).
-

alternatives/README.md

@@ -81,7 +81,7 @@ It also supports writing some inline-C using `#def`, as some form of poor-man's
 You get no support for declaring function signatures, this piggy-backs on the
 regular FFI (CAPI or otherwise).
 
-See https://ghc.gitlab.haskell.org/ghc/doc/users_guide/utils.html#writing-haskell-interfaces-to-c-code-hsc2hs for more information.
+See <https://ghc.gitlab.haskell.org/ghc/doc/users_guide/utils.html#writing-haskell-interfaces-to-c-code-hsc2hs> for more information.
 
 ## `c2hs`
 
@@ -116,15 +116,15 @@ cShowStruct $ HaskellStruct 1234 5678
 ```
 
 However, the syntax for these is rather arcane, and not all common patterns can
-be expressed (see https://well-typed.com/blog/2023/03/purgatory/ for some
+be expressed (see <https://well-typed.com/blog/2023/03/purgatory/> for some
 examples).
 
 The `Storable` story here is similar to the one in `hsc2hs`, albeit with
 slightly different syntax. Unlike `hsc2hs`, however, `c2hs` does not use the C
 compiler, but does its own calculations; these have been known to be unreliable
 at times, especially with cross compilation.
 
-See https://github.com/haskell/c2hs/wiki/User-Guide for more information.
+See <https://github.com/haskell/c2hs/wiki/User-Guide> for more information.
 
 ## `inline-c`
 
@@ -200,33 +200,33 @@ Haskell files, but from richer API descriptions. In this section we mention a
 few of these; perhaps we can take some inspiration from these API descriptions
 in the kind of customization options that `hs-bindgen` should offer.
 
-### https://github.com/gtk2hs/gtk2hs/tree/master/tools/apiGen
+### <https://github.com/gtk2hs/gtk2hs/tree/master/tools/apiGen>
 
 > It works by extracting an api description from the C source files and
 > extracting documentation from the docbook documentation produced by gtk-doc.
 
-### https://github.com/haskell-gi/haskell-gi
+### <https://github.com/haskell-gi/haskell-gi>
 
 > Generate Haskell bindings for GObject Introspection capable libraries.
 
 This is essential next version of `apiGen`.
 
-### https://github.com/brendanhay/amazonka
+### <https://github.com/brendanhay/amazonka>
 
 > The gen package contain a code generator for synthesising Haskell data types,
 > packages, and configuration from the botocore service definitions.
 
-where https://github.com/boto/botocore is
+where <https://github.com/boto/botocore> is
 
 > A low-level interface to a growing number of Amazon Web Services. The botocore
 > package is the foundation for the AWS CLI as well as boto3. Botocore is
 > maintained and published by Amazon Web Services.
 
-### https://hackage.haskell.org/package/godot-haskell
+### <https://hackage.haskell.org/package/godot-haskell>
 
 Generates bindings from the Godot documentation, not from general header files.
 
-### https://github.com/ekmett/gl
+### <https://github.com/ekmett/gl>
 
 > The `gl` package supplies low level bindings to all of the OpenGL
 > specification for Haskell. This package, `glgen`, is used to build the `gl`
@@ -235,15 +235,15 @@ Generates bindings from the Godot documentation, not from general header files.
 Generates bindings from the [Khronos XML specification of
 OpenGL](https://registry.khronos.org/OpenGL/).
 
-### https://hackage.haskell.org/package/vulkan
+### <https://hackage.haskell.org/package/vulkan>
 
 Generates bindings from the Vulkan docs.
 
 The `README`
 [goes into some detail](https://github.com/expipiplus1/vulkan?tab=readme-ov-file#how-the-c-types-relate-to-haskell-types)
 on the chosen relation between C types and Haskell types.
 
-### https://hackage.haskell.org/package/vulkan-api
+### <https://hackage.haskell.org/package/vulkan-api>
 
 Generate bindings from the Vulkan XML spec. Makes some different choices for the
 mappings; see discussion in

ansi-diff/CHANGELOG.md

@@ -1,3 +1,5 @@
+# Changelog
+
 ## 0.1.0 -- YYYY-mm-dd
 
 * First version. Released on an unsuspecting world.

dev/binding-spec.md

@@ -23,9 +23,9 @@
   To serve as an example, consider a point in time when we have the following
   modules:
 
-    * Module `V1` has version `1.8`.
-    * Module `V2` has version `2.3`.
-    * Module `V3` has version `3.1`.
+  * Module `V1` has version `1.8`.
+  * Module `V2` has version `2.3`.
+  * Module `V3` has version `3.1`.
 
 * We support two types of compatibility.
 

dev/building-manual.md

@@ -14,7 +14,7 @@ for your platform as described in [dev-environment.md](dev-environment.md).
 On the [`manual`](../manual) directory, create the following
 `cabal.project.local` file:
 
-```
+```cabal
 package manual
   extra-include-dirs:
       /path/to/hs-bindgen/manual/c
@@ -37,7 +37,7 @@ package hs-vector
 On Linux, since it supports Unicode characters, also add the following to the
 file:
 
-```
+```cabal
 package *
   ghc-options:
     -optc-DSUPPORTS_UNICODE
@@ -90,8 +90,8 @@ cabal run manual
   export BINDGEN_EXTRA_CLANG_ARGS="-nostdinc $CLANG_ARGS"
   ```
 
-- Missing shared libraries: If you see `cannot open shared object file: No such file or directory`,
-  add the library's directory to `LD_LIBRARY_PATH` on Linux,
+- Missing shared libraries: If you see `cannot open shared object file: No such
+  file or directory`, add the library's directory to `LD_LIBRARY_PATH` on Linux,
   `DYLD_LIBRARY_PATH` on MacOS and `PATH` on Windows.
 
 - Unicode-related compilation errors: Verify that `SUPPORTS_UNICODE` is only
@@ -110,4 +110,4 @@ cabal run manual
 
 ### More troubleshooting
 
-See [here](./troubleshooting.md)
+See the [section on troubleshooting](./troubleshooting.md).

dev/ci.md

@@ -1,3 +1,5 @@
+# Continues development, continuous integration
+
 We have a two tiered CI. In particular
 
 - We do not automatically run CI on pushes.

dev/code-structure.md

@@ -1,3 +1,5 @@
+# Code structure
+
 - `HsBindgen.Language` contains data structures that are more general; that is,
   not directly related to binding generation, and that could live in separate
   packages.

dev/dev-environment.md

@@ -6,6 +6,7 @@ Linux, NixOS, and macOS.
 ## General Prerequisites
 
 All platforms require (last updated October 9, 2025):
+
 - GHC 9.4.8 or greater (or compatible version)
 - Cabal (latest version)
 - LLVM/Clang (version 14 - 21)
@@ -55,25 +56,29 @@ macOS setup is similar to Linux but with platform-specific considerations.
 ### Prerequisites
 
 Install LLVM and Clang:
+
 ```bash
 brew install llvm@16
 ```
 
 ### Environment Setup
 
 1. **Set LLVM paths**:
+
    ```bash
    export LLVM_PATH=/opt/homebrew/opt/llvm@16  # Adjust for your installation
    export LLVM_CONFIG=$LLVM_PATH/bin/llvm-config
    export LIBCLANG_PATH=$LLVM_PATH/lib/
    ```
 
 2. **SDK configuration**:
+
    ```bash
    export SDKROOT=$(xcrun --show-sdk-path --sdk macosx)
    ```
 
 3. **Library paths**:
+
    ```bash
    export DYLD_LIBRARY_PATH=/path/to/your/c/libs:$DYLD_LIBRARY_PATH
    ```
@@ -88,6 +93,7 @@ and Clang, so no separate LLVM installation is needed.
 ### Environment Setup
 
 1. Set LLVM paths (PowerShell):
+
    ```powershell
    $env:LLVM_PATH = "C:\ghcup\ghc\9.12.2\mingw"
    $env:LLVM_CONFIG = "$env:LLVM_PATH\bin\llvm-config.exe"
@@ -97,6 +103,7 @@ and Clang, so no separate LLVM installation is needed.
 2. Library paths:
 
    Windows uses `PATH` for finding DLLs:
+
    ```powershell
    $env:PATH = "C:\path\to\your\c\libs;" + $env:PATH
    ```

dev/project-structure.md

@@ -5,7 +5,7 @@ help new developers understand how the codebase is organized.
 
 ## Repository Layout
 
-```
+```text
 hs-bindgen/
 ├── alternatives/
 ├── ansi-diff/

dev/testing.md

@@ -26,7 +26,7 @@ cabal run -- test-hs-bindgen --accept
 
 A very useful thing to debug failing CI is to add:
 
-```
+```yaml
 - name: Setup tmate session
   uses: mxschmitt/action-tmate@v3
 ```

dev/troubleshooting.md

@@ -10,7 +10,7 @@ with `hs-bindgen`.
 
 Error:
 
-```
+```text
 Error: [Cabal-4345]
 Missing dependency on a foreign library:
 * Missing (or bad) C library: game
@@ -20,14 +20,16 @@ Missing dependency on a foreign library:
 Solution:
 
 1. Build the C libraries first:
+
    ```bash
    cd manual/c
    make
    cd ..
    ```
 
 2. Create a `cabal.project.local` file with proper paths:
-   ```
+
+   ```cabal
    package hs-game
      extra-include-dirs: /path/to/hs-bindgen/manual/c
      extra-lib-dirs:     /path/to/hs-bindgen/manual/c
@@ -45,7 +47,7 @@ Solution:
 
 Error:
 
-```
+```text
 fatal error: manual_examples.h: No such file or directory
 #include "manual_examples.h"
 ```
@@ -60,14 +62,14 @@ Solution:
 
 Error:
 
-```
+```text
 undefined reference to 'hs_bindgen_c_example_helloworld'
 ```
 
 Solution:
 Add the C library to your `.cabal` file:
 
-```
+```cabal
 extra-libraries: hs-bindgen-c-example
 ```
 
@@ -82,7 +84,7 @@ for `lib<name>.so` binary file name.
 
 Error:
 
-```
+```text
 error while loading shared libraries: libhs-bindgen-c-example.so: cannot open shared object file: No such file or directory
 ```
 
@@ -115,6 +117,7 @@ Solution:
 - Linux: Usually works
 - macOS/Windows/LLVM: Avoid Unicode characters in C code
 - Use CPP macros to conditionally handle Unicode:
+
   ```c
   #if defined(SUPPORTS_UNICODE)
   #else

examples/README.md

@@ -13,8 +13,8 @@ examples include bindings and toy programs for the following C libraries:
 The examples are only tested (in CI) on Ubuntu. They might work on other
 distributions such as Windows or MacOS as well, but we offer no guarantees.
 
-The following software should be installed before trying to build and run one of the
-examples:
+The following software should be installed before trying to build and run one of
+the examples:
 
 * A version of GHC that is compatible with `hs-bindgen`, such as `9.6.x`
 * A version of Cabal that is compatible with `hs-bindgen`, such as `3.16.x`
@@ -60,33 +60,37 @@ as the following requirements are met:
   * The package should have its own project file at
     `REPOSITORY_ROOT/examples/libfoo/hs-project/cabal.project`, which should
     contain at least:
-    ```
+
+    ```cabal
     import: ../../../cabal.project.base
     packages: .
               ../../../c-expr-runtime
               ../../../hs-bindgen-runtime
     ```
+
     If other `hs-bindgen` packages are required, add them to `packages`.
-*  Add a script at `REPOSITORY_ROOT/examples/libfoo/generate-and-run.sh`
-  * The script should install the `libfoo` C package (locally)
-  * The script should run `hs-bindgen-cli` on `libfoo`'s header files and put
+* Add a script at `REPOSITORY_ROOT/examples/libfoo/generate-and-run.sh`
+* The script should install the `libfoo` C package (locally)
+* The script should run `hs-bindgen-cli` on `libfoo`'s header files and put
     the generated modules into the Haskell project
-  * The script should make sure that the Haskell package can find the installed
+* The script should make sure that the Haskell package can find the installed
     `libfoo` package. For locally installed packages, this probably means
     setting `LD_LIBRARY_PATH` and updating the
     `REPOSITORY_ROOT/examples/libfoo/hs-project/cabal.project.local` file so
     that it includes:
-    ```
+
+    ```cabal
     package libfoo
       extra-include-dirs:
         -- insert absolute path to installation directory for header files here
       extra-lib-dirs:
         -- insert absolute path to installation directory for dll files here
     ```
+
     If a `cabal.project.local` file already exists, then the file should be
     updated to include the lines above. Otherwise, it should create the file
     with the lines above.
-  * The script should run the Haskell executable
+* The script should run the Haskell executable
 * Add a composite action by creating a new file at
    `REPOSITORY_ROOT/.github/actions/examples/libfoo.action.yml`
   * The composite action should install example-specific prerequisites, such as
@@ -96,11 +100,12 @@ as the following requirements are met:
 * Update the workflow file at `REPOSITORY_ROOT/.github/workflows/examples.yml`
   * Add `'libfoo'` to the `example` array of the workflow matrix
   * Towards the end of the file, add a step that calls the `libfoo` composite action:
+
     ```yml
     - name: 🧪 Build and run libfoo example
       if: ${{ matrix.example == 'libfoo' }}
       uses: ./.github/actions/examples/libfoo
     ```
 
 Now create a PR with these changs and (hopefully) you will observe that a new
-job is run that tests the new example project.
+job is run that tests the new example project.

examples/botan/README.md

@@ -12,6 +12,7 @@ nix-shell -p ccache
 ```
 
 Or, for example, on Ubuntu:
+
 ```bash
 apt-get install ccache
 ```
@@ -25,6 +26,7 @@ TODO: on Windows, use sccache instead
 ```
 
 This script will:
+
 1. Build the botan-3 C++ library
 2. Generate Haskell bindings using `hs-bindgen`
 3. Create `cabal.project.local` with the necessary configuration

examples/c-minisat/README.md

@@ -19,6 +19,7 @@ nix-shell -p minisat
 ```
 
 This script will:
+
 1. Build the minisat-c-bindings C library
 2. Create symbolic links for the shared library (see quirks below)
 3. Generate Haskell bindings using `hs-bindgen`