Manual: Translation part

Author: dschrempf

manual/LowLevel/Translation/01-GeneratedNames.md

@@ -19,7 +19,7 @@ Haskell name will be, and also is less likely to result in name clashes.
 
 By default, we use the name in the C header wherever one exists. An obvious
 example is function definitions, where the candidate name for a function `foo`
-is simply `foo`. Similarly, if a struct is given a tag or a typedef,
+is simply `foo`. Similarly, if a `struct` is given a tag or a `typedef`,
 
 ```c
 struct foo { .. };

manual/LowLevel/Translation/02-Structs.md

@@ -22,18 +22,16 @@ data Triple = Triple
   , triple_b :: CInt
   , triple_c :: CInt
   }
+  deriving stock (Eq, Show)
 
 instance F.Storable Triple where ...
-deriving stock instance Show Triple
-deriving stock instance Eq Triple
 ```
 
 ## Structures with and without `typedef`
 
 Adding a `typedef` matching the name of the structure, or using a `typedef` in
 place of a structure name, does not change the generated bindings. For more
-details, see the [section on name
-generation](/manual/LowLevel/GeneratedNames.md).
+details, see the [section on name generation](01-GeneratedNames.md).
 
 ```c
 typedef struct triple triple;
@@ -47,10 +45,8 @@ typedef struct triple triple_t;
 
 ```haskell
 newtype Triple_t = Triple_t { un_Triple_t :: Triple }
-
-deriving newtype instance F.Storable Triple_t
-deriving stock instance Eq Triple_t
-deriving stock instance Show Triple_t
+  deriving stock   (Eq, Show)
+  deriving newtype (Storable)
 ```
 
 ## Nested structures
@@ -82,7 +78,7 @@ creates the following bindings (instances omitted for brevity):
 ```haskell
 data Door = Door
   { door_height :: CFloat
-  , door_width :: CFloat
+  , door_width  :: CFloat
   }
 
 data Room = Room
@@ -135,7 +131,7 @@ struct aula2 {
 ```haskell
 data Aula2_door = Aula2_door
   { aula2_door_height :: CFloat
-  , aula2_door_width :: CFloat
+  , aula2_door_width  :: CFloat
   }
 
 data Aula2 = Aula2
@@ -166,11 +162,11 @@ structure in their `Storable` instance:
 
 ```haskell
 data Aula_setup = Aula_setup
-  { aula_setup_window_id :: CChar
-  , aula_setup_tilt :: CInt
+  { aula_setup_window_id    :: CChar
+  , aula_setup_tilt         :: CInt
   , aula_setup_close_blinds :: CInt
   , aula_setup_projector_id :: CChar
-  , aula_setup_power_mode :: CInt
+  , aula_setup_power_mode   :: CInt
   }
 
 instance F.Storable Aula_setup where
@@ -304,5 +300,5 @@ foreign import ccall safe "Structs_create_square" create_square
   :: CDouble -> IO (Ptr Square)
 ```
 
-Note that opaque types do not get a Storable instance, and therefore can not be
+Note that opaque types do not get a `Storable` instance, and therefore can not be
 used by value.

manual/LowLevel/Translation/03-Enums.md

@@ -124,8 +124,8 @@ class Integral (CEnumZ a) => CEnum a where
   toCEnum   :: CEnumZ a -> a
   fromCEnum :: a -> CEnumZ a
 
-  declaredValues  :: proxy a -> DeclaredValues a
-  showsUndeclared :: proxy a -> Int -> CEnumZ a -> ShowS
+  declaredValues     :: proxy a -> DeclaredValues a
+  showsUndeclared    :: proxy a -> Int -> CEnumZ a -> ShowS
   readPrecUndeclared :: ReadPrec a
 ```
 
@@ -143,7 +143,7 @@ instance CEnum Index where
     , (1, NonEmpty.singleton "B")
     , (2, NonEmpty.singleton "C")
     ]
-  showsUndeclared = showsWrappedUndeclared "Index"
+  showsUndeclared    = showsWrappedUndeclared "Index"
   readPrecundeclared = readPrecWrappedUndeclared "Index"
 ```
 
@@ -250,7 +250,7 @@ showCursorKind :: CXCursorKind -> String
 showCursorKind = \case
     CXCursor_UnexposedExpr -> "CXCursor_UnexposedExpr"
     CXCursor_UnexposedStmt -> "CXCursor_UnexposedStmt"
-    kind -> show kind
+    kind                   -> show kind
 ```
 
 We also provide a helper function `showCEnum` for C enums without a specialized

manual/LowLevel/Translation/06-Globals.md

@@ -193,11 +193,11 @@ x_ptr = unsafePerformIO fe8f4js8
 
 Memory layout:
 
-| type                     | name          | address | value   |
-| ------------------------ | ------------- | ------- | ------- |
-| int                      | x             | 1000    | 17      |
-|                          |               | ...     |         |
-| int* ; Ptr CInt          | x_ptr         | 2000    | 1000    |
+| type              | name  | address | value |
+|-------------------|-------|---------|-------|
+| `int`             | x     | 1000    | 17    |
+|                   |       | ...     |       |
+| `int* ; Ptr CInt` | x_ptr | 2000    | 1000  |
 
 Constant:
 
@@ -380,13 +380,13 @@ x_elem_ptr = IncompleteArray.toFirstElemPtr x_ptr
 
 Memory layout:
 
-| type                                  | name          | address | value   |
-| ------------------------------------- | ------------- | ------- | ------- |
-| int[]                                 | x             | 1000    | 1       |
-|                                       |               | 1004    | 2       |
-|                                       |               | 1008    | 3       |
-|                                       |               | ...     |         |
-| (*int)[] ; Ptr (IncompleteArray CInt) | x_ptr         | 2000    | 1000    |
+| type                                    | name  | address | value |
+|-----------------------------------------|-------|---------|-------|
+| `int[]`                                 | x     | 1000    | 1     |
+|                                         |       | 1004    | 2     |
+|                                         |       | 1008    | 3     |
+|                                         |       | ...     |       |
+| `(*int)[] ; Ptr (IncompleteArray CInt)` | x_ptr | 2000    | 1000  |
 
 Constant:
 

manual/LowLevel/Usage/06-BindingSpecifications.md

@@ -123,7 +123,7 @@ module Vector.Types where
 
 newtype Length = UnsafeWrap { unwrap :: Double }
 
-instance Show Length where ..
+instance Show Length where ...
 
 pattern Length :: Double -> Length
 pattern Length x <- (unwrap -> x)

manual/c/structs.h

@@ -1,5 +1,18 @@
 #include <stdio.h>
 
+/* -------------------------------------------------------------------------- */
+/* Structures with and without typedef. */
+
+typedef struct triple {
+  int a;
+  int b;
+  int c;
+} triple;
+
+typedef struct triple triple_t;
+
+void mk_triple(int a, int b, int c, triple *triple);
+
 /* -------------------------------------------------------------------------- */
 /* Nested structures. */
 

manual/hs/manual/app/Manual/Types/Structs.hs

@@ -14,9 +14,6 @@ import HsBindgen.Runtime.FlexibleArrayMember qualified as FLAM
 import HsBindgen.Runtime.IncompleteArray qualified as IA
 
 import Manual.Tools
-
-import Example
-import Example.Unsafe
 import Structs
 import Structs.Safe