From d9bbbfeea3055b53240752ae3160e8f18db5b2e9 Mon Sep 17 00:00:00 2001
From: xdrm-brackets <xdrm.brackets.dev@gmail.com>
Date: Tue, 13 Nov 2018 14:06:33 +0100
Subject: [PATCH] update readme : add installation instructions

---
 README.md | 116 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 88 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index ebef49f..c171916 100644
--- a/README.md
+++ b/README.md
@@ -18,24 +18,80 @@ author:      xdrm-brackets
 
 <!-- toc -->
 
-  * [I. Commands](#i-commands)
+  * [I. How to use](#i-how-to-use)
+    + [1) Requirements](#1-requirements)
+    + [2) Installation](#2-installation)
+    + [3) Usage](#3-usage)
+        * [1. Create build file](#1-create-build-file)
+        * [2. Run on the target](#2-run-on-the-target)
+  * [II. Commands](#ii-commands)
     + [1) Comments](#1-comments)
-    + [2) package management](#2-package-management)
-    + [3) setup configuration](#3-setup-configuration)
-    + [4) service management](#4-service-management)
-    + [5) aliases](#5-aliases)
-    + [6) custom scripts](#6-custom-scripts)
-  * [II. Path Expressions](#ii-path-expressions)
-    + [File Formats](#file-formats)
+    + [2) Install/remove Packages](#2-installremove-packages)
+    + [3) Setup configuration](#3-setup-configuration)
+    + [4) Service management](#4-service-management)
+    + [5) custom scripts](#5-custom-scripts)
+    + [6) Aliases](#6-aliases)
+  * [III. Path Expressions](#iii-path-expressions)
+    + [1) Syntax](#1-syntax)
+    + [2) File Formats](#2-file-formats)
 - [Example](#example)
 
 <!-- tocstop -->
 
 ----
 
+### I. How to use
 
 
-### I. Commands
+
+#### 1) Requirements
+
+In order to install the `nix-amer` executable, you must have :
+
+- any recent linux system (_has not been tested over other OS_)
+- `go` installed (_has not been tested under version **1.11**_)
+
+
+
+#### 2) Installation
+
+Simply launch the following command in any terminal
+
+```bash
+$ go get -u github.com/xdrm-brackets/nix-amer
+```
+
+> For those who don't know, it will load the project sources into `$GOPATH/src/github.com/xdrm-brackets/nix-amer` and compile into the executable at `$GOPATH/bin/nix-amer`.
+
+
+
+#### 3) Usage
+
+###### 1. Create build file
+
+The first step is to write your build file according to the installation you want. While writing your build file you can check the syntax by using the `-dry-run` command-line argument as follows :
+
+```bash
+$ nix-amer -p apt-get -dry-run <path/to/build/file>
+```
+
+> The `-p` argument (package manager) is mandatory but it will have no effect in `-dry-run` mode. You can use for instance `apt-get` as a default.
+
+
+
+###### 2. Run on the target
+
+Once your build file is correct and fulfills your needs, you can log in to the target machine, install the nix-amer and run it with your build file. Nix-amer's rich and colorful command-line output will give you a good feedback to rapidly fix problems.
+
+
+
+------
+
+
+
+
+
+### II. Commands
 
 Your whole setup remains in 1 only build file. Each line contains one instruction, the list of instructions is listed below.
 
@@ -47,7 +103,7 @@ Each line beginning with one of the following characters : `[`, `#` or `;` is co
 
 
 
-#### 2) package management
+#### 2) Install/remove Packages
 
 These instructions allow you to interact with the package system available on your system.
 
@@ -65,7 +121,7 @@ Remove the listed packages. If more than one, use spaces to separate package nam
 
 
 
-#### 3) setup configuration
+#### 3) Setup configuration
 
 This instruction allow you to set fields of configuration files without the need of an editor and in a developer-readable manner.
 
@@ -77,7 +133,7 @@ Update a configuration file where \<expr\> is a dot-separated human-readable [pa
 
 
 
-#### 4) service management
+#### 4) Service management
 
 These instructions allow you to interact with the service system (_cf. [systemd](https://github.com/systemd/systemd)_).
 
@@ -88,9 +144,21 @@ Perform the action on services. If more than one, use spaces to separate service
 
 
 
-#### 5) aliases
+#### 5) custom scripts
 
-The file format allows you to create aliases to file paths for more readability in the [path expression](#ii-path-expressions) or with the [`run` command](#6-custom-scripts).
+These instructions allow you to use custom scripts for complex operations.
+
+```
+run <script>
+```
+
+Execute the executable located at the path \<script\>. If script is an [alias](#6-aliases) it will resolve to its path
+
+
+
+#### 6) Aliases
+
+The file format allows you to create aliases to file paths for more readability in the [path expression](#ii-path-expressions) or with the [`run` command](#5-custom-scripts).
 
 ```
 alias name /path/to.file
@@ -102,36 +170,28 @@ Create the alias `name` which resolves to the path `/path/to.file`.
 
 
 
-#### 6) custom scripts
-
-These instructions allow you to use custom scripts for complex operations.
-
-```
-run <script>
-```
-
-Execute the executable located at the path \<script\>. If script is an [alias](#5-aliases) it will resolve to its path
-
 
 
 ----
 
 
 
-### II. Path Expressions
+### III. Path Expressions
 
+
+#### 1) Syntax
 The syntax is pretty fast-forward, it uses 2 levels (file, fields) to find your configuration line : `location_or_alias@fields`.
 
 | Field     | Description                          | Example                    |
 | --------- | :----------------------------------- | -------------------------- |
-| `location_or_alias` | Path to the configuration file to edit. The file will be created if not found. If the path is an [alias](#5-aliases) created before in the file, it will resolve to the alias value as a filename. | `/etc/nginx/nginx.conf`, `some-alias` |
+| `location_or_alias` | Path to the configuration file to edit. The file will be created if not found. If the path is an [alias](#6-aliases) created before in the file, it will resolve to the alias value as a filename. | `/etc/nginx/nginx.conf`, `some-alias` |
 | `fields` | Dot-separated chain of strings that match a configuration field. If the field does not point to a raw field but an existing field container, the \<value\> will replace the group with a text value. | `AllowGroups`, `http.gzip` |
 
-> The `fields` is processed only for known file formats listed in this [section](#file-formats).
+> The `fields` is processed only for known file formats listed in this [section](#2-file-formats).
 
 
 
-#### File Formats
+#### 2) File Formats
 
 Configuration files can be written according to some standards or application-specific syntax. This tool uses standard and third-party to parse the following formats :