Initial operation

1 files changed, 38 insertions, 10 deletions

diff --git a/README.md b/README.md
index fd6faf2..6d32ac1 100644
--- a/README.md
+++ b/README.md
@@ -14,20 +14,20 @@ docker.
 Some stuff are hard to package or upstream makes the effort to keep it harder
 and harder to package. Distros are left behind the planned obsolescence.
 
-This alleviates the pain like ff you find yourself in the urge to install that
-hyped application but have no choice other than run magic commands and install
-untrusted code.
+This humble tool alleviates the pain like if you find yourself in the urge to
+install that hyped application but have no choice other than run magic commands
+and install untrusted code.
 
-It replace curl-pipe-bash statements like
+It replaces curl-pipe-bash statements like
 
-    curl -L $backdoor_url | bash
+    curl $backdoor_url | bash
 
 by this one:
 
     trashman install <package>
 
-Instead of being just a shorthand, `trashman` packages try to be as best as possible
-to no fetch keys and scripts from remote locations without some basic checks. So if
+Instead of being just a shorthand, `trashman` packages try as best as possible
+not to fetch keys and scripts from remote locations without some basic checks. So if
 you have to add files into `/etc/apt/trusted.gpg.d`, `trashman` will provide those
 keys or fingerprints instead of donwloading it from somewhere, in which case it could
 be easily tampered.
@@ -102,21 +102,46 @@ do the actual merge:
 
     trashman merge
 
+## How it works
+
+Basically `trashman` is just a dispatcher/router for scripts available under
+it's `share/` directory. It scans every available package for the available
+implementation that best fits your current distro.
+
+Say that you're running Debian GNU/Linux. First trashman tries to find scripts
+that matches `debian` distro, trying `linux` target next and finally `unix`.
+
+This ways, it's possible to implement generic package management procedures
+as longs as specific to each distro.
+
 ## Writing a package
 
 You might use [templater](https://templater.fluxo.info):
 
-    cd path/to/trashman/repo && templater share/package/<package_name> dumpster
+    cd path/to/trashman/repo && templater share/package/<package_name> trashman
 
 packages are simply as having the following files:
 
-* `share/trashman/<name>/info`: describe package purpose.
-* `share/trashman/<name>/<distro>/<action>`: script that runs on a given action.
+* `share/trashman/<package>/info`: describe package purpose.
+* `share/trashman/<package>/<ancestor>/<family>/<distro>/<action>`: script that runs on a given action.
+* `share/trashman/<package>/<ancestor>/<family>/<action>`: script that runs on a given action, fallback.
+* `share/trashman/<package>/<ancestor>/<action>`: script that runs on a given action, fallback.
 
 Where actions can be like `install`, `test`, `remove` or `upgrade`. You don't have
 to implement all actions. Actually, no action is required to create a package, but
 having no action makes it useless.
 
+### Test action
+
+The test action may return the following exit codes:
+
+* 0: the package is installed system-wide.
+* 1: the package is not installed system-wide.
+* 2: the package is partially installed system-wide.
+
+Yes. This is far from deterministic builds. We're talking about scripts that might fail
+anytime, due to network errors or inconsistencies.
+
 ### Idempotency
 
 Shit. I think I can't even spell this word correctly. Idempowhat? So you're saying
@@ -131,6 +156,9 @@ You don't need a DSL to do that. It's as simply as
 
 It's recommended that you try to make your packaging script to be idempotent.
 
+This way,`trashman` turns into a configuration manager, going beyond the basic
+package management.
+
 ## Naming candidates
 
 While designing this tools, the following names were considered: