From 3608e8170b19ddab30c610e96e22aaef5edc0cbd Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Sun, 27 Mar 2005 12:39:17 +0000 Subject: [PATCH] * doc/automake.texi: Use @:, @., @!, and @tie{} where appropriate. --- ChangeLog | 4 ++ doc/automake.texi | 109 +++++++++++++++++++++++----------------------- doc/stamp-vti | 2 +- doc/version.texi | 2 +- 4 files changed, 61 insertions(+), 56 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3778769dd..203110340 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2005-03-27 Alexandre Duret-Lutz + + * doc/automake.texi: Use @:, @., @!, and @tie{} where appropriate. + 2005-03-16 Alexandre Duret-Lutz * lib/am/lisp.am ($(am__ELCFILES)): Do not attempt to recover diff --git a/doc/automake.texi b/doc/automake.texi index b5d2fd5a2..b9efd1388 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -253,7 +253,7 @@ Frequently Asked Questions about Automake * maintainer-mode:: missing and AM_MAINTAINER_MODE * wildcards:: Why doesn't Automake support wildcards? * distcleancheck:: Files left in build directory after distclean -* Flag Variables Ordering:: CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS +* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS * renamed objects:: Why are object files sometimes renamed? * Per-Object Flags:: How to simulate per-object flags? * Multiple Outputs:: Writing rules for tools with many output files @@ -583,9 +583,9 @@ Sometimes the standard directories---even as augmented by Automake---are not enough. In particular it is sometimes useful, for clarity, to install objects in a subdirectory of some predefined directory. To this end, Automake allows you to extend the list of -possible installation directories. A given prefix (e.g. @samp{zar}) +possible installation directories. A given prefix (e.g., @samp{zar}) is valid if a variable of the same name with @samp{dir} appended is -defined (e.g. @samp{zardir}). +defined (e.g., @samp{zardir}). @cindex HTML installation, example @@ -868,7 +868,7 @@ Here is the @file{configure.ac} from GNU Hello. in this example use a deprecated syntax. For the current approach, see the description of @code{AM_INIT_AUTOMAKE} in @ref{Public macros}. -@c FIXME: This definitely requires an update, e.g. to GNU Hello 2.1.1. +@c FIXME: This definitely requires an update, e.g., to GNU Hello 2.1.1. @example dnl Process this file with autoconf to produce a configure script. @@ -1501,7 +1501,7 @@ encompasses many macros like @code{AC_FUNC_ALLOCA}, By the way, direct assignments to @code{LIBOBJS} are no longer supported. You should always use @code{AC_LIBOBJ} for this purpose. -@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs. @code{LIBOBJS}, +@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}. @item AC_PROG_RANLIB @@ -1561,7 +1561,7 @@ Output Variables, autoconf, The Autoconf Manual}. If the Autoconf manual says that a macro calls @code{AC_SUBST} for @var{var}, or defines the output variable @var{var} then @var{var} will be defined in each @file{Makefile.in} generated by Automake. -E.g. @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so +E.g.@: @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so you can use these variables in any @file{Makefile.am} if @code{AC_PATH_XTRA} is called. @@ -1871,7 +1871,7 @@ option is intended for use by the internal automake test suite only; @file{dirlist} is useful in the following situation: suppose that @command{automake} version @code{1.6.2} is installed with -$prefix=/usr by the system vendor. Thus, the default search +@samp{--prefix=/usr} by the system vendor. Thus, the default search directories are @c @code looks better than @file here @@ -2394,15 +2394,16 @@ AM_INIT_AUTOMAKE @end example Note that if you're upgrading your @file{configure.ac} from an earlier -version of Automake, it is not always correct to simply move the package -and version arguments from @code{AM_INIT_AUTOMAKE} directly to +version of Automake, it is not always correct to simply move the +package and version arguments from @code{AM_INIT_AUTOMAKE} directly to @code{AC_INIT}, as in the example above. The first argument to -@code{AC_INIT} should be the name of your package (e.g. @samp{GNU Automake}), -not the tarball name (e.g. @samp{automake}) that you used to pass to -@code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a tarball name from -the package name, which should work for most but not all package names. -(If it doesn't work for yours, you can use the -four-argument form of @code{AC_INIT} to provide the tarball name explicitly). +@code{AC_INIT} should be the name of your package (e.g., @samp{GNU +Automake}), not the tarball name (e.g., @samp{automake}) that you used +to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a +tarball name from the package name, which should work for most but not +all package names. (If it doesn't work for yours, you can use the +four-argument form of @code{AC_INIT} to provide the tarball name +explicitly). @cindex @code{PACKAGE}, prevent definition @cindex @code{VERSION}, prevent definition @@ -2572,7 +2573,7 @@ the @code{SUBDIRS} variable. The @code{SUBDIRS} variable holds a list of subdirectories in which building of various sorts can occur. The rules for many targets -(e.g. @code{all}) in the generated @file{Makefile} will run commands +(e.g., @code{all}) in the generated @file{Makefile} will run commands both locally and in all specified subdirectories. Note that the directories listed in @code{SUBDIRS} are not required to contain @file{Makefile.am}s; only @file{Makefile}s (after configuration). @@ -2647,7 +2648,7 @@ then maybe in @file{opt/}. However @samp{make dist} should always recurse into both @file{src/} and @file{opt/}. Because @file{opt/} should be distributed even if it -is not needed in the current configuration. This means +is not needed in the current configuration. This means @file{opt/Makefile} should be created @emph{unconditionally}. There are two ways to setup a project like this. You can use Automake @@ -2657,7 +2658,7 @@ Variables, autoconf, The Autoconf Manual}). Using Automake conditionals is the preferred solution. Before we illustrate these two possibility, let's introduce @code{DIST_SUBDIRS}. -@subsection @code{SUBDIRS} vs. @code{DIST_SUBDIRS} +@subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS} @cindex @code{DIST_SUBDIRS}, explained Automake considers two sets of directories, defined by the variables @@ -2778,7 +2779,7 @@ is relevant to the discussion). The above examples all assume that every @file{Makefile} is created, even in directories that are not going to be built. The simple reason is that we want @samp{make dist} to distribute even the directories -that are not being built (e.g. platform-dependent code), hence +that are not being built (e.g., platform-dependent code), hence @file{make dist} must recurse into the subdirectory, hence this directory must be configured and appear in @code{DIST_SUBDIRS}. @@ -3547,7 +3548,7 @@ option. For libraries whose destination directory is known when Automake runs, Automake will automatically supply the appropriate @option{-rpath} -option to libtool. This is the case for libraries listed explicitly in +option to libtool. This is the case for libraries listed explicitly in some installable @code{_LTLIBRARIES} variables such as @code{lib_LTLIBRARIES}. @@ -3819,7 +3820,7 @@ the object files that libtool operates on do not necessarily end in Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, , -@code{AC_LIBOBJ} vs. @code{LIBOBJS}, autoconf, The Autoconf Manual}). +@code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}). @node Libtool Issues @subsection Common Issues Related to Libtool's Use @@ -4329,7 +4330,7 @@ Libtool libraries (where the expected object extension is @file{.lo}): @code{LTLIBOBJS} is defined automatically by Autoconf and should not be defined by hand (as in the past), however at the time of writing @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually. -@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs. @code{LIBOBJS}, +@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}. @@ -4746,7 +4747,7 @@ Automatic selection of the linker depending on which combinations of source code. @item -Automatic selection of the appropriate linker flags (e.g. @option{-L} and +Automatic selection of the appropriate linker flags (e.g., @option{-L} and @option{-l}) to pass to the automatically selected linker in order to link in the appropriate Fortran 77 intrinsic and run-time libraries. @@ -5018,7 +5019,7 @@ hand-crafted code in @file{configure} to append @samp{$U} to basenames in @code{LIBOBJS}. This is no longer true today. Starting with version 2.54, Autoconf takes care of rewriting @code{LIBOBJS} and @code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} -vs. @code{LIBOBJS}, autoconf, The Autoconf Manual}) +vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}) @node Dependencies @section Automatic dependency tracking @@ -5323,7 +5324,7 @@ they can be used to decide whether @file{foo.o} should be rebuilt. It's a different story if @file{foo.h} doesn't exist by the first @command{make} run. For instance there might be a rule to build @file{foo.h}. This time @file{file.o}'s build will fail because the -compiler can't find @file{foo.h}. @command{make} failed to trigger the +compiler can't find @file{foo.h}. @command{make} failed to trigger the rule to build @file{foo.h} first by lack of dependency information. @vindex BUILT_SOURCES @@ -5787,7 +5788,7 @@ as follows. @item PYTHON_VERSION The Python version number, in the form @var{major}.@var{minor} -(e.g. @samp{1.5}). This is currently the value of +(e.g., @samp{1.5}). This is currently the value of @samp{sys.version[:3]}. @item PYTHON_PREFIX @@ -6067,13 +6068,13 @@ subdirectory of @code{mandir}. Valid section names are the digits Sometimes developers prefer to name a man page something like @file{foo.man} in the source, and then rename it to have the correct -suffix, e.g. @file{foo.1}, when installing the file. Automake also -supports this mode. For a valid section named @var{SECTION}, there is a -corresponding directory named @samp{man@var{SECTION}dir}, and a -corresponding @code{_MANS} variable. Files listed in such a variable -are installed in the indicated section. If the file already has a -valid suffix, then it is installed as-is; otherwise the file suffix is -changed to match the section. +suffix, for example @file{foo.1}, when installing the file. Automake +also supports this mode. For a valid section named @var{SECTION}, +there is a corresponding directory named @samp{man@var{SECTION}dir}, +and a corresponding @code{_MANS} variable. Files listed in such a +variable are installed in the indicated section. If the file already +has a valid suffix, then it is installed as-is; otherwise the file +suffix is changed to match the section. For instance, consider this example: @example @@ -6180,7 +6181,7 @@ For instance @code{data_DATA} files are installed by @code{install-data}, while @code{bin_PROGRAMS} files are installed by @code{install-exec}. Any variable using a user-defined directory prefix with @samp{exec} in -the name (e.g. @code{myexecbin_PROGRAMS}) is installed by +the name (e.g., @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All other user-defined prefixes are installed by @code{install-data}. @@ -6341,7 +6342,7 @@ has a built-in list of commonly used files that are automatically included if they are found in the current directory (either physically, or as the target of a @file{Makefile.am} rule). This list is printed by @samp{automake --help}. Also, files that are read by @command{configure} -(i.e. the source files corresponding to the files specified in various +(i.e.@: the source files corresponding to the files specified in various Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are automatically distributed. Files included in @file{Makefile.am}s (using @code{include}) or in @file{configure.ac} (using @code{m4_include}), and @@ -7003,7 +7004,7 @@ Automake will complain if it sees such options in an @option{tar-v7} selects the old V7 tar format. This is the historical default. This antiquated format is understood by all tar -implementations and supports file names with up to 99 characters. When +implementations and supports file names with up to 99 characters. When given longer file names some tar implementations will diagnose the problem while other will generate broken tarballs or use non-portable extensions. Furthermore, the V7 format cannot store empty @@ -7015,7 +7016,7 @@ directories. When using this format, consider using the It fully supports empty directories. It can store file names with up to 256 characters, provided that the file name can be split at directory separator in two parts, first of them being at most 155 -bytes long. So, in most cases the maximum file name length will be +bytes long. So, in most cases the maximum file name length will be shorter than 256 characters. However you may run against broken tar implementations that incorrectly handle file names longer than 99 characters (please report them to @email{bug-automake@@gnu.org} so we @@ -7037,7 +7038,7 @@ package can still be built), but @samp{make dist} will fail. @item @var{version} @cindex Option, @var{version} -A version number (e.g. @samp{0.30}) can be specified. If Automake is not +A version number (e.g., @samp{0.30}) can be specified. If Automake is not newer than the version specified, creation of the @file{Makefile.in} will be suppressed. @@ -7743,7 +7744,7 @@ This in turns means that @samp{make distcheck} will not work, because it relies on VPATH builds. Some people can live without this (actually, many Automake users have never heard of @samp{make distcheck}). Other people may prefer to revamp the existing -@file{Makefile}s to support VPATH. Doing so does not necessarily +@file{Makefile}s to support VPATH@. Doing so does not necessarily require Automake, only Autoconf is needed (@pxref{Build Directories, , Build Directories, autoconf, The Autoconf Manual}). The necessary substitutions: @samp{@@scrdir@@}, @samp{@@top_srcdir@@}, and @@ -7883,7 +7884,7 @@ older than the requested version. Automake's programming interface is not easy to define. Basically it should include at least all @strong{documented} variables and targets that a @file{Makefile.am} author can use, any behavior associated with -them (e.g. the places where @samp{-hook}'s are run), the command line +them (e.g., the places where @samp{-hook}'s are run), the command line interface of @command{automake} and @command{aclocal}, @dots{} @heading What is not in the API @@ -7964,7 +7965,7 @@ lists. * maintainer-mode:: missing and AM_MAINTAINER_MODE * wildcards:: Why doesn't Automake support wildcards? * distcleancheck:: Files left in build directory after distclean -* Flag Variables Ordering:: CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS +* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS * renamed objects:: Why are object files sometimes renamed? * Per-Object Flags:: How to simulate per-object flags? * Multiple Outputs:: Writing rules for tools with many output files @@ -8011,7 +8012,7 @@ update, not the original timestamp of this revision. This is meant to make sure that @command{make} notices sources files have been updated. This timestamp shift is troublesome when both sources and generated -files are kept under CVS. Because CVS processes files in alphabetical +files are kept under CVS@. Because CVS processes files in alphabetical order, @file{configure.ac} will appear older than @file{configure} after a @command{cvs update} that updates both files, even if @file{configure} was newer than @file{configure.ac} when it was @@ -8062,7 +8063,7 @@ to generated files. There are several solutions to this: @itemize @item All developers should use the same versions, so that the rebuilt files -are identical to files in CVS. (This starts to be difficult when each +are identical to files in CVS@. (This starts to be difficult when each project you work on uses different versions.) @item Or people use a script to fix the timestamp after a checkout (the GCC @@ -9151,7 +9152,7 @@ Automake. @table @asis @item 1994-09-19 First CVS commit. -If we can trust the CVS repository, David J. MacKenzie (djm) started +If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started working on Automake (or AutoMake, as it was spelt then) this Monday. The first version of the @command{automake} script looks as follows. @@ -9452,7 +9453,7 @@ lasts. @item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux. -@item 1996-11-26 David J. MacKenzie releases Autoconf 2.12. +@item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12. Between June and October, the Autoconf development is almost staled. Roland McGrath has been working at the beginning of the year. David @@ -9520,7 +9521,7 @@ a better solution than @code{AM_MAINTAINER_MODE} Conditionals support was implemented by Ian Lance Taylor. At the time, Tom and Ian were working on an internal project at Cygnus. They -were using ILU, which is pretty similar to CORBA. They wanted to +were using ILU, which is pretty similar to CORBA@. They wanted to integrate ILU into their build, which was all @file{configure}-based, and Ian thought that adding conditionals to @command{automake} was simpler than doing all the work in @file{configure} (which was the @@ -9587,7 +9588,7 @@ This implements a new dependency tracking schemed that should be able to handle automatic dependency tracking using any compiler (not just gcc) and any make (not just GNU @command{make}). In addition, the new scheme should be more reliable than the old one, as -dependencies are generated on the end user's machine. Alexandre Oliva +dependencies are generated on the end user's machine. Alexandre Oliva creates depcomp for this purpose. @xref{Dependency Tracking Evolution}, for more details about the @@ -9626,7 +9627,7 @@ Akim sends a batch of 14 patches to @email{automake@@gnu.org}. @quotation Aiieeee! I was dreading the day that the Demaillator turned his -sights on automake... and now it has arrived! -- Tom Tromey +sights on automake@dots{} and now it has arrived! -- Tom Tromey @end quotation It's only the beginning: in two months he will send 192 patches. Then @@ -9672,7 +9673,7 @@ Autoconf 2.13 compatibility yet, this experimental scanner was only used when an environment variable was set, the traditional grep-scanner being still the default. -@item 2001-04-25 Gary V. Vaughan releases Libtool 1.4 +@item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4 It has been more than two years since Automake 1.4, CVS Automake has suffered lot's of heavy changes and still is not ready for release. @@ -9681,7 +9682,7 @@ Libtool 1.4 had to be distributed with a patch against Automake 1.4. @item 2001-05-08 Automake 1.4-p1 @itemx 2001-05-24 Automake 1.4-p2 -Gary V. Vaughan, the principal Libtool maintainer, makes a ``patch +Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch release'' of Automake: @quotation @@ -9875,8 +9876,8 @@ This release tries to simplify the compilation rules it outputs to reduce the size of the Makefile. The complaint initially come from the libgcj developers. Their @file{Makefile.in} generated with Automake 1.4 and custom build rules (1.4 did not support compiled -Java) is 250KB. The one generated by 1.8 was over 9MB! 1.9 gets it -down to 1.2MB. +Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it +down to 1.2MB@. Aside from this it contains mainly minor changes and bug-fixes. @@ -9952,7 +9953,7 @@ around this. @unnumberedsubsubsec Historical Note The code generated by Automake is often inspired by the -@file{Makefile} style of a particular author. In the case of the first +@file{Makefile} style of a particular author. In the case of the first implementation of dependency tracking, I believe the impetus and inspiration was Jim Meyering. (I could be mistaken. If you know otherwise feel free to correct me.) @@ -9982,7 +9983,7 @@ architecture (because it in fact would never be compiled). @itemize @item This approach also relied on the existence of @command{gcc} and GNU -@command{make}. (A limitation, not technically a bug.) +@command{make}. (A limitation, not technically a bug.) @item Dependency tracking was still done by the developer, so the problems from the first implementation relating to massaging of dependencies by diff --git a/doc/stamp-vti b/doc/stamp-vti index 7138e1a5e..b69d01527 100644 --- a/doc/stamp-vti +++ b/doc/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 5 March 2005 +@set UPDATED 27 March 2005 @set UPDATED-MONTH March 2005 @set EDITION 1.9a @set VERSION 1.9a diff --git a/doc/version.texi b/doc/version.texi index 7138e1a5e..b69d01527 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 5 March 2005 +@set UPDATED 27 March 2005 @set UPDATED-MONTH March 2005 @set EDITION 1.9a @set VERSION 1.9a -- 2.47.2