[Gsrc-commit] trunk r2795: update documentation

[Brandon Invergo]

------------------------------------------------------------
revno: 2795
revision-id: address@hidden
parent: address@hidden
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Mon 2014-01-06 21:24:17 +0000
message:
  update documentation
modified:
  doc/gsrc.texi                  gsrc.texi-20100621151235-73qm58fnc905qvlr-1

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2013-11-15 18:56:36 +0000
+++ b/doc/gsrc.texi     2014-01-06 21:24:17 +0000
@@ -10,7 +10,7 @@
 This manual is for the GNU Source Release Collection (version
 @value{VERSION}, updated @value{UPDATED}).
 
-Copyright @copyright{} 2011, 2012, 2013 Free Software Foundation, Inc.
+Copyright @copyright{} 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -118,7 +118,7 @@
 Makefile-based build system, and is written in GNU Make.  The GARNOME
 build system for GNOME was another example of a system using GAR.
 
-Note that GSRC is not intended to be a full package management system
+Note that GSRC is not intended to be a full package-management system
 or source distribution.  It is just a more convenient way to compile
 GNU packages from source on an existing system.
 
@@ -161,20 +161,32 @@
 @node Building GNU packages,  , Introduction, Introduction
 @section Building GNU packages
 
-If you have never built a GNU package by hand, this section will
-briefly show the process so you will have an idea of what GSRC is
-doing.
-
address@hidden @bullet
+If you have never built a GNU package by hand, this section will briefly
+show the process so you will have an idea of what GSRC is doing.  If you
+are already familiar with this, you may skip this section.
+
+The build process is performed via commands entered into a shell, which
+is generally done in a terminal or a terminal emulator.  The dollar sign
+in the following examples represents the @dfn{shell prompt}, denoting
+the point at which you enter commands, while the characters following
+the prompt show the commands that you must enter.  While much of the
+build process is conveniently automated, such that you do not need to
+manually compile every file, you still must take a few steps.
+
+For example, to build the package ``hello'' version 2.9, you must
+perform the following steps in your terminal:
+
address@hidden
 @item Download the package and unpack it
 @example
-$ wget http://ftpmirror.gnu.org/gnu/hello/hello-2.6.tar.gz
-$ tar xvfz hello-2.6.tar.gz
+$ wget http://ftpmirror.gnu.org/gnu/hello/hello-2.9.tar.gz
+$ tar xvfz hello-2.9.tar.gz
 @end example
 
address@hidden Run the configure script
address@hidden Run the @file{configure} script
 @example
-$ cd hello-2.6; ./configure
+$ cd hello-2.9
+$ ./configure
 @end example
 
 @item Compile the source code
@@ -187,7 +199,12 @@
 $ make install
 @end example
 
address@hidden itemize
address@hidden enumerate
+
+In some unfortunate cases, the process is not as straight-forward and
+may require some extra intervention on your part.  GSRC abstracts away
+most of these steps so that all you need to enter to install a program
+is @code{make install}.
 
 
 @node Getting started, Advanced configuration, Introduction, Top
@@ -227,6 +244,9 @@
 $ bzr update
 @end example
 
