doc: wrapping, categorizing, and indexing improvements.

[Ralf Wildenhues]

I paged through the PDF version of the manual looking for long lines,
and went through the index looking for markup errors and wrong entries
like '(void)' stemming from wrong number of arguments to @deftypefun
and the like: there must be a space after } in
  @deftypefun {const char *}lt_dlgetsearchpath (void)

so that lt_dlgetsearchpath gets indexed.

OK to push?

Thanks,
Ralf

    doc: wrapping, categorizing, and indexing improvements.
    
    * doc/libtool.texi (Creating object files, Linking libraries)
    (Link mode, Inter-library dependencies)
    (Linking with dlopened modules, Libltdl interface)
    (User defined module data, Module loaders for libltdl)
    (Cheap tricks): Some texinfo markup and indexing fixes, wrapping
    of long lines in input and output.

diff --git a/doc/libtool.texi b/doc/libtool.texi
index 9314612..2f30b0c 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -510,7 +510,7 @@ to the compiler to tell it to generate PIC rather than the 
standard
 position-dependent code.
 
 @cindex library object file
address@hidden @samp{.lo} files
address@hidden @file{.lo} files
 @cindex object files, library
 Since this is a library implementation detail, libtool hides the
 complexity of PIC compiler flags and uses separate library object files
@@ -585,7 +585,7 @@ pic_object='@value{objdir}/foo.o'
 non_pic_object='foo.o'
 @end example
 
address@hidden -no-suppress, libtool compile mode option
address@hidden @option{-no-suppress}, libtool compile mode option
 Notice that the second run of GCC has its output discarded.  This is
 done so that compiler warnings aren't annoyingly duplicated.  If you
 need to see both sets of warnings (you might have conditional code
@@ -628,7 +628,7 @@ shared libraries, libtool simply acts as a wrapper for the 
system
 @command{ar} (and possibly @code{ranlib}) commands.
 
 @cindex libtool libraries
address@hidden @samp{.la} files
address@hidden @file{.la} files
 Again, the libtool control file name (@samp{.la} suffix) differs from
 the standard library name (@samp{.a} suffix).  The arguments to
 libtool are the same ones you would use to produce an executable named
@@ -636,8 +636,8 @@ libtool are the same ones you would use to produce an 
executable named
 
 @example
 a23$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o}
-*** Warning: Linking the shared library libhello.la against the non-libtool
-*** objects  foo.o hello.o is not portable!
+*** Warning: Linking the shared library libhello.la against the
+*** non-libtool objects foo.o hello.o is not portable!
 ar cru .libs/libhello.a
 ranlib .libs/libhello.a
 creating libhello.la
@@ -1617,7 +1617,7 @@ Pass a link-specific flag to the compiler driver 
(@code{CC}) during linking.
 @end table
 
 If the @var{output-file} ends in @samp{.la}, then a libtool library is
-created, which must be built only from library objects (@samp{.lo} files).
+created, which must be built only from library objects (@file{.lo} files).
 The @option{-rpath} option is required.  In the current implementation,
 libtool libraries may not depend on other uninstalled libtool libraries
 (@pxref{Inter-library dependencies}).
@@ -3264,7 +3264,7 @@ library systems and simple dynamic library systems.
 Some platforms, such as AIX, do not even allow you this
 flexibility.  In order to build a shared library, it must be entirely
 self-contained (that is, have references only to symbols that are found
-in the @samp{.lo} files or the specified @samp{-l} libraries), and you
+in the @file{.lo} files or the specified @samp{-l} libraries), and you
 need to specify the @option{-no-undefined} flag.  By default, libtool
 builds only static libraries on these kinds of platforms.
 
@@ -3609,7 +3609,7 @@ intrinsics_la_LIBADD    = ../libloader/libinterface.la
         cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la
 @end example
 
address@hidden -weak option
address@hidden @option{-weak} option
 For a more complex example, see the sources of @file{libltdl} in the
 Libtool distribution, which is built with the help of the @option{-weak}
 option.
