[Gsrc-commit] /srv/bzr/gsrc/trunk r1563: update documentation

[Brandon Invergo]

------------------------------------------------------------
revno: 1563
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Sun 2013-01-06 13:23:20 +0100
message:
  update documentation
modified:
  doc/gsrc.texi

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2012-12-08 16:24:49 +0000
+++ b/doc/gsrc.texi     2013-01-06 12:23:20 +0000
@@ -10,7 +10,7 @@
 This manual is for the GNU Source Release Collection (version
 @value{VERSION}, updated @value{UPDATED}).
 
-Copyright @copyright{} 2011, 2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2011, 2012, 2013 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -172,8 +172,11 @@
 the usual @code{./configure} and @code{make} commands needed to build
 a GNU package.
 
-The @code{deps/}
-subdirectory contains GARfiles for a few external packages.
+The @code{deps/} subdirectory contains build recipes for some non-GNU
+packages on which GNU packages depend. The @code{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.).
 
 To stay up-to-date with the latest releases of GNU software, you can
 pull in recent changes to your local copy of GSRC:
@@ -189,6 +192,7 @@
 * Setting your environment::
 * Useful targets::
 * Complex packages::
+* Finding packages::
 @end menu
 
 @c *******************************************************************
@@ -281,7 +285,10 @@
 
 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.
address@hidden, @code{LD_LIBRARY_PATH}, @code{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
+contain executable files.
 
 There is a sample script @file{setup.sh} in the top-level source
 directory which can be used to set the main environment variables.
@@ -333,19 +340,30 @@
 @end example
 
 Each target depends on the previous one, so typing @code{make -C
-gnu/hello install} builds all the earlier targets first.
+gnu/hello install} executes all the earlier targets first.
 
 To see some information about a package, use the target @code{pkg-info}.
 
 @example
 $ make -C gnu/hello pkg-info
 make: Entering directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
-Name: hello
-Version: 2.8
+Name:        GNU Hello
+Version:     2.8
+URL:         http://www.gnu.org/software/hello/manual/
 Description: A program that produces a familiar, friendly greeting
