From f3459e183c3b9dfeb833097e87c8156a8da56ecf Mon Sep 17 00:00:00 2001
From: Lucio Andrés Illanes Albornoz <lucio@lucioillanes.de>
Date: Mar 11 2020 17:49:28 +0000
Subject: etc/README.md: updated.


---

diff --git a/etc/README.md b/etc/README.md
index e501b35..9278610 100644
--- a/etc/README.md
+++ b/etc/README.md
@@ -16,6 +16,7 @@ internal repositories required in order to build Midipix.
 	3.2. [Adding a package](#32-adding-a-package)  
 	3.3. [Addressing build failure](#33-addressing-build-failure)  
 	3.4. [Patches and ``vars`` files](#34-patches-and-vars-files)  
+	3.5. [``pkgtool.sh``](#35-pkgtoolsh)  
 4. [Build variables](#4-build-variables)  
 	4.1. [Build steps](#41-build-steps)  
 	4.2. [Package variables](#42-package-variables)  
@@ -284,25 +285,9 @@ package configuration failed or appears relevant, log the configuration process 
 in, most usually, ``${PKG_BUILD_DIR}/config.log``.  
 
 If ``--dump-on-abort`` was specified, a subset of the variables set and environment
-variables will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``, which may subsequently
-be used in order to obtain a package build shell environment with ``pkgtool.sh``, e.g.:  
-  
-```
-midipix_build@sandbox:(src/midipix_build)> $ ./pkgtool.sh mc
-==> 2020/03/11 15:46:28 Launching shell `/usr/bin/zsh' within package environment and `/home/midipix_build/midipix/nt64/debug/tmp'.
-==> 2020/03/11 15:46:28 Run $R to rebuild `mc'.
-==> 2020/03/11 15:46:28 Run $RS <step> to restart the specified build step of `mc'
-==> 2020/03/11 15:46:28 Run $D to automatically regenerate the patch for `mc'.
-midipix_build@sandbox:(src/midipix_build)> $
-```
-  
-Consult sections [3.2](#32-adding-a-package), [3.4](#34-patches-and-vars-files), [4](#4-build-variables),
-[4.1](#41-build-steps), and [4.2](#42-package-variables) for further information
-concerning the package build process.  
-  
-> N.B. When using ``pkgtool.sh`` on a build w/ build variables (see section [4](#4-build-variables))
-overriden on the command line or via the environment, ensure that they are included in the
-``pkgtool.sh`` command line or exported, respectively.
+variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``, which may
+subsequently be used in order to obtain a package build shell environment with the
+``pkgtool.sh`` script (see section [3.5](#35-pkgtoolsh).)
   
 [Back to top](#table-of-contents)
 
@@ -334,6 +319,39 @@ for a list of package build steps and how they are overriden.
 [Back to top](#table-of-contents)
 
 [//]: # "}}}"
+[//]: # "{{{ 3.5. ``pkgtool.sh``"
+## 3.5. ``pkgtool.sh``
+
+When ``build.sh`` is executed with the ``--dump-on-abort`` option, a subset of the
+variables set and environment variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``
+on build failure, which may subsequently be used in order to obtain a package build shell
+environment with the ``pkgtool.sh`` script, e.g.:  
+  
+```
+midipix_build@sandbox:(src/midipix_build)> $ ./pkgtool.sh -a nt64 -b debug mc
+==> 2020/03/11 15:46:28 Launching shell `/usr/bin/zsh' within package environment and `/home/midipix_build/midipix/nt64/debug/tmp'.
+==> 2020/03/11 15:46:28 Run $R to rebuild `mc'.
+==> 2020/03/11 15:46:28 Run $RS <step> to restart the specified build step of `mc'
+==> 2020/03/11 15:46:28 Run $D to automatically regenerate the patch for `mc'.
+midipix_build@sandbox:(src/midipix_build)> $
+```
+  
+If a package build shell environment is desired for a package that has either not been
+built at all or built successfully, ``pkgshell.sh`` will attempt to rebuild the package
+at build steps up until, by default, ``build``, and then forcibly abort the build and
+write ``${BUILD_WORKDIR}/${PKG_NAME}.dump`` as above prior to entering the shell.  
+  
+Consult sections [3.2](#32-adding-a-package), [3.4](#34-patches-and-vars-files), [4](#4-build-variables),
+[4.1](#41-build-steps), and [4.2](#42-package-variables) for further information
+concerning the package build process.  
+  
+> N.B. When using ``pkgtool.sh`` on a build w/ build variables (see section [4](#4-build-variables))
+overriden on the command line or via the environment, ensure that they are included in the
+``pkgtool.sh`` command line, preceding the package name, or exported, respectively.
+  
+[Back to top](#table-of-contents)
+
+[//]: # "}}}"
 
 [//]: # "{{{ 4. Build variables"
 ## 4. Build variables