reword most of Documentation

Signed-off-by: Matthias Gatto <[email protected]>

HACKING.md

@@ -1,32 +1,29 @@
 # Do You Want To Know More?
 
-*Info that will be useful if you want to Hack COGNAC*
+*Essential Information for Hacking COGNAC*
 
-## Unix philosophy, and COGNAC Paradigms.
+## Unix Philosophy and COGNAC Paradigms.
 
-Most peoples have hear the sentence "Do One Thing and Do It Well", and heard that's how Unix is and how Unix should be.
+Most people have heard the phrase "Do One Thing and Do It Well" and associate it with the Unix philosophy. It’s said that this is how Unix operates and how it should be.
 
-I personally don't know how much this is true nor a good idea, and like most peoples I use to pretend to understand this, but did not, I don't know if I got it now, but I have a far better understand of what it uses to.
+Personally, I used to wonder how much truth there was to this statement, or whether it was even a good idea. Like many others, I would nod along, pretending to understand it, but I didn’t really get it. Now, though, I feel I have a much better understanding of what it truly means.
 
-How so ? You didn't ask. By reading source from some Unix OS.
-When I read a complete [shell](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s1/sh.c), the whole source of [ls](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s6/ls.c), or a fully running [cat](https://github.com/klange/toaruos/blob/master/apps/cat.c), I got hit by the realisation that most of those programmes take less line of code, that I would need to write half of an object interface in any language.
+ow, you ask? By reading the source code of some Unix-based OSes.
+When I read a complete [shell](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s1/sh.c), the whole source of [ls](https://github.com/dspinellis/unix-history-repo/blob/BSD-1-Snapshot-Development/s6/ls.c), or a fully running [cat](https://github.com/klange/toaruos/blob/master/apps/cat.c), I had a realization: most of these programs are written in far fewer lines of code than I would need just to write half of an object interface in a modern language.
 
-But it kind of made sense, programmes were made to interact together, and where we tend to see a program as a whole project, a program on Unix use to do only one thing, and do it well.
-You don't need modularity in your program if writing a whole program anew is faster than creating an interface, and as program are made to interact together, it's not completely wrong to see cat/grep/wc or any Unix program as an object, inheriting some text handling class.
+It started to make sense. These programs were built to interact with each other. While we tend to view programs as entire projects nowadays, in Unix, a program was designed to do just one thing—and do it well. Modularity wasn’t a priority. Why create a complex interface when writing an entirely new program could be faster? In Unix, programs like cat, grep, and wc are almost like objects in an object-oriented system, inheriting basic text-handling class.
 
-COGNAC is bash, and as sure try to follow this idea.
+COGNAC is based on Bash, and it follows a similar philosophy.
 
-It use lot of small program interactive together, and is complet by a few utilities in bin/ that do some text handling.
+It uses a lot of small programs that interact with each other and is supplemented by a few utilities in the bin/ directory that handle text processing tasks.
 
-Makefile was create to... make files, and so Makefile is use that way.
+The Makefile was originally created to "make" files, and COGNAC uses it in that way.
 
-Scripts use by the makefile, do the job of creating the file, and the makefile check that they have been created, and that there's no need to rebuild them.
+The scripts used by the Makefile handle the actual file creation, while the Makefile itself checks if files need to be rebuilt or not.
 
 ## Templating
 
-the templating system cognac is homemade, it read SRC file and generate DEST file
-it uses multiple keyword, each surrounded by 4 underscore (example: `____api_version____`)
-as an example, you can look at [lib.h](./lib.h) or [main_tpl.c](./main_tpl.c)
+COGNAC’s templating system is homemade. It reads SRC files and generates DEST files. It uses several keywords, each surrounded by four underscores (e.g., `____api_version____`).
+For example, you can check out [lib.h](./lib.h) or [main_tpl.c](./main_tpl.c)
 
-Some rules support multiples languages sure as `____func_code____`, which will generate functions calls,
-and some are not. (like `____functions_proto____` which for now support only C)
+Some rules support multiple languages, like `____func_code____`, which generates function calls. Others, like `____functions_proto____`, currently support only C.

README.md

@@ -3,48 +3,46 @@
 
 ## Usage
 
-*note: The main purpose of this repository is to generate source code. If your goal is to compile osc-sdk-c or oapi-cli, please use their respective repositories, which handle the code generation process for you.*
+*note: The primary purpose of this repository is to generate source code. If your goal is to compile osc-sdk-c or oapi-cli, please refer to their respective repositories, which handle the code generation process for you.*
 
 ### Brief
 
-configure COGNAC Makefile using `./configure`
-you can use `cognac_gen.sh SOURCE DEST LANGUAGE` to generate a file from a template
-the Makefile is here to help you generate all the files.
-if you want to generate everything, just call `make`
+To configure the COGNAC Makefile, use `./configure.`
+You can use `cognac_gen.sh SOURCE DEST LANGUAGE` to generate files from a template.
+The Makefile is designed to help you generate all the required files.
+If you want to generate everything, simply run `make`.
 
 ### Generated Files
 
-COGNAC generate 4 files:
-- main.c: source of the cli
-- osc_sdk.h: header of C library
-- osc_sdk.c: code of C library
-- $(CLI_NAME)-completion.bash: autocompletion file
+COGNAC generates four main files:
+- main.c: Source code for the CLI.
+- osc_sdk.h: Header file for the C library.
+- osc_sdk.c: Source code for the C library.
+- $(CLI_NAME)-completion.bash: Autocompletion file for the CLI.
 
 ### cognac_gen.sh
 
-cognac_gen.sh is the script that generate everything, it's a shell script, that call sub-shell script,
-and a few C binaries that are compiled by the Makefile. (see bin/)
+cognac_gen.sh is the script responsible for generating all the necessary files. It’s a shell script that calls sub-shell scripts and executes a few C binaries, which are compiled by the Makefile (see bin/).
 
-It takes 3 arguments, a source file, a destination file, and a language.
-The language is here because some keyword can be interpreted differently depending on the wanted language.
+It takes three arguments: a source file, a destination file, and a language.
+The language argument is crucial as certain keywords might be interpreted differently depending on the target language.
 
-It uses a file call osc-api.json which is the OpenAPI represent as json.
-For Outscale API, we take the yaml source, and convert it to json using yq.
+The script uses a file called osc-api.json, which represents the OpenAPI specification in JSON format.
+For the Outscale API, the YAML source is converted to JSON using yq.
 
-When generated API Call, COGNAC assume that the OpenAPI file have some components named CallRequest,
-So if the API have a call named `CreatePony`, it should have a `#/components/schemas/CreatePonyRequest`.
+When generating API calls, COGNAC assumes that the OpenAPI file contains components named CallRequest.
+For example, if the API has a call named `CreatePony`, the corresponding component should be located at `#/components/schemas/CreatePonyRequest`.
 
-*Note: 2 versions of yq exist, one in python and one in go, default yq depend on the distribution. On Arch base the python is the default one, on Debian-base it's the go, cognac handle both, but in order to use the go version you need to pass `--yq-go` to `./configure`*
+*Note: There are two versions of yq: one written in Python and one in Go. The default version depends on your distribution. On Arch-based distributions, the Python version is typically the default, whereas on Debian-based distributions, the Go version is default. COGNAC supports both, but to use the Go version, you need to pass `--yq-go` to `./configure`.*
 
-### Example with a new api.
+### Example: Generating a CLI for a New API
 
-You have an API, that is not outscale api, and want to generate a CLI, from it.
-You have only an UNL with a yaml file, let's say `https://ponyapi.yolo`
-The API Request componant are not call "XRequest" but "XInput".
+Let’s say you have an API that is not the Outscale API, and you want to generate a CLI for it.
+You have a URL to a YAML file, such as `https://ponyapi.yolo/`, and the API request components are named `XInput` instead of `XRequest`.
 
-The first step is to configure the Makefile to handle the CLI name `pony-cli`, and tell Makefile how to get the API, and change the `Input` to `request`.
+To configure the Makefile to generate the CLI with the name `pony-cli`, and adjust the component naming convention, follow these steps:
 
-To do so, you first call 
+Run the following command:
 ```bash
 ./configure --cli-name=pony-cli --api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG) | sed "s/Input/Request/" > osc-api.json'
 ```
@@ -54,39 +52,47 @@ To do so, you first call
 ```bash
 --api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG) | sed "s/Input/Request/" > osc-api.json'
 ```
-Is the script that will be used to get the api-file.
+This script is used to fetch the API file.
 
 
-First, it retrieves the API in yaml using `curl -s https://ponyapi.yolo`
-Then convert it to json using `| yq $(YQ_ARG)`, *Note the usage of `$(YQ_ARG)`, so ./configure can handle go version of yq*
-Finally, rename all component named `XInput` into `XRequest`.
+Here’s what the script does:
 
-Doing so you can now use the Makefile, but you should also check `./configure --help` which contain some useful options.
-`--wget-json-search` and `--compile-json-c` are 2 useful options as json-search is not easy to install, and a recent version of `json-c` is required if you want to support colour.
+1. Retrieves the API in YAML format using curl -s `https://ponyapi.yolo/.`
+2. Converts the YAML to JSON using yq `$(YQ_ARG)`. *Note the usage of `$(YQ_ARG)`, so ./configure can handle go version of yq*
+3. Renames all components named `XInput` to `XRequest`.
 
-Now you can simply call `make` which will generate every file, and compile the CLI for you.
-It will also create a C SDK, which will be made of 2 files: `osc-sdk.c` and `osc-sdk.h`.
+Once this setup is complete, you can now use the Makefile. It's also a good idea to run ./configure --help, as it contains several useful options.
+- `--wget-json-search`: Helps with downloading `json-search`, which can be tricky to install.
+- `--compile-json-c`: Ensures a recent version of `json-c` is compiled, required for color support.
 
-If you want more control on the generation, you can call make rules yourself, so `make main.c osc_sdk.c osc_sdk.h pony-cli-completion.bash pony-cli`
+Now, simply run `make` to generate all necessary files and compile the CLI. This will also create a C SDK, consisting of two files: `osc-sdk.c` and `osc-sdk.h`.
 
+If you want more control over the generation process, you can manually invoke specific Makefile rules:
+```bash
+make main.c osc_sdk.c osc_sdk.h pony-cli-completion.bash pony-cli
+```
 
-## Dependency
 
-Non-exhaustive list:
+## Dependencies
+
+Here’s a non-exhaustive list of required dependencies:
 - GNU sed
 - bash
 - jq
 - [json-search](https://github.com/cosmo-ray/json-search)
 - make
 - pkg-config
-- C Compiller
+- C Compiler
+
+### Optional Dependencies
+- libfuse2 (require if building appimage or with `--wget-json-search`)
 
 
 ## Contribution
 
 Open Pull Requests and Issues are welcome.
 
-If you want to add binary in bin/ please try to make it easy to compile.
-That mean, don't add dependencies that are not already require by a CLI.
+If you want to add binaries to the bin/ directory, please ensure they are easy to compile.
+This means avoiding additional dependencies that are not already required by the CLI.
 
 For more information about cognac code, see [HACKING.md](./HACKING.md)