[Gsrc-commit] /srv/bzr/gsrc/trunk r2260: document MANIFEST.rec file and fix text markings

[Brandon Invergo]

------------------------------------------------------------
revno: 2260
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Thu 2013-04-04 00:09:36 +0200
message:
  document MANIFEST.rec file and fix text markings
modified:
  doc/gsrc.texi

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2013-01-27 23:04:01 +0000
+++ b/doc/gsrc.texi     2013-04-03 22:09:36 +0000
@@ -163,17 +163,17 @@
 
 @noindent
 This will create a directory @file{gsrc}.  The build definitions for
-GNU packages are in the @code{gnu/} subdirectory.  Large sub-projects,
+GNU packages are in the @file{gnu} subdirectory.  Large sub-projects,
 such as GNOME, have their own subdirectory containing packages
-(i.e. @code{gnome/}).  Each package has its own subdirectory within
-its parent, for example @code{gnu/emacs/} or @code{gnome/evince/},
+(i.e. @file{gnome}).  Each package has its own subdirectory within
+its parent, for example @file{gnu/emacs} or @file{gnome/evince},
 containing a @file{config.mk} file for configuring the package and a
 @file{Makefile} for building it.  This @file{Makefile} will execute
-the usual @code{./configure} and @code{make} commands needed to build
+the usual @file{./configure} and @command{make} commands needed to build
 a GNU package.
 
-The @code{deps/} subdirectory contains build recipes for some non-GNU
-packages on which GNU packages depend. The @code{external/}
+The @file{deps/} subdirectory contains build recipes for some non-GNU
+packages on which GNU packages depend. The @file{external}
 subdirectory contains references to other dependencies which you may
 have to install outside of GSRC, such as via your GNU/Linux
 distribution's package manager (APT, Pacman, Yum, etc.).
@@ -241,17 +241,17 @@
 @node  Building a simple package, Installing a package, Initial setup, Getting 
started
 @section Building a simple package
 
-To build any package, simply type @code{make} in the package's
-subdirectory.  You can change to the directory with the @code{cd}
-command in the shell, or with the @option{-C} option of @code{make}.
-For example, to build the @file{hello} package in the @file{gnu/hello}
+To build any package, simply type @command{make} in the package's
+subdirectory.  You can change to the directory with the @command{cd}
+command in the shell, or with the @option{-C} option of @command{make}.
+For example, to build the @dfn{hello} package in the @file{gnu/hello}
 subdirectory use:
 
 @example
 $ make -C gnu/hello
 @end example
 
-This will download, unpack, configure and build the @file{hello} package.
+This will download, unpack, configure and build the @dfn{hello} package.
 The package will be built in the subdirectory @file{gnu/hello/work}.
 
 @example
@@ -272,14 +272,14 @@
 $ mkdir /gnu
 @end example
 
-Then to install the package use the @code{install} target,
+Then to install the package use the @option{install} target,
 
 @example
 $ make -C gnu/hello install
 @end example
 
-The package should be automatically installed under @file{/gnu/}, with
-any executable programs under @code{/gnu/bin/}.
+The package should be automatically installed under @file{/gnu}, with
+any executable programs under @file{/gnu/bin/}.
 
 @example
 $ /gnu/bin/hello --version
@@ -293,9 +293,9 @@
 
 If you want to use the newly installed package by default you will
 need to modify the relevant variables in your environment, such as
address@hidden, @code{LD_LIBRARY_PATH}, @code{INFOPATH}, etc. These
address@hidden, @env{LD_LIBRARY_PATH}, @env{INFOPATH}, etc. These
 variables inform your system of the locations of relevant files on
-it. For example, @code{PATH} contains a list of all directories that
+it. For example, @env{PATH} contains a list of all directories that
 contain executable files.
 
 There is a sample script @file{setup.sh} in the top-level source
@@ -306,7 +306,7 @@
 @end example
 
 Note that you need to load this file into the current shell with the
