From 30172884243c7cc670d245cad6d64bddf674a639 Mon Sep 17 00:00:00 2001
From: Jaromil <jaromil@dyne.org>
Date: Wed, 8 Jun 2016 16:49:06 +0200
Subject: [PATCH] fill in documentation

translatable strings
and mode of operation
---
 doc/HACKING.md          | 32 ++++++++++++++++++++++++++++++++
 doc/README-functions.md | 17 ++++++++++++-----
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/doc/HACKING.md b/doc/HACKING.md
index feb8661..3e989ad 100644
--- a/doc/HACKING.md
+++ b/doc/HACKING.md
@@ -1,6 +1,28 @@
 libdevuansdk
 ------------
 
+## Strings for translation
+
+To support gettext translation use Zuper's functions for noticing messages to console:
+
+ - `notice` (green visible header)
+ - `act` (bullet point information)
+ - `warning` (orange warning, non fatal)
+ - `error` (fatal error) followed by `zerr` and `zshexit`
+
+Each string should not contain any variable, but pointers to
+variables, then be followed by actual variables as arguments. So for
+instance:
+
+```
+notice "Starting to bake files in ::1 directory:: for target ::2 arch::" $dir $arch
+```
+
+This will print the string with variables in it, but string will
+contain references to them. This is so that gettext translations will
+point to the same string even in case of name of variables changing.
+
+
 ## Code style
 
 ### Leading whitespace
@@ -38,3 +60,13 @@ libdevuansdk is split into three stages. See `doc/WORKFLOW.md` for more info on
 
 ### Stage 3
 * packing
+
+## Submodule administration
+
+To update all submodules use:
+
+```
+git submodule foreach git pull --rebase origin master
+```
+
+This will cycle through all submodules and update them to the respective latest HEAD. After this the repository needs to be updated with the reference to this new HEAD with a commit.
diff --git a/doc/README-functions.md b/doc/README-functions.md
index b7f5ad4..b833fba 100644
--- a/doc/README-functions.md
+++ b/doc/README-functions.md
@@ -4,18 +4,25 @@ libdevuansdk functions
 # zlibs/debootstrap
 
 ## bootstrap()
-Stages 1, 2, and 3 of debootstrap.
 
-## config_cleanup()
+Main function, goes through stages 1, 2, and 3 of debootstrap.
+
+Other internal functions are prefixed with `config_` and `tar_`
+
+### config_cleanup() ###
+
 Final cleanup of the rootfs.
 
-## config_thirdstage()
+### config_thirdstage() ###
+
 Shell script for the system's third debootstrap stage.
 
-## tar_bootstrap()
+### tar_bootstrap() ###
+
 Make a tarball of a base working system, ready to be worked on later.
 
-## tar_unpack()
+### tar_unpack() ###
+
 Unpack the tarball of a base working system to the strapdir.
 
 # zlibs/helpers