Re: doc: wrapping, categorizing, and indexing improvements.

[Ralf Wildenhues]

Hi Gary,

* Gary V. Vaughan wrote on Mon, Sep 13, 2010 at 05:24:51AM CEST:
> On 12 Sep 2010, at 21:12, Ralf Wildenhues wrote:
> > OK to push?
> 
> Okay with nits addressed.

Thanks for the review.

> > @cindex libtool libraries
> > address@hidden @samp{.la} files
> > address@hidden @file{.la} files
> > Again, the libtool control file name (@samp{.la} suffix) differs from
> 
> Why the inconsistency between @file in the cindex entry, and @samp
> in the body?

Oversight.

> > 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).
> 
> Same here: @samp{.la} vs @file{.lo}.  If you have good reason to change
> to @file, please do it everywhere.

Yep.  I skimmed through the whole file now.

> > address@hidden {const char *}lt_dlgetsearchpath (void)
> > address@hidden {const char *} lt_dlgetsearchpath (void)
> > Return the current user-defined library search path.
> > @end deftypefun
> 
> Might be nicer to split spacing fixes into a separate commit than
> @samp to @file conversions.

Indeed.  I'm thus pushing the following two patches.

Cheers,
Ralf

    docs: @file and @option markup fixes.
    
    * doc/libtool.texi (Creating object files, Linking libraries)
    (Linking executables, Link mode, Finish mode, Autoconf macros)
    (Using Automake, Inter-library dependencies, Dlpreopening)
    (Linking with dlopened modules, Finding the dlname)
    (Libltdl interface, Test descriptions, Multiple dependencies):
    Add @option where needed, replace @samp with @file as
    appropriate.

diff --git a/doc/libtool.texi b/doc/libtool.texi
index 9314612..cd9270e 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -510,11 +510,11 @@ 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
-(the PIC one lives in the @address@hidden subdirectory and the
+(the PIC one lives in the @address@hidden subdirectory and the
 static one lives in the current directory).  On systems without shared
 libraries, the PIC library object files are not created, whereas on
 systems where all code is PIC, such as AIX, the static ones are not
@@ -533,7 +533,7 @@ a23$
 @end example
 
 Note that libtool silently creates an additional control file on each
address@hidden invocation.  The @samp{.lo} file is the libtool object,
address@hidden invocation.  The @file{.lo} file is the libtool object,
 which Libtool uses to determine what object file may be built into a
 shared library.  On @samp{a23}, only static libraries are supported so
 the library objects look like this:
@@ -564,7 +564,7 @@ gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1
 burger$
 @end example
 
-Note that Libtool automatically created @address@hidden directory
+Note that Libtool automatically created @address@hidden directory
 upon its first execution, where PIC library object files will be stored.
 
 Since @samp{burger} supports shared libraries, and requires PIC
@@ -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,9 +628,9 @@ 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
-Again, the libtool control file name (@samp{.la} suffix) differs from
-the standard library name (@samp{.a} suffix).  The arguments to
address@hidden @file{.la} files
+Again, the libtool control file name (@file{.la} suffix) differs from
+the standard library name (@file{.a} suffix).  The arguments to
 libtool are the same ones you would use to produce an executable named
 @file{libhello.la} with your compiler (@pxref{Link mode}):
 
@@ -646,7 +646,7 @@ a23$
 @end example
 
 Aha!  Libtool caught a common address@hidden trying to build a library
-from standard objects instead of special @samp{.lo} object files.  This
+from standard objects instead of special @file{.lo} object files.  This
 doesn't matter so much for static libraries, but on shared library
 systems, it is of great importance.  (Note that you may replace
 @file{libhello.la} with @file{libhello.a} in which case libtool won't
@@ -700,7 +700,7 @@ make it easier to clean up the build directory, and to help 
ensure that
 other programs fail horribly if you accidentally forget to use libtool
 when you should.
 
-Again, you may want to have a look at the @samp{.la} file in order
+Again, you may want to have a look at the @file{.la} file in order
 to see what Libtool stores in it.  In particular, you will see that
 Libtool uses this file to remember the destination directory for the
 library (the argument to @option{-rpath}) as well as the dependency
@@ -742,7 +742,7 @@ burger$
 
 Libtool's way is almost the address@hidden, you should avoid using
 @option{-L} or @option{-l} flags to link against an uninstalled libtool
-library.  Just specify the relative path to the @samp{.la} file, such as
+library.  Just specify the relative path to the @file{.la} file, such as
 @file{../intl/libintl.la}.  This is a design decision to eliminate any
 ambiguity when linking against uninstalled shared libraries.}
 (@pxref{Link mode}):
@@ -1481,7 +1481,7 @@ Allow symbols from @var{output-file} to be resolved with 
@code{dlsym}
 
 @item -export-symbols @var{symfile}
 Tells the linker to export only the symbols listed in @var{symfile}.
-The symbol file should end in @samp{.sym} and must contain the name of one
+The symbol file should end in @file{.sym} and must contain the name of one
 symbol per line.  This option has no effect on some platforms.
 By default all symbols are exported.
 
@@ -1545,9 +1545,9 @@ If @var{output-file} is a library, it will eventually be 
installed in
 the run-time path of the program.  On platforms that don't support
 hardcoding library paths into executables and only search PATH for
 shared libraries, such as when @var{output-file} is a Windows (or
-other PE platform) DLL, the @samp{.la} control file will be installed in
+other PE platform) DLL, the @file{.la} control file will be installed in
 @var{libdir}, but see @option{-bindir} above for the eventual destination