address@hidden command, instead of executing it (which would only apply
address@hidden command, instead of executing it (which would only apply
 the definitions temporarily in a subshell).
 
 After loading this file, your environment variables should include the
@@ -320,7 +320,7 @@
 @end example
 
 If you want to restore your original environment variables they are
-saved in the variables @code{ORIG_PATH}, @code{ORIG_LD_LIBRARY_PATH},
+saved in the variables @env{ORIG_PATH}, @env{ORIG_LD_LIBRARY_PATH},
 etc.
 
 @example
@@ -334,7 +334,7 @@
 @section Useful targets
 
 To clean up the build directory and delete any downloaded files, use
-the @code{clean} target:
+the @option{clean} target:
 
 @example
 $ make -C gnu/hello clean
@@ -347,11 +347,11 @@
 $ make -C gnu/hello fetch checksum extract configure build install
 @end example
 
-Each target depends on the previous one, so typing @code{make -C
+Each target depends on the previous one, so typing @command{make -C
 gnu/hello install} executes all the earlier targets first.
 
 To see some information about a package, use the target
address@hidden 
address@hidden 
 
 @example
 $ make -C gnu/hello pkg-info
@@ -368,7 +368,7 @@
 stowed)'' or ``installed (stowed)'' (@pxref{Package versions}).
 
 To view a more concise summary, ideal for producing a list of packages
-in script, use the target @code{pkg-info-curt}.
+in script, use the target @option{pkg-info-curt}.
 
 @example
 $ make -C gnu/hello pkg-info-curt
@@ -380,7 +380,7 @@
 
 To get a better idea of what files will be downloaded and which
 dependencies must be built in order to use a package, use the
address@hidden target.
address@hidden target.
 
 @example
 $ make -C gnu/hello fetch-list
@@ -398,14 +398,14 @@
 @end example
 
 Most GNU packages are highly configurable. To see which configuration
-options are available to you, you may invoke the @code{help-config}
+options are available to you, you may invoke the @option{help-config}
 target. 
 
 Finally, if you choose to remove a package, you may use the
address@hidden target. This target ``un-stows'' the package; if you
address@hidden target. This target ``un-stows'' the package; if you
 were to re-install it, the package would not need to be
 re-built. Instead, it would merely be re-stowed. To completely remove
-a package, use the @code{uninstall-pkg} target.
+a package, use the @option{uninstall-pkg} target.
 
 @c *******************************************************************
 
@@ -414,7 +414,7 @@
 
 If a package depends on other packages these will be built
 automatically in the correct order.  To see the dependencies of any
-package use the @code{dep-list} target.
+package use the @option{dep-list} target.
 
 @example
 $ make -C gnu/gnupg dep-list
@@ -423,10 +423,13 @@
 make: Leaving directory `/home/gnu/gsrc/gnu/gnupg'
 @end example
 
-The dependencies are searched for in the @file{gnu/} subdirectory by
-default, with some additional external packages such as @code{zlib} in
-the @file{deps/} subdirectory. Remember that some dependencies are not
-provided by GSRC and must be installed separately.
+The dependencies are searched for in the @file{gnu}, @file{gnustep}
+and @file{gnome} subdirectories by default. Of course, packages might
+depend on software that does not belong to the GNU project. In those
+cases, GSRC will try to determine whether these external packages are
+installed on your system. If one is not present, you will have to
+install it separately, for example via your distribution's software
+repositories.
 
 Note that the dependencies can be more than one level deep,
 
@@ -437,7 +440,7 @@
 make: Leaving directory `/home/gnu/gsrc/gnu/readline'
 @end example
 
-So, to install a complex package like @code{gnupg} use the same
+So, to install a complex package like @dfn{gnupg} use the same
 commands as for a simple package,
 
 @example
@@ -454,7 +457,7 @@
 you find or discover a package relevant to your needs? Fortunately,
 the build recipes are described by metadata, which can help you in
 searching. For example, you can use standard GNU tools such as
address@hidden to search the text of the build recipes for key words.
address@hidden to search the text of the build recipes for key words.
 
 A template script is installed, called @file{gsrc}, that provides a
 simple means for searching for packages via keywords, printing
@@ -465,7 +468,7 @@
 to access GSRC from outside its source directory.
 
 For example, here we search for an editor, discover the program
address@hidden, read information about it, and then install it.
address@hidden, read information about it, and then install it.
 
 @example
 $ gsrc search editor
@@ -496,6 +499,17 @@
 very simple and, indeed, can be used as a template to be expanded to
 include the functionality that you desire. 
 
+More robust searching can be performed with the file
address@hidden If you have acquired GSRC by downloading it as a
address@hidden archive, this file should be present in the package's
+root directory. If you have acquired GSRC by cloning its code
+repository, you will have to generate this file. Simply navigate to
+the package's root directory and enter @command{make manifest}; you will
+want to run this every time you pull updates to the repository. The
+resulting file is a @dfn{recfile}, which can be queried as a database
+using GNU Recutils, which must be installed (@pxref{recsel, , ,recutils,
+Recutils}).
+
 @c *******************************************************************
 
 @node Advanced configuration, GNU Free Documentation License, Getting started, 
Top
@@ -541,8 +555,8 @@
 @table @code
 @item BOOTSTRAP
 If defined (the default), the environment variables
address@hidden, @code{CPLUS_INCLUDE_PATH} and @code{LDFLAGS}
-point to the @file{include/} and @file{lib/} subdirectories of the
address@hidden, @env{CPLUS_INCLUDE_PATH} and @env{LDFLAGS}
+point to the @file{include} and @file{lib} subdirectories of the
 installation directory.  This forces the use of any previously
 installed libraries in preference to the normal system libraries.  To
 disable this feature, remove the definition @code{BOOTSTRAP=1} in
@@ -642,7 +656,7 @@
 
 If you have a patch that you would like to apply to a package, the
 process can be automated by GSRC. First, in the package's directory,
-make a subdirectory called @file{files/} and move the patch file(s)
+make a subdirectory called @file{files} and move the patch file(s)
 there. Next, create two variables in the package's @file{Makefile}:
 
 @example
@@ -651,8 +665,8 @@
 @end example
 
 @code{PATCHFILES} holds a list of all the patch files in the
address@hidden/} subdirectory. @code{PATCHOPTS} contains the option switches
-to pass to the @code{patch} program. 
address@hidden subdirectory. @code{PATCHOPTS} contains the option switches
+to pass to the @command{patch} program. 
 
 Next, the patch file's checksum is added to the checksums file for the
 package. 
