From 6dfee27922a8f5ffe0b866ef489ee3b8abd09e6e Mon Sep 17 00:00:00 2001
From: =?utf8?q?Mat=C3=ADas=20Fonzo?= <selk@dragora.org>
Date: Mon, 15 Apr 2019 13:02:39 -0300
Subject: [PATCH] qi: clarify the order in which qi looks for a recipe

---
 qi/doc/qi.html | 25 ++++++++++++++++---------
 qi/doc/qi.info | 56 +++++++++++++++++++++++++++++++-------------------------
 qi/doc/qi.texi | 26 ++++++++++++++++++--------
 qi/src/qi.in   | 17 ++++++++++++-----
 4 files changed, 77 insertions(+), 47 deletions(-)
diff --git a/qi/doc/qi.html b/qi/doc/qi.html
index dda08994..ee1fbde4 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,
-4 April 2019), which is a simple but well-integrated package manager.
+15 April 2019), which is a simple but well-integrated package manager.
 
 Copyright (C) 2019 Matias Andres Fonzo, Santiago del Estero,
 Argentina.
@@ -110,7 +110,7 @@ Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a
 <a name="SEC_Top"></a>
 
 <p>This user guide is for Qi (version 1.0-rc59,
-4 April 2019).
+15 April 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
@@ -831,7 +831,7 @@ Long description.
 
 <p>The first line of the value represented is a brief description of the
 software (called &quot;blurb&quot;).  A blank line separates the <em>brief
-description</em> from the <em>long description</em>, it should contain a more
+description</em> from the <em>long description</em>, which should contain a more
 descriptive description of the software.
 </p>
 <p>An example looks like:
@@ -877,13 +877,20 @@ licensing.  Comma would have lower precedence, plus added special terms.
 <h3 class="section">5.4 Building packages</h3>
 <a name="index-package-build"></a>
 
-<p>A recipe is any valid regular file.  qi sets priorities to read a recipe,
-for example, the Current Working Directory has priority over the working
-tree (or where the recipes reside); the &lsquo;<samp>${worktree}/recipes</samp>&rsquo; is
-the second place where qi searchs for a recipe.  We complete the
-possibility of using the directory name to invoke a recipe if it contains
-&quot;recipe&quot; as a valid file name.
+<p>A recipe is any valid regular file.  Qi sets priorities for reading a
+recipe, the order in which qi looks for a recipe is:
 </p>
+<ol>
+<li> Current working directory.
+
+</li><li> If the specified path name does not contain &quot;recipe&quot; as the last
+component.  Qi will complete it by adding &quot;recipe&quot; to the path name.
+
+</li><li> If the recipe is not in the current working directory, it will be
+searched under &lsquo;<samp>${worktree}/recipes</samp>&rsquo;.  The last component will be
+completed adding &quot;recipe&quot; to the specified path name.
+</li></ol>
+
 <p>To build a single package, type:
 </p>
 <div class="example">
diff --git a/qi/doc/qi.info b/qi/doc/qi.info
index f12a33e8..e053b153 100644
--- a/qi/doc/qi.info
+++ b/qi/doc/qi.info
@@ -1,6 +1,6 @@
 This is qi.info, produced by makeinfo version 6.1 from qi.texi.
 
-This user guide is for Qi (version 1.0-rc59, 4 April 2019), which is a
+This user guide is for Qi (version 1.0-rc59, 15 April 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, 4 April 2019).
+This user guide is for Qi (version 1.0-rc59, 15 April 2019).
 
 * Menu:
 
@@ -617,7 +617,7 @@ description.  By convention, the syntax of 'description' is:
 
    The first line of the value represented is a brief description of the
 software (called "blurb").  A blank line separates the _brief
-description_ from the _long description_, it should contain a more
+description_ from the _long description_, which should contain a more
 descriptive description of the software.
 
 An example looks like:
@@ -656,12 +656,18 @@ TO DO.
 5.4 Building packages
 =====================
 
-A recipe is any valid regular file.  qi sets priorities to read a
-recipe, for example, the Current Working Directory has priority over the
-working tree (or where the recipes reside); the '${worktree}/recipes' is
-the second place where qi searchs for a recipe.  We complete the
-possibility of using the directory name to invoke a recipe if it
-contains "recipe" as a valid file name.
+A recipe is any valid regular file.  Qi sets priorities for reading a
+recipe, the order in which qi looks for a recipe is:
+
+  1. Current working directory.
+
+  2. If the specified path name does not contain "recipe" as the last
+     component.  Qi will complete it by adding "recipe" to the path
+     name.
+
+  3. If the recipe is not in the current working directory, it will be
+     searched under '${worktree}/recipes'.  The last component will be
+     completed adding "recipe" to the specified path name.
 
 To build a single package, type:
 