-of the @samp{.dll} or other library file itself.
+of the @file{.dll} or other library file itself.
 
 @item -R @var{libdir}
 If @var{output-file} is a program, add @var{libdir} to its run-time
@@ -1616,18 +1616,18 @@ Pass a linker-specific flag directly to the linker.
 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).
+If the @var{output-file} ends in @file{.la}, then a libtool library is
+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}).
 
-If the @var{output-file} ends in @samp{.a}, then a standard library is
+If the @var{output-file} ends in @file{.a}, then a standard library is
 created using @code{ar} and possibly @code{ranlib}.
 
 @cindex partial linking
 @cindex linking, partial
-If @var{output-file} ends in @samp{.o} or @samp{.lo}, then a reloadable object
+If @var{output-file} ends in @file{.o} or @file{.lo}, then a reloadable object
 file is created from the input files (generally using @samp{ld -r}).
 This method is often called @dfn{partial linking}.
 
@@ -1736,7 +1736,7 @@ compilation environment after they were built in a 
cross-compilation
 environment.  Cross-compilation environments may rely on recent libtool
 features, and running libtool in finish mode will make it easier to
 work with older versions of libtool.  This task is performed whenever
-the @var{mode-arg} is a @samp{.la} file.
+the @var{mode-arg} is a @file{.la} file.
 
 @node Uninstall mode
 @section Uninstall mode
@@ -1875,7 +1875,7 @@ default library search path.
 Define the preprocessor symbol @samp{LT_MODULE_EXT} to the extension
 used for runtime loadable modules.  If you use libltdl to open
 modules, then you can simply use the libtool library extension,
address@hidden
address@hidden
 @end defmac
 
 @defmac LT_SYS_MODULE_PATH
@@ -1959,7 +1959,7 @@ hell_static_LDFLAGS = -static
 @end example
 
 You may use the @samp{program_LDFLAGS} variable to stuff in any flags
-you want to pass to libtool while linking @samp{program} (such as
+you want to pass to libtool while linking @file{program} (such as
 @option{-static} to avoid linking uninstalled shared libtool libraries).
 
 Building a libtool library is almost as address@hidden note the use of
@@ -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.
 
@@ -3480,7 +3480,7 @@ module opened in this way, call @var{func}.
 
 @noindent
 To open all of the modules preloaded into @file{libhell.la}
-(presumably from within the @samp{libhell.a} initialisation code):
+(presumably from within the @file{libhell.a} initialisation code):
 
 @example
 #define preloaded_symbols lt_libhell_LTX_preloaded_symbols
@@ -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.
@@ -3625,7 +3625,7 @@ Unfortunately, because of the variation in library names,
 your package needs to determine the correct file to dlopen.
 
 The most straightforward and flexible implementation is to determine the
-name at runtime, by finding the installed @samp{.la} file, and searching
+name at runtime, by finding the installed @file{.la} file, and searching
 it for the following lines:
 
 @example
@@ -3880,8 +3880,8 @@ If the file with the file name @var{filename} cannot be 
found
 libltdl tries to append the following extensions:
 
 @enumerate 1
address@hidden the libtool archive extension @samp{.la}
address@hidden the extension used for native dynamically loadable modules on 
the host platform, e.g., @samp{.so}, @samp{.sl}, etc.
address@hidden the libtool archive extension @file{.la}
address@hidden the extension used for native dynamically loadable modules on 
the host platform, e.g., @file{.so}, @file{.sl}, etc.
 @end enumerate
 
 This lookup strategy was designed to allow programs that don't
@@ -5315,7 +5315,7 @@ library works properly.
 
 @item link-2.test
 @pindex link-2.test
-This test makes sure that files ending in @samp{.lo} are never linked
+This test makes sure that files ending in @file{.lo} are never linked
 directly into a program file.
 
 @item nomode.test
@@ -5354,7 +5354,7 @@ shell scripts.
 @item suffix.test
 @pindex suffix.test
 When other programming languages are used with libtool (@pxref{Other
-languages}), the source files may end in suffixes other than @samp{.c}.
+languages}), the source files may end in suffixes other than @file{.c}.
 This test validates that libtool can handle suffixes for all the file
 types that it supports, and that it fails when the suffix is invalid.
 
@@ -5871,7 +5871,7 @@ in cases where it is necessary.
 
 On all known systems, building a static library can be accomplished by
 running @kbd{ar cru address@hidden @var{obj1}.o @var{obj2}.o @dots{}},
-where the @samp{.a} file is the output library, and each @samp{.o} file is an
+where the @file{.a} file is the output library, and each @file{.o} file is an
 object file.
 
 On all known systems, if there is a program named @command{ranlib}, then it



    doc: avoid long lines in input and output, indexing fixes.
    
    * doc/libtool.texi (Linking libraries)
    (Module loaders for libltdl): Manually line-wrap examples, to
    avoid long lines.
    (Libltdl interface, User defined module data)
    (Module loaders for libltdl): Wrap long @deftypefun input lines
    using trailing '@'.  Use @deftypefun rather than @deftp where
    appropriate, and add spaces in @deftypefun lines to fix the
    index entries generated from these lines.
    (Cheap tricks): Use @smallexample rather than @example, to avoid
    long lines.

diff --git a/doc/libtool.texi b/doc/libtool.texi
index cd9270e..a3555dc 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -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
@@ -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