@@ -661,9 +675,9 @@
 $ make makesum
 @end example
 
-Note that if the @code{make makesums} command fails due to GPG
+Note that if the @command{make makesums} command fails due to GPG
 verification and you trust the source from which the package or patch
-was downloaded, you may instead use @code{make makesums GPGV=true} to
+was downloaded, you may instead use @command{make makesums GPGV=true} to
 skip this key verification step.
 
 Finally, you may build the package as normal. The patch(es) will be
@@ -687,29 +701,29 @@
 far. 
 
 When you install a package, it is first actually installed to the
address@hidden/gnu/packages/} directory in a sub-directory with the name
-<package>-<version> (i.e. @file{/gnu/packages/hello-2.7/}). In the
-example of the package @code{hello}, the executable @file{hello}
address@hidden/gnu/packages} directory in a sub-directory with the name
+<package>-<version> (i.e. @file{/gnu/packages/hello-2.7}). In the
+example of the package @dfn{hello}, the executable @file{hello}
 is installed to @file{/gnu/packages/hello-2.7/bin/hello} instead of
 @file{/gnu/bin/hello}. All other files installed by
 the package are installed in a similar manner. Next, GSRC makes
-symbolic links to those files inside the parent @file{/gnu/}
+symbolic links to those files inside the parent @file{/gnu}
 directory. Thus, @file{/gnu/bin/hello} is ultimately a symlink to
 @file{/gnu/packages/hello-2.7/bin/hello}. This is referred to as
 ``stowing''; a package with symlinks to its files installed in the
 system is said to be ``stowed''.
 
 When a new version of a package is released, you do not have to
-uninstall the previous version first. When @code{hello 2.8} is built
+uninstall the previous version first. When @dfn{hello 2.8} is built
 and installed, it is put into its own package directory,
address@hidden/gnu/packages/hello-2.8/} and the directory of @code{hello 2.7}
address@hidden/gnu/packages/hello-2.8} and the directory of @dfn{hello 2.7}
 is left untouched. When GSRC finalizes the installation, the old
 symlinks are removed and new ones are created to the latest
 version's files. Thus, while there would then actually be two versions
 of the package installed, only the latest one would be stowed.
 
-If you want to stow a particular version of the package, you may
-pass the @code{GARVERSION} variable to @code{make install}. Be sure to
+If you want to stow a particular version of the package, you may pass
+the @code{GARVERSION} variable to @command{make install}. Be sure to
 update the checksums when you do so, otherwise the process will fail!
 
 @example
@@ -718,7 +732,7 @@
 
 If you had previously built version 2.7, then GSRC will merely re-stow
 those files. Of course, if you have not previously built it, or if
-you have previously run @code{make clean}, the package will be built
+you have previously run @command{make clean}, the package will be built
 from scratch.
 
 Note: this method may fail if the package naming format or
@@ -735,7 +749,7 @@
 @end example
 
 This would install the newly configured package to
address@hidden/gnu/packages/hello-2.8-no-nls/}. 
address@hidden/gnu/packages/hello-2.8-no-nls}. 
 
 @c *******************************************************************