[Gsrc-commit] /srv/bzr/gsrc/trunk r1566: Update documentation

[Brandon Invergo]

------------------------------------------------------------
revno: 1566
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Sun 2013-01-06 14:39:24 +0100
message:
  Update documentation
modified:
  doc/gsrc.info
  doc/gsrc.texi
  doc/version.texi

=== modified file 'doc/gsrc.info'
--- a/doc/gsrc.info     2012-12-08 16:24:49 +0000
+++ b/doc/gsrc.info     2013-01-06 13:39:24 +0000
@@ -1,9 +1,9 @@
 This is gsrc.info, produced by makeinfo version 4.13 from gsrc.texi.
 
 This manual is for the GNU Source Release Collection (version
-2012.09.06, updated 8 December 2012).
+2013.01.06, updated 6 January 2013).
 
-   Copyright (C) 2011, 2012 Free Software Foundation, Inc.
+   Copyright (C) 2011, 2012, 2013 Free Software Foundation, Inc.
 
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License,
@@ -23,8 +23,8 @@
 GNU Source Release Collection
 *****************************
 
-This manual is for GNU Source Release Collection (version 2012.09.06,
-8 December 2012).
+This manual is for GNU Source Release Collection (version 2013.01.06,
+6 January 2013).
 
 * Menu:
 
@@ -114,8 +114,11 @@
 `Makefile' will execute the usual `./configure' and `make' commands
 needed to build a GNU package.
 
-   The `deps/' subdirectory contains GARfiles for a few external
-packages.
+   The `deps/' subdirectory contains build recipes for some non-GNU
+packages on which GNU packages depend. The `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:
@@ -130,6 +133,7 @@
 * Setting your environment::
 * Useful targets::
 * Complex packages::
+* Finding packages::
 
 
 File: gsrc.info,  Node: Initial setup,  Next: Building a simple package,  
Prev: Getting started,  Up: Getting started
@@ -159,7 +163,13 @@
      config.status: creating setup.sh
      config.status: creating GNUmakefile
      config.status: creating doc/Makefile
-     $
+
+   You can optionally install the documentation and the `gsrc' script
+(*note Finding packages::). Note that these are installed to the
+directory specified in the previous step. Be sure to set your
+environment to be able to use them (*note Setting your environment::).
+
+     $ make install
 
 
 File: gsrc.info,  Node: Building a simple package,  Next: Installing a 
package,  Prev: Initial setup,  Up: Getting started
@@ -210,7 +220,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 `PATH',
-`LD_LIBRARY_PATH', `INFOPATH', etc.
+`LD_LIBRARY_PATH', `INFOPATH', etc. These variables inform your system
+of the locations of relevant files on it. For example, `PATH' contains
+a list of all directories that contain executable files.
 
    There is a sample script `setup.sh' in the top-level source
 directory which can be used to set the main environment variables.
@@ -252,18 +264,30 @@
      $ make -C gnu/hello fetch checksum extract configure build install
 
    Each target depends on the previous one, so typing `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 `pkg-info'.
 
      $ 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'
+
+   The "Status" can  be any of: "not installed", "installed (not
+stowed)" or "installed (stowed)" (*note Package versions::).
+
+   To view a more concise summary, ideal for producing a list of
+packages in script, use the target `pkg-info-curt'.
+
+     $ 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'
 
    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
@@ -286,7 +310,7 @@
 options are available to you, you may invoke the `help' target.
 
 
-File: gsrc.info,  Node: Complex packages,  Prev: Useful targets,  Up: Getting 
started
+File: gsrc.info,  Node: Complex packages,  Next: Finding packages,  Prev: 
Useful targets,  Up: Getting started
 
 2.6 Complex packages
 ====================
@@ -302,7 +326,8 @@
 
    The dependencies are searched for in the `gnu/' subdirectory by
 default, with some additional external packages such as `zlib' in the
-`deps/' subdirectory.
+`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,
 
@@ -318,12 +343,62 @@
      $ make -C gnu/gnupg install
 
 