+Alternatively, quarter-annual ``snapshots'' of GSRC are made available
+for download at @url{http://ftpmirror.gnu.org/gnu/gsrc}.
+
 @menu
 * Initial setup::
 * Building a simple package::
@@ -285,11 +305,22 @@
 @node  Building a simple package, Installing a package, Initial setup, Getting 
started
 @section Building a simple package
 
-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 from the root GSRC directory use:
+All interaction with GSRC is performed via the program Make.  When you
+execute Make via the @command{make} command, you generally must provide
+a @dfn{target} that tells Make which @dfn{recipe}, consisting of a
+series of pre-defined commands, to execute.  For example, the
address@hidden target will tell Make to execute a recipe to build the
+software, while the @option{install} target will execute a recipe for
+installing it.  Often, a default recipe will be available that will
+typically build the software, allowing you to omit the @option{build}
+target.
+
+Thus, in GSRC, to build any package, type @command{make build} (or,
+simply @command{make}) in the package's subdirectory.  You can change to
+the directory with the @command{cd} command in the shell, or with the
address@hidden option of @command{make}.  For example, to build the
address@hidden package in the @file{gnu/hello} subdirectory from the root
+GSRC directory use:
 
 @example
 $ make -C gnu/hello
@@ -299,7 +330,7 @@
 The package will be built in the subdirectory @file{gnu/hello/work}.
 
 @example
-$ ./gnu/hello/work/hello-2.8/src/hello
+$ ./gnu/hello/work/hello-2.9/src/hello
 Hello, world!
 @end example
 
@@ -326,7 +357,7 @@
 
 @example
 $ /gnu/bin/hello --version
-hello (GNU hello) 2.8
+hello (GNU hello) 2.9
 @end example
 
 
@@ -403,7 +434,7 @@
 $ make -C gnu/hello pkg-info
 make: Entering directory `/home/gnu/gsrc/gnu/hello'
 Name:        GNU Hello
-Version:     2.8
+Version:     2.9
 URL:         http://www.gnu.org/software/hello/manual/
 Description:
  GNU Hello prints the message "Hello, world!" and then exits.  It
@@ -422,7 +453,7 @@
 @example
 $ make -C gnu/hello pkg-info-curt
 make: Entering directory `/home/gnu/gsrc/gnu/hello'
-gnu/hello 2.8
+gnu/hello 2.9
  A program that produces a familiar, friendly greeting
 make: Leaving directory `/home/gnu/gsrc/gnu/hello'
 @end example
@@ -435,13 +466,13 @@
 $ make -C gnu/hello fetch-list
 make: Entering directory `/home/gnu/gsrc/gnu/hello'
 Name: hello
-Version: 2.8
+Version: 2.9
 Location: http://ftpmirror.gnu.org/hello/
 Distribution files:
-       hello-2.8.tar.gz
+       hello-2.9.tar.gz
 Patch files:
 Signature files:
-       hello-2.8.tar.gz.sig
+       hello-2.9.tar.gz.sig
 Dependencies:
 make: Leaving directory `/home/gnu/gsrc/gnu/hello'
 @end example
@@ -456,7 +487,7 @@
 re-built. Instead, it would merely be re-stowed. To completely remove a
 package, use the @option{uninstall-pkg} target.  When you update a
 package to a new version, the old version is merely un-stowed and the
-new version is installed alongside it @pxref{Package versions}.  In
+new version is installed alongside it (@pxref{Package versions}).  In
 order to clean out old package versions, use the
 @option{uninstall-pkg-old} target.
 
@@ -464,9 +495,9 @@
 @node Complex packages, Finding packages, Useful targets, Getting started
 @section Complex packages
 
-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 @option{dep-list} target.
+If building or using a package depends on other GNU packages, these will
+be built automatically in the correct order.  To see the dependencies of
+any package use the @option{dep-list} target.
 
 @example
 $ make -C gnu/gnupg dep-list
@@ -710,12 +741,12 @@
 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 its build script. Typically, all
-user configuration may be done here. By default, it contains the
+For convenience, every package has a file called @file{config.mk} in its
+directory which is imported by its build script. Typically, all user
+configuration should 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.
+cases, package-specific, user-customize-able variables are also defined
+in this file.
 
 Generally speaking, user configuration is done exclusively in
 @file{config.mk} while @file{Makefile} contains the information and
@@ -770,7 +801,8 @@
 
 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@@gnu.org}.
address@hidden@@gnu.org}.  You should also contact the maintainers of
+the software package to make them aware of the problem.
 
 
 @node Package versions,  , Patching packages, Advanced configuration
@@ -782,21 +814,21 @@
 
 When you install a package, it is first actually installed to the
 @file{/gnu/packages} directory in a sub-directory with the name
-<package>-<version> (i.e. @file{/gnu/packages/hello-2.7}). In the
+<package>-<version> (i.e. @file{/gnu/packages/hello-2.8}). 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
+is installed to @file{/gnu/packages/hello-2.8/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}
 directory. Thus, @file{/gnu/bin/hello} is ultimately a symlink to
address@hidden/gnu/packages/hello-2.7/bin/hello}. This is referred to as
address@hidden/gnu/packages/hello-2.8/bin/hello}. This is referred to as
 @dfn{stowing}; 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
+uninstall the previous version first. When @dfn{hello 2.9} is built
 and installed, it is put into its own package directory,
address@hidden/gnu/packages/hello-2.8} and the directory of @dfn{hello 2.7}
address@hidden/gnu/packages/hello-2.9} and the directory of @dfn{hello 2.8}
 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
@@ -807,10 +839,10 @@
 update the checksums when you do so, otherwise the process will fail!
 
 @example
-$ make -C gnu/hello makesum install GARVERSION=2.7
+$ make -C gnu/hello makesum install GARVERSION=2.8
 @end example
 
-If you had previously built version 2.7, then GSRC will merely re-stow
+If you had previously built version 2.8, then GSRC will merely re-stow
 those files. Of course, if you have not previously built it, or if
 you have previously run @command{make clean}, the package will be built
 from scratch.
@@ -829,7 +861,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.9-no-nls}.
 
 
 @node Technical information, GNU Free Documentation License, Advanced 
configuration, Top
@@ -916,12 +948,12 @@
 For example, in a typical GNU package, configuration is done with a
 @file{configure} script while building and installing are done with a
 @file{Makefile}. So, for the package @dfn{hello}, the @option{build}
-target will depend on a rule called
address@hidden/hello-2.8/Makefile} (@option{build} plus the
+target will depend on a target called
address@hidden/hello-2.9/Makefile} (@option{build-} plus the
 location of the @file{Makefile} distributed with the package). For a
 Python-based package that is installed via a @file{setup.py}, the
address@hidden target will depend on
address@hidden/somepkg-1.0/setup.py}. The file @file{gar.lib.mk}
address@hidden target will depend on the target
address@hidden/foo-1.0/setup.py}. The file @file{gar.lib.mk}
 contains many generalized Make recipes to handle each of these
 different scenarios.
 
@@ -1059,7 +1091,7 @@
 @tab
 This is the directory of the master site under which the package
 files can be found. For most GNU packages, this can simply be
address@hidden(GARNAME)}.
address@hidden(GARNAME)/}.
 
 @item
 @code{DISTFILE_SITES}
@@ -1166,6 +1198,15 @@
 may also be included.
 
 @item
address@hidden
address@hidden
+This variable contains a list of all of the Info documentation files
+installed by a program.  To use this variable, you must include the
address@hidden file from the @file{gar.lib} directory.  If this variable
+is not defined and @file{info.mk} is included, then it will have a
+default value of @code{$(GARNAME).info}
+
address@hidden
 @code{BUILDDEPS}
 @tab
 This variable contains a space-separated list of the programs required
@@ -1214,7 +1255,7 @@
 @code{CONFIGURE_SCRIPTS}, @code{BUILD_SCRIPTS} and
 @code{INSTALL_SCRIPTS}. As mentioned previously, user-level targets,
 such as @option{build}, depend on lower-level targets such as
address@hidden/hello-2.8/Makefile}. These are the targets that
address@hidden/hello-2.9/Makefile}. These are the targets that
 must be implemented for each of the designated configure/build/install
 scripts. For each target, a recipe is written using the normal Make
 syntax to perform the necessary task. Recall that phony targets may be
@@ -1222,7 +1263,7 @@
 @code{INSTALL_SCRIPTS = java}, then a target named @code{install-java}
 must be written.
 
-The second kind of targets that may be written are pre and post
+The second kind of targets that may be written are pre- and post-
 rules. These recipes are run before or after the specified top-level
 target. For example, a target called @option{pre-build} is run
 immediately before the @option{build} target. These targets are
@@ -1237,7 +1278,7 @@
 @example
 NAME = GNU Hello
 GARNAME = hello
-GARVERSION = 2.8
+GARVERSION = 2.9
 HOME_URL = http://www.gnu.org/software/hello/manual/
 DESCRIPTION = A program that produces a familiar, friendly greeting
 define BLURB