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

[Gary V. Vaughan]

Hallo Ralf,

On 12 Sep 2010, at 21:12, Ralf Wildenhues wrote:
> 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.

Cool, thanks!

> OK to push?

Okay with nits addressed.

> 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

Why the inconsistency between @file in the cindex entry, and @samp
in the body?

> 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).

Same here: @samp{.la} vs @file{.lo}.  If you have good reason to change
to @file, please do it everywhere.

> 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

Might be nicer to split spacing fixes into a separate commit than
@samp to @file conversions.  The following all belong in a spacing
fixes patch I think:

> @@ -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

Cheers,
-- 
Gary V. Vaughan (address@hidden)

PGP.sig
Description: This is a digitally signed message part