+File: gsrc.info,  Node: Finding packages,  Prev: Complex packages,  Up: 
Getting started
+
+2.7 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 `grep'
+to search the text of the build recipes for key words.
+
+   A template script is provided, called `gsrc', that provides a simple
+means for searching for packages via keywords, printing information
+about a package, and printing its location. Since `gsrc' is installed
+to the same location as executables installed by GSRC, if you have set
+up your environment to use GSRC packages (*note Setting your
+environment::), you can use the `gsrc' script to access GSRC from
+outside its source directory.
+
+   For example, here we search for an editor, discover the program
+`moe', read information about it, and then install it.
+
+     $ 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
+
+   If you view the `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.
+
+
 File: gsrc.info,  Node: Advanced configuration,  Next: GNU Free Documentation 
License,  Prev: Getting started,  Up: Top
 
 3 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.
@@ -341,7 +416,7 @@
 3.1 Global configuration
 ========================
 
-The build loads the following configuration files:
+Building a package loads the following configuration files:
 
 `config.mk'
      Specifies the installation directory prefix.  Created by the
@@ -415,11 +490,11 @@
      cases, you may wish to redirect this output to somewhere other than
      your screen. In this case, you may set the variable
      `REDIRECT_OUTPUT' to any value other than "n". To edit where the
