Re: [PATCH 1/3] Replace 'automake' with @command{automake} where appropriate in automake.texi

[Ralf Wildenhues]

Hello William,

working my way through my patch backlog ... sorry for the long delay.

* William Pursell wrote on Thu, Dec 04, 2008 at 10:03:56AM CET:
> Ralf Wildenhues wrote:
>> * William Pursell wrote on Mon, Dec 01, 2008 at 10:06:10PM CET:
>
>>> @@ -11677,7 +11677,7 @@ A major and long-awaited release, that comes more 
>>> than two years after
>>>  @item The new dependency tracking scheme that uses @command{depcomp}.
>>>  Aside from the improvement on the dependency tracking itself
>>>  (@pxref{Dependency Tracking Evolution}), this also streamlines the use
>>> -of automake generated @file{Makefile.in}s as the @file{Makefile.in}s
>>> +of @command{automake} generated @file{Makefile.in}s as the 
>>> @file{Makefile.in}s
>>
>> I have a question here: shouldn't this be address@hidden'
>> here?  With hyphenation, in German I tend to have a good feeling about
>> when it's needed and when not, but I'm not quite sure whether those
>> rules (which I probably can't even formulate precisely) carry over to
>> English writing.
>
> As a native English speaker, I have absolutely no idea.
> I'm not even sure that English has rules. :)

Believe me, it does.  But as with standards, there are various sets of
rules to choose from, and they tend to change over time, e.g., when they
are just ignored sufficiently often.  :-)

> My intuition says that either form is grammatically
> correct, that including the hyphen is probably slightly
> more correct, and that leaving it out is slightly more
> natural.  I don't think the distinction is enough that
> anyone would notice either way.  Opinions may vary, of
> course, and it is entirely likely that I am completely
> wrong.

After reading <http://en.wikipedia.org/wiki/Hyphen> and considering
again a subscription of the Chicago Manual of Style, I am pretty sure
that hyphenation is the correct thing to do in this situation.

I have thusly pushed your patch with this change, as well as with the
comments from my previous review addressed, which was here:
<http://thread.gmane.org/gmane.comp.sysutils.automake.patches/3326/focus=3331>

Cheers, and thanks again,
Ralf

2009-03-04  William Pursell  <address@hidden>

        Replace 'automake' with @command{automake} or Automake in automake.texi
        * doc/automake.texi: Avoid bare `automake' in the manual,
        replacing occurrences with address@hidden' when the command
        is meant, and `Automake' when speaking about the software
        package in general.

diff --git a/doc/automake.texi b/doc/automake.texi
index 930b91a..450d55c 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -1867,7 +1867,7 @@ At @command{make} time, certain variables are used to 
determine which
 objects are to be built.  The variable names are made of several pieces
 that are concatenated together.
 
-The piece that tells automake what is being built is commonly called
+The piece that tells @command{automake} what is being built is commonly called
 the @dfn{primary}.  For instance, the primary @code{PROGRAMS} holds a
 list of programs that are to be compiled and linked.
 @vindex PROGRAMS
@@ -3157,9 +3157,9 @@ directories, in this order:
 
 @table @code
 @item @var{acdir-APIVERSION}
-This is where the @file{.m4} macros distributed with automake itself
-are stored.  @var{APIVERSION} depends on the automake release used;
-for automake 1.6.x, @var{APIVERSION} = @code{1.6}.
+This is where the @file{.m4} macros distributed with Automake itself
+are stored.  @var{APIVERSION} depends on the Automake release used;
+for Automake 1.6.x, @var{APIVERSION} = @code{1.6}.
 
 @item @var{acdir}
 This directory is intended for third party @file{.m4} files, and is
@@ -3193,7 +3193,7 @@ drops the @var{APIVERSION} directory.  For example, if 
one specifies
 @end enumerate
 
 This option, @option{--acdir}, is intended for use by the internal
-automake test suite only; it is not ordinarily needed by end-users.
+Automake test suite only; it is not ordinarily needed by end-users.
 
 @subsubsection Modifying the macro search path: @samp{-I @var{dir}}
 
@@ -3248,7 +3248,7 @@ If the @address@hidden option is used, then 
@command{aclocal}
 will search for the @file{dirlist} file in @var{dir}.  In the
 @samp{--acdir=/opt/private/} example above, @command{aclocal} would look
 for @file{/opt/private/dirlist}.  Again, however, the @option{--acdir}
-option is intended for use by the internal automake test suite only;
+option is intended for use by the internal Automake test suite only;
 @option{--acdir} is not ordinarily needed by end-users.
 
 @file{dirlist} is useful in the following situation: suppose that
@@ -3810,7 +3810,7 @@ choose the assembler for you (by default the C compiler) 
and set
 @acindex AM_PROG_CC_C_O
 @acindex AC_PROG_CC_C_O
 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
-the manner required by automake.  You must use this instead of
+the manner required by Automake.  You must use this instead of
 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
 using per-target flags or subdir-objects with C sources.
 
@@ -3955,7 +3955,7 @@ skip this section!
 @itemx AM_DEP_TRACK
 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
 These macros are used to implement Automake's automatic dependency
-tracking scheme.  They are called automatically by automake when
+tracking scheme.  They are called automatically by Automake when
 required, and there should be no need to invoke them manually.
 
 @item AM_MAKE_INCLUDE
@@ -5403,7 +5403,7 @@ after the source file, but other factors can change this. 
 If a file in
 the @code{_SOURCES} variable has an unrecognized extension, Automake
 will do one of two things with it.  If a suffix rule exists for turning
 files with the unrecognized extension into @file{.o} files, then
-automake will treat this file as it will any other source file
address@hidden will treat this file as it will any other source file
 (@pxref{Support for Other Languages}).  Otherwise, the file will be
 ignored as though it were a header file.
 
