From f5e50130a03461035535d3720feb5174507c6532 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=A9cate=20Kleidukos?=
Date: Mon, 22 Jul 2024 00:05:22 +0200
Subject: [PATCH 1/2] Start the manual and architecture document
---
README.md | 30 +++-----------------------
doc/ARCHITECTURE.md | 3 +++
doc/MANUAL.md | 52 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 58 insertions(+), 27 deletions(-)
create mode 100644 doc/ARCHITECTURE.md
create mode 100644 doc/MANUAL.md
diff --git a/README.md b/README.md
index 860c985..4a060bf 100644
--- a/README.md
+++ b/README.md
@@ -19,32 +19,8 @@ The tool can be used with the following GHC versions:
Pick the one that matches your operating system *and* GHC version.
-## Usage
+## 🤸 Documentation
-Go in your project and build it with the GHC environment files enabled:
+Read the [Manual](./doc/MANUAL.md) to learn how to use this tool
-```
-$ cabal build --write-ghc-environment-files=always
-```
-
-Then run the `print-api` binary from within the same directory:
-
-```
-$ print-api -p
-```
-
-For instance in the [`text-display`](https://github.com/haskell-text/text-display) repository:
-
-```haskell
-❯ print-api -p text-display
-
-module Data.Text.Display where
- type Display :: * -> Constraint
- class Display a where
- displayBuilder :: a -> Data.Text.Internal.Builder.Builder
- displayList :: [a] -> Data.Text.Internal.Builder.Builder
- displayPrec :: GHC.Types.Int -> a -> Data.Text.Internal.Builder.Builder
- {-# MINIMAL displayBuilder | displayPrec #-}
- {-# MINIMAL displayBuilder | displayPrec #-}
- type role OpaqueInstance phantom representational
-```
+Additional details can be found in the [Architecture document](./doc/ARCHITECTURE.md)
diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md
new file mode 100644
index 0000000..976c3e9
--- /dev/null
+++ b/doc/ARCHITECTURE.md
@@ -0,0 +1,3 @@
+# Architecture
+
+## How the GHC API is used
diff --git a/doc/MANUAL.md b/doc/MANUAL.md
new file mode 100644
index 0000000..b7ef58b
--- /dev/null
+++ b/doc/MANUAL.md
@@ -0,0 +1,52 @@
+## NAME
+
+print-api – Export the public API of your Haskell package
+
+## SYNOPSIS
+
+
+ - print-api (-p|--package-name PACKAGE NAME)
+ - Export the API of a package
+
+
+## DESCRIPTION
+
+*print-api* exports the API exposed by a Haskell package. This is used to maintain a file that can be tracked by version control and used in Golden Tests.
+
+## OPTIONS
+
+### -p|--package-name PACKAGE NAME
+
+_Mandatory_
+
+Specify for which package you wish to have the API export.
+
+## Usage
+
+Go in your project and build it with the GHC environment files enabled:
+
+```
+$ cabal build --write-ghc-environment-files=always
+```
+
+Then run the `print-api` binary from within the same directory:
+
+```
+$ print-api -p
+```
+
+For instance in the [`text-display`](https://github.com/haskell-text/text-display) repository:
+
+```haskell
+❯ print-api -p text-display
+
+module Data.Text.Display where
+ type Display :: * -> Constraint
+ class Display a where
+ displayBuilder :: a -> Data.Text.Internal.Builder.Builder
+ displayList :: [a] -> Data.Text.Internal.Builder.Builder
+ displayPrec :: GHC.Types.Int -> a -> Data.Text.Internal.Builder.Builder
+ {-# MINIMAL displayBuilder | displayPrec #-}
+ {-# MINIMAL displayBuilder | displayPrec #-}
+ type role OpaqueInstance phantom representational
+```
From 92269342ebd6bf4f632016488ee709a6862992c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=A9cate=20Kleidukos?=
Date: Mon, 22 Jul 2024 00:13:10 +0200
Subject: [PATCH 2/2] lay out the plan
---
doc/ARCHITECTURE.md | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md
index 976c3e9..012b5b7 100644
--- a/doc/ARCHITECTURE.md
+++ b/doc/ARCHITECTURE.md
@@ -1,3 +1,7 @@
# Architecture
-## How the GHC API is used
+## The GHC API
+
+### Compatibility over several versions
+
+### The package database