-     output will be redirected, set the OUTPUT variable. By default, if
-     you set `REDIRECT_OUTPUT', standard text output will be redirected
-     to `/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 (*note Redirections:
+     output will be redirected, set the `OUTPUT' variable. By default,
+     if you set `REDIRECT_OUTPUT', standard text output will be
+     redirected to `/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 (*note Redirections:
      (bash)Redirections. for more details on redirection). Set in
      `gar.conf.mk'
 
@@ -436,28 +511,28 @@
 
    GNU packages take most of their configuration in the form of options
 passed to the `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 `CONFIGURE_OPTS' variable.
+Any options added to this variable will be appended to the options set
+by default by GSRC.
 
      CONFIGURE_OPTS = --disable-gtk --without-png
 
    For convenience, every package has a file called `config.mk' in its
-directory which is imported by the `Makefile'. Typically, all user
+directory which is imported by its build script. Typically, all user
 configuration may be done here. By default, it contains the
 `CONFIGURE_OPTS' and `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
-`config.mk' while `Makefile' contains the recipe to make sure the
-package builds correctly. Thus, you should not need to modify the
-`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
-`Makefile'. Thus, you do not need to worry about setting them correctly
-in `config.mk'.
+   Generally speaking, user configuration is done exclusively in
+`config.mk' while `Makefile' contains the information and recipe
+necessary for the package to build correctly. Thus, you should not need
+to modify the `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 `Makefile', because they are necessary for proper building and
+installation in GSRC. Therefore, you do not need to worry about setting
+them correctly in `config.mk'.
 
 
 File: gsrc.info,  Node: Patching packages,  Next: Package versions,  Prev: 
Package configuration,  Up: Advanced configuration
@@ -465,7 +540,7 @@
 3.3 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 `files/' and move the patch file(s) there.
 Next, create two variables in the package's `Makefile':
@@ -474,17 +549,23 @@
      PATCHOPTS = -p0
 
    `PATCHFILES' holds a list of all the patch files in the `files/'
-subdirectory. `PATCHOPTS' contains the option switches nto pass to the
-`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.
-
-     $ make makesum install
+subdirectory. `PATCHOPTS' contains the option switches to pass to the
+`patch' program.
+
+   Next, the patch file's checksum is added to the checksums file for
+the package.
+
+     $ make makesum
 
    Note that if the `make makesums' command fails due to GPG
-verification and you trust the source from which the package was
-downloaded, you may instead use `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 `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.
+
+     $ make install
 
    If the package requires a patch to even build properly, then this is
 a bug in GSRC. Please report such build problems to <address@hidden>.
@@ -507,7 +588,9 @@
 other files installed by the package are installed in a similar manner.
 Next, GSRC makes symbolic links to those files inside the parent `/gnu/'
 directory. Thus, `/gnu/bin/hello' is ultimately a symlink to
-`/gnu/packages/hello-2.7/bin/hello'.
+`/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 `hello 2.8' is built and
@@ -515,19 +598,19 @@
 `/gnu/packages/hello-2.8/' and the directory of `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.
+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 `GARVERSION' variable to `make install'. Be sure to update the
 checksums when you do so, otherwise the process will fail!
 
      $ make -C gnu/hello makesum install GARVERSION=2.7
 
    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 `make clean', the package will be
-build from scratch.
+re-stow those files. Of course, if you have not previously built it, or
+if you have previously run `make clean', the package will be built from
+scratch.
 
    Note: this method may fail if the package naming format or
 compression algorithm has changed between versions (i.e. a change from
@@ -1032,21 +1115,22 @@
 
 
 Tag Table:
-Node: Top768
-Node: Introduction1105
-Node: Building GNU packages2633
-Node: Getting started3221
-Node: Initial setup4481
-Node: Building a simple package5574
-Node: Installing a package6244
-Node: Setting your environment6903
-Node: Useful targets8046
-Node: Complex packages9728
-Node: Advanced configuration10785
-Node: Global configuration11299
-Node: Package configuration14973
-Node: Patching packages16577
-Node: Package versions17823
-Node: GNU Free Documentation License20330
+Node: Top773
+Node: Introduction1109
+Node: Building GNU packages2637
+Node: Getting started3225
+Node: Initial setup4740
+Node: Building a simple package6116
+Node: Installing a package6786
+Node: Setting your environment7445
+Node: Useful targets8751
+Node: Complex packages11010
+Node: Finding packages12183
+Node: Advanced configuration14052
+Node: Global configuration14565
+Node: Package configuration18250
+Node: Patching packages19874
+Node: Package versions21147
+Node: GNU Free Documentation License23758
 
 End Tag Table

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2013-01-06 12:23:20 +0000
+++ b/doc/gsrc.texi     2013-01-06 13:39:24 +0000
@@ -225,7 +225,15 @@
 config.status: creating setup.sh
 config.status: creating GNUmakefile
 config.status: creating doc/Makefile
-$
address@hidden example
+
+You can optionally install the documentation and the @file{gsrc}
+script (@pxref{Finding packages}). Note that these are installed to the
+directory specified in the previous step. Be sure to set your
+environment to be able to use them (@pxref{Setting your environment}).
+
address@hidden
+$ make install
 @end example
 
 @c *******************************************************************
@@ -342,7 +350,8 @@
 Each target depends on the previous one, so typing @code{make -C
 gnu/hello install} executes all the earlier targets first.
 
-To see some information about a package, use the target @code{pkg-info}.
+To see some information about a package, use the target
address@hidden 
 
 @example
 $ make -C gnu/hello pkg-info
@@ -355,6 +364,9 @@
 make: Leaving directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
 @end example
 
+The ``Status'' can  be any of: ``not installed'', ``installed (not
+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}.
 
@@ -437,13 +449,15 @@
 searching. For example, you can use standard GNU tools such as
 @code{grep} to search the text of the build recipes for key words.
 
-A template script is provided, called @file{gsrc}, that provides a
+A template script is installed, 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.
+information about a package, and printing its location. Since
address@hidden is installed to the same location as executables installed
+by GSRC, if you have set up your environment to use GSRC packages
+(@pxref{Setting your environment}), you can use the @file{gsrc} script
+to access GSRC from outside its source directory.
 
-In this example, we search for an editor, discover the program
+For example, here we search for an editor, discover the program
 @code{moe}, read information about it, and then install it.
 
 @example

=== modified file 'doc/version.texi'
--- a/doc/version.texi  2012-12-08 16:24:49 +0000
+++ b/doc/version.texi  2013-01-06 13:39:24 +0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 8 December 2012
address@hidden UPDATED-MONTH December 2012
address@hidden EDITION 2012.09.06
address@hidden VERSION 2012.09.06
address@hidden UPDATED 6 January 2013
address@hidden UPDATED-MONTH January 2013
address@hidden EDITION 2013.01.06
address@hidden VERSION 2013.01.06