@@ -5653,7 +5653,7 @@ lib_LIBRARIES = libfoo.a sub/libc++.a
 would be built from @file{sub_libc___a.c}, i.e., the default source
 was the canonized name of the target, with @file{.c} appended.
 We believe the new behavior is more sensible, but for backward
-compatibility automake will use the old name if a file or a rule
+compatibility @command{automake} will use the old name if a file or a rule
 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
 
 @cindex @code{check_PROGRAMS} example
@@ -5690,7 +5690,7 @@ needs to be avoided: when a target should not be built 
from sources.
 We already saw such an example in @ref{true}; this happens when all
 the constituents of a target have already been compiled and just need
 to be combined using a @code{_LDADD} variable.  Then it is necessary
-to define an empty @code{_SOURCES} variable, so that automake does not
+to define an empty @code{_SOURCES} variable, so that @command{automake} does 
not
 compute a default.
 
 @example
@@ -6660,7 +6660,7 @@ If no directory prefix is given, the files are assumed to 
be in the
 current directory.
 
 Note that automatic de-ANSI-fication will not work when the package is
-being built for a different host architecture.  That is because automake
+being built for a different host architecture.  That is because 
@command{automake}
 currently has no way to build @command{ansi2knr} for the build machine.
 
 @c FIXME: this paragraph might be better moved to an `upgrading' section.
@@ -6783,7 +6783,7 @@ executable extensions.  For those maintainers, the 
@option{no-exeext}
 option (@pxref{Options}) will disable this feature.  This works in a
 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
 rule for a target named @code{foo} in @file{Makefile.am} will override
-an automake-generated rule for @samp{foo$(EXEEXT)}.  Without
+an @command{automake}-generated rule for @samp{foo$(EXEEXT)}.  Without
 the @option{no-exeext} option, this use will give a diagnostic.
 
 
@@ -7695,7 +7695,7 @@ the same directory as the @file{Makefile.am} file that 
lists the
 @file{.texi} files.  If you used @code{AC_CONFIG_AUX_DIR} in
 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
-there.  In both cases, automake then supplies @file{texinfo.tex} if
+there.  In both cases, @command{automake} then supplies @file{texinfo.tex} if
 @option{--add-missing} is given, and takes care of its distribution.
 However, if you set the @code{TEXINFO_TEX} variable (see below),
 it overrides the location of the file and turns off its installation
@@ -8835,7 +8835,7 @@ Do not hook @code{dist-gzip} to @code{dist}.
 If your @file{Makefile.am} defines a rule for target @code{foo}, it
 will override a rule for a target named @samp{foo$(EXEEXT)}.  This is
 necessary when @code{EXEEXT} is found to be empty.  However, by
-default automake will generate an error for this use.  The
+default @command{automake} will generate an error for this use.  The
 @option{no-exeext} option will disable this error.  This is intended for
 use only where it is known in advance that the package will not be
 ported to Windows, or any other operating system using extensions on
@@ -9211,7 +9211,7 @@ statement) is evaluated when @command{configure} is run.  
Note that you
 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
 time @command{configure} is run.  If @code{AM_CONDITIONAL} is run
 conditionally (e.g., in a shell @code{if} statement), then the result
-will confuse automake.
+will confuse @command{automake}.
 @end defmac
 
 @cindex @option{--enable-debug}, example
@@ -11500,7 +11500,7 @@ use today, i.e., @code{bin_PROGRAMS} instead of 
@code{PROGRAMS},
 @code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
 in use; and @code{TEXINFOS} and @code{MANS} still have no directory
 prefixes.)  Adding support for prefixes like that was one of the major
-ideas in automake; it has lasted pretty well.
+ideas in @command{automake}; it has lasted pretty well.
 
 AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
 Pinard's doing).
@@ -11601,7 +11601,7 @@ author (@pxref{maintainer-mode}).
 
 @item 1996-05-28 Automake 1.0
 
-After only six months of heavy development, the automake script is
+After only six months of heavy development, the @command{automake} script is
 3134 lines long, plus 973 lines of @file{Makefile} fragments.  The
 package has 30 pages of documentation, and 38 test cases.
 @file{aclocal.m4} contains 4 macros.
@@ -11822,7 +11822,7 @@ One of Akim's goal was moving all these hard-coded 
rules to separate
 Another significant contribution of Akim is the interface with the
 ``trace'' feature of Autoconf.  The way to scan @file{configure.in} at
 this time was to read the file and grep the various macro of interest
-to Automake.  Doing so could break in many unexpected ways; automake
+to Automake.  Doing so could break in many unexpected ways; @command{automake}
 could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
 where the arguments are known only when M4 is run), or conversely it
 could detect some macro that was not expanded (because it is called
@@ -11874,7 +11874,7 @@ A major and long-awaited release, that comes more than 
two years after
 @item The new dependency tracking scheme that uses @command{depcomp}.
 Aside from the improvement on the dependency tracking itself
 (@pxref{Dependency Tracking Evolution}), this also streamlines the use
-of automake generated @file{Makefile.in}s as the @file{Makefile.in}s
+of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s
 used during development are now the same as those used in
 distributions.  Before that the @file{Makefile.in}s generated for
 maintainers required GNU @command{make} and GCC, they were different
@@ -12236,7 +12236,7 @@ Java.)  This problem is easy to fix, by modifying 
dependency
 generators to record every probe, instead of every successful open.
 
 @item
-Since automake generates dependencies as a side effect of compilation,
+Since Automake generates dependencies as a side effect of compilation,
 there is a bootstrapping problem when header files are generated by
 running a program.  The problem is that, the first time the build is
 done, there is no way by default to know that the headers are