From 7b317930b90ed2f4484a7497e07f21ff548d0b34 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Mat=C3=ADas=20Fonzo?= <selk@dragora.org>
Date: Fri, 29 Mar 2019 10:37:27 -0300
Subject: [PATCH] qi: doc: added chapter 'Examining packages'

---
 qi/doc/qi.html | 69 ++++++++++++++++++++++++++++++++++++++++++----------------
 qi/doc/qi.info | 69 +++++++++++++++++++++++++++++++++++++++-------------------
 qi/doc/qi.texi | 46 +++++++++++++++++++++++++++++----------
 3 files changed, 132 insertions(+), 52 deletions(-)
diff --git a/qi/doc/qi.html b/qi/doc/qi.html
index dbb135d6..99b6c1ad 100644
--- a/qi/doc/qi.html
+++ b/qi/doc/qi.html
@@ -1,7 +1,7 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <!-- This user guide is for Qi (version 1.0-rc59,
-28 March 2019), which is a simple but well-integrated package manager.
+29 March 2019), which is a simple but well-integrated package manager.
 
 Copyright (C) 2019 Matias Andres Fonzo, Santiago del Estero,
 Argentina.
@@ -83,7 +83,8 @@ ul.no-bullet {list-style: none}
     <li><a id="toc-The-meta-file" href="#The-meta-file">5.5 The meta file</a></li>
   </ul></li>
   <li><a id="toc-Order-files-1" href="#Order-files">6 Order files</a></li>
-  <li><a id="toc-Exit-status-1" href="#Exit-status">7 Exit status</a></li>
+  <li><a id="toc-Examining-packages-1" href="#Examining-packages">7 Examining packages</a></li>
+  <li><a id="toc-Exit-status-1" href="#Exit-status">8 Exit status</a></li>
   <li><a id="toc-GNU-Free-Documentation-License" href="#License">Appendix A GNU Free Documentation License</a></li>
   <li><a id="toc-Index-1" href="#Index">Index</a></li>
 </ul>
@@ -96,7 +97,7 @@ Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a
 </div>
 <span id="SEC_Top"></span>
 <p>This user guide is for Qi (version 1.0-rc59,
-28 March 2019).
+29 March 2019).
 </p>
 <table class="menu" border="0" cellspacing="0">
 <tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="1">Introduction</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Description and features of qi
@@ -111,11 +112,13 @@ Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a
 </td></tr>
 <tr><td align="left" valign="top">&bull; <a href="#Order-files" accesskey="6">Order files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Handling build order
 </td></tr>
-<tr><td align="left" valign="top">&bull; <a href="#Exit-status" accesskey="7">Exit status</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Exit codes
+<tr><td align="left" valign="top">&bull; <a href="#Examining-packages" accesskey="7">Examining packages</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Debugging purposes
 </td></tr>
-<tr><td align="left" valign="top">&bull; <a href="#License" accesskey="8">License</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">GNU Free Documentation License
+<tr><td align="left" valign="top">&bull; <a href="#Exit-status" accesskey="8">Exit status</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Exit codes
 </td></tr>
-<tr><td align="left" valign="top">&bull; <a href="#Index" accesskey="9">Index</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+<tr><td align="left" valign="top">&bull; <a href="#License" accesskey="9">License</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">GNU Free Documentation License
+</td></tr>
+<tr><td align="left" valign="top">&bull; <a href="#Index">Index</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 </td></tr>
 </table>
 
