[Gsrc-commit] trunk r2588: update manual

[Brandon Invergo]

------------------------------------------------------------
revno: 2588
revision-id: address@hidden
parent: address@hidden
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Fri 2013-10-04 18:13:52 +0200
message:
  update manual
modified:
  doc/gsrc.texi                  gsrc.texi-20100621151235-73qm58fnc905qvlr-1

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2013-10-04 15:32:55 +0000
+++ b/doc/gsrc.texi     2013-10-04 16:13:52 +0000
@@ -198,7 +198,7 @@
 @chapter Getting started
 
 GSRC is distributed directly using the Bazaar version control system
-or via a a compressed archive.  You can check out the latest version
+or via a compressed archive.  You can check out the latest version
 from the Bazaar repository using
 
 @example
@@ -206,21 +206,23 @@
 @end example
 
 @noindent
-This will create a directory @file{gsrc}.  The build definitions for
-GNU packages are in the @file{gnu} subdirectory.  Large sub-projects,
-such as GNOME, have their own subdirectory containing packages
-(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
address@hidden for building it.  This @file{Makefile} will execute
-the usual @file{./configure} and @command{make} commands needed to build
-a GNU package.
+This will create a directory @file{gsrc}.  The build definitions for GNU
+packages are in the @file{gnu} subdirectory.  Large sub-projects, such
+as GNOME, have their own subdirectory containing packages
+(i.e. @file{gnome}).  The @file{external} subdirectory contains
+references to dependencies which you may have to install outside of
+GSRC, such as via your GNU/Linux distribution's package manager (APT,
+Pacman, Yum, etc.).  If these dependencies are required for a given
+package and are not found on your system, you will be automatically
+notified.  Finally, the @file{decommissioned} directory contains former
+GNU packages that have been decommissioned.
 
-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.).
+Each package has its own subdirectory within its parent directory, for
+example @file{gnu/emacs} or @file{gnome/evince}.  Package directories
+contain a @file{config.mk} file for configuring the package and a
address@hidden for building it.  This @file{Makefile} will automate the
+usual @file{./configure} and @command{make} commands needed to build a
+GNU package.
 
 To stay up-to-date with the latest releases of GNU software, you can
 pull in recent changes to your local copy of GSRC:
@@ -260,11 +262,15 @@
 $ ./configure --prefix=/gnu
 checking for a BSD-compatible install... /usr/bin/install -c
 checking whether build environment is sane... yes
-checking for a thread-safe mkdir -p... /bin/mkdir -p
-checking for gawk... no
-checking for mawk... mawk
+checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
+checking for gawk... gawk
 checking whether make sets $(MAKE)... yes
+checking whether make supports nested variables... yes
+checking for recsel... /usr/bin/recsel
+checking for recfmt... /usr/bin/recfmt
+checking that generated files are newer than configure... done
 configure: creating ./config.status
+config.status: creating gsrc
 config.status: creating config.mk
 config.status: creating setup.sh
 config.status: creating GNUmakefile
@@ -289,7 +295,7 @@
 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:
+subdirectory from the root GSRC directory use:
 
 @example
 $ make -C gnu/hello
@@ -299,7 +305,7 @@
 The package will be built in the subdirectory @file{gnu/hello/work}.
 
 @example
-$ ./gnu/hello/work/hello-2.7/src/hello
+$ ./gnu/hello/work/hello-2.8/src/hello
 Hello, world!
 @end example
 
@@ -327,7 +333,7 @@
 
 @example
 $ /gnu/bin/hello --version
-hello (GNU hello) 2.7
+hello (GNU hello) 2.8
 @end example
 
 @c *******************************************************************
@@ -335,15 +341,15 @@
 @node Setting your environment, Useful targets, Installing a package, Getting 
started
 @section Setting your environment
 