@@ -1471,7 +1477,7 @@ Index
 * Menu:
 
 * configuration file:                    The qirc file.       (line   6)
-* environment variables:                 Recipes.             (line 229)
+* environment variables:                 Recipes.             (line 235)
 * exit codes:                            Exit status.         (line   6)
 * handling build order:                  Order files.         (line   6)
 * introduction:                          Introduction.        (line   6)
@@ -1487,27 +1493,27 @@ Index
 * package upgrade:                       Packages.            (line 143)
 * recipes:                               Recipes.             (line   6)
 * special variables:                     Recipes.             (line  58)
-* the meta file:                         Recipes.             (line 277)
+* the meta file:                         Recipes.             (line 283)
 * variables:                             Recipes.             (line  29)
 * writing recipes:                       Recipes.             (line 186)
 
 
 
 Tag Table:
-Node: Top804
-Node: Introduction1646
-Node: Invoking qi2815
-Node: The qirc file6233
-Node: Packages7310
-Ref: Packages-Footnote-114346
-Node: Recipes14459
-Ref: Recipes-Footnote-126620
-Node: Order files26765
-Node: Creating packages28067
-Node: Examining packages29107
-Node: Exit status30017
-Node: License31957
-Node: Index57073
+Node: Top805
+Node: Introduction1648
+Node: Invoking qi2817
+Node: The qirc file6235
+Node: Packages7312
+Ref: Packages-Footnote-114348
+Node: Recipes14461
+Ref: Recipes-Footnote-126751
+Node: Order files26896
+Node: Creating packages28198
+Node: Examining packages29238
+Node: Exit status30148
+Node: License32088
+Node: Index57204
 
 End Tag Table
 
diff --git a/qi/doc/qi.texi b/qi/doc/qi.texi
index d0dc5021..0e5876ef 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 4 April 2019
+@set UPDATED 15 April 2019
 
 @copying
 This user guide is for Qi (version @value{VERSION},
@@ -734,7 +734,7 @@ Long description.
 
 The first line of the value represented is a brief description of the
 software (called "blurb").  A blank line separates the @emph{brief
-description} from the @emph{long description}, it should contain a more
+description} from the @emph{long description}, which should contain a more
 descriptive description of the software.
 
 @noindent
@@ -781,12 +781,22 @@ TO DO.
 @section Building packages
 @cindex package build
 
-A recipe is any valid regular file.  qi sets priorities to read a recipe,
-for example, the Current Working Directory has priority over the working
-tree (or where the recipes reside); the @samp{$@{worktree@}/recipes} is
-the second place where qi searchs for a recipe.  We complete the
-possibility of using the directory name to invoke a recipe if it contains
-"recipe" as a valid file name.
+A recipe is any valid regular file.  Qi sets priorities for reading a
+recipe, the order in which qi looks for a recipe is:
+
+@enumerate
+@item
+Current working directory.
+
+@item
+If the specified path name does not contain "recipe" as the last
+component.  Qi will complete it by adding "recipe" to the path name.
+
+@item
+If the recipe is not in the current working directory, it will be
+searched under @samp{$@{worktree@}/recipes}.  The last component will be
+completed adding "recipe" to the specified path name.
+@end enumerate
 
 @noindent
 To build a single package, type:
diff --git a/qi/src/qi.in b/qi/src/qi.in
index 6069513e..fce69f11 100644
--- a/qi/src/qi.in
+++ b/qi/src/qi.in
@@ -188,11 +188,18 @@ build_mode()
 {
     recipe=$1
 
-    # A recipe is any valid regular file, the current working directory
-    # has priority over the working tree (or where the recipes reside).
-    # The 'worktree' is the second place where to find a recipe.  Also,
-    # we complete the possibility of using the directory name to invoke
-    # a recipe if it contains "recipe" as valid file name.
+    # A recipe is any valid regular file.  Qi sets priorities for reading a
+    # recipe, the order in which qi looks for a recipe is:
+    #
+    # 1. Current working directory.
+    #
+    # 2. If the specified path name does not contain "recipe" as the last
+    # component.  Qi will complete it by adding "recipe" to the path
+    # name.
+    #
+    # 3. If the recipe is not in the current working directory, it will be
+    # searched under '${worktree}/recipes'.  The last component will be
+    # completed adding "recipe" to the specified path name.
 
     if test ! -f "$recipe"
     then
-- 
2.11.4.GIT