-URL: http://www.gnu.org/software/hello/manual/
-make: Leaving directory
-`/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+Status:      not installed
+make: Leaving directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
address@hidden example
+
+To view a more concise summary, ideal for producing a list of packages
+in script, use the target @code{pkg-info-curt}.
+
address@hidden
+$ make -C gnu/hello pkg-info-curt
+make: Entering directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+gnu/hello 2.8
+ A program that produces a familiar, friendly greeting
+make: Leaving directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
 @end example
 
 To get a better idea of what files will be downloaded and which
@@ -372,7 +390,7 @@
 
 @c *******************************************************************
 
address@hidden Complex packages,  , Useful targets, Getting started
address@hidden Complex packages, Finding packages, Useful targets, Getting 
started
 @section Complex packages
 
 If a package depends on other packages these will be built
@@ -388,7 +406,8 @@
 
 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.
+the @file{deps/} subdirectory. Remember that some dependencies are not
+provided by GSRC and must be installed separately.
 
 Note that the dependencies can be more than one level deep,
 
@@ -409,10 +428,59 @@
 
 @c *******************************************************************
 
address@hidden Finding packages,  , Complex packages, Getting started
address@hidden Finding packages
+
+GSRC provides build recipes for several hundred packages. So, how can
+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.
+
+A template script is provided, called @file{gsrc}, that provides a
+simple means for searching for packages via keywords, printing
+information about a package, and printing its location. If you put the
+script somewhere in your PATH, you can use it to interact with GSRC
+without being in the GSRC directory.
+
+In this example, we search for an editor, discover the program
address@hidden, read information about it, and then install it.
+
address@hidden
+$ gsrc search editor
+gnu/denemo 0.9.6
+ A music notation editor
+gnu/ed 1.7
+ An implementation of the standard Unix editor
+gnu/emacs 24.2
+ The extensible, customizable text editor
+gnu/gnusound 0.7.5
+ A multitrack sound editor
+gnu/moe 1.4
+ A simple-to-use text editor
+gnu/nano 2.3.1
+ A simple text editor similar to Pico
+gnu/sed 4.2.2
+ A text stream editor
+$ gsrc info moe
+Name:        Moe
+Version:     1.4
+URL:         http://www.gnu.org/software/moe
+Description: A simple-to-use text editor
+Status:      not installed
+$ make -C $(gsrc path moe) install
address@hidden example
+
+If you view the @file{gsrc} script's code, you will find that it is
+very simple and, indeed, can be used as a template to be expanded to
+include the functionality that you desire. 
+
address@hidden 
*******************************************************************
+
 @node Advanced configuration, GNU Free Documentation License, Getting started, 
Top
 @chapter Advanced configuration
 
-The default behavior of GSRC may be configured, both globally and for
+The default behavior of GSRC may be configured both globally and for
 individual packages. All configuration is done in simple Makefiles, so
 some familiarity with GNU Make, while not required, is recommended for
 more advanced changes.
@@ -429,7 +497,7 @@
 @node Global configuration, Package configuration, Advanced configuration, 
Advanced configuration
 @section Global configuration
 
-The build loads the following configuration files:
+Building a package loads the following configuration files:
 
 @table @file
 @item config.mk
@@ -503,13 +571,12 @@
 cases, you may wish to redirect this output to somewhere other than
 your screen. In this case, you may set the variable
 @code{REDIRECT_OUTPUT} to any value other than ``n''. To edit where
-the output will be redirected, set the OUTPUT variable. By default, if
+the output will be redirected, set the @code{OUTPUT} variable. By default, if
 you set @code{REDIRECT_OUTPUT}, standard text output will be
 redirected to @file{/dev/null}, which means it is thrown away, while
 errors will be printed to the screen. You can instead, for example,
 redirect to log files of your choosing (@pxref{Redirections, , ,bash,
-Bash} for more details on 
-redirection). Set in @file{gar.conf.mk}
+Bash} for more details on redirection). Set in @file{gar.conf.mk}
 
 @end table
 
@@ -524,35 +591,35 @@
 
 GNU packages take most of their configuration in the form of options
 passed to the @file{configure} script. One may easily customize these
-options in a GSRC Makefile by setting the CONFIGURE_OPTS variable. Any
-options added to this variable will be appended to the options set by
-default by GSRC. 
+options in a GSRC Makefile by setting the @code{CONFIGURE_OPTS}
+variable. Any options added to this variable will be appended to the
+options set by default by GSRC. 
 
 @example
 CONFIGURE_OPTS = --disable-gtk --without-png
 @end example
 
 For convenience, every package has a file called @file{config.mk} in
-its directory which is imported by the @file{Makefile}. Typically, all
+its directory which is imported by its build script. Typically, all
 user configuration may be done here. By default, it contains the
 @code{CONFIGURE_OPTS} and @code{BUILD_OPTS} variables. In some special
 cases, package-specific, user-customize-able variables are also
 defined in this file. 
 
-Generally speaking, user configuration may take place exclusively in
address@hidden while @file{Makefile} contains the recipe to make
-sure the package builds correctly. Thus, you should not need to modify
-the @file{Makefile} unless you have special requirements. Note that,
-because they are necessary for proper building and installation in
-GSRC, most configuration options relating to directory locations (such
-as where to install, where to search for libraries, etc.) are set in
-the @file{Makefile}. Thus, you do not need to worry about setting them
-correctly in @file{config.mk}.
+Generally speaking, user configuration is done exclusively in
address@hidden while @file{Makefile} contains the information and
+recipe necessary for the package to build correctly. Thus, you should
+not need to modify the @file{Makefile} unless you have special
+requirements. Note that most configuration options relating to
+directory locations (such as where to install, where to search for
+libraries, etc.) are set in the @file{Makefile}, because they are
+necessary for proper building and installation in GSRC. Therefore, you
+do not need to worry about setting them correctly in @file{config.mk}.
 
 @node  Patching packages, Package versions, Package configuration, Advanced 
configuration
 @section Patching packages
 
-If you have a patch that you would like to apply to the package, the
+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)
 there. Next, create two variables in the package's @file{Makefile}:
@@ -564,19 +631,26 @@
 
 @code{PATCHFILES} holds a list of all the patch files in the
 @file{files/} subdirectory. @code{PATCHOPTS} contains the option switches
-nto pass to the @code{patch} program. Next, the patch file's checksum
-is added to the checksums file for the package. Finally, you may build
-the package as normal. The patch(es) will be applied automatically in
-the process.
+to pass to the @code{patch} program. 
+
+Next, the patch file's checksum is added to the checksums file for the
+package. 
 
 @example
-$ make makesum install
+$ make makesum
 @end example
 
 Note that if the @code{make makesums} command fails due to GPG
-verification and you trust the source from which the package was
-downloaded, you may instead use @code{make makesums GPGV=true} to skip
-this key verification step.
+verification and you trust the source from which the package or patch
+was downloaded, you may instead use @code{make makesums GPGV=true} to
+skip this key verification step.
+
+Finally, you may build the package as normal. The patch(es) will be
+applied automatically in the process. 
+
address@hidden
+$ make install
address@hidden example
 
 If the package requires a patch to even build properly, then this is a
 bug in GSRC. Please report such build problems to
@@ -600,7 +674,9 @@
 the package are installed in a similar manner. Next, GSRC makes
 symbolic links to those files inside the parent @file{/gnu/}
 directory. Thus, @file{/gnu/bin/hello} is ultimately a symlink to
address@hidden/gnu/packages/hello-2.7/bin/hello}. 
address@hidden/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
@@ -608,10 +684,10 @@
 @file{/gnu/packages/hello-2.8/} and the directory of @code{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, there would then actually be two versions of the
-package installed, but only one would be in use via the symlinks.
+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 switch to a particular version of the package, you may
+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
 update the checksums when you do so, otherwise the process will fail!
 
@@ -619,9 +695,9 @@
 $ make -C gnu/hello makesum install GARVERSION=2.7
 @end example
 
-If you had previously built version 2.7, then GSRC will merely re-symlink
-to those files. Of course, if you have not previously built it, or if
-you have previously run @code{make clean}, the package will be build
+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
 from scratch.
 
 Note: this method may fail if the package naming format or