update docs

11 files changed, 59 insertions, 6 deletions

diff --git a/HACKING/build-system.md b/HACKING/HACKING_build-system.md
index 6c8381a..6c8381a 100644
--- a/HACKING/build-system.md
+++ b/HACKING/HACKING_build-system.md
diff --git a/HACKING/HACKING_chroot-tools.md b/HACKING/HACKING_chroot-tools.md
new file mode 100644
index 0000000..e50aa11
--- /dev/null
+++ b/HACKING/HACKING_chroot-tools.md
@@ -0,0 +1,3 @@
+Unfortunately, `makechrootpkg.sh` is GPLv2 ONLY.  This means that
+everything that uses it must be held to GPLv2+ instead of GPLv3+.  I'm
+calling this anything that gets loaded into the same process as it.
diff --git a/HACKING/code-quality.md b/HACKING/HACKING_code-quality.md
index 06f301d..06f301d 100644
--- a/HACKING/code-quality.md
+++ b/HACKING/HACKING_code-quality.md
diff --git a/HACKING/code-style.md b/HACKING/HACKING_code-style.md
index 601ead1..601ead1 100644
--- a/HACKING/code-style.md
+++ b/HACKING/HACKING_code-style.md
diff --git a/HACKING/contributing.md b/HACKING/HACKING_contributing.md
index 3a9d083..3a9d083 100644
--- a/HACKING/contributing.md
+++ b/HACKING/HACKING_contributing.md
diff --git a/HACKING/HACKING_librefetch.md b/HACKING/HACKING_librefetch.md
new file mode 100644
index 0000000..f4ac4f1
--- /dev/null
+++ b/HACKING/HACKING_librefetch.md
@@ -0,0 +1,25 @@
+`librefetch` respects `SOURCE_DATE_EPOCH`[1] for reproducible builds,
+and has had this behavior from the start (though the variable name
+wasn't there from the start, that came later).  But how can this be!?
+If you asked h01ger (the guy heading up reproducible builds in Debian
+and Fedora), tar needs to support `--clamp-mtime` to do this, and that
+flag wasn't in any tar implementation when librefetch came into
+existence.  The flag not yet being in upstream GNU tar was for a long
+time the biggest blocker to most of upstream Debian being
+reproducible!
+
+While it is a nice flag that I'm surprised wasn't added years ago,
+it's trivial to just adjust the input files first: 
+
+	find . -exec touch --no-dereference --date=DATE -- {} +`
+
+Of course, `--clamp-mtime`/`--mtime` is now in upstream GNU tar.  So
+librefetch supporting this is no longer impressive.  But, librefetch
+still isn't using `--mtime`.  Why?  Well, because it uses libarchive
+`bsdtar`, not GNU tar, and bsdtar still doesn't have the flag.
+
+I wrote this document mostly because I expect that sometime in the
+future I'll think to myself "I should simplify the code and just use
+`--mtime`", not remembering the differences between tars.
+
+[1]: https://reproducible-builds.org/specs/source-date-epoch/
diff --git a/HACKING/HACKING_libs.md b/HACKING/HACKING_libs.md
new file mode 100644
index 0000000..8bebaf6
--- /dev/null
+++ b/HACKING/HACKING_libs.md
@@ -0,0 +1,15 @@
+Special stuff about hacking ih the /src/lib directory:
+
+ - Everything should be GPLv2 AND GPLv3 compatible.  No GPLv3 only.
+ - Name a file `libre${NAME}` if it should be executable directly, or
+   `${name}.sh` if it should only be available to be sourced.
+ - When printing a message that is internal to /src/lib, and not part
+   of the programm calling the library; prefix the print command with
+   `_l`.  `_l()` is defined in `common.sh` (and `librelib`, since it
+   cannot use any libraries itself).
+ - When changing the message functions, be aware that some are
+   duplicated in:
+    * /src/chroot-tools/chcleanup
+    * /src/chroot-tools/distcc-tool
+    * /src/lib/librelib
+   And that they probably need to be updated as well.
diff --git a/HACKING/licensing.md b/HACKING/HACKING_licensing.md
index ec83689..ec83689 100644
--- a/HACKING/licensing.md
+++ b/HACKING/HACKING_licensing.md
diff --git a/HACKING/mksource.md b/HACKING/HACKING_mksource.md
index 01d759d..01d759d 100644
--- a/HACKING/mksource.md
+++ b/HACKING/HACKING_mksource.md
diff --git a/HACKING/testing.md b/HACKING/HACKING_testing.md
index 8dee485..8dee485 100644
--- a/HACKING/testing.md
+++ b/HACKING/HACKING_testing.md
diff --git a/HACKING/translations.md b/HACKING/HACKING_translations.md
index 2229d2a..085a18c 100644
--- a/HACKING/translations.md
+++ b/HACKING/HACKING_translations.md
@@ -5,6 +5,7 @@ created by copying PO-template (`.pot`) files, and filling in the missing
 To add a translation, you'll first (1) need to create the `.pot` files if you
 don't already have them, and then (2) copy them and (3) fill them in.
 
+
 ## 1. Create the `.pot` files
 
 If you are working from a release source tarball, you can skip this step (the
@@ -33,6 +34,7 @@ strings. The failure will be evident by the error message:
 
 If you see this error, refer to the "Updating translations" section below.
 
+
 ## 2. Create the `.po` Files
 
 Create a folder under `po/` with the two-letter language code[^1] you want to
@@ -46,20 +48,28 @@ For example:
 
 [^1]: See the langauge code table: <http://www.lingoes.net/en/translator/langcode.htm>
 
+
 ## 3. Fill the `.po` Files
 
 From there you can open each .po file in your favorite text editor, and fill in
 the `msgstr` values with translations of the associated `msgid` keys.
 
+
 ## 4. Synchronizing/Updating Translations
 
-If you have modified the libretools source code, it is likely that the program
-will fail to compile, due to the translation files being mis-aligned with the
-latest changes. You will need to run `msgmerge` to merge the newly generated
-.pot templates into the existing .po files, as indicated by the `msgcmp` command
-trace in the build log.
+Normally, the translations are prepared as part of the dist make target
+(the same command used to generate the release source-ball). Eg:
+
+    $ make dist
+
+However, if you have modified the libretools source code significantly or
+modified any translatable strings, it is likely that the `make` command will
+fail, due to the translation files being mis-aligned with the latest changes.
+You will need to run `msgmerge` to merge the newly generated .pot templates
+into the existing .po files, as indicated by the `msgcmp` command traces in
+the build log.
 
-e.g. if the following error message appeers after this log trace:
+Eg: If the following error message appeers after this log trace:
 
     msgcmp --use-untranslated --use-fuzzy po/es/libretools.po po/libretools.pot
     ....