-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, @env{LD_LIBRARY_PATH}, @env{INFOPATH}, etc. These
-variables inform your system of the locations of relevant files on
-it. For example, @env{PATH} contains a list of all directories that
-contain executable files.
+If you want to use the newly installed package without having to specify
+its full path, you will need to modify the relevant variables in your
+environment, such as @env{PATH}, @env{LD_LIBRARY_PATH}, @env{INFOPATH},
+etc. These variables inform your system of the locations of relevant
+files on 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
-directory which can be used to set the main environment variables.
+There is a sample script @file{setup.sh} in the top-level GSRC directory
+which can be used to set the main environment variables.
 
 @example
 $ source setup.sh
@@ -495,6 +501,9 @@
 $ make -C gnu/gnupg install
 @end example
 
+All of the dependencies (and the dependencies' dependencies) will be
+built and installed first, as needed.
+
 @c *******************************************************************
 
 @node Finding packages,  , Complex packages, Getting started
@@ -512,7 +521,7 @@
 @file{gsrc} 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.
+to access GSRC from outside the GSRC directory.
 
 For example, here we search for an editor, discover the program
 @dfn{moe}, read information about it, and then install it.
@@ -647,24 +656,24 @@
 
 @item MAKE_ARGS_PARALLEL
 Set this to @code{-j @var{N}} to allow N parallel processes in the
-build.  Note that multiple dependencies are built one-by-one, only the
+build.  Note that multiple dependencies are built one-by-one; only the
 commands within each build are performed in parallel. Set in
 @file{gar.conf.mk}
 
 @item USE_COLOR
-It's easy to miss the messages printed by GSRC amongst all the output
-of the build process. Set this to ``y'' to enable colorized output of
-GSRC messages, which may make them more visible. Set it to anything
-else to disable color. In either case, four more variables are
-defined: @code{MSG}, @code{ERR}, @code{OK} and @code{OFF}. The first
-three define strings to insert at the beginning of a normal message,
-an error message, or a message indicating success, respectively. The
address@hidden code is inserted at the end of the message. When
address@hidden is ``y'', these variables contain ANSI escape
-sequences to change properties of the text (i.e. to set colors or text
-weight). Otherwise, they may contain textual indicators, such as
-``==> '' to begin a message. Some sensible default values for both
-cases are included. Set in @file{gar.conf.mk}.
+It's easy to miss the messages printed by GSRC amongst all the output of
+the build process. Set this to ``y'' to enable colorized output of GSRC
+messages, which may make them more visible. Set it to anything else to
+disable color. In either case, four more variables are defined:
address@hidden, @code{MSG2}, @code{ERR}, @code{OK} and @code{OFF}. The first
+four define strings to insert at the beginning of a normal message
+(@code{MSG}, @code{MSG2}), an error message (@code{ERR}), or a message
+indicating success (@code{OK}). The @code{OFF} code is inserted at the
+end of the message. When @code{USE_COLOR} is ``y'', these variables
+contain ANSI escape sequences to change properties of the text (i.e. to
+set colors or text weight). Otherwise, they may contain textual
+indicators, such as ``==> '' to begin a message. Some sensible default
+values for both cases are included. Set in @file{gar.conf.mk}.
 
 @item REDIRECT_OUTPUT
 A typical build process produces a lot of textual output. In some
@@ -708,13 +717,13 @@
 
 Generally speaking, user configuration is done exclusively in
 @file{config.mk} while @file{Makefile} contains the information and
-recipe necessary for the package to build correctly. Thus, you should
+recipes 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}.
+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
@@ -752,6 +761,11 @@
 $ make install
 @end example
 
+If the patching process fails and you are sure that the patch is for the
+version of the package contained in GSRC, then you may have to modify
+the @option{-p} option in the @code{PATCHOPTS} variable (@pxref{patch
+Options, , ,diffutils,patch}).
+
 If the package requires a patch to even build properly, then this is a
 bug in GSRC. Please report such build problems to
 @email{bug-gsrc@@gnu.org}. 
@@ -775,8 +789,8 @@
 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''.
address@hidden; a package with symlinks to its files installed in the
+system is said to be @dfn{stowed}.
 
 When a new version of a package is released, you do not have to
 uninstall the previous version first. When @dfn{hello 2.8} is built