debian/copyright updates; clscan: fix formatting

[gnulib.git] / doc / relocatable-maint.texi

diff --git a/doc/relocatable-maint.texi b/doc/relocatable-maint.texi
index c743d4a..f972b2f 100644 (file)
--- a/doc/relocatable-maint.texi
+++ b/doc/relocatable-maint.texi
@@ -8,14 +8,14 @@ and have it work correctly (including i18n).  So many users need to go
 through @code{configure; make; make install} with all its
 dependencies, options, and hurdles.
 
-Red Hat, Debian, and similar package systems solve the ``ease of
+Red Hat, Debian, and other binary distributions solve the ``ease of
 installation'' problem, but they hardwire path names, usually to
 @file{/usr} or @file{/usr/local}.  This means that users need root
 privileges to install a binary package, and prevents installing two
 different versions of the same binary package.
 
 A relocatable program can be moved or copied to a different location
-on the filesystem.  It is possible to make symlinks to the installed
+on the file system.  It is possible to make symlinks to the installed
 and moved programs, and invoke them through the symlink. It is
 possible to do the same thing with a hard link @emph{only} if the hard
 link file is in the same directory as the real program.
@@ -46,7 +46,7 @@ sets the environment variable that controls shared library searching
 
 This approach does not always work.  On OpenBSD and OpenServer,
 prereleases of Libtool 1.5 put absolute file names of libraries in
-executables, which prevents searching any other locations. 
+executables, which prevents searching any other locations.
 
 @item
 On Windows, the executable's own directory is searched for libraries,
@@ -82,13 +82,34 @@ bindtextdomain (PACKAGE, LOCALEDIR);
 @noindent
 becomes:
 
-@example 
+@example
 bindtextdomain (PACKAGE, relocate (LOCALEDIR));
 @end example
 
 The prototype for this function is in @file{relocatable.h}.
 
 @item
+The @code{set_program_name} function can also configure some
+additional libraries to relocate files that they access, by defining
+corresponding C preprocessor symbols to 1.  The libraries for which
+this is supported and the corresponding preprocessor symbols are:
+
+@table @asis
+@item libcharset
+@code{DEPENDS_ON_LIBCHARSET}
+
+@item libiconv
+@code{DEPENDS_ON_LIBICONV}
+
+@item libintl
+@code{DEPENDS_ON_LIBINTL}
+@end table
+
+Defining the symbol for a library makes every program in the package
+depend on that library, whether the program really uses the library or
+not, so this feature should be used with some caution.
+
+@item
 If your package installs shell scripts, also import the
 @code{relocatable-script} module.  Then, near the beginning of each
 shell script that your package installs, add the following:
@@ -101,17 +122,26 @@ if test "@@RELOCATABLE@@" = yes; then
   orig_installdir="$bindir" # see Makefile.am's *_SCRIPTS variables
   func_find_curr_installdir # determine curr_installdir
   func_find_prefixes
-  # Relocate the directory variables that we use.
-  gettext_dir=`
-    echo "$gettext_dir/" \
+  relocate () @{
+    echo "$1/" \
     | sed -e "s%^$@{orig_installprefix@}/%$@{curr_installprefix@}/%" \
-    | sed -e 's,/$,,'`
+    | sed -e 's,/$,,'
+  @}
+else
+  relocate () @{
+    echo "$1"
+  @}
 fi
+
+# Get some relocated directory names.
+sysconfdir=`relocate "@@sysconfdir@@"`
+some_datadir=`relocate "@@datadir@@/something"`
 @end example
 
 You must adapt the definition of @code{orig_installdir}, depending on
 where the script gets installed.  Also, at the end, instead of
-@code{gettext_dir}, transform those variables that you need.
+@code{sysconfdir} and @code{some_datadir}, transform those variables
+that you need.
 
 @item
 In your @file{Makefile.am}, for every program @command{foo} that gets
@@ -125,8 +155,8 @@ endif
 @end example
 
 @item
-You may also need to add one or two variable assignments to your
-@file{configure.ac}.  
+You may also need to add a couple of variable assignments to your
+@file{configure.ac}.
 
 If your package (or any package you rely on, e.g.@: gettext-runtime)
 will be relocated together with a set of installed shared libraries,