Restructure README

1 files changed, 117 insertions, 119 deletions

diff --git a/README b/README
index 167677e..d86c082 100644
--- a/README
+++ b/README
@@ -29,7 +29,6 @@ Previous developments
 3. From a directory full of blocks, find the latest block of the longest chain
 4. API for calling some of the bash scripts
 
-
 Description
 -----------
 This is an installable repository which provides various tools for running
@@ -114,97 +113,6 @@ This will output an archive with your aknet-gpg-keyring to your $HOME folder.
 
 It will NOT remove your IPFS repository, neither is going to clean it.
 
-Examples
---------
-
-### Add a news article ( `ak -m news --add` )
-
-You could use ZCHAIN with NEWS model. Or MIXTAPE model, or make your own.
-``` bash
-$ ak -m news --create
-```
-
-This would pop up a vim editor for you to write a news article or whatever is
-text or markdown format with a title.
-
-Saving the file, will save it locally, add it to IPFS, sign it, pack detached
-signature with metadata on a JSON object. Then a block will be created packing
-your GPG public key, the news/add action with the JSON object and a detached
-signature of this, timestamp and finally an entry for the previous *zblock*.
-After that, we finally write this as a JSON object, add it to IPFS, sign it
-and pack a *ZBLOCK*. The ZBLOCK is then published over our IPNS zchain key.
-
-Other options... let's try help!
-
-``` console
-$ ak -m news -h
-ak-news - Module to read, create and add zblocks
-================================================
-    -h, --help                  Prints this help message
-    -l, --local-index           Prints an indexed table of your news files
-    -i, --import <file>         #TODO
-    -a, --add <file>            Creates a data file from the news file you point to
-    -r, --read <zblock>         Reads a zblock as a news data
-    -c, --create                Vim is going to pop up, you will write and save your
-                                newsletter and it's going to be saved
-    -s, --specs                 Print specs of data block
-```
-
-Clearly there is a TODO item. Import is not working so avoid it, or fix it.
-Add is nice, you can add an already existing file directly. `news` is the second
-module after `mixtape`. Both modules need refactoring but they work at a level
-that someone can be productive with these tools.
-
-### Explore chains ( `ak-zchain --crawl` )
-
-You can view your zchain as a JSON object using `enter`. There are some flags
-in order to either view other zchains or change the depth of view ( includes or
-ignores data object and action ).
-
-``` console
-$ ak zchain --crawl -h
-ak zchain --crawl [-N | --no-verify] [-l | --limit <number>] [zblock]
-ak zchain --crawl [-N | --no-verify] [-l | --limit <number>] -n <zchain>
-Usage:
-
-    --help, -h                             Print this help and exit
-
-    --chain <ipns-link>, -n <ipns-link>    Crawl specified chain
-
-    --no-verify, -N                        Don't verify signatures
-
-    <ipfs-link>                            Specify IPFS CID for entrance
-
-Note that combined flags don't work for now
-Running with no flags crawls your chain based on AK_ZLATEST environment
-variable
-```
-
-### Connect to networks ( `ak network` )
-```console
-$ ak network
-ak-network - AK Nettool
-=======================
-
-Network tools
-
-Usage:
-
-   -h, --help                           Prints this help message
-
-   -c, --connect [ipfs|cjdns]           Connect to network(s)
-
-   -p, --peers [ipfs|cjdns|stellar]     Outputs peers found
-
-   -s, --scan [ipfs|cjdns|stellar]      Scan network(s) for peers
-
-Bonus: CJDNS network scanning flags
-
-   -s, --scan cjdns [-w|--whole]        Scan using HIA's knowledge
-
-   -s, --scan cjdns [-d|--dump]         Scan using CJDNS' dumpLinks (default)
-```
-
 Podman (or Docker)
 ------------------
 
@@ -252,8 +160,8 @@ Concepts under thought
 - Spam defence (e.g. how to protect the network from abuse cases) (important)
 - Reduce size of all parts of chain (stringify JSON) (improvement)
 
-Script usage
-------------
+Scripts' description
+--------------------
 
 Utilities
 ---------
@@ -269,12 +177,6 @@ Utilities
  - ak-zblock               # zblock tools
  - ak-zchain               # zchain tools
 
-Experimental
-------------
- - ak-mempool                      # TODO
- - ak-mine                     PROTO Prototype miner
- - ak-get-balances                 # Returns a balances from SCHAIN
-
 Modules
 -------
  - articles                 PROTO Adds an article to your ZCHAIN