@@ -981,7 +984,7 @@ line of &lsquo;<samp>description</samp>&rsquo; (mentioned as the &quot;brief des
 <hr>
 <span id="Order-files"></span><div class="header">
 <p>
-Next: <a href="#Exit-status" accesskey="n" rel="next">Exit status</a>, Previous: <a href="#Recipes" accesskey="p" rel="prev">Recipes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
+Next: <a href="#Examining-packages" accesskey="n" rel="next">Examining packages</a>, Previous: <a href="#Recipes" accesskey="p" rel="prev">Recipes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 </div>
 <span id="Order-files-1"></span><h2 class="chapter">6 Order files</h2>
 <span id="index-handling-build-order"></span>
@@ -1041,11 +1044,38 @@ libs/tiff
 
 
 <hr>
+<span id="Examining-packages"></span><div class="header">
+<p>
+Next: <a href="#Exit-status" accesskey="n" rel="next">Exit status</a>, Previous: <a href="#Order-files" accesskey="p" rel="prev">Order files</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
+</div>
+<span id="Examining-packages-1"></span><h2 class="chapter">7 Examining packages</h2>
+<span id="index-package-examination"></span>
+
+<p>There is an option to make use of the &quot;extraction mode&quot; which serves to
+examine binary packages for debugging purposes.  The extraction mode
+consists of decompressing a package into a single directory, verifying
+its integrity and preserving its properties.
+</p>
+<div class="example">
+<pre class="example">qi -x mksh-R56c-x86_64+1.tlz
+</pre></div>
+
+<p>This action will put the content of &quot;mksh-R56c-x86_64+1.tlz&quot; into a
+single directory, which is a private directory for the user who requested
+the action, creation mode will be 0700 <strong>(u=,g=rwx,o=rwx)</strong>.  The
+package content will reside on this location, default mask to deploy the
+content will be 0000 <strong>(u=rwx,g=rwx,o=rwx)</strong>.
+</p>
+<p>The creation of the custom directory is influenced by the value of the
+<code>TMPDIR</code> variable.
+</p>
+
+<hr>
 <span id="Exit-status"></span><div class="header">
 <p>
-Next: <a href="#License" accesskey="n" rel="next">License</a>, Previous: <a href="#Order-files" accesskey="p" rel="prev">Order files</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
+Next: <a href="#License" accesskey="n" rel="next">License</a>, Previous: <a href="#Examining-packages" accesskey="p" rel="prev">Examining packages</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 </div>
-<span id="Exit-status-1"></span><h2 class="chapter">7 Exit status</h2>
+<span id="Exit-status-1"></span><h2 class="chapter">8 Exit status</h2>
 <span id="index-exit-codes"></span>
 
 <p>All the conditions of exit codes are described in this chapter.
@@ -1079,26 +1109,26 @@ arguments in case of error.
 </p>
 <ul class="no-bullet">
 <li>- Tarball files from tar(1).
-Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
+Supported extension: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
 .tar.xz, .txz
 
 </li><li>- Tarballs files from tarlz(1).
 Supported extension: .tar.lz, .tlz
 
-</li><li>- Zip files from unzip(1):
-Supported extensions: .zip, .ZIP
+</li><li>- Zip files from unzip(1).
+Supported extension: .zip, .ZIP
 
-</li><li>- Gzip files from gzip(1):
-Supported extensions: .gz, .Z
+</li><li>- Gzip files from gzip(1).
+Supported extension: .gz, .Z
 
-</li><li>- Bzip2 files from bzip2(1):
-Supported extensions: .bz2
+</li><li>- Bzip2 files from bzip2(1).
+Supported extension: .bz2
 
-</li><li>- Lzip files from lzip(1):
-Supported extensions: .lz
+</li><li>- Lzip files from lzip(1).
+Supported extension: .lz
 
 </li><li>- Xz files from xz(1).
-Supported extensions: .xz
+Supported extension: .xz
 </li></ul>
 
 </dd>
@@ -1674,6 +1704,7 @@ Previous: <a href="#License" accesskey="p" rel="prev">License</a>, Up: <a href="
 <tr><td></td><td valign="top"><a href="#index-package-build">package build</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recipes">Recipes</a></td></tr>
 <tr><td></td><td valign="top"><a href="#index-package-conflicts">package conflicts</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
 <tr><td></td><td valign="top"><a href="#index-package-de_002dinstallation">package de-installation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-package-examination">package examination</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Examining-packages">Examining packages</a></td></tr>
 <tr><td></td><td valign="top"><a href="#index-package-installation">package installation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
 <tr><td></td><td valign="top"><a href="#index-package-upgrade">package upgrade</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Packages">Packages</a></td></tr>
 <tr><td colspan="4"> <hr></td></tr>
diff --git a/qi/doc/qi.info b/qi/doc/qi.info
index cd8f95e1..e2dd23e6 100644
--- a/qi/doc/qi.info
+++ b/qi/doc/qi.info
@@ -1,6 +1,6 @@
 This is qi.info, produced by makeinfo version 6.6 from qi.texi.
 
-This user guide is for Qi (version 1.0-rc59, 28 March 2019), which is a
+This user guide is for Qi (version 1.0-rc59, 29 March 2019), which is a
 simple but well-integrated package manager.
 
    Copyright © 2019 Matias Andres Fonzo, Santiago del Estero, Argentina.
@@ -22,7 +22,7 @@ File: qi.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Qi user guide
 *************
 
-This user guide is for Qi (version 1.0-rc59, 28 March 2019).
+This user guide is for Qi (version 1.0-rc59, 29 March 2019).
 
 * Menu:
 
@@ -32,6 +32,7 @@ This user guide is for Qi (version 1.0-rc59, 28 March 2019).
 * Packages::                  Managing packages
 * Recipes::                   Building packages
 * Order files::               Handling build order
+* Examining packages::        Debugging purposes
 * Exit status::               Exit codes
 * License::                   GNU Free Documentation License
 * Index::
@@ -783,7 +784,7 @@ of 'description' (mentioned as the "brief description").
 <http://lists.gnu.org/archive/html/gnu-linux-libre/2016-05/msg00003.html>.
 
 
-File: qi.info,  Node: Order files,  Next: Exit status,  Prev: Recipes,  Up: Top
+File: qi.info,  Node: Order files,  Next: Examining packages,  Prev: Recipes,  Up: Top
 
 6 Order files
 *************
@@ -832,9 +833,31 @@ should build the recipes/packages:
      libs/tiff
 
 
-File: qi.info,  Node: Exit status,  Next: License,  Prev: Order files,  Up: Top
+File: qi.info,  Node: Examining packages,  Next: Exit status,  Prev: Order files,  Up: Top
 
-7 Exit status
+7 Examining packages
+********************
+
+There is an option to make use of the "extraction mode" which serves to
+examine binary packages for debugging purposes.  The extraction mode
+consists of decompressing a package into a single directory, verifying
+its integrity and preserving its properties.
+
+     qi -x mksh-R56c-x86_64+1.tlz
+
+   This action will put the content of "mksh-R56c-x86_64+1.tlz" into a
+single directory, which is a private directory for the user who
+requested the action, creation mode will be 0700 *(u=,g=rwx,o=rwx)*.
+The package content will reside on this location, default mask to deploy
+the content will be 0000 *(u=rwx,g=rwx,o=rwx)*.
+
+   The creation of the custom directory is influenced by the value of
+the 'TMPDIR' variable.
+
+
+File: qi.info,  Node: Exit status,  Next: License,  Prev: Examining packages,  Up: Top
+
+8 Exit status
 *************
 
 All the conditions of exit codes are described in this chapter.
@@ -860,21 +883,21 @@ All the conditions of exit codes are described in this chapter.
 
      Compressed files means:
 
-        - Tarball files from tar(1).  Supported extensions: .tar,
+        - Tarball files from tar(1).  Supported extension: .tar,
           .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz, .tar.xz, .txz
 
         - Tarballs files from tarlz(1).  Supported extension: .tar.lz,
           .tlz
 
-        - Zip files from unzip(1): Supported extensions: .zip, .ZIP
+        - Zip files from unzip(1).  Supported extension: .zip, .ZIP
 
-        - Gzip files from gzip(1): Supported extensions: .gz, .Z
+        - Gzip files from gzip(1).  Supported extension: .gz, .Z
 
-        - Bzip2 files from bzip2(1): Supported extensions: .bz2
+        - Bzip2 files from bzip2(1).  Supported extension: .bz2
 
-        - Lzip files from lzip(1): Supported extensions: .lz
+        - Lzip files from lzip(1).  Supported extension: .lz
 
-        - Xz files from xz(1).  Supported extensions: .xz
+        - Xz files from xz(1).  Supported extension: .xz
 
 '4'
      File empty, not regular, or expected.
@@ -1415,6 +1438,7 @@ Index
 * package build:                         Recipes.             (line 185)
 * package conflicts:                     Packages.            (line  30)
 * package de-installation:               Packages.            (line 104)
+* package examination:                   Examining packages.  (line   6)
 * package installation:                  Packages.            (line  55)
 * package upgrade:                       Packages.            (line 143)
 * recipes:                               Recipes.             (line   6)
@@ -1426,17 +1450,18 @@ Index
 
 Tag Table:
 Node: Top807
-Node: Introduction1552
-Node: Invoking qi2714
-Node: The qirc file6076
-Node: Packages7154
-Ref: Packages-Footnote-114201
-Node: Recipes14314
-Ref: Recipes-Footnote-126282
-Node: Order files26427
-Node: Exit status27756
-Node: License29710
-Node: Index54826
+Node: Introduction1601
+Node: Invoking qi2763
+Node: The qirc file6125
+Node: Packages7203
+Ref: Packages-Footnote-114250
+Node: Recipes14363
+Ref: Recipes-Footnote-126331
+Node: Order files26476
+Node: Examining packages27812
+Node: Exit status28662
+Node: License30621
+Node: Index55737
 
 End Tag Table
 
diff --git a/qi/doc/qi.texi b/qi/doc/qi.texi
index 99373d68..05714449 100644
--- a/qi/doc/qi.texi
+++ b/qi/doc/qi.texi
@@ -8,7 +8,7 @@
 @comment %**end of header
 
 @set VERSION 1.0-rc59
-@set UPDATED 28 March 2019
+@set UPDATED 29 March 2019
 
 @copying
 This user guide is for Qi (version @value{VERSION},
@@ -60,6 +60,7 @@ This user guide is for Qi (version @value{VERSION},
 * Packages::                  Managing packages
 * Recipes::                   Building packages
 * Order files::               Handling build order
+* Examining packages::        Debugging purposes
 * Exit status::               Exit codes
 * License::                   GNU Free Documentation License
 * Index::
@@ -982,6 +983,29 @@ libs/tiff
 @end example
 
 
+@node Examining packages
+@chapter Examining packages
+@cindex package examination
+
+There is an option to make use of the "extraction mode" which serves to
+examine binary packages for debugging purposes.  The extraction mode
+consists of decompressing a package into a single directory, verifying
+its integrity and preserving its properties.
+
+@example
+qi -x mksh-R56c-x86_64+1.tlz
+@end example
+
+This action will put the content of "mksh-R56c-x86_64+1.tlz" into a
+single directory, which is a private directory for the user who requested
+the action, creation mode will be 0700 @strong{(u=,g=rwx,o=rwx)}.  The
+package content will reside on this location, default mask to deploy the
+content will be 0000 @strong{(u=rwx,g=rwx,o=rwx)}.
+
+The creation of the custom directory is influenced by the value of the
+@env{TMPDIR} variable.
+
+
 @node Exit status
 @chapter Exit status
 @cindex exit codes
@@ -1014,26 +1038,26 @@ Compressed files means:
 
 @itemize @minus
 @item Tarball files from tar(1).
-Supported extensions: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
+Supported extension: .tar, .tar.gz, .tgz, .tar.Z, .tar.bz2, .tbz2, .tbz,
 .tar.xz, .txz
 
 @item Tarballs files from tarlz(1).
 Supported extension: .tar.lz, .tlz
 
-@item Zip files from unzip(1):
-Supported extensions: .zip, .ZIP
+@item Zip files from unzip(1).
+Supported extension: .zip, .ZIP
 
-@item Gzip files from gzip(1):
-Supported extensions: .gz, .Z
+@item Gzip files from gzip(1).
+Supported extension: .gz, .Z
 
-@item Bzip2 files from bzip2(1):
-Supported extensions: .bz2
+@item Bzip2 files from bzip2(1).
+Supported extension: .bz2
 
-@item Lzip files from lzip(1):
-Supported extensions: .lz
+@item Lzip files from lzip(1).
+Supported extension: .lz
 
 @item Xz files from xz(1).
-Supported extensions: .xz
+Supported extension: .xz
 @end itemize
 
 @item 4
-- 
2.11.4.GIT