@@ -4039,7 +4039,7 @@ Replace the current user-defined library search path with
 by @code{LT_PATHSEP_CHAR}.  Return 0 on success.
 @end deftypefun
 
address@hidden {const char *}lt_dlgetsearchpath (void)
address@hidden {const char *} lt_dlgetsearchpath (void)
 Return the current user-defined library search path.
 @end deftypefun
 
@@ -4175,7 +4175,10 @@ Some of the internal information about each loaded 
module that is
 maintained by libltdl is available to the user, in the form of this
 structure:
 
address@hidden {Type} {struct} lt_dlinfo @{ @w{char address@hidden;} @w{char 
address@hidden;} @w{int @var{ref_count};} @w{int @var{is_resident};} @w{int 
@var{is_symglobal};} @w{int @var{is_symlocal};address@hidden
address@hidden {Type} {struct} lt_dlinfo @{ @w{char address@hidden;} @
+  @w{char address@hidden;} @w{int @var{ref_count};} @
+  @w{int @var{is_resident};} @w{int @var{is_symglobal};} @
+  @w{int @var{is_symlocal};address@hidden
 @code{lt_dlinfo} is used to store information about a module.
 The @var{filename} attribute is a null-terminated character string of
 the real module file name.  If the module is a libtool module then
@@ -4205,7 +4208,8 @@ The opaque type used to hold the module interface details 
for each
 registered libltdl client.
 @end deftp
 
address@hidden {Type} int lt_dlhandle_interface (@w{lt_dlhandle @var{handle},} 
@w{const char address@hidden)
address@hidden {Type} int lt_dlhandle_interface (@w{lt_dlhandle @var{handle},} @
+  @w{const char address@hidden)
 Functions of this type are called to check that a handle conforms to a
 library's expected module interface when iterating over the global
 handle list.  You should be careful to write a callback function of
@@ -4238,9 +4242,10 @@ my_interface_cb (lt_dlhandle handle, const char 
*id_string)
   return 0;
 @}
 @end example
address@hidden deftp
address@hidden deftypefn
 
address@hidden lt_dlinterface_id lt_dlinterface_register (@w{const char 
address@hidden, @w{lt_dlhandle_interface address@hidden)
address@hidden lt_dlinterface_id lt_dlinterface_register @
+  (@w{const char address@hidden, @w{lt_dlhandle_interface address@hidden)
 Use this function to register your interface validator with libltdl,
 and in return obtain a unique key to store and retrieve per-module data.
 You supply an @var{id_string} and @var{iface} so that the resulting
@@ -4253,7 +4258,9 @@ all modules will be matched.
 Release the data associated with @var{iface}.
 @end deftypefun
 
address@hidden int lt_dlhandle_map (@w{lt_dlinterface_id @var{iface}}, @w{int 
(address@hidden) (lt_dlhandle @var{handle}, void * @var{data})}, @w{void * 
@var{data}})
address@hidden int lt_dlhandle_map (@w{lt_dlinterface_id @var{iface}}, @
+  @w{int (address@hidden) (lt_dlhandle @var{handle}, void * @var{data})}, @
+  @w{void * @var{data}})
 For each module that matches @var{iface}, call the function
 @var{func}.  When writing the @var{func} callback function, the
 argument @var{handle} is the handle of a loaded module, and
@@ -4264,7 +4271,8 @@ return that non-zero value.  Otherwise 0 is eventually 
returned when
 @var{func} has been successfully called for all matching modules.
 @end deftypefun
 
address@hidden lt_dlhandle lt_dlhandle_iterate (@w{lt_dlinterface_id 
@var{iface}}, @w{lt_dlhandle @var{place}})
address@hidden lt_dlhandle lt_dlhandle_iterate (@w{lt_dlinterface_id @
+  @var{iface}}, @w{lt_dlhandle @var{place}})
 Iterate over the module handles loaded by @var{iface}, returning the
 first matching handle in the list if @var{place} is @code{NULL}, and
 the next one on subsequent calls.  If @var{place} is the last element
@@ -4455,7 +4463,8 @@ register_myloader (void)
   dlloader.dlloader_data = (lt_user_data)myloader_function;
 
   /* Add my loader as the default module loader. */
-  if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, "myloader") != 0)
+  if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader,
+                       "myloader") != 0)
     return ERROR;
 
   return OK;
@@ -4475,7 +4484,8 @@ during the initialisation phase.
 libltdl provides the following functions for writing your own module
 loaders:
 
address@hidden int lt_dlloader_add (@w{lt_dlloader address@hidden,} 
@w{lt_user_dlloader address@hidden,} @w{const char address@hidden)
address@hidden int lt_dlloader_add (@w{lt_dlloader address@hidden,} @
+  @w{lt_user_dlloader address@hidden,} @w{const char address@hidden)
 Add a new module loader to the list of all loaders, either as the
 last loader (if @var{place} is @code{NULL}), else immediately before the
 loader passed as @var{place}.  @var{loader_name} will be returned by
@@ -4504,7 +4514,7 @@ if (lt_dlloader_remove ("myloader") != 0)
 @end example
 @end deftypefun
 
address@hidden {lt_dlloader *}lt_dlloader_next (@w{lt_dlloader address@hidden)
address@hidden {lt_dlloader *} lt_dlloader_next (@w{lt_dlloader address@hidden)
 Iterate over the module loaders, returning the first loader if @var{place} is
 @code{NULL}, and the next one on subsequent calls.  The handle is for use with
 @code{lt_dlloader_add}.
@@ -4516,7 +4526,7 @@ if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) 
!= 0)
 @end example
 @end deftypefun
 
address@hidden {lt_dlloader *}lt_dlloader_find (@w{const char address@hidden)
address@hidden {lt_dlloader *} lt_dlloader_find (@w{const char address@hidden)
 Return the first loader with a matching @var{loader_name} identifier, or else
 @code{NULL}, if the identifier is not found.
 
@@ -4533,14 +4543,14 @@ if (lt_dlloader_add (lt_dlloader_find ("dlopen"), 
myloader) != 0)
 @end example
 @end deftypefun
 
address@hidden {const char *}lt_dlloader_name (@w{lt_dlloader address@hidden)
address@hidden {const char *} lt_dlloader_name (@w{lt_dlloader address@hidden)
 Return the identifying name of @var{place}, as obtained from
 @code{lt_dlloader_next} or @code{lt_dlloader_find}.  If this function fails,
 it will return @code{NULL} and set an error for retrieval with
 @code{lt_dlerror}.
 @end deftypefun
 
address@hidden {lt_user_data *}lt_dlloader_data (@w{lt_dlloader address@hidden)
address@hidden {lt_user_data *} lt_dlloader_data (@w{lt_dlloader address@hidden)
 Return the address of the @code{dlloader_data} of @var{place}, as
 obtained from @code{lt_dlloader_next} or @code{lt_dlloader_find}.  If
 this function fails, it will return @code{NULL} and set an error for
@@ -6875,7 +6885,7 @@ tree, @code{/home/src/libtool/libtool} is a libtool 
script that has been
 configured for your platform, and @code{~/bin} is a directory in your
 @env{PATH}:
 
address@hidden
address@hidden
 trick$ cd ~/bin
 trick$ sed 's%^\(macro_version=\).*$%\1@@VERSION@@%;
             s%^\(macro_revision=\).*$%\1@@package_revision@@%;
@@ -6889,7 +6899,7 @@ Copyright (C) 2010 Free Software Foundation, Inc.
 This is free software; see the source for copying conditions.  There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 trick$
address@hidden example
address@hidden smallexample
 @end itemize
 
 The output of the final @samp{libtool --version} command shows that the