From 479aa1e943ea2c97a64d06a97fb7af813beca82e Mon Sep 17 00:00:00 2001
From: =?utf8?q?Mat=C3=ADas=20Fonzo?= <selk@dragora.org>
Date: Sat, 30 Mar 2019 20:00:33 -0300
Subject: [PATCH] qi: doc: added chapter 'Creating packages'

---
 qi/doc/qi.html | 64 ++++++++++++++++++++++++++++++++++++++++----------
 qi/doc/qi.info | 74 +++++++++++++++++++++++++++++++++++++++++-----------------
 qi/doc/qi.texi | 40 ++++++++++++++++++++++++++++---
 3 files changed, 142 insertions(+), 36 deletions(-)
diff --git a/qi/doc/qi.html b/qi/doc/qi.html
index 1f6657c4..d9e76aaf 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,
-29 March 2019), which is a simple but well-integrated package manager.
+30 March 2019), which is a simple but well-integrated package manager.
 
 Copyright (C) 2019 Matias Andres Fonzo, Santiago del Estero,
 Argentina.
@@ -83,8 +83,9 @@ 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-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-Creating-packages-1" href="#Creating-packages">7 Creating packages</a></li>
+  <li><a id="toc-Examining-packages-1" href="#Examining-packages">8 Examining packages</a></li>
+  <li><a id="toc-Exit-status-1" href="#Exit-status">9 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>
@@ -97,7 +98,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,
-29 March 2019).
+30 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
@@ -112,11 +113,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="#Examining-packages" accesskey="7">Examining packages</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Debugging purposes
+<tr><td align="left" valign="top">&bull; <a href="#Creating-packages" accesskey="7">Creating packages</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Making Qi packages
 </td></tr>
-<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
+<tr><td align="left" valign="top">&bull; <a href="#Examining-packages" accesskey="8">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="9">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="9">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="#License">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>
@@ -888,7 +891,7 @@ created redirecting both, standard error and standard output to tee(1).
 <p>The variable <code>TMPDIR</code> sets the temporary directory for sources, which is
 used for package extractions (see <a href="#Examining-packages">Examining packages</a>) and to prepend
 the value of &lsquo;<samp>${srcdir}</samp>&rsquo; and &lsquo;<samp>${destdir}</samp>&rsquo; on build mode.  By
-convention its default value is equal to &lsquo;<samp>/tmp</samp>&rsquo;.
+convention its default value is equal to &lsquo;<samp>/usr/src/qi/build</samp>&rsquo;.
 </p>
 <p>The variables <code>QICFLAGS</code>, <code>QICXXFLAGS</code>, and <code>QILDFLAGS</code> have
 no effect by default.  The environment variables such as <code>CFLAGS</code>,
@@ -985,7 +988,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="#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>
+Next: <a href="#Creating-packages" accesskey="n" rel="next">Creating 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>
@@ -1047,11 +1050,47 @@ libs/tiff
 
 
 <hr>
+<span id="Creating-packages"></span><div class="header">
+<p>
+Next: <a href="#Examining-packages" accesskey="n" rel="next">Examining packages</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="Creating-packages-1"></span><h2 class="chapter">7 Creating packages</h2>
+<span id="index-package-creation"></span>
+
+<p>The &quot;creation mode&quot; is an internal function of qi to make new Qi compatible
+packages, the creation mode is available through the -c option.  A package
+is produced using the contents of the Current Directory, finally the
+package is written out to the file name.
+</p>
+<div class="example">
+<pre class="example">Usage: qi -c [<var>OUTPUT/packagename.tlz</var>]...
+</pre></div>
+
+<p>The argument for the file name to be written must contain a fully
+qualified named directory as the output directory where the produced
+package will be written.  The file name should be composed using the
+full name: name-version-architecture+release.tlz
+</p>
+<p><small>EXAMPLE</small>
+</p>
+<div class="example">
+<pre class="example">cd /usr/local/pkgs
+cd claws-mail-3.17.1-x86_64+1
+qi -c /var/cache/qi/packages/x86_64/local/claws-mail-3.17.1-x86_64+1.tlz
+</pre></div>
+
+<p>In this case, the package &quot;claws-mail-3.17.1-x86_64+1.tlz&quot; will be written
+into &lsquo;<samp>/var/cache/qi/packages/x86_64/local/</samp>&rsquo;.
+</p>
+<p>All produced packages are complemented by a checksum file (.sha256).
+</p>
+
+<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>
+Next: <a href="#Exit-status" accesskey="n" rel="next">Exit status</a>, Previous: <a href="#Creating-packages" accesskey="p" rel="prev">Creating 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="Examining-packages-1"></span><h2 class="chapter">7 Examining packages</h2>
+<span id="Examining-packages-1"></span><h2 class="chapter">8 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
@@ -1078,7 +1117,7 @@ the content will be equal to <strong>u=rwx,g=rwx,o=rwx (0000)</strong>.
 <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">8 Exit status</h2>
