New doc chapter "Using the library".

1 files changed, 157 insertions, 0 deletions

diff --git a/doc/libunistring.texi b/doc/libunistring.texi
index e40c70e..b5eb976 100644
--- a/doc/libunistring.texi
+++ b/doc/libunistring.texi
@@ -5,6 +5,7 @@
 @settitle GNU libunistring
 @finalout
 @c Indices:
+@c   am = autoconf macro  @amindex
 @c   cp = concept         @cindex
 @c   fn = function        @findex
 @c   tp = type            @tindex
@@ -12,6 +13,8 @@
 @c   ky = keystroke       @kindex
 @c   pg = program         @pindex
 @c   vr = variable        @vindex
+@defcodeindex am
+@syncodeindex am cp
 @syncodeindex fn cp
 @syncodeindex tp cp
 @ifclear texi2html
@@ -142,6 +145,7 @@ A copy of the license is included in @ref{GNU GPL}.
 * uninorm.h::                   Normalization forms
 * unicase.h::                   Case mappings
 * uniregex.h::                  Regular expressions
+* Using the library::           How to link with the library and use it?
 * More functionality::          More advanced functionality
 * Licenses::                    Licenses
 
@@ -213,6 +217,14 @@ unicase,h
 * Case insensitive comparison::
 * Case detection::
 
+Using the library
+
+* Installation::
+* Compiler options::
+* Include files::
+* Autoconf macro::
+* Reporting problems::
+
 Licenses
 
 * GNU GPL::                     GNU General Public License
@@ -728,6 +740,151 @@ NULL is returned and @code{errno} is set.
 @include unicase.texi
 @include uniregex.texi
 
+@node Using the library
+@chapter Using the library
+
+This chapter explains some practical considerations, regarding the
+installation and compiler options that are needed in order to use this
+library.
+
+@menu
+* Installation::
+* Compiler options::
+* Include files::
+* Autoconf macro::
+* Reporting problems::
+@end menu
+
+@node Installation
+@section Installation
+
+@cindex dependencies
+Before you can use the library, it must be installed.  First, you have to
+make sure all dependencies are installed.  They are listed in the file
+@file{DEPENDENCIES}.
+
+@cindex installation
+Then you can proceed to build and install the library, as described in the
+file @file{INSTALL}.  For installation on Windows systems, please refer to
+the file @file{README.woe32}.
+
+@node Compiler options
+@section Compiler options
+
+Let's denote as @code{LIBUNISTRING_PREFIX} the value of the @samp{--prefix}
+option that you passed to @code{configure} while installing this package.
+If you didn't pass any @samp{--prefix} option, then the package is installed
+in @file{/usr/local}.
+
+Let's denote as @code{LIBUNISTRING_INCLUDEDIR} the directory where the
+include files were installed.  This is usually the same as
+@code{$@{LIBUNISTRING_PREFIX@}/include}.  Except that if you passed an
+@samp{--includedir} option to @code{configure}, it is the value of that
+option.
+
+Let's further denote as @code{LIBUNISTRING_LIBDIR} the directory where
+the library itself was installed.  This is the value that you passed
+with the @samp{--libdir} option to @code{configure}, or otherwise the
+same as @code{$@{LIBUNISTRING_PREFIX@}/lib}.  Recall that when building
+in 64-bit mode on a 64-bit GNU/Linux system that supports executables
+in either 64-bit mode or 32-bit mode, you should have used the option
+@code{--libdir=$@{LIBUNISTRING_PREFIX@}/lib64}.
+
+@cindex compiler options
+So that the compiler finds the include files, you have to pass it the
+option @code{-I$@{LIBUNISTRING_INCLUDEDIR@}}.
+
+So that the compiler finds the library during its linking pass, you have
+to pass it the options @code{-L$@{LIBUNISTRING_LIBDIR@} -lunistring}.
+On some systems, in some configurations, you also have to pass options
+needed for linking with @code{libiconv}.  The autoconf macro
+@code{gl_LIBUNISTRING} (see @ref{Autoconf macro}) deals with this
+particularity.
+
+@node Include files
+@section Include files
+
+Most of the include files have been presented in the introduction, see
+@ref{Introduction}, and subsequent detailed chapters.
+
+Another include file is @code{<unistring/version.h>}. It contains the
+version number of the libunistring library.
+
+@deftypevr Macro int _LIBUNISTRING_VERSION
+This constant contains the version of libunistring that is being used
+at compile time.  It encodes the major and minor parts of the version
+number only.  These parts are encoded in the form @code{(major<<8) + minor}.
+@end deftypevr
+
+@deftypevr Constant int _libunistring_version
+This constant contains the version of libunistring that is being used
+at run time.  It encodes the major and minor parts of the version
+number only.  These parts are encoded in the form @code{(major<<8) + minor}.
+@end deftypevr
+
+It is possible that @code{_libunistring_version} is greater than
+@code{_LIBUNISTRING_VERSION}.  This can happen when you use
+@code{libunistring} as a shared library, and a newer, binary
+backward-compatible version has been installed after your program
+that uses @code{libunistring} was installed.
+
+@node Autoconf macro
+@section Autoconf macro
+
+@cindex autoconf macro
+GNU Gnulib provides an autoconf macro that test for the availability
+of @code{libunistring}.  It is contained in the Gnulib module
+@url{http://www.gnu.org/software/gnulib/MODULES.html#module=libunistring}.
+
+@amindex gl_LIBUNISTRING
+The macro is called @code{gl_LIBUNISTRING}.  It searches for an installed
+libunistring.  If found, it sets and AC_SUBSTs @code{HAVE_LIBUNISTRING=yes}
+and the @code{LIBUNISTRING} and @code{LTLIBUNISTRING} variables and augments
+the @code{CPPFLAGS} variable, and defines the C macro
+@code{HAVE_LIBUNISTRING} to 1.  Otherwise, it sets and AC_SUBSTs
+@code{HAVE_LIBUNISTRING=no} and @code{LIBUNISTRING} and @code{LTLIBUNISTRING}
+to empty.
+
+The complexities that @code{AM_ICONV} deals with are the following:
+
+@itemize @bullet
+@item
+On some operating systems, in some configurations, libunistring depends
+on @code{libiconv}, and the options for linking with libiconv must be
+mentioned explicitly on the link command line.
+
+@item
+GNU @code{libunistring}, if installed, is not necessarily already in the
+search path (@code{CPPFLAGS} for the include file search path,
+@code{LDFLAGS} for the library search path).
+
+@item
+GNU @code{libunistring}, if installed, is not necessarily already in the
+run time library search path.  To avoid the need for setting an environment
+variable like @code{LD_LIBRARY_PATH}, the macro adds the appropriate
+run time search path options to the @code{LIBUNISTRING} variable.  This works
+on most systems.
+@end itemize
+
+@node Reporting problems
+@section Reporting problems
+
+@cindex bug reports
+@cindex bug tracker
+@cindex mailing list
+If you encounter any problem, please don't hesitate to send a detailed
+bug report to the @code{bug-libunistring@@gnu.org} mailing list.  You can
+alternatively also use the bug tracker at the project page
+@url{https://savannah.gnu.org/projects/libunistring}.
+
+Please always include the version number of this library, and a short
+description of your operating system and compilation environment with
+corresponding version numbers.
+
+For problems that appear while building and installing @code{libunistring},
+for which you don't find the remedy in the @file{INSTALL} file, please include
+a description of the options that you passed to the @samp{configure} script.
+
 @node More functionality
 @chapter More advanced functionality