* Karl Berry wrote on Fri, Mar 19, 2010 at 10:42:14PM CET:
> Is the intention that even the n...@acronym{gnu} cases should be
> replaced? Then what purpose is the @acronym keyword for?
>
> I wrote about that earlier. Minor typographic change which is rarely
> used in GNU manuals.
Proposed patches for libtool. I found some cleanup when doing the
patch. I'm posting the cleanup first, since the rest is boring,
but it belongs after the other patch.
Will push soonish unless I hear complaints.
Thanks,
Ralf
Fix a couple of documentation errors.
* doc/libtool.texi (Autoconf macros): Improve hyphenation.
(Using libltdl): libltdl uses the Lesser General Public License,
not the Library General Public License.
diff --git a/doc/libtool.texi b/doc/libtool.texi
index e6d38d8..a64b8c0 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -1834,7 +1834,7 @@ GNU linker. The result is stored in the shell variable
@end defmac
@defmac LT_PATH_NM
-Try to find a BSD compatible @command{nm} or a MS compatible
+Try to find a BSD-compatible @command{nm} or a MS-compatible
@command{dumpbin} command on this machine. The result is stored in the
shell variable @samp{$NM}, which is @code{AC_SUBST}ed.
@end defmac
@@ -3705,7 +3705,7 @@ libtool's dlpreopen (see @pxref{Dlpreopening})
@end itemize
@noindent
-libltdl is licensed under the terms of the GNU Library General
+libltdl is licensed under the terms of the GNU Lesser General
Public License, with the following exception:
@quotation
Do not use @sc nor @acronym in the manual.
* doc/libtool.texi: Remove all usage of @sc.
diff --git a/doc/libtool.texi b/doc/libtool.texi
index f07eaf2..e6d38d8 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -56,11 +56,11 @@ identical to this one except for the removal of this
paragraph
Copyright @copyright{} 2009 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the @sc{gnu} Free Documentation License, Version 1.3
+under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts. A copy of the license is included in
-the section entitled "@sc{gnu} Free Documentation License".
+the section entitled "GNU Free Documentation License".
@end titlepage
@@ -75,12 +75,12 @@ the section entitled "@sc{gnu} Free Documentation License".
@comment node-name, next, previous, up
@top Shared library support for GNU
-This file documents @sc{gnu} Libtool, a script that allows package developers
+This file documents GNU Libtool, a script that allows package developers
to provide generic shared library support. This edition documents
version @value{VERSION}.
@xref{Reporting bugs}, for information on how to report problems with
-...@sc{gnu} Libtool.
+GNU Libtool.
@menu
* Introduction:: What the heck is libtool?
@@ -231,13 +231,13 @@ for each platform on which his package ran. He also had
to design a
configuration interface so that the package installer could choose what
sort of libraries were built.
-...@sc{gnu} Libtool simplifies the developer's job by encapsulating both the
+GNU Libtool simplifies the developer's job by encapsulating both the
platform-specific dependencies, and the user interface, in a single
-script. @sc{gnu} Libtool is designed so that the complete functionality of
+script. GNU Libtool is designed so that the complete functionality of
each host type is available via a generic interface, but nasty quirks
are hidden from the programmer.
-...@sc{gnu} Libtool's consistent interface is reassur...@dots{} users don't
need
+GNU Libtool's consistent interface is reassur...@dots{} users don't need
to read obscure documentation in order to have their favorite source
package build shared libraries. They just run your package
@code{configure} script (or equivalent), and libtool does all the dirty
@@ -267,18 +267,18 @@ or want to write code to extend libtool in a consistent
way.
@cindex motivation for writing libtool
@cindex design philosophy
-Since early 1995, several different @sc{gnu} developers have recognized the
+Since early 1995, several different GNU developers have recognized the
importance of having shared library support for their packages. The
primary motivation for such a change is to encourage modularity and
-reuse of code (both conceptually and physically) in @sc{gnu} programs.
+reuse of code (both conceptually and physically) in GNU programs.
-Such a demand means that the way libraries are built in @sc{gnu} packages
+Such a demand means that the way libraries are built in GNU packages
needs to be general, to allow for any library type the package installer
might want. The problem is compounded by the absence of a standard
procedure for creating shared libraries on different platforms.
The following sections outline the major issues facing shared library
-support in @sc{gnu}, and how shared library support could be standardized
+support in GNU, and how shared library support could be standardized
with libtool.
@cindex specifications for libtool
@@ -291,13 +291,13 @@ system:
The system must be as elegant as possible.
@item
-The system must be fully integrated with the @sc{gnu} Autoconf and Automake
-utilities, so that it will be easy for @sc{gnu} maintainers to use. However,
+The system must be fully integrated with the GNU Autoconf and Automake
+utilities, so that it will be easy for GNU maintainers to use. However,
the system must not require these tools, so that it can be used by
-n...@sc{gnu} packages.
+non-GNU packages.
@item
-Portability to other (n...@sc{gnu}) architectures and tools is desirable.
+Portability to other (non-GNU) architectures and tools is desirable.
@end enumerate
@node Issues
@@ -388,7 +388,7 @@ It isolates the problems and inconsistencies in library
building that
plague @file{Makefile} writers by wrapping the compiler suite on
different platforms with a consistent, powerful interface.
-With luck, libtool will be useful to and used by the @sc{gnu} community, and
+With luck, libtool will be useful to and used by the GNU community, and
that the lessons that were learned in writing it will be taken up by
designers of future library systems.
@@ -1113,9 +1113,9 @@ listing all the object files every time.
If you just want to link this convenience library into programs, then
you could just ignore libtool entirely, and use the old @command{ar} and
-...@command{ranlib} commands (or the corresponding @sc{gnu} Automake
+...@command{ranlib} commands (or the corresponding GNU Automake
@samp{_LIBRARIES} rules). You can even install a convenience library
-using @sc{gnu} Libtool, though you probably don't want to and hence @sc{gnu}
+using GNU Libtool, though you probably don't want to and hence GNU
Automake doesn't allow you to do so.
@example
@@ -1147,13 +1147,13 @@ libraries. But be careful not to link a single
convenience library,
directly or indirectly, into a single program or library, otherwise you
may get errors about symbol redefinitions.
-The key is remembering that a convenience library contains @sc{pic}
-objects, and can be linked where a list of @sc{pic} objects makes sense;
+The key is remembering that a convenience library contains PIC
+objects, and can be linked where a list of PIC objects makes sense;
i.e.@: into a shared library. A static convenience library contains
-n...@sc{pic} objects, so can be linked into an old static library, or
+non-PIC objects, so can be linked into an old static library, or
a program.
-When @sc{gnu} Automake is used, you should use @code{noinst_LTLIBRARIES}
+When GNU Automake is used, you should use @code{noinst_LTLIBRARIES}
instead of @code{lib_LTLIBRARIES} for convenience libraries, so that
the @option{-rpath} option is not passed when they are linked.
@@ -1829,12 +1829,12 @@ path to particular system commands:
@defmac LT_PATH_LD
Add a @option{--with-gnu-ld} option to @file{configure}. Try to find
the path to the linker used by @samp{$CC}, and whether it is the
-...@sc{gnu} linker. The result is stored in the shell variable
+GNU linker. The result is stored in the shell variable
@samp{$LD}, which is @code{AC_SUBST}ed.
@end defmac
@defmac LT_PATH_NM
-Try to find a @sc{bsd} compatible @command{nm} or a @sc{ms} compatible
+Try to find a BSD compatible @command{nm} or a MS compatible
@command{dumpbin} command on this machine. The result is stored in the
shell variable @samp{$NM}, which is @code{AC_SUBST}ed.
@end defmac
@@ -1852,7 +1852,7 @@ are stored in the shell variables
@samp{$enable_dlopen_self} and
@defmac LT_SYS_DLOPEN_DEPLIBS
Define the preprocessor symbol @samp{LTDL_DLOPEN_DEPLIBS} if the
-...@sc{os} needs help to load dependent libraries for @samp{dlopen} (or
+OS needs help to load dependent libraries for @samp{dlopen} (or
equivalent).
@end defmac
@@ -1896,7 +1896,7 @@ package you need to do one of the following:
@enumerate 1
@item
-Download the latest Automake distribution from your nearest @sc{gnu}
+Download the latest Automake distribution from your nearest GNU
mirror, install it, and start using it.
@item
@@ -1921,7 +1921,7 @@ libtool distribution's @file{demo} subdirectory.
First, to link a program against a libtool library, just use the
@samp{program_lda...@footnote{@c
@c
-Since @sc{gnu} Automake 1.5, the flags @option{-dlopen}
+Since GNU Automake 1.5, the flags @option{-dlopen}
or @option{-dlpreopen} (@pxref{Link mode}) can be employed with the
@var{program_LDADD} variable. Unfortunately, older releases didn't
accept these flags, so if you are stuck with an ancient Automake, we
@@ -1984,7 +1984,7 @@ However, when you distribute libtool with your own
packages
operating system that are used to compile your package.
For this reason, libtool must be @dfn{configured} before it can be
-used. This idea should be familiar to anybody who has used a @sc{gnu}
+used. This idea should be familiar to anybody who has used a GNU
@code{configure} script. @code{configure} runs a number of tests for
system features, then generates the @file{Makefile}s (and possibly a
@file{config.h} header file), after which you can run @code{make} and
@@ -2001,7 +2001,7 @@ generate a libtool script for the installer's host
machine.
@node LT_INIT
@subsection The @code{LT_INIT} macro
-If you are using @sc{gnu} Autoconf (or Automake), you should add a call to
+If you are using GNU Autoconf (or Automake), you should add a call to
@code{LT_INIT} to your @file{configure.ac} file. This macro
adds many new tests to the @code{configure} script so that the generated
libtool script will understand the characteristics of the host. It's the
@@ -2082,7 +2082,7 @@ libtool: $(LIBTOOL_DEPS)
$(SHELL) ./config.status libtool
@end example
-If you are using @sc{gnu} Automake, you can omit the assignment, as Automake
+If you are using GNU Automake, you can omit the assignment, as Automake
will take care of it. You'll obviously have to create some dependency
on @file{libtool}.
@@ -2144,12 +2144,12 @@ specifying @option{--enable-static} to
@command{configure}.
@item pic-only
Change the default behaviour for @command{libtool} to try to use only
-...@sc{pic} objects. The user may still override this default by specifying
+PIC objects. The user may still override this default by specifying
@option{--without-pic} to @command{configure}.
@item no-pic
Change the default behaviour of @command{libtool} to try to use only
-n...@sc{pic} objects. The user may still override this default by
+non-PIC objects. The user may still override this default by
specifying @option{--with-pic} to @command{configure}.
@end table
@@ -2502,7 +2502,7 @@ include libltdl/Makefile.inc
@item --quiet
@itemx -q
-Work silently. @samp{libtoolize --quiet} is used by @sc{gnu} Automake
+Work silently. @samp{libtoolize --quiet} is used by GNU Automake
to add libtool files to your package if necessary.
@item --recursive
@@ -2662,12 +2662,12 @@ you can see how libtool behaves on static-only
platforms.
You may want to put a small note in your package @file{README} to let
other developers know that @option{--disable-shared} can save them time.
-The following example note is taken from the g...@footnote{@sc{gnu} Image
+The following example note is taken from the g...@footnote{gnu Image
Manipulation Program, for those who haven't taken the plunge. See
@url{http://www.gimp.org/}.} distribution @file{README}:
@example
-The GIMP uses @sc{gnu} Libtool in order to build shared libraries on a
+The GIMP uses GNU Libtool in order to build shared libraries on a
variety of systems. While this is very nice for making usable
binaries, it can be a pain when trying to debug a program. For that
reason, compilation of shared libraries can be turned off by
@@ -2975,7 +2975,7 @@ may also be replaced by other libraries using it.
Often, people want to encode the name of the package release into the
shared library so that it is obvious to the user which package their
programs are linked against. This convention is used especially on
-...@sc{gnu}/Linux:
+GNU/Linux:
@example
trick$ @kbd{ls /usr/lib/libbfd*}
@@ -2997,7 +2997,7 @@ So, in order to accommodate both views, you can use the
@option{-release}
flag in order to set release information for libraries for which you do not
want to use @option{-version-info}. For the @file{libbfd} example, the
next release that uses libtool should be built with @samp{-release
-2.9.0}, which will produce the following files on @sc{gnu}/Linux:
+2.9.0}, which will produce the following files on GNU/Linux:
@example
trick$ @kbd{ls /usr/lib/libbfd*}
@@ -3515,7 +3515,7 @@ provide only static linkage can't even load the intrinsic
interpreter
methods. Not so! We can statically link those methods by
@strong{dlpreopening} them.
-Unfortunately, since platforms such as @sc{aix} and cygwin require
+Unfortunately, since platforms such as AIX and cygwin require
that all library symbols must be resolved at compile time, the
interpreter maintainers will need to provide a library to both its own
dlpreopened modules, and third-party modules loaded by dlopen. In
@@ -3681,7 +3681,7 @@ hiding the various difficulties of dlopening libraries
from programmers.
It consists of a few headers and small C source files that can be
distributed with applications that need dlopening functionality. On
some platforms, whose dynamic linkers are too limited for a simple
-implementation of @file{libltdl} services, it requires @sc{gnu} DLD, or it
+implementation of @file{libltdl} services, it requires GNU DLD, or it
will only emulate dynamic linking with libtool's dlpreopening mechanism.
@noindent
@@ -3699,19 +3699,19 @@ libltdl supports currently the following dynamic
linking mechanisms:
@item
@code{NSAddImage} or @code{NSLinkModule} (Darwin and Mac OS X)
@item
-...@sc{gnu} DLD (emulates dynamic linking for static libraries)
+GNU DLD (emulates dynamic linking for static libraries)
@item
libtool's dlpreopen (see @pxref{Dlpreopening})
@end itemize
@noindent
-libltdl is licensed under the terms of the @sc{gnu} Library General
+libltdl is licensed under the terms of the GNU Library General
Public License, with the following exception:
@quotation
-As a special exception to the @sc{gnu} Lesser General Public License,
+As a special exception to the GNU Lesser General Public License,
if you distribute this file as part of a program or library that
-is built using @sc{gnu} Libtool, you may include it under the same
+is built using GNU Libtool, you may include it under the same
distribution terms that you use for the rest of that program.
@end quotation
@@ -3740,7 +3740,7 @@ To use libltdl in your program you have to include the
header file @file{ltdl.h}
@noindent
The early releases of libltdl used some symbols that violated the
-...@sc{posix} namespace conventions. These symbols are now deprecated,
+POSIX namespace conventions. These symbols are now deprecated,
and have been replaced by those described here. If you have code that
relies on the old deprecated symbol names, defining
@samp{LT_NON_POSIX_NAMESPACE} before you include @file{ltdl.h} provides
@@ -3752,7 +3752,7 @@ your application in order to use this version of libltdl.
Note that libltdl is not well tested in a multithreaded environment,
though the intention is that it should work (@pxref{Thread Safety
in libltdl, , Using libltdl in a multi threaded environment}). It was
-reported that @sc{gnu}/Linux's glibc 2.0's @code{dlopen} with
+reported that GNU/Linux's glibc 2.0's @code{dlopen} with
@samp{RTLD_LAZY} (which libltdl uses by default) is not thread-safe,
but this problem is supposed to be fixed in glibc 2.1. On the other
hand, @samp{RTLD_NOW} was reported to introduce problems in
@@ -3885,7 +3885,7 @@ module loader. The @var{advise} parameter is opaque and
can only be
accessed with the functions documented below.
Note that this function does not change the content of @var{advise}, so
-unlike the other calls in this @sc{api} takes a direct @code{lt_dladvise}
+unlike the other calls in this API takes a direct @code{lt_dladvise}
type, and not a pointer to the same.
@end deftypefun
@@ -3945,7 +3945,7 @@ unresolved symbols in subsequently loaded modules.
If neither the @code{symglobal} nor the @code{symlocal} hints are set,
or if a module is loaded without using the @code{lt_dlopenadvise} call
in any case, then the visibility of the module's symbols will be as per
-the default for the underlying module loader and @sc{os}. Even if a
+the default for the underlying module loader and OS. Even if a
suitable hint is passed, not all loaders are able to act upon it in
which case @code{lt_dlgetinfo} will reveal whether the hint was actually
followed.
@@ -3963,7 +3963,7 @@ visible to subsequently loaded modules.
If neither the @code{symglobal} nor the @code{symlocal} hints are set,
or if a module is loaded without using the @code{lt_dlopenadvise} call
in any case, then the visibility of the module's symbols will be as per
-the default for the underlying module loader and @sc{os}. Even if a
+the default for the underlying module loader and OS. Even if a
suitable hint is passed, not all loaders are able to act upon it in
which case @code{lt_dlgetinfo} will reveal whether the hint was actually
followed.
@@ -4148,13 +4148,13 @@ If you wish to use libltdl in a multithreaded
environment, then you
must mutex lock around libltdl calls, since they may in turn be calling
non-thread-safe system calls on some target hosts.
-Some old releases of libtool provided a mutex locking @sc{api} that
+Some old releases of libtool provided a mutex locking API that
was unusable with POSIX threads, so callers were forced to lock around
-all libltdl @sc{api} calls anyway. That mutex locking @sc{api} was
+all libltdl API calls anyway. That mutex locking API was
next to useless, and is not present in current releases.
Some future release of libtool may provide a new POSIX thread
-compliant mutex locking @sc{api}.
+compliant mutex locking API.
@node User defined module data
@section Data associated with loaded modules
@@ -4278,7 +4278,7 @@ if no such named module has been loaded by @var{iface}.
However, you might still need to maintain your own list of loaded
module handles (in parallel with the list maintained inside libltdl)
if there were any other data that your application wanted to associate
-with each open module. Instead, you can use the following @sc{api}
+with each open module. Instead, you can use the following API
calls to do that for you. You must first obtain a unique interface id
from libltdl as described above, and subsequently always use it to
retrieve the data you stored earlier. This allows different libraries
@@ -4318,12 +4318,12 @@ Return the address of the data associated with
@var{key} and
@var{handle}, or else @code{NULL} if there is none.
@end deftypefun
-Old versions of libltdl also provided a simpler, but similar, @sc{api}
+Old versions of libltdl also provided a simpler, but similar, API
based around @code{lt_dlcaller_id}. Unfortunately, it had no
provision for detecting whether a module belonged to a particular
interface as libltdl didn't support multiple loaders in the same
-address space at that time. Those @sc{api}s are no longer supported
-as there would be no way to stop clients of the old @sc{api}s from
+address space at that time. Those APIs are no longer supported
+as there would be no way to stop clients of the old APIs from
seeing (and accidentally altering) modules loaded by other libraries.
@@ -4353,7 +4353,7 @@ already in use by libltdl's builtin loaders:
@item "dlopen"
The system dynamic library loader, if one exists.
@item "dld"
-The @sc{gnu} dld loader, if @file{libdld} was installed when libltdl was
+The GNU dld loader, if @file{libdld} was installed when libltdl was
built.
@item "dlpreload"
The loader for @code{lt_dlopen}ing of preloaded static modules.
@@ -4381,7 +4381,7 @@ level types.
@deftypefn {Type} {struct} lt_user_dlloader @{...@w{const char
*...@var{sym_prefix};} @w{lt_module_open *...@var{module_open};}
@w{lt_module_close *...@var{module_close};} @w{lt_find_sym *...@var{find_sym};}
@w{lt_dlloader_exit *...@var{dlloader_exit};} @}
If you want to define a new way to open dynamic modules, and have the
-...@code{lt_dlopen} @sc{api} use it, you need to instantiate one of these
+...@code{lt_dlopen} API use it, you need to instantiate one of these
structures and pass it to @code{lt_dlloader_add}. You can pass whatever
you like in the @var{dlloader_data} field, and it will be passed back as
the value of the first parameter to each of the functions specified in
@@ -4510,7 +4510,7 @@ Return the first loader with a matching @var{loader_name}
identifier, or else
The identifiers that may be used by libltdl itself, if the host
architecture supports them are @dfn{dlop...@footnote{this is used for
-the host dependent module loading @sc{api} -- @code{shl_load} and
+the host dependent module loading API -- @code{shl_load} and
@code{LoadLibrary} for example}, @dfn{dld} and @dfn{dlpreload}.
@example
@@ -5057,8 +5057,8 @@ shared libraries (@option{--disable-static}).
@file{demo-nofast.test} configures @file{demo/libtool} to
disable the fast-install mode (@option{--enable-fast-install=no}).
@file{demo-pic.test} configures @file{demo/libtool} to
-prefer building @sc{pic} code (@option{--with-pic}), @file{demo-nopic.test}
-to prefer n...@sc{pic} code (@option{--without-pic}).
+prefer building PIC code (@option{--with-pic}), @file{demo-nopic.test}
+to prefer non-PIC code (@option{--without-pic}).
@item demo-deplibs.test
@pindex demo-deplibs.test
@@ -5458,7 +5458,7 @@ can make changes to the libtool configuration process
without affecting
other systems.
@item man pages for @command{ld} and @command{cc}
-These generally describe what flags are used to generate @sc{pic}, to create
+These generally describe what flags are used to generate PIC, to create
shared libraries, and to link against only static libraries. You may
need to follow some cross references to find the information that is
required.
@@ -5580,7 +5580,7 @@ platforms where it claims to support shared libraries:
Note: The vendor-distributed HP-UX @command{sed}(1) programs are horribly
broken, and cannot handle libtool's requirements, so users may report
unusual problems. There is no workaround except to install a working
-...@command{sed} (such as @sc{gnu} @command{sed}) on these systems.
+...@command{sed} (such as GNU @command{sed}) on these systems.
Note: The vendor-distributed NCR MP-RAS @command{cc} programs emits
copyright on standard error that confuse tests on size of
@@ -5642,8 +5642,8 @@ IBM has online documentation at
@subsection Compilers
The only compiler characteristics that affect libtool are the flags
-needed (if any) to generate @sc{pic} objects. In general, if a C compiler
-supports certain @sc{pic} flags, then any derivative compilers support the
+needed (if any) to generate PIC objects. In general, if a C compiler
+supports certain PIC flags, then any derivative compilers support the
same flags. Until there are some noteworthy exceptions to this rule,
this section will document only C compilers.
@@ -5653,8 +5653,8 @@ of the platform:
@table @code
@item gcc
-This is the @sc{gnu} C compiler, which is also the system compiler for many
-free operating systems (FreeBSD, @sc{gnu}/Hurd, @sc{gnu}/Linux, Lites, NetBSD,
and
+This is the GNU C compiler, which is also the system compiler for many
+free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and
OpenBSD, to name a few).
The @option{-fpic} or @option{-fPIC} flags can be used to generate
@@ -5672,26 +5672,26 @@ they are bundled with:
@table @code
@item aix3*
@itemx aix4*
-Most AIX compilers have no @sc{pic} flags, since AIX (with the exception of
+Most AIX compilers have no PIC flags, since AIX (with the exception of
AIX for IA-64) runs on PowerPC and RS/6000 chips. @footnote{All code compiled
for the PowerPC and RS/6000 chips (@code{powerpc-*-*}, @code{powerpcle-*-*},
and @code{rs6000-*-*}) is position-independent, regardless of the operating
system or compiler suite. So, ``regular objects'' can be used to build
-shared libraries on these systems and no special @sc{pic} compiler flags are
+shared libraries on these systems and no special PIC compiler flags are
required.}
@item hpux10*
-Use @samp{+Z} to generate @sc{pic}.
+Use @samp{+Z} to generate PIC.
@item osf3*
-Digital/UNIX 3.x does not have @sc{pic} flags, at least not on the PowerPC
+Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC
platform.
@item solaris2*
-Use @option{-KPIC} to generate @sc{pic}.
+Use @option{-KPIC} to generate PIC.
@item sunos4*
-Use @option{-PIC} to generate @sc{pic}.
+Use @option{-PIC} to generate PIC.
@end table
@node Reloadable objects