+<span id="Exit-status-1"></span><h2 class="chapter">9 Exit status</h2>
 <span id="index-exit-codes"></span>
 
 <p>All the conditions of exit codes are described in this chapter.
@@ -1706,6 +1745,7 @@ Previous: <a href="#License" accesskey="p" rel="prev">License</a>, Up: <a href="
 <tr><td></td><td valign="top"><a href="#index-package-blacklist">package blacklist</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-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-creation">package creation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Creating-packages">Creating 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>
diff --git a/qi/doc/qi.info b/qi/doc/qi.info
index 53e2a150..3f7fd1c1 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, 29 March 2019), which is a
+This user guide is for Qi (version 1.0-rc59, 30 March 2019), which is a
 simple but well-integrated package manager.
 
    Copyright © 2019 Matias Andres Fonzo, Santiago del Estero, Argentina.
@@ -13,7 +13,7 @@ simple but well-integrated package manager.
      the section entitled "GNU Free Documentation License".
 INFO-DIR-SECTION Package management
 START-INFO-DIR-ENTRY
-* Qi: (qi).                     A user-friendly package manager.
+* Qi: (qi).                   A user-friendly package manager.
 END-INFO-DIR-ENTRY
 
 
@@ -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, 29 March 2019).
+This user guide is for Qi (version 1.0-rc59, 30 March 2019).
 
 * Menu:
 
@@ -32,6 +32,7 @@ This user guide is for Qi (version 1.0-rc59, 29 March 2019).
 * Packages::                  Managing packages
 * Recipes::                   Building packages
 * Order files::               Handling build order
+* Creating packages::         Making Qi packages
 * Examining packages::        Debugging purposes
 * Exit status::               Exit codes
 * License::                   GNU Free Documentation License
@@ -692,7 +693,7 @@ Qi has environment variables which can be used at build time:
    The variable 'TMPDIR' sets the temporary directory for sources, which
 is used for package extractions (see *note Examining packages::) and to
 prepend the value of '${srcdir}' and '${destdir}' on build mode.  By
-convention its default value is equal to '/tmp'.
+convention its default value is equal to '/usr/src/qi/build'.
 
    The variables 'QICFLAGS', 'QICXXFLAGS', and 'QILDFLAGS' have no
 effect by default.  The environment variables such as 'CFLAGS',
@@ -785,7 +786,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: Examining packages,  Prev: Recipes,  Up: Top
+File: qi.info,  Node: Order files,  Next: Creating packages,  Prev: Recipes,  Up: Top
 
 6 Order files
 *************
@@ -835,9 +836,38 @@ should build the recipes:
      libs/tiff
 
 
-File: qi.info,  Node: Examining packages,  Next: Exit status,  Prev: Order files,  Up: Top
+File: qi.info,  Node: Creating packages,  Next: Examining packages,  Prev: Order files,  Up: Top
 
-7 Examining packages
+7 Creating packages
+*******************
+
+The "creation mode" is an internal function of qi to make new Qi
+compatible packages, the creation mode is available through the -c
+option.  A package is produced using the contents of the Current
+Directory, finally the package is written out to the file name.
+
+     Usage: qi -c [OUTPUT/PACKAGENAME.TLZ]...
+
+   The argument for the file name to be written must contain a fully
+qualified named directory as the output directory where the produced
+package will be written.  The file name should be composed using the
+full name: name-version-architecture+release.tlz
+
+   EXAMPLE
+
+     cd /usr/local/pkgs
+     cd claws-mail-3.17.1-x86_64+1
+     qi -c /var/cache/qi/packages/x86_64/local/claws-mail-3.17.1-x86_64+1.tlz
+
+   In this case, the package "claws-mail-3.17.1-x86_64+1.tlz" will be
+written into '/var/cache/qi/packages/x86_64/local/'.
+
+All produced packages are complemented by a checksum file (.sha256).
+
+
+File: qi.info,  Node: Examining packages,  Next: Exit status,  Prev: Creating packages,  Up: Top
+
+8 Examining packages
 ********************
 
 There is an option to make use of the "extraction mode" which serves to
@@ -859,7 +889,7 @@ the 'TMPDIR' variable.
 
 File: qi.info,  Node: Exit status,  Next: License,  Prev: Examining packages,  Up: Top
 
-8 Exit status
+9 Exit status
 *************
 
 All the conditions of exit codes are described in this chapter.
@@ -1439,6 +1469,7 @@ Index
 * package blacklist:                     Packages.            (line 176)
 * package build:                         Recipes.             (line 185)
 * package conflicts:                     Packages.            (line  30)
+* package creation:                      Creating packages.   (line   6)
 * package de-installation:               Packages.            (line 104)
 * package examination:                   Examining packages.  (line   6)
 * package installation:                  Packages.            (line  55)
@@ -1451,19 +1482,20 @@ Index
 
 
 Tag Table:
-Node: Top807
-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26403
-Node: Order files26548
-Node: Examining packages27883
-Node: Exit status28752
-Node: License30717
-Node: Index55833
+Node: Top805
+Node: Introduction1648
+Node: Invoking qi2810
+Node: The qirc file6172
+Node: Packages7250
+Ref: Packages-Footnote-114297
+Node: Recipes14410
+Ref: Recipes-Footnote-126463
+Node: Order files26608
+Node: Creating packages27942
+Node: Examining packages28993
+Node: Exit status29868
+Node: License31833
+Node: Index56949
 
 End Tag Table
 
diff --git a/qi/doc/qi.texi b/qi/doc/qi.texi
index 5b51bede..574b86d0 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 29 March 2019
+@set UPDATED 30 March 2019
 
 @copying
 This user guide is for Qi (version @value{VERSION},
@@ -29,7 +29,7 @@ Texts.  A copy of the license is included in the section entitled
 
 @dircategory Package management
 @direntry
-* Qi: (qi).                     A user-friendly package manager.
+* Qi: (qi).                   A user-friendly package manager.
 @end direntry
 
 @titlepage
@@ -60,6 +60,7 @@ This user guide is for Qi (version @value{VERSION},
 * Packages::                  Managing packages
 * Recipes::                   Building packages
 * Order files::               Handling build order
+* Creating packages::         Making Qi packages
 * Examining packages::        Debugging purposes
 * Exit status::               Exit codes
 * License::                   GNU Free Documentation License
@@ -830,7 +831,7 @@ Qi has environment variables which can be used at build time:
 The variable @env{TMPDIR} sets the temporary directory for sources, which is
 used for package extractions (see @ref{Examining packages}) and to prepend
 the value of @samp{$@{srcdir@}} and @samp{$@{destdir@}} on build mode.  By
-convention its default value is equal to @samp{/tmp}.
+convention its default value is equal to @samp{/usr/src/qi/build}.
 
 The variables @env{QICFLAGS}, @env{QICXXFLAGS}, and @env{QILDFLAGS} have
 no effect by default.  The environment variables such as @env{CFLAGS},
@@ -987,6 +988,39 @@ libs/tiff
 @end example
 
 
+@node Creating packages
+@chapter Creating packages
+@cindex package creation
+
+The "creation mode" is an internal function of qi to make new Qi compatible
+packages, the creation mode is available through the -c option.  A package
+is produced using the contents of the Current Directory, finally the
+package is written out to the file name.
+
+@example
+Usage: qi -c [@var{OUTPUT/packagename.tlz}]...
+@end example
+
+The argument for the file name to be written must contain a fully
+qualified named directory as the output directory where the produced
+package will be written.  The file name should be composed using the
+full name: name-version-architecture+release.tlz
+
+@sc{Example}
+
+@example
+cd /usr/local/pkgs
+cd claws-mail-3.17.1-x86_64+1
+qi -c /var/cache/qi/packages/x86_64/local/claws-mail-3.17.1-x86_64+1.tlz
+@end example
+
+In this case, the package "claws-mail-3.17.1-x86_64+1.tlz" will be written
+into @samp{/var/cache/qi/packages/x86_64/local/}.
+
+@noindent
+All produced packages are complemented by a checksum file (.sha256).
+
+
 @node Examining packages
 @chapter Examining packages
 @cindex package examination
-- 
2.11.4.GIT