@@ -295,25 +197,11 @@ Modules
 
  Read more at the `./MODULES` file
 
-FS tools
---------
- - ak-fs
-
-```bash
-$ ak fs --help
-
-Tools to add, get and cat files to/from the Arching Kaos File System
-
-Usage:
-
-   -h, --help                                Prints this help message
-
-   --add, --import <file>                    Adds/Imports a file to the AKFS system
-
-   --get, --export <hash> <output file>      Exports a file from the AKFS system
-
-   --cat <hash>                              Concatenates from given hash
-```
+Experimental
+------------
+ - ak-mempool                      # TODO
+ - ak-mine                     PROTO Prototype miner
+ - ak-get-balances                 # Returns a balances from SCHAIN
 
 Libraries
 ---------
@@ -351,3 +239,113 @@ Example:
 AK_DEBUG="yes"; ak zchain --crawl -l 1
 ```
 
+Examples
+--------
+
+### Add a news article ( `ak -m news --add` )
+
+You could use ZCHAIN with NEWS model. Or MIXTAPE model, or make your own.
+``` bash
+$ ak -m news --create
+```
+
+This would pop up a vim editor for you to write a news article or whatever is
+text or markdown format with a title.
+
+Saving the file, will save it locally, add it to IPFS, sign it, pack detached
+signature with metadata on a JSON object. Then a block will be created packing
+your GPG public key, the news/add action with the JSON object and a detached
+signature of this, timestamp and finally an entry for the previous *zblock*.
+After that, we finally write this as a JSON object, add it to IPFS, sign it
+and pack a *ZBLOCK*. The ZBLOCK is then published over our IPNS zchain key.
+
+Other options... let's try help!
+
+``` console
+$ ak -m news -h
+ak-news - Module to read, create and add zblocks
+================================================
+    -h, --help                  Prints this help message
+    -l, --local-index           Prints an indexed table of your news files
+    -i, --import <file>         #TODO
+    -a, --add <file>            Creates a data file from the news file you point to
+    -r, --read <zblock>         Reads a zblock as a news data
+    -c, --create                Vim is going to pop up, you will write and save your
+                                newsletter and it's going to be saved
+    -s, --specs                 Print specs of data block
+```
+
+Clearly there is a TODO item. Import is not working so avoid it, or fix it.
+Add is nice, you can add an already existing file directly. `news` is the second
+module after `mixtape`. Both modules need refactoring but they work at a level
+that someone can be productive with these tools.
+
+### Explore chains ( `ak-zchain --crawl` )
+
+You can view your zchain as a JSON object using `enter`. There are some flags
+in order to either view other zchains or change the depth of view ( includes or
+ignores data object and action ).
+
+``` console
+$ ak zchain --crawl -h
+ak zchain --crawl [-N | --no-verify] [-l | --limit <number>] [zblock]
+ak zchain --crawl [-N | --no-verify] [-l | --limit <number>] -n <zchain>
+Usage:
+
+    --help, -h                             Print this help and exit
+
+    --chain <ipns-link>, -n <ipns-link>    Crawl specified chain
+
+    --no-verify, -N                        Don't verify signatures
+
+    <ipfs-link>                            Specify IPFS CID for entrance
+
+Note that combined flags don't work for now
+Running with no flags crawls your chain based on AK_ZLATEST environment
+variable
+```
+
+### Connect to networks ( `ak network` )
+```console
+$ ak network
+ak-network - AK Nettool
+=======================
+
+Network tools
+
+Usage:
+
+   -h, --help                           Prints this help message
+
+   -c, --connect [ipfs|cjdns]           Connect to network(s)
+
+   -p, --peers [ipfs|cjdns|stellar]     Outputs peers found
+
+   -s, --scan [ipfs|cjdns|stellar]      Scan network(s) for peers
+
+Bonus: CJDNS network scanning flags
+
+   -s, --scan cjdns [-w|--whole]        Scan using HIA's knowledge
+
+   -s, --scan cjdns [-d|--dump]         Scan using CJDNS' dumpLinks (default)
+```
+
+FS tools
+--------
+ - ak-fs
+
+```bash
+$ ak fs --help
+
+Tools to add, get and cat files to/from the Arching Kaos File System
+
+Usage:
+
+   -h, --help                                Prints this help message
+
+   --add, --import <file>                    Adds/Imports a file to the AKFS system
+
+   --get, --export <hash> <output file>      Exports a file from the AKFS system
+
+   --cat <hash>                              Concatenates from given hash
+```