update docs

15 files changed, 124 insertions, 58 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
     ....
diff --git a/INSTALL-VCS b/INSTALL-VCS
index 771a85c..e56071c 100644
--- a/INSTALL-VCS
+++ b/INSTALL-VCS
@@ -1,17 +1,70 @@
-The only tricky thing when building from Git is the weird dependence
-on the devtools-par source code.
+The 'auto-thing' build-system is quite magical. Gererally, it is not
+necessary to modify any of the Makefiles. New files are detected and handled
+automagically, based on the VCS. The only caveat of building from VCS
+is the weird dependence on the 'devtools-par' source code.
 
-The build system will by default look at `$(topdir)/../devtools-par`
-for the devtools-par source code, and copy the relevant files into the
+The build system will look for 'devtools-par' in a sibling directory
+($(topdir)/../devtools-par) and copy the relevant files into the
 libretools directory.  This can be changed by adjusting the
 `devtoolsdir` configuration variable, see "Configuration" in the main
 INSTALL file.  If the `$(devtoolsdir)` directory does not exist, but
 all of the copied files exist in the libretools directory, they will
-simply be used.
-
-The distribution tarball includes the copies of the devtools files,
-so it is not necessary to download the devtools source separately
-when using the tarball.
+simply be used. The distribution tarball includes the copies of the
+devtools files, so it is not necessary to download the devtools source
+separately when using the tarball.
 
 Once you have the devtools source taken care of, you can build and
 install like normal.
+
+  $ make clean
+  $ make
+
+Both `make clean` and `make ` are important if the sources have been modified
+significantly, in order to pick-up new scripts, documentation changes, and new
+translation strings. if you get errors, read HACKING/HACKING_translations.md.
+
+To generate the libretools source-ball expected by the libretools PKGBUILD,
+ensure that a versioned git tag exists of the form: vYYYYMMDD (e.g. v20190907)
+on the currently checked-out branch of the libretools git repo. If the
+'devtools-par' code has also changed, ensure that a versioned git tag exists of
+the form: libretools-YYYYMMDD on the currently checked-out branch of
+'devtools-par'. Then build the source tarball with a command of this form:
+
+  $ make clean
+  $ make
+  $ make dist
+
+Again, run `make clean` and `make` if you have made significant code changes,
+including to 'devtools-par', to ensure that everything is in-sync.
+
+This will produce two archives named as one of the following forms:
+  libretools-YYYYMMDD.tar{,.gz}
+  libretools-YYYYMMDD-N-XXXXXXXX.tar{,.gz}
+
+where: 'YYYYMMDD' is taken from the git tag
+       'N' is the number of commits on above the tag
+       'XXXXXXXX' is the git hash of the branch tip
+
+Two stamps will also be created:
+
+  $ cat ./.srcversion-*
+  DEVTOOLS_VERSION = YYYYMMDD
+  DEVTOOLS_COMMIT = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+  LIBRETOOLS_VERSION = YYYYMMDD
+  LIBRETOOLS_COMMIT = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+Normally, we want a source-ball named of the first form uploaded
+to the repo server. That is what the PKGBUILD source expects; so
+the ideal situation is when the version tag is on the tip of the
+branch. In that case, the 'N' and the git hash are not appended
+to the filename. If necessary, you can specify a name of the
+outputs explicitly:
+
+  $ make clean
+  $ make
+  $ make dist LIBRETOOLS_VERSION=YYYYMMDD
+
+But that would probably imply replacing the existing source-ball
+with the same name on the server (the initial release); so it
+would be better to adjust the PKGBUILD, for minor revisions, to
+expect the new revision filename instead.
diff --git a/src/chroot-tools/HACKING.md b/src/chroot-tools/HACKING.md
index e50aa11..877be97 100644..120000
--- a/src/chroot-tools/HACKING.md
+++ b/src/chroot-tools/HACKING.md
@@ -1,3 +1 @@
-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.
+../../HACKING/HACKING_chroot-tools.md
\ No newline at end of file
diff --git a/src/lib/HACKING.md b/src/lib/HACKING.md
index 8bebaf6..08d090b 100644..120000
--- a/src/lib/HACKING.md
+++ b/src/lib/HACKING.md
@@ -1,15 +1 @@
-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.
+../../HACKING/HACKING_libs.md
\ No newline at end of file
diff --git a/src/librefetch/HACKING.md b/src/librefetch/HACKING.md
index f4ac4f1..8afc07d 100644..120000
--- a/src/librefetch/HACKING.md
+++ b/src/librefetch/HACKING.md
@@ -1,25 +1 @@
-`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/
+../../HACKING/HACKING_librefetch.md
\ No newline at end of file