automake 1.9.5 minor doc updates

[Karl Berry]

In reading through some of the current automake manual, I found a few
small items, see diff below.  The Hello code is in flux, so I didn't
bother to update that.

Two other things I noticed I did not attempt to fix:

1)
Node: Uniform
   For instance, installation of HTML files is part of Automake, you
could use this to install raw HTML documentation:
 htmldir = $(prefix)/html
 html_DATA = automake.html

I don't understand this.  Does the user really have to define htmldir?
Isn't that defined by default now?  As written, it seems like the word
"not" is missing, ie, "HTML files is not part of Automake".

2)
Node: Public macros

I don't perceive any ordering to the macros here.  I suggest putting the
most important ones first, eg, AM_INIT_AUTOMAKE, and the obsolete ones
last -- maybe even in a separate (sub)section.

Cheers,
karl


*** /usr/local/gnu/src/automake-1.9.5/doc/ORIG/automake.texiSat Feb 12 
13:16:20 2005
--- /usr/local/gnu/src/automake-1.9.5/doc/automake.texi Sun Mar 27 16:41:09 2005
***
*** 660,664 
  
  Some @code{Makefile} variables are reserved by the GNU Coding Standards
! for the use of the ``user'' -- the person building the package.  For
  instance, @code{CFLAGS} is one such variable.
  
--- 660,664 
  
  Some @code{Makefile} variables are reserved by the GNU Coding Standards
! for the use of the ``user''---the person building the package.  For
  instance, @code{CFLAGS} is one such variable.
  
***
*** 671,675 
  any of these variables at build time.
  
! To get around this problem, automake introduces an automake-specific
  shadow variable for each user flag variable.  (Shadow variables are not
  introduced for variables like @code{CC}, where they would make no
--- 671,675 
  any of these variables at build time.
  
! To get around this problem, Automake introduces an automake-specific
  shadow variable for each user flag variable.  (Shadow variables are not
  introduced for variables like @code{CC}, where they would make no
***
*** 708,712 
  new architectures and fix probes broken by changes in new kernel
  versions.  You are encouraged to fetch the latest versions of these
! files from @url{ftp://ftp.gnu.org/gnu/config/} before making a release.
  
  @item depcomp
--- 708,714 
  new architectures and fix probes broken by changes in new kernel
  versions.  You are encouraged to fetch the latest versions of these
! files from
! @url{http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/build-aux/}
! before making a release.
  
  @item depcomp
***
*** 746,751 
  
  @item texinfo.tex
! Not a program, this file is required for @code{make dvi}, @code{make ps}
! and @code{make pdf} to work when Texinfo sources are in the package.
  
  @item ylwrap
--- 748,756 
  
  @item texinfo.tex
! Not a program, this file is required for @code{make dvi}, @code{make
! ps} and @code{make pdf} to work when Texinfo sources are in the
! package.  You are encouraged to fetch the latest version from
! @url{http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/build-aux/}
! before making a release.
  
  @item ylwrap
***
*** 840,844 
  @cindex GNU Hello, example
  
! @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
  renowned for its classic simplicity and versatility.  This section shows
  how Automake could be used with the GNU Hello package.  The examples
--- 845,849 
  @cindex GNU Hello, example
  
! @uref{http://www.gnu.org/software/hello, GNU Hello} is
  renowned for its classic simplicity and versatility.  This section shows
  how Automake could be used with the GNU Hello package.  The examples

Diff finished at Sun Mar 27 16:41:14

typos in 1.9.5 manual

[Karl Berry]

File: automake.info,  Node: Include
   Makefile fragments included this way are always distributed because
there are needed to rebuild `Makefile.in'.

there -> they

File: automake.info,  Node: Extending aclocal
... The reason we have to be stricter is that a
future implementation of `aclocal' (*note Future of aclocal::) will
have to temporary include all these third party `.m4' files

temporary -> temporarily

overriding cxxld?

[Karl Berry]

Hi folks,

Question: is it possible to override CXXLD as an environment variable (I
didn't see it in the configure scripts I looked at), or to somehow
"fake" passing it on the command line?  If not, maybe this could be
added as a new envvar?

Background: I need to link libstdc++ (but not libc, libgcc, etc.)
statically (see below).  So far, the best way I've found to do that is
to use a one-line script (say it's called cxxhack):
  exec gcc "$@" -Wl,-Bstatic -lstdc++ -Wl,-Bdynamic -lm

Normally, I think I could say configure CXXLD=cxxhack, or maybe
configure && make CXXLD=cxxhack, or some such.  Unfortunately, in my
case, I'm configuring the package that needs this as part of a much
larger product (again, see below if you care), and there is no easy way
to pass these settings down through all the levels, for various reasons
that aren't worth going into here.

If I could change the configure.ac or Makefile.am source in the
subproduct to change the setting of CXXLD in the final generated
Makefile, that would work.  I could not see how to do this.  Or maybe
there is some other different approach which would achieve the same
result.  Any advice would be appreciated ...

Thanks,
Karl

(*) Here is all the background, in case anyone has a flash of insight,
although it's not directly relevant to the question.  This is for TeX
Live (http://tug.org/texlive), which includes lcdf-typetools
(http://www.lcdf.org/~eddietwo/type), which is written in C++.  We
distribute ready-to-run binaries as part of TL.

In the past, we have dynamically linked against libstdc++, but with the
advent of gcc4 and the usual ABI incompatibility (argh) this is no
longer a good option.  If we link against libstdc++.5 compiled with
gcc3, it will not work on new/future systems where .5 is compiled with
gcc4, or perhaps not even available at all.  Debian, Red Hat, and
probably other distributions are doing this, so it's a practical
problem.  On the other hand, if we link against libstdc++.5 compiled
with gcc4, or libstdc++.6, it will not work on current/older systems.

Static linking is certainly not ideal, and may have problems
(http://www.trilithium.com/johan/2005/06/static-libstdc/), but it seems
to work out in our case, and I have been unable to think of a decent
alternative.

Re: overriding cxxld?

[Karl Berry]

if special-need; then
AC_SUBST([CXXLD], [cxxhack])
else
AC_SUBST([CXXLD], ['$(CXX)'])
fi

Thanks Stepan, that should fly.  I wasn't sure if a simple AC_SUBST
would override the default, and it is time-consuming to blindly try.

Happy hacking,
Karl

Re: Info files--declaration and distribution

[Karl Berry]

Hi Stepan,

I suggest that the info files should not be distributed by default.

Well, I strongly, strongly, disagree, and so do the GNU standards, and
GNU practice for the last 20 years.  I can't see how dropping them would
do anything but cause trouble.

Let me know if we really need to debate this :).

karl

Re: Info files--declaration and distribution

[Karl Berry]

Besides everything Eli said ...

But anyway, if you can invest a few minutes to explain me the possible
troubles, I think I could learn from it.

One concern I have is that building info files can be painful.  Usually
it is simple, but not always.  I don't think we should do anything to
imply that it is somehow "optional" to do so, or that maintainers should
leave the burden of doing so up to the users.

Best,
Karl

Re: Cygwin: texi2dvi stumbles over texinfo.tex (was: failed checks for automake 1.9.6)

[Karl Berry]

(Sorry for the delayed reply.)

| ---! /var/lib/texmf/web2c/etex.fmt was written by pdfetex
| (Fatal format file error; I'm stymied)

I believe it's a Cygwin problem and/or TeX installation problem on the
particular machine.  In essence, texi2dvi is doing this:
  echo '\input texinfo @bye' >txiversion.tex
  tex txiversion.tex

The error message from TeX means that the binary ("tex", which was
hardwired) being run is trying to load a .fmt that was written by
something else ("etex").  It has nothing to do with the contents of the
file.  I'd expect "tex story" from the command line to fail in the same
way.

Usually the solution would be to rebuild the .fmt file with the right
executable, and usually just removing the .fmt and then invoking the
binary should do that (it is able to make the .fmt automatically these
days, although I don't know if that happens with this Cygwin setup).

In this case, it is not clear to me why running "tex" is trying to read
etex.fmt (normally it would read "tex.fmt"); is Cygwin doing something
with links or shell scripts?

It is also not clear to me why PDF output works; I'd expect the same
error, since the same "tex" binary gets invoked.

I think you need to talk to whomever is responsible for the Cygwin TeX
support.  Meanwhile, I changed texi2dvi to use $TEX instead of
hardwiring "tex" in the version test.  I'm not sure if that will
actually get around this brokenness or not, but it seems desirable in
any case.  You can get it from Texinfo CVS on savannah.gnu.org if you
feel like trying it.

To reproduce, you could do this, for example:

Not surprisingly, the failure doesn't reproduce for me (the test
succeeds), since my TeX installation actually functions :).

Hope this helps,
Karl

RE: Cygwin: texi2dvi stumbles over texinfo.tex (was: failed checks for automake 1.9.6)

[Karl Berry]

  Ok, you got me curious.  How does TeX know what application wrote the file
if it's not "to do with" the contents of that file?

Sorry, I was referring to the one-line source file
\input texinfo @bye

As for the .fmt file, yes, it surely records whether tex, etex, pdfetex,
etc., was used to generate it.  Hence the error.

Ralf, what is the output if you run
  tex \\end
from the command line?  Also
  etex \\end
and
  pdfetex \\end

This is e-TeXk, Version 3.141592-2.2 (Web2C 7.5.4)

This shows that texi2dvi is invoking etex.

This is pdfeTeXk, Version 3.141592-1.21a-2.2 (Web2C 7.5.4) (INITEX)

This shows that mktexfmt is invoking pdfetex to build etex.fmt.

This mismatch is causing the error.

This is controlled by the file fmtutil.cnf.  What does that file look
like in your installation?

Re: Cygwin: texi2dvi stumbles over texinfo.tex

[Karl Berry]

This line in fmtutil.cnf indicates the problem:

etexpdfetex language.def-translate-file=cp227.tcx 
*etex.ini

Either (1) the second word should be changed to "etex", or
(2) it should be arranged for "etex" in invoke pdfetex instead of etex.
E.g., make "etex" a link to pdfetex, instead of its own binary.

We do (2) for TeX Live.

I suspect you could also work around this Cygwin configuration bug by
setting TEX=tex before running texi2dvi.

HTH,
karl

optional documentation formats and targets?

[Karl Berry]

(Sorry for the wide distribution, but I wasn't sure who would be
affected, and wanted to seek advice.)

Eric Blake from m4 (thanks Eric) asked about the coding standards:

And since dvi et. al are not invoked by 'make all', it is not
obvious whether 'make install-dvi' should depend on dvi or be a
no-op if the user didn't first do 'make dvi'.

I am inclined to say that install-DOCFMT should depend on DOCFMT.  Does
that sound ok?  ... Analogous to `install' depending on `all'.  (Doesn't
it?)  It seems that latter dependency is only implicitly stated in the
standards, but maybe that is ok.


Eric also pointed out a possible discrepancy in the coding standards
saying that not all documentation formats need be supported:

http://www.gnu.org/prep/standards/standards.html#Directory-Variables
states that for htmldir, dvidir, pdfdir, psdir, "(It is not required to
support documentation in all these formats.)".  

I am not sure why that caveat is present.  Does anyone see a problem
with simply removing the parenthetical?  I think in practice it will not
make a difference; there is no suggestion that these formats should be
included in distributions, or built by default, or anything like that.

One more related point from Eric:

dvi, html, pdf, and ps are also listed as standard make targets, but
with a caveat "Generate documentation files in the given format, if
possible."

In this case, I think the caveat is ok.  I can imagine some (unusual)
manual not making sense in, say, DVI format, because it makes extensive
use of hyperlinks or something.


Thoughts?

Thanks,
Karl

Re: Cygwin: texi2dvi stumbles over texinfo.tex

[Karl Berry]

Hi Ralf and all,

[Excluding cygwin, I doubt they care about this part.]

$ texindex ./main.au ./main.cp ./main.pg ./main.sb
Segmentation fault (core dumped)

Regrettably, with both the texindex in the released 4.8, and the
texindex from current CVS, I get no seg fault on GNU/Linux (x86).  I
have no Cygwin system, and I'm afraid the numeric stack trace doesn't
mean anything to me.  Can you run it under gdb and see where it's
crashing?

Thanks,
Karl

Re: Cygwin: texi2dvi stumbles over texinfo.tex

[Karl Berry]

the script needs to initialize IFS

Ok, I put in the initialization.  Thanks for the report & explanation.

- I don't know about the NULL_DEVICE and the path_sep setting changes

I don't either, I just do what I'm told :).  Whatever the Cygwin folks
say should be done in the Cygwin part of the code is fine, of course.
I'll attach the current system.h from Texinfo CVS.  Please let me know
if changes should be made.

Thanks,
Karl



system.h
Description: Binary data

Re: gnupload example

[Karl Berry]

I suggested changing the example to:
   --to alpha.gnu.org:gnu/automake \\

But actually I had it exactly wrong, and you had it right in the first
place.  The gnu/ must *not* be there in the filename: directive, because
the ftp-upload script on the server side puts it in.  So it should come
back out; my earlier failed upload (which is why I sent the report) must
have failed for some other reason.  (Depressing that the script no
longer bothers to send any error messages.  Sigh.)

Very sorry, Ralf, but please undo ...

Let me try another minor suggestion: perhaps it would be worth including
the url
http://www.gnu.org/prep/maintain/html_node/Automated-FTP-Uploads.html in
the --help output.

Thanks,
Karl

formatting in gnupload

[Karl Berry]

It's a trivial point, but in gnupload in CVS, I see:

for file;
do

Why the newline?  In the other cases I see in the script the "do" (or
"then") is on the same line, as in

while test -n "$1"; do

(Just wondering.)

Best,
k

Re: formatting in gnupload

[Karl Berry]

|  You may _not_ leave the `do' on the same line as `for', since some
|  shells improperly grok:
| 
|   for arg; do

How depressing that we have to uglify our sources merely to cater to a
badly broken proprietary /bin/sh.

Oh well.  Thanks for the info.

manual/html_mono/.symlinks

[Karl Berry]

We got a report on webmasters that the links
http://www.gnu.org/software/automake/manual/html_mono/autoconf.html#Particular%20Programs
http://www.gnu.org/software/automake/manual/html_mono/autoconf.html#Setting%20Output%20Variables

on
http://www.gnu.org/software/automake/manual/html_mono/automake.html#Invoking%20Automake

didn't resolve.  I know I have failed to implement a good external
cross-reference mechanism in Texinfo.  Still in the works.

As a workaround until that glorious day comes, I added a .symlinks file
in automake/manual/html_mono to try to make them resolve.  Hope that
doesn't disturb anything.

Best,
Karl

Automake mailing list link wrong

[Karl Berry]

Hello Automakers -- we received this report on webmasters,
can you dtrt please?  Thanks.

   Queue: webmasters
 Subject: Automake mailing list link wrong
   Owner: Nobody
  Requestors: nightstrike / gmail / com


On here:

http://www.gnu.org/software/automake/

There is a link called "mailing lists" which points here:
http://sources.redhat.com/automake/#lists

Which contains archives that haven't been updated in over 2 years.
The real place it should point is somewhere on lists.gnu.org.

support for lzma in automake?

[Karl Berry]

Hi folks,

Could we have a new option in automake for making lzma-compressed
tarballs, a la bzip2?  The package to use is lzma-utils, from
http://tukaani.org/lzma/.  Generally, it compresses better and
uncompresses faster than bzip.

Jim, perhaps you would like to supply a patch :)?  (Jim was the one who
instigated this.)

The compression algorithm was invented by Igor Pavlov, a Russian
programmer, and the original implementation is his 7zip package -- but
he works only on Windows, and included a small bit of non-free code for
rar format (unrelated to the actual compression algorithm).

There's also a p7zip package which ports 7zip to Unix, but it still has
the nonfree code, no configure script, and retains the, um, unique
interface of 7zip.

lzma-utils, in contrast, has removed the nonfree code, has the standard
configure && make, and has more or less the same options as gzip and
bzip2.

rms has said ok to using it on ftp.gnu.org (for example).  Sergey is
looking into supporting it in tar.

Sorry for all the background.  Just writing it down while I'm thinking
about it, really.

Thanks,
Karl

not hardwiring gpg

[Karl Berry]

Hello automakers,

Will you accept this change from Jim Meyering to gnupload?
(Until now we have copied the gnulib gnupload from automake.)

Thanks,
Karl


--- automake/lib/gnupload   2007-07-08 01:09:48.0 -0700
+++ gnulib/build-aux/gnupload   2007-12-15 06:41:32.0 -0800
@@ -25,5 +25,5 @@
 set -e
 
-GPG='/usr/bin/gpg --batch --no-tty'
+GPG='gpg --batch --no-tty'
 to=
 

-local vs. -hook?

[Karl Berry]

Reading the Extending node in the automake 1.10.1 manual:

   However, various useful targets have a `-local' version 
   ...
   Some rule also have a way to run another rule, called a "hook"

What I am missing is an explanation of the difference (from the user's
perspective.  That is, when to use install-exec-local and when
install-exec-hook?  If it doesn't matter, then I think it would be worth
saying so explicitly.

Also:
(a) "Some rule" is not grammatical here; it should be "Some rules".
(b) Shouldn't it be "Some targets also have a way to run another target"?

Thanks,
Karl

Re: slib

[Karl Berry]

There is nothing in https://savannah.gnu.org/maintenance/DownloadArea
about requesting access from administrators.  How is uploading
supposed to work?

I've never used gnupload for savannah.nongnu.org.  I can only suggest
trying to do it manually as a test; that is, sign the files, and then
run the scp or rsync or sftp commands given on the above page to
transfer the triplets.  That would tell us whether it's a savannah
problem (no permission), a documentation problem (the page isn't saying
the right thing any more), or a gnupload problem (if the direct upload
works).

Best,
k

Re: slib

[Karl Berry]

I see bug-automake is CC:ed on this message.  Is this about a bug in
gnupload, and if yes, what's the nature of the bug?

Sorry for the lack of clarity.

Aubrey is able to upload to savannah.nongnu using the direct commands
(rsync/scp/sftp), but not using gnupload.  It surprises me.  Quoting
parts of the previous messages, he ran gnupload this way and failed:

  bash-3.2$ gnupload --to [EMAIL PROTECTED]:releases/freesnell/ 
/home/jaffer/pub/FreeSnell.zip
  Signing /home/jaffer/pub/FreeSnell.zip...
  Uploading /home/jaffer/pub/FreeSnell.zip to [EMAIL 
PROTECTED]:releases/freesnell/...
  You tried to execute: scp -d -t releases/freesnell/
  Sorry, you are not allowed to execute that command.
  lost connection

But ran scp directly this way, and succeeded:

  bash-3.2$ scp FreeSnell.zip FreeSnell.zip.sig 
dl.sv.nongnu.org:/releases/freesnell/
  FreeSnell.zip 100%  585KB 292.4KB/s   00:02
  FreeSnell.zip.sig 100%  189 0.2KB/s   00:00


Thanks,
Karl

Re: -local vs. -hook?

[Karl Berry]

Well, does that half-sentence that I added above make it clearer?

Yes it does, thanks.

With -local, there is no ordering guarantee (typically they are run
early, but with parallel make, there is no way to be sure of that),

How about saying that explicitly?  It's an implication that will not be
immediately obvious to many readers.  That exact text (with the final
comma changed to a period) seems good to me.

> (b) Shouldn't it be "Some targets also have a way to run another target"?
Hmm, is that just a very nitpicky remark or does it bear some meaning

No unusual meaning, I had just managed to confuse myself.  Just ignore
it, sorry.

Thanks,
k

Re: -local vs. -hook?

[Karl Berry]

But that text is what's already in the manual!  

I don't see it.  Maybe I missed it.  If so, sorry.

Maybe you can put your suggestions in a proposed patch, so that we
can avoid misunderstanding?

The first and last hunk are unrelated tiny fixes that I just happened to
notice going through the source.  The rest adds the text about execution
order.

karl

--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -7783,7 +7783,7 @@ Automake also supports two install hooks, 
@code{install-exec-hook} and
 @code{install-data-hook}.  These hooks are run after all other install
 rules of the appropriate type, exec or data, have completed.  So, for
 instance, it is possible to perform post-installation modifications
-using an install hook.  @ref{Extending} gives some examples.
+using an install hook.  @xref{Extending}, for some examples.
 @cindex Install hook
 
 @section Staged installs
@@ -9280,23 +9280,28 @@ clean-local:
 -rm -rf testSubDir
 @end example
 
-Older version of this manual used to show how to use
[EMAIL PROTECTED] to install a file to some hard-coded
-location, but you should avoid this.  (@pxref{Hard-Coded Install Paths})
+You may be tempted to use @code{install-data-local} to install a file
+to some hard-coded location, but you should avoid this.
+(@pxref{Hard-Coded Install Paths})
+
+With the @code{-local} targets, there is no particular guarantee of
+execution order; typically, they are run early, but with parallel
+make, there is no way to be sure of that.
 
 @cindex @option{-hook} targets
 @cindex hook targets
-
-Some rules also have a way to run another rule, called a @dfn{hook},
-after their work is done.  The hook is named after the principal target,
-with @samp{-hook} appended.  The targets allowing hooks are
[EMAIL PROTECTED], @code{install-exec}, @code{uninstall}, @code{dist},
-and @code{distcheck}.
 @trindex install-data-hook
 @trindex install-exec-hook
 @trindex uninstall-hook
 @trindex dist-hook
 
+In contrast, some rules also have a way to run another rule, called a
[EMAIL PROTECTED]; these are always executed after their work is done.  The
+hook is named after the principal target, with @samp{-hook} appended.
+The targets allowing hooks are @code{install-data},
[EMAIL PROTECTED], @code{uninstall}, @code{dist}, and
[EMAIL PROTECTED]
+
 For instance, here is how to create a hard link to an installed program:
 
 @example
@@ -10883,7 +10888,7 @@ should not be concerned by such site policies: use the 
appropriate
 standard directory variable to install your files so that installer
 can easily redefine these variables to match their site conventions.
 
-Installing files that should be used by another package, is slightly
+Installing files that should be used by another package is slightly
 more involved.  Let's take an example and assume you want to install
 shared library that is a Python extension module.  If you ask Python
 where to install the library, it will answer something like this:

sections without nodes in automake manual?

[Karl Berry]

I noticed automake.texi has many sectioning commands without nodes.
Mostly but not entirely @subsub-level entries.

This is quite unusual.  It leads to some very long nodes.  Was it a
deliberate decision?  In cases like Install and Dist, I even venture to
say that it is a bug.

Anyway, if it is deliberate, the usual Texinfo style is to use the
@subsubheading (etc.) commands, instead of @subsubsection.  As is done
in the `API versioning' chapter (unlike all others that I saw).

Below is the edited output from C-u C-c C-s with the places I saw that
were potentially missing @nodes.

karl

lines matching "[EMAIL PROTECTED]>\\|[EMAIL 
PROTECTED](appendix\\(?:s\\(?:\\(?:ubs\\(?:ubs\\)?\\)?ec\\)\\)?\\|chap\\(?:heading\\|ter\\)\\|heading\\|majorheading\\|s\\(?:ection\\|ub\\(?:heading\\|s\\(?:ection\\|ub\\(?:heading\\|section\\)\\)\\)\\)\\|top\\|unnumbered\\(?:s\\(?:\\(?:ubs\\(?:ubs\\)?\\)?ec\\)\\)?\\)\\>"
 in buffer automake.texi/doc/automake/src/gnu/~.
   3061:@node Macro search path
   3062:@subsection Macro search path
   3096:@subsubsection Modifying the macro search path: 
@option{--acdir}
   3110:@subsubsection Modifying the macro search path: @samp{-I 
@var{dir}}
   3123:@subsubsection Modifying the macro search path: 
@file{dirlist}

   3979:@node Conditional Subdirectories
   3980:@section Conditional Subdirectories
   4011:@subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
   4043:@subsection Conditional subdirectories with 
@code{AM_CONDITIONAL}
   4084:@subsection Conditional Subdirectories with @code{AC_SUBST}
   4118:@subsection Non-configured Subdirectories

   4564:@node Conditional Sources
   4565:@subsection Conditional compilation of sources
   4577:@subsubsection Conditional compilation using @code{_LDADD} 
substitutions
   4615:@subsubsection Conditional compilation using Automake 
conditionals

   4650:@node Conditional Programs
   4651:@subsection Conditional compilation of programs
   4661:@subsubsection Conditional programs using 
@command{configure} substitutions
   4686:@subsubsection Conditional programs using Automake 
conditionals

   5199:@node Libtool Issues
   5200:@subsection Common Issues Related to Libtool's Use
   5202:@subsubsection @samp{required file `./ltmain.sh' not found}
   5230:@subsubsection Objects @samp{created with both libtool and 
without}

   6903:@node Built sources example
   6904:@subsection Built sources example
   6916:@unnumberedsubsec First try
   6957:@unnumberedsubsec Using @code{BUILT_SOURCES}
   7006:@unnumberedsubsec Recording dependencies manually
   7042:@unnumberedsubsec Build @file{bindir.h} from @file{configure}
   7067:@unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}.
   7087:@unnumberedsubsec Which is best?

   7703:@node Install
   7704:@chapter What Gets Installed
   7709:@section Basics of installation
   7740:@section The two parts of install
   7773:@section Extending installation
   7789:@section Staged installs
   7822:@section Rules for the user

   7901:@node Dist
   7902:@chapter What Goes in a Distribution
   7904:@section Basics of distribution
   7963:@section Fine-grained distribution control
   7985:@section The dist hook
   8035:@section Checking the distribution
   8129:@section The types of distributions

   8168:@node Tests
   8169:@chapter Support for test suites
   8177:@section Simple Tests
   8248:@section DejaGnu Tests
   8292:@section Install Tests

   8870:@node Conditionals
   8871:@chapter Conditionals
   8877:@unnumberedsec Usage
   8983:@unnumberedsec Portability
   8996:@unnumberedsec Limits

   9687:@node CVS
   9688:@section CVS and generated files
   9690:@subsection Background: distributed generated files
   9711:@subsection Background: CVS and timestamps
   9734:@subsection Living with CVS in Autoconfiscated projects
   9742:@subsubheading All files in CVS
   9808:@subsubheading Generated files out of CVS
   9834:@subsection Third-party files

   9849:@node maintainer-mode
   9850:@section @command{missing} and @code{AM_MAINTAINER_MODE}
   9852:@subsection @command{missing}
   9881:@subsection @code{AM_MAINTAINER_MODE}

  10212:@node Flag Variables Ordering
  10213:@section Flag Variables Ordering
  10234:@subsection Compile Flag Variables
  10412:@subsection Other Variables

  11726:@node Dependency Tracking Evolution
  11727:@section Dependency Tracking in Automake
  11736:@subsection First Take
  11737:@unnumberedsubsubsec Description
  11751:@unnumberedsubsubsec Bugs
  11787:@unnumberedsubsubsec Historical Note
  11795:@subsection Dependencies As S

Re: sections without nodes in automake manual?

[Karl Berry]

AIUI, the subsubheadings do not cause entries in the contents of the
PDF file.  I'm not sure I think that's better, though.  Are there
other differences I overlooked?

Not in terms of formatting, but in terms of theory and how Texinfo is
typically used -- @section and the like should always be used with a
corresponding @node; to get just a "heading" with no corresponding node,
use the @heading series.

I can go through them; 

Thanks.

do you rather propose to split into several nodes, or just use less
headings?

I think it would be better to add the @node commands (and, consequently,
@menu's also).  That would make the Info version of the manual nicer to
browse, since the nodes won't be so long.

Thanks,
karl

missing help2man

[Karl Berry]

Hi everyone,

(Automake folks: Werner sent the following to bug-texinfo.)

I've just tried to compile texinfo from the CVS; everything worked
fine until info.1 was generated -- no help2man was installed on my
system.  After fixing this, building succeeded.

However, I've observed one minor issue: After the `make' error, a file
`info.1' has been created with the contents

  .ab help2man is required to generate this page

Running `make' again after installation of help2man retained this
file, which is wrong.

I suggest that in case help2man isn't found, the dummy version of
info.1 gets removed (perhaps by adding `|| rm -f $@ && false' to the
rules using HELP2MAN).

Although I could change this in Texinfo as you suggest, it seems to me
it affects every package using help2man and there's no reason to change
Texinfo specially.

The "missing" script (which is what gets invoked when help2man is
missing) is clearly creating the target file with that .ab line
intentionally.

I believe it does so because the idea is to let potential contributors
get on with the "real" work of the package without bothering with
help2man.  If it didn't generate the target, the error message would
persist forever.  (It also hardly matters if anyone not making a release
generates the real man pages.)

And it throws the make error so the user is likely to actually see the
issue and can install help2man if they so desire.

So I'm not seeing any useful change to make here ... ?

karl

Re: missing help2man

[Karl Berry]

> Although I could change this in Texinfo as you suggest, it seems to
> me it affects every package using help2man and there's no reason to
> change Texinfo specially.

I don't think so.  The difference to other packages is probably that

Sorry, I still do.  I don't see that texinfo is doing anything different
than (say) coreutils, wrt help2man.

texinfo doesn't check the existence of help2man at configure time
which would basically the right thing to do.  

I don't think that would be the right thing to do.  We certainly don't
want help2man to be required by anyone except those building from CVS.
(And it hardly matters even for most of those; the only time it really
matters is when making a release.)

Instead, it is a
run-time requirement caused by the --enable-mainter switch.

I was not aware that --enable-maintainer-mode has anything to do with
help2man.  The reason I do that for Texinfo is simply to disable
autotool dependencies for the sake of importing Texinfo into TeX Live.
When I will remove Texinfo from TL (sometime before the next TL
release), it won't need --enable-maintainer any more.  I guess I should
take it out of the dev sources now; but I don't see how it's going to
change anything about your report.

Do you suggest to call make repeatedly until all dummy man pages
are created?  I can't believe that.

Agreed, that is bad, but I still see no better alternative.

And the result is that I get all man pages right except the
first one (which stays with the `.ab' error message).  Not a useful
behaviour IMHO.

Agreed, that is bad, but I still see no better alternative.  And it
doesn't hurt you, because you're not making a Texinfo release.

I still believe that the fix for this, if there is one, belongs in
missing and/or automake, not texinfo.

Best,
karl

Re: missing help2man

[Karl Berry]

wl> My opinion: Provide a switch to `missing' (say, `-k' or
`--keep-going', similar to the same option in `make') .  

But who's going to use it?  missing is invoked in the bowels of the
generated Makefiles when help2man is not available.  I'm not sure
there's a simple way to override it.  Maybe make HELP2MAN="missing -k".

But all this is for the case when (a) help2man is needed (ie, a
developer working from the source tree, not a release), and (b) help2man
is not available.

Wl> If help2man is found, and --enable-maintainer-mode is active, simply
delete *all* man pages before rebuilding them.

It's not clear to me how to do that.  The man page targets are normal
targets.  Adding the equivalent of rm -f $(man_MANS) before each one
doesn't seem like a good idea.  There's no way to know if help2man is
available before running missing, the way things are now.

Anyway, maintainer-mode isn't very interesting; few packages use it.
The more important question is what to do in non-maintainer mode, where
(it seems to me) exactly the same problem will occur.  For instance, in
GNU Hello (well, except that has only one man page) or coreutils.

rw> Let 'missing' not create the output file and exit 1?  Let 'missing'
create the output file and exit 0, so that all man pages will
contain the `.ab' error message?

Yes, those are the two choices I can think of too.  Neither one is very
appealing.  Definitely not the first.

rw> Maybe another way to go is to exit 0, let all man pages be created,
but at least add a `dist' hook to ensure that the packaged man pages
are not the dummy ones?

What would the dist hook do?  Remove all the man pages?

Thanks,
Karl

Re: missing help2man

[Karl Berry]

Check that none of the man pages contain the error message.  If any
do, error out with a descriptive message.

Ok, sounds good.

We could also move such a check into 'distcheck'.  That way 'dist' could
still work if you don't have help2man, only 'distcheck' wouldn't.

I think it would be best for both make dist and make distcheck to fail
if help2man is not available and those spuriously-generated man pages
somehow crept in.  That is the only time (making a distribution) that it
really matters!

Thanks,
Karl

Re: missing help2man

[Karl Berry]

I'm still wondering about whether and how to document this in the
manual.  

I think one place would be the Preparing Distributions node, explaining
that distcheck and dist will fail if `missing'-generated man pages are
present.

And perhaps the maintainer-mode node, since that is where missing is
discussed, explaining about the help2man "replacement" not failing.  (By
the way, I find it odd that that node contains two subsections, instead
of them being their own nodes.)

The only place that now talks about help2man specifically is
distcleancheck, in an example.  That doesn't seem like the right place.
I noticed a typo in that node, though:
Because we don't to force want our users to install `help2man',
"want" should be deleted.

Thanks for all your work, as always.

karl

auto-inserting COPYING

[Karl Berry]

I just learned that in some circumstances automake will insert a COPYING
file if it's missing (albeit with a warning), e.g., at make dist?  (I
didn't look into the precise details.)

I expect there's probably been plenty of discussion about it that I'm
unaware of, but to my naive eyes, this is simply a mistake.  It seems to
me that the license file of whatever sort should always be included in
the sources: http://www.gnu.org/licenses/gpl-faq.html#WhyMustIInclude.

Having automake insert it tempts people to treat it as an auto-generated
file.

If there are significant arguments for auto-inclusion of COPYING, we
should probably ask rms about it explicitly.  Unless he's already given
his blessing, in which case forget this whole thing.

Thanks,
Karl

Re: auto-inserting COPYING

[Karl Berry]

according to NEWS it was actually 
deprecated in version 1.8.

So maybe it's time to remove it, instead of adding the warning (as Ralf
so recently did)?  In this case, it seems to me the resulting
incompatibility (of not adding the file) is actually desirable because
it will force the authors relying on it to make their licensing
decisions explicit -- as they should have been in the first place.

http://lists.gnu.org/archive/html/bug-automake/2008-09/msg00035.html
in which rms shares his thoughts on the matter.

Thanks for the pointers.  But I don't see rms saying that adding a
COPYING file is ok:

rms> It occurs to me that Automake could warn about the lack rather than
rms> supply one.  Or it could ask what to do in this case.

"rather than" being the crucial phrase.  (I completely agree with Ralf
that an interactive query is not right.)

Best,
Karl

Re: auto-inserting COPYING

[Karl Berry]

I think it would make Automake less convenient, which is why I chose
against it, but that's of course only my opinion.

I think the potential for confusion outweighs by far the trivial
convenience, but that's of course only my opinion too.

And yes, the only other sane semantics IMVHO would be to let automake
fail hard in 'gnu' and 'gnits' mode if COPYING is not present.

I agree.

Adding a yes-please-copy-COPYING option does not seem sensible either.

I agree.

RMS never suggested the solution I used, but if I understood him
correctly, then he did not veto it either.  Maybe I should ask again.

Well, that would be the way to get a definitive answer (and hence your
deniability, etc., if he rejects it).  But I leave it to you whether you
want to do it, since I don't know what was said before.

I won't argue the point farther (*).  Thanks for your patience.

karl

(*) At least until the issue comes up again :).  The only reason I
brought it up now is because a savannah user wished to leave COPYING out
of his source tree, considering it a generated file because automake
inserted it.  On the savannah side of things, we just want the projects
to always have the license.  Anything else would be maddeningly
confusing.  I realize the situation with privately-held projects can be
different.

Re: sections without nodes in automake manual?

[Karl Berry]

I'm not sure I like info files where each 5-line subsubsection is a
separate node

Sure.  Splitting/lumping is always a judgement call.

+* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories

Probably a period after "vs", to match the @subsection name (and because
this manual is (primarily?) in American English rather than British
English).

+* Non-configured Subdirectories::  Not even creating a @samp{Makefile}

I think "Unconfigured" would be somewhat more idiomatic English, unless
I'm missing some subtle distinction you're making.

+* The two Parts of Install::Installing data and programs separately

two should be capitalized.

+...@node Subdirectories with AM_CONDITIONAL
+...@subsection Conditional Subdirectories with @code{AM_CONDITIONAL}

I am a fan of making the node name and sectioning name the same,
wherever possible.  Overall, this makes it easier for the reader.  I
think length of the node name is far less important.

So in this case (and the following similar cases) I would either have
the "Conditional" in both names, or neither.

+...@node Required file ltmain.sh not found
 @subsubsection @samp{required file `./ltmain.sh' not found}

Perhaps prepend the word "Error:" to both, and downcase "required" in
the @node.

@subsubsection Objects @samp{created with both libtool and without}

Why @samp?  Is this more error message text?

-...@subsection Third-party files
+...@subheading Third-party files

Files should be capitalized for consistency.  Probably something to
check throughout ...

+...@node Recommendations for Tools
 @subsection Recommendations for Tool Writers

Again I'd make the two names the same.  In this case, the two versions
even mean different things :).

+* Future Directions for Dependencies::  Languages Automake does not know
...
+...@node Future Directions for Dependencies
 @subsection Future Directions for Automake's Dependency Tracking

I think the @subsection should be made the same as @node here.
"Automake's" doesn't buy anything.

That's an unusual description in the menu, but interesting :).

For example, one thing I don't like much with the result yet is that the
introductory chapter has a section about two-part install, and its name
is very similar to the section about two-part install later.

Can you send me the whole master menu after applying changes above as
you see fit, and I'll look again?

Thanks,
Karl

Re: sections without nodes in automake manual?

[Karl Berry]

   * Unfortunately, you cannot use periods, commas, colons or
 parentheses within a node name; these confuse the Texinfo
 processors.  Perhaps this limitation will be removed some day, too.

Oh yeah :).

Well, the situation is that in practice, periods only cause trouble in
unusual circumstances.  Like a cross-manual reference to the node from
another manual?  And even then it often works.  To be honest, I don't
remember the exact problematic case(s).

Colons, on the other hand, are definitely troublesome, even in regular
menus they can break.

So, you're right, probably best to leave the punctuation out of the node
names.  None of this behavior has changed since the inception of
Texinfo, by the way.

| * Future Directions for Dependencies::  Languages Automake does not know
What is unusual about it?

Just that "languages" and "dependencies" sound like quite different
things, even though they're not in this case, exactly.  I think it's ok.

Thanks, here you go.

Nothing jumped out at me.  What were the "close" introductory names you
were concerned about?


All I noticed were several that need capitalization fixes:

* Length limitations::  Staying below the command line length limit
* Macro search path::   How aclocal finds .m4 files
* Public macros::   Macros that you can use.
* Obsolete macros:: Macros that you should stop using.
* Private macros::  Macros that you should not use.
* Program variables::   Variables used when building a program
* Built sources example::   Several ways to handle built sources.

Maybe something like grep '^...@node .* [a-z]' would help for a quick
check.  (It'll get false matches too, but anyway.)

Thanks,
Karl

Re: dvi, pdf rules: incorrect invocation of texi2dvi, texi2pdf

[Karl Berry]

  env TEXINPUTS=../build-aux::/...

Certainly that is wrong.  Thanks for the patch.

For automake, the workaround is simple: Add a -I option always, for example
'-I .'. The texi2dvi bug occurs only if no -I options are passed.

1) It seems to me that -I . could have undesired effects.  The run
   doesn't necessarily want . first.  -I /uglyworkarounddir would be
   safer, seems to me.

2) Do we really want to enshrine a workaround forever in automake
   against one particular version of texi2dvi?  Seems ugly.

Ralf, you asked how long -I has been around.  Looking at the news file,
it seems the answer is, texinfo 4.0, released in September 1999.
Its implementation, like texi2dvi itself, has grown more and more
complex over the years, but the option has always been there.

And, you asked whether -I is the "official" way to do it now.  No.
Nothing has changed in this regard.  TEXINPUTS has always been supported
in TeX and always will be.  Anything that could supposedly substitute
for texi2dvi/texi2pdf (I am not aware of anything) would have to
understand both TEXINPUTS and -I or it would be unusable.

install-local target?

[Karl Berry]

1) In the Extending node of the automake (1.10.2) manual, there's a typo:

now: respected by `automake' to ensure the user always have the last word.
new: respected by `automake' to ensure the user always has the last word.

   Also, it might be clearer to make each of the following two sentences
   into an @item.


2) Anyway, what I'm really writing about is ... I gather there is no
   install-local target.  Or any other way to run additional commands at
   install time, after install-exec and install-data have run.
   
   The usefulness is to run a post-install command installed by
   install-exec, using data installed by install-data.  I need to do
   this in the TeX tree.
   
   I worked around it by using a different rule that depends on install,
   which is fine, so this isn't make-or-break or anything.  I just
   wanted to suggest it.  Or is there another way to accomplish it?
   I guess install: could be made into a double-colon target, but
   that doesn't exactly seem right either.

Thanks,
Karl

debugging feature for recursive rules

[Karl Berry]

I have found myself needing to go through the complicated shell
sequence for the $(RECURSIVE_TARGETS) rule more than once when debugging
the Makefile.am's in a big directory tree (namely TeX Live).  Typically
I get a mysterious "*** failed", exit status 1, and there's no easy way
to know which command failed.

I'd like to suggest that that initial silencing "@" become a variable,
say RECURSIVE_TARGET_VERBOSE.  Of course the default would still be @,
but then it could easily be overridden with, say, "set -vx;", to at least help
narrow down the point of failure.

Wdyt?

Thanks,
Karl

comment after trailing backslash inconsistent warning

[Karl Berry]

automake 1.10.2 complains about "comment after trailing backslash"
sometimes, but not every time.  In the appended Makefile.am, I get 
Makefile.am:23: comment following trailing backslash
which is true enough, but there are also comments after trailing
backslashes at line 124 and line 108.  And if I delete the one at line
23, it still does not complain about the others.

Perhaps it's some subtle portability issue I do not know, but I thought
I'd report it.

Also, I don't want that message at all.  Can/Should it be turned off?
It is useful to have lists with a trailing \ on each line for the usual
separator vs. terminator reasons.  In my case, the whole tree requires a
pretty new GNU make anyway, so I assume whatever portability issue is
being warned about does not apply.  At least I've never seen any problem
with the generated files.

Thanks,
Karl

Re: debugging feature for recursive rules

[Karl Berry]

Try `make SHELL="/bin/bash -vx"', that should help for all rules that

Good suggestion.  Perhaps it should be added to the manual, if you
didn't already.

Thanks,
Karl

Re: install-local target?

[Karl Berry]

Hi Ralf,

maybe install-hook would be better,

Sure.

- It isn't clear to me what should happen if the user typed
  make install-data
or
  make install-exec
only.  Letting the hook run after one of them only seems clearly wrong.

Yes, that would be wrong.

Not running it at all would require some sort of `post-install' target

Sorry, I don't understand all these complications.  I didn't intend you
to go down any of those roads.  I was thinking of something simple:

install: install-data install-exec
$(MAKE) install-hook

Or it could be a variable:

install: install-data install-exec
$(POST_INSTALL_HOOK)

Can you work around it (or have already done so) 

I worked around it by adding the rules to a different top-level target
("world"), which my TeX builders are accustomed to using anyway.  This
is suboptimal.

by simply adding
install-{data,exec}-local 

I don't see how I can use install-{data,exec}-local to accomplish this.
The command has to run once, after both install-data and install-exec
have finished.

It's certainly not the end of the world if it seems too complicated to
you for any reason.

Thanks,
Karl

Re: debugging feature for recursive rules

[Karl Berry]

Very good.  Minor comments:

 * Hard-Coded Install Paths::Installing to Hard-Coded Locations

Wrong capitalization in the menu description this time, should be
"hard-coded locations".

+don't work as expected.  Besides debug options provided by the

Suggest inserting "the" after "Besides".

+it.  Note however, that this will execute commands prefixed with

it. However, this will @emph{still execute} commands prefixed with

Re: install-local target?

[Karl Berry]

you still need to specifically document something like this for users of
your package:

Good point.  The issue doesn't actually arise in my particular case, but
it would if we made a general feature.

is it possible for your package to just use the uninstalled programs
for this post-installation action, and hook things into
install-data-hook?  

Hmm, maybe.  I should certainly try that before changing anything in
Automake.

Also, what does your current workaround do if
the user uses $(DESTDIR) at `make install' time, or overwrites
prefix (as in `make install prefix=/tmp/dest') temporarily?

Probably fails completely.

to get a feeling for how important and realistic an example this is.

Well, it's "realistic" in the sense that it does exist in the real world,
but it's not "important" in the sense that it's widely needed
(obviously).

We shouldn't add to the Automake API without good need.

Agreed.  Let's forget the whole thing.  Thanks for putting up with my
persistence.

Re: comment after trailing backslash inconsistent warning

[Karl Berry]

There is no appendix to your message.

As usual :).

The line numbers are probably off now since I made more
changes since sending the message, but the essential point is that it
complains about \
#
at the end of man1_MANS definition (it is not present below), but does
not complain about the same at the end of EXTRA_DIST (twice).

IIRC there is some portability issue connected with this, 

No doubt.  I doubt the portability issue, whatever it is, relevant to my
source, but I won't put you to the trouble of looking it up.  It seems
better to just put up with the lack of a final \ than introduce
something in Automake to conditionally silence the warning.

Thanks,
karl


##
OS = UNIX
PAPER = a4
CHMOD = chmod
BINMODE = +x

AM_CPPFLAGS = -DUNIX -DPAPER=\"$(PAPER)\"

bin_PROGRAMS = epsffit psbook psnup psresize psselect pstops
bin_SCRIPTS = getafm showchar \
  extractres fixdlsrps fixfmps fixmacps fixpsditps fixpspps \
  fixscribeps fixtpps fixwfwps fixwpps fixwwps includeres psmerge
CLEANFILES = $(bin_SCRIPTS)

PERL = /usr/bin/env perl
MAKETEXT = $(PERL) $(srcdir)/maketext

man1_MANS = epsffit.1 psbook.1 psnup.1 psresize.1 psselect.1 pstops.1 \
getafm.1 \
extractres.1 fixdlsrps.man fixfmps.man fixmacps.man \
fixpsditps.man fixpspps.man fixscribeps.man fixtpps.man \
fixwfwps.man fixwpps.man fixwwps.man includeres.man psmerge.man
dist_man_MANS = $(man1_MANS)

%: %.pl
$(MAKETEXT) OS=$(OS) PERL="$(PERL)" $< >$@

%: %.sh
cp $< $@
$(CHMOD) $(BINMODE) $@

%.1: %.man
$(MAKETEXT) PAPER=$(PAPER) "MAN=$(man1_MANS)" $< >$@

epsffit_SOURCES = \
config.h \
epsffit.c \
pserror.c \
pserror.h

psbook_SOURCES = \
config.h \
psbook.c \
pserror.c \
pserror.h \
psutil.c \
psutil.h

psnup_SOURCES = \
config.h \
pserror.c \
pserror.h \
psnup.c \
psspec.c \
psspec.h \
psutil.c \
psutil.h

psresize_SOURCES = \
config.h \
pserror.c \
pserror.h \
psresize.c \
psspec.c \
psspec.h \
psutil.c \
psutil.h

psselect_SOURCES = \
config.h \
pserror.c \
pserror.h \
psselect.c \
psutil.c \
psutil.h

pstops_SOURCES = \
pserror.c \
pserror.h \
psspec.c \
psspec.h \
pstops.c \
psutil.c \
psutil.h

## 
EXTRA_DIST = \
LICENSE

# scripts.
EXTRA_DIST += \
getafm.sh \
showchar.sh \
extractres.pl \
fixdlsrps.pl \
fixfmps.pl \
fixmacps.pl \
fixpsditps.pl \
fixpspps.pl \
fixscribeps.pl \
fixtpps.pl \
fixwfwps.pl \
fixwpps.pl \
fixwwps.pl \
includeres.pl \
psmerge.pl \
#

## Not used
##
EXTRA_DIST += \
Makefile.bcc \
Makefile.msc \
Makefile.nt \
Makefile.os2 \
Makefile.sc \
Makefile.unix \
Makefile.wat \
descrip.mms \
maketext \
md68_0.ps \
md71_0.ps \
#

## Eventually delete these files
##
EXTRA_DIST += Makefile.in.orig configure.in.orig

Re: texi2dvi ignores -o under unclear circumstances.

[Karl Berry]

Hi Jack,

Thanks for the report.

Running texi2dvi -o doc/foo.dvi doc/foo.texi causes a copy of foo.dvi

Akim, are you around now?  Can you look into this?
(I am drowning just now after two weeks away.)

Thanks,
Karl

gnupload --help examples

[Karl Berry]

More about gnupload --help.

First, all the existing examples in gnupload --help use automake 1.8.2b.
This isn't either of rms' recommended version number schemes for test
releases.  Would you agree to changing to something generic, like
foobar-0.9.90?  I'm happy to send a patch if you like, although of
course it is a trivial text change.

Second, I don't understand the point of having both examples 2 and 3.
If I am maintaining foo-latest symlinks, then surely I would want them
for all releases on all sites.  So how about just dropping #2?  I also
don't understand (from the help message) why #3 accomplishes this and #2
doesn't.

For reference, here are the two examples:

2. Same as above, but also create symbolic links to automake-latest.tar.*:
  gnupload --to sources.redhat.com:~ftp/pub/automake \\
   --to alpha.gnu.org:automake \\
   --symlink-regex \\
   automake-1.8.2b.tar.gz automake-1.8.2b.tar.bz2

3. Symlink automake-1.8.2b.tar.gz to automake-latest.tar.gz and
automake-1.8.2b.tar.bz2 to automake-latest.tar.bz2 on both sites:

  gnupload --to sources.redhat.com:~ftp/pub/automake \\
   --to alpha.gnu.org:automake \\
   --symlink automake-1.8.2b.tar.gz automake-latest.tar.gz \\
 automake-1.8.2b.tar.bz2 automake-latest.tar.bz2


Thanks,
Karl

Re: gnupload --help examples

[Karl Berry]

Sure.  These numbers were real Automake versions though, 

I know.

want to genericize the package name as well?

Yep, that's what I meant to suggest.

--symlink also allows you to pass target names other than
*-latest.tar.gz I guess, so #2 shows how --symlink-regex works while
#3 shows how --symlink works?

I see.  But since the examples are equivalent, it's not a very
interesting thing to show for --symlink.  I think the examples should be
practical, not theoretical.

I guess I don't see the point in explaining --symlink, since
--symlink-regex already does what's desired, if symlinks are desired at
all.  It's not like we are duty-bound to show an example for every
option.  There are plenty of options already without examples.

Also, I think that a separate example should show uploading multiple
formats, instead of throwing it in with all the test uploads.  In
general, I think all the examples should try to show just one new thing,
not many things mixed together.

I altered the last example to be about a mistaken upload, instead of
retiring an existing release.  In general, it seems to me that we don't
want to suggest that it's a good idea to delete test (or any) releases.
I also didn't see any purpose to the "--" here, so I removed it.

  0. Upload foobar-1.0.tar.gz to ftp.gnu.org:gnu/foobar
gnupload --to ftp.gnu.org:foobar foobar-1.0.tar.gz

Indeed, just goes to show why simple examples, and testing, are needed :).

Feel free to propose a patch that makes this more clear.  

See below for my new text.  If you want a patch instead, that's fine, I
just thought this would be easier to read.

If you know of a painless way to test these options, then I'm all
ears.  I'm a big fan of testing all code.

I know of no easy (or even not so easy) way to test anything related to
ftp uploads, especially not with hypothetical package names and versions :(.
I think this is one case where you just have to take it
on faith/inspection and let users report the problems when they actually
try to instantiate them.

Thanks,
k

--
1. Upload foobar-1.0.tar.gz to ftp.gnu.org:
  gnupload --to ftp.gnu.org:foobar foobar-1.0.tar.gz

2. Upload foobar-1.0.tar.gz and foobar-1.0.tar.xz to ftp.gnu.org:
  gnupload --to ftp.gnu.org:foobar foobar-1.0.tar.gz foobar-1.0.tar.xz

3. Same as above, and also create symbolic links to foobar-latest.tar.*:
  gnupload --to ftp.gnu.org:foobar \\
   --symlink-regex \\
   foobar-1.0.tar.gz foobar-1.0.tar.xz

4. Upload foobar-0.9.90.tar.gz to two sites:
  gnupload --to alpha.gnu.org:foobar \\
   --to sources.redhat.com:~ftp/pub/foobar \\
   foobar-0.9.90.tar.gz

5. Delete oopsbar-0.9.91.tar.gz and upload foobar-0.9.91.tar.gz:
  gnupload --to alpha.gnu.org:foobar \\
   --to sources.redhat.com:~ftp/pub/foobar \\
   --delete oopsbar-0.9.91.tar.gz \\
   foobar-0.9.91.tar.gz

Re: gnupload --help examples

[Karl Berry]

Erm, the --rmsymlink and --delete options work on all remaining files up
to the net --rmsymlink, --delete, or -- option.  So that -- really needs
to be there.  Or we need to change the semantics of these optinos.

Ok, my mistake.  I think that should be pointed out explicitly.
(See below.)

Kind of thinking that all GNU developers should
be able to test upload functionality there.

That would be ideal, but it seems like a major departure from the way
uploads work now.  I don't want to ask the FSF sysadmins to devote time
to such an idea.

However, it occurs to me that we can ask Sergey if he could easily set
up such a thing at his hosting site.  I'll do that.

Almost anything can be tested.  

True enough, but in this case it would require creating an ersatz
package foobar with "maintainers" being everyone who wants to test,
which all seems like a time-consuming pain to me.  I'd rather not.

It's more of a question whether the work required to actually make
it work exceeds the potential benefits.

Indeed.  Anyway, let's not wait to push the new help message, ok?

By the way, is there any documentation anywhere beyond the help message?
(I'm not volunteering, just wondering. :)

Thanks,
k

--
1. Upload foobar-1.0.tar.gz to ftp.gnu.org:
  gnupload --to ftp.gnu.org:foobar foobar-1.0.tar.gz

2. Upload foobar-1.0.tar.gz and foobar-1.0.tar.xz to ftp.gnu.org:
  gnupload --to ftp.gnu.org:foobar foobar-1.0.tar.gz foobar-1.0.tar.xz

3. Same as above, and also create symbolic links to foobar-latest.tar.*:
  gnupload --to ftp.gnu.org:foobar \\
   --symlink-regex \\
   foobar-1.0.tar.gz foobar-1.0.tar.xz

4. Upload foobar-0.9.90.tar.gz to two sites:
  gnupload --to alpha.gnu.org:foobar \\
   --to sources.redhat.com:~ftp/pub/foobar \\
   foobar-0.9.90.tar.gz

5. Delete oopsbar-0.9.91.tar.gz and upload foobar-0.9.91.tar.gz
   (the -- terminates the list of files to delete):
  gnupload --to alpha.gnu.org:foobar \\
   --to sources.redhat.com:~ftp/pub/foobar \\
   --delete oopsbar-0.9.91.tar.gz \\
   -- foobar-0.9.91.tar.gz

automake.texi and @acronym

[Karl Berry]

It seems wrong to use @acronym{GNU} three times in the @copying text,
when it isn't used in many more places -- including one other place in
@copying.

Personally, I'd just eliminate all uses of @acronym instead of trying to
keep it consistent.  Few GNU manuals use it.

karl

Re: automake.texi and @acronym

[Karl Berry]

The texinfo manual even uses @acronym{GNU} as
example.

It's an example of how to use a Texinfo command.  It doesn't necessarily
mean that GNU manuals should use it.  There are plenty of Texinfo
commands which are there for "alternatives".

Do you have a rationale for eliminating @acronym?

I've very very rarely seen it used in other GNU manuals.  The Texinfo
manual itself, for example, doesn't (aside from the description of the
command itself).  Emacs and GCC don't (last time I looked).  Etc.

Also, simplicity argues to remove it.  Do we really want hundreds of
'@acronym{GNU}"s scattered everywhere?  Yuck.

You might ask, why does it exist at all.  The answer is, in non-GNU
manuals, I sometimes wanted to print all-caps words in one point size
smaller type, which is a common typographical refinement.  However, GNU
manuals don't do this.

So I vote for the color "invisible" :).

Best,
Karl

Re: automake.texi and @acronym

[Karl Berry]

I'm okay with changing the m4 and autoconf manuals with
s/@acronym{GNU}/GNU/ 

s/@acronym{(.*)}/\1/ 

if we agree that it is easier to maintain, 

Is to me.

and doesn't buy much typographically.

I think having the (minor) benefit of consistency between GNU manuals
outweighs the (minor) typographic refinement.

Re: automake.texi and @acronym

[Karl Berry]

What about @sc{gnu}, which also appears in some but not all GNU manuals?

In terms of "logical" markup, @sc should definitely not be used.

Typographically, I greatly dislike it (in running text) as well.

Is there any difference between @acronym and @sc?

Yes.  @sc is small caps (=x-height size), @acronym is one-point-size
smaller.

Re: automake.texi and @acronym

[Karl Berry]

Hi Simon,

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.  De facto standard is not to use it.  Which is
also simpler in the source.  To try to use it consistently/everywhere
leads into deep waters (I have to do this in my TeX editorial life,
and it is exceedingly time-consuming).  And it can't be used in node
names in any case, so there will always be inconsistencies.  Do we
have to keep going with this?

The automake manual contains the uses below.  The hits in fdl.texi seems
problematic to me...

I didn't realize that fdl.texi used it.  I might be able to get that
changed, but I don't see that as a barrier to getting rid of it
everywhere else, anyway.  No one reads fdl.texi, or expects perfect
consistency with the rest of a manual, anyway.  For instance, its
formatting of its "sections" is idiosyncratic, to say the least.  And
no, I don't want to go down that road, either.

k

bug#7766: (lack of) config.h description in manual

[Karl Berry]

Hi Ralf and all,

A new GNU maintainer just asked me about how to use $(pkgdatadir) from
his C program.  I looked at the Automake manual and didn't see anywhere
especially good to point him at :(.  A couple thoughts I had as a result
of looking at this for him:

First, tiny English point in node Optional:
< As for `AC_CONFIG_FILES' (*note Requirements::), parts of the
> As with ...

The main point: although "amhello Explained" talks about
AC_CONFIG_HEADERS and gives a partial example, I don't see any "real"
description of how to determine what ends up in config.h and what the
#define names are.  If I'm not just missing something, I suggest a new
node, perhaps under "Generalities", which talks about Automake/C
linkage, including autoheader, etc.

The apparent reference definition for AC_CONFIG_HEADERS (in node
"Optional") says nothing about what it really does.

It belatedly occurs to me that perhaps this topic is gone into in more
detail in the Autoconf manual.  I don't have the energy to search
through it now, but if that is so, at least a cross-reference to that
would be nice.  (FWIW, I looked at all occurrences of config\.h and
CONFIG_HEADERS in the automake manual.)


Subsidiary points: in the general index (I continue to very strongly
encourage you to merge all indexes, BTW), I didn't find anything useful
for "preprocessor", or "#define", or "config.h", or anything else I
could think of.  Fortran preprocessing was the only thing.

Finally, the "amhello explained" node is pretty long.  It seems to break
up naturally into three pieces, for each of the files being explained.
Perhaps it would be good to make them each separate (sub)nodes.


Of course, all the above are just some ideas, please do whatever makes
sense and forget the rest.

Happy hacking in 2011,
karl

bug#7773: (lack of) config.h description in manual

[Karl Berry]

Following up to my own mail, it seems I have been missing something
basic all these years, since it's never come up in my own packages: in
order to use the directory variables like $(LIBDIR) in the code, it
seems each package has to hack them in to config.h, e.g., via gnulib's
"configmake" module.  Right?

This is surprising.  A programmer coming to the autotools would hardly
expect to have to write their own glue script merely to get access to
the standard directories in the code.

I strongly suggest explicitly discussing this in the manual.  Maybe even
showing an example of how to do it, or at least referring to gnulib's
configmake.

(It'd be even better IMHO to just make them standardly available in
config.h somehow, e.g., as #define AM_LIBDIR and the like, but I can't
wrap my mind around a real spec, sorry ...)

Thanks,
k

bug#7773: (lack of) config.h description in manual

[Karl Berry]

Hi Ralf,

I'm closing it, for reasons explained below.

And I'm reopening it, maybe.  Not too clear on debbugs interactions.

No, I do not think that automake.info should repeat all
of autoconf.info information.

Me either.  I don't ever intend to suggest creating such redundancy.

  info Autoconf "Defining Directories"

Thanks for the reference.  Now that I know it, I suggest the Automake
manual simply have a sentence with an xref to that node.  Why?  Because
many people (e.g., almost all the new GNU maintainers) come to the
autotools through automake.  A pointer would help them (just as it would
have helped me, but anyway)

For example, as part of the amhello explanation:

--- ORIG/automake.texi  2011-01-02 00:24:40.0 -0800
+++ automake.texi   2011-01-03 15:57:50.0 -0800
@@ -1737,4 +1737,9 @@
 @file{README} during @code{make install}.
 
+One thing not covered in this example is accessing the installation
+directory values (@pxref{Standard Directory Variables}) from your
+program code, that is, getting them into @file{config.h}.  For this,
+...@pxref{defining Directories,,, autoconf, Autoconf}.
+
 
 @node Generalities

That does not work, and the above node explains why: the GNU Coding
Standards forbid it, implicitly.

Hmm, I'm not so sure that the GCS forbids doing the right thing (or that
it has to stay that way even if it does), but I won't pursue it further.
Life goes on.


Thanks,
k

bug#7766: (lack of) config.h description in manual

[Karl Berry]

Hmm, I see a natural split into two, not three nodes.  

Ok, fine.

Below, I replaced the existing one rather than using another lower
hierarchy level.  Does this seem acceptable to you?

Sure, but I suggest making the @node names closer to the @section names,
and not using that unusual-looking /.

@node amhello/configure.ac
->
@node amhello's configure.ac Setup Explained

@subsection Configure setup explained
->
@subsection @code{amhello}'s @file{configure.ac} Setup Explained

Ditto for the other node.

And then I think the upper-level menu could just use the node names.

(In general, despite longstanding precedent in various GNU manuals, my
belief is that it is not helpful to readers to have @node names that
unnecessarily differ from their section names.  The result is confusion
when an xref is made.)

Re capitalization, I seem to recall that we tried to systematically
Capitalize Node/Section Names a while back.  I don't see other downcased
names in the top-level menu just now, anyway.

+...@anchor{amhello Explained}

Very good.  Extra credit for thinking to do that :).

Thanks,
k

bug#8289: distcheck and make dvi

[Karl Berry]

Hi Ralf and all,

make distcheck runs make dvi.  If an author has only made .pdf's with
images, this will cause a surprising error that .eps files are missing.
(Someone just wrote me about this.)

I see the issue has been noted before, e.g.:
http://comments.gmane.org/gmane.comp.sysutils.automake.general/10304

I suggest that the workaround Ralf suggests there -- an empty make rule
for dvi: -- be explicitly documented.  Another (often preferable) option
is to create and distribute the .eps files, of course.

Another possible change, in addition to messing with the documentation,
would be to make the "dvi" a variable that such non-dvi-generating
people can override with "pdf" if they wish.  Then they could get the
benefit of the check in a clean way without forcing .eps.  Or maybe
dvi: pdf
would have the same effect?  I'm not sure.

Thanks,
Karl

bug#8289: distcheck and make dvi

[Karl Berry]

However, there are cases where dvi output just
isn't feasible in practice.

Yep.  Therein lies the essence of the problem.

not bother checking dvi output and rather test PDF output seems
like another good alternative.

I can't agree with that.  That's trading DVI-generation problems for
PDF-generation problems.  Believe me, there will be just as many if not
more.  Any manual which has *only* eps files, for starters.

All together, for a general fix, my suggestion is to simply replace the
hardwired "dvi" string with a new variable name, like
$(AM_DISTCHECK_DOC) or some such (no idea if that's a reasonable name,
but you get the idea), which defaults to dvi and which users can
override either with "pdf" or with some no-op target.  Which in turn
would need to be created/documented if one doesn't exist already.

How does that sound?

jack> violate the GNU coding standards, to which automake-generated
makefiles are meant to comply?

The dvi: pdf kludge was a user override.  The coding standards aren't an
issue in that case.

Thanks,
k

bug#8289: distcheck and make dvi

[Karl Berry]

Hi Jack,

New automake options? Something like:

I like my idea of a variable better :).
Seems simpler/less intrusive/more general.

Best,
k

bug#8326: can't override dvi: target, or others with -local

[Karl Berry]

Aside from the discussion in #8289 about alternatives to the hardwired
make dvi being run by make distcheck, there seems to be another problem,
namely putting a simple
dvi:
in a Makefile.am doesn't work to override the default rule. I get an
error like this:

  doc/Makefile.am:12: user target `dvi' defined here...
  automake: ... overrides Automake target `dvi' defined here
  doc/Makefile.am:12: consider using dvi-local instead of dvi

Looking for the code that's enforcing this, I see in Rule.pm around line
this comment:
  # -am targets listed in %dependencies support a -local
  # variant.  If the user tries to override TARGET or
  # TARGET-am for which there exists a -local variant,
  # just tell the user to use it.

But dvi-local does not suffice for the case at hand; that is, it can't
be used to avoid rebuilding the dvi, as far as I can see.  Certainly
merely adding dvi-local: does nothing in particular.  Is there another
way?

(Aside: I'm just curious, what can dvi-local actually be used for?
If there's a known use for it, I suggest mentioning it in the doc.)

As far as I can see, this behavior contradicts the documentation (node:
Extending), which simply says:

   * As far as rules are concerned, a user-defined rule overrides any
 `automake'-defined rule for the same target.

So my report is to suggest implementing that :).  Perhaps there should
be a warning in case of such overrides, but a fatal "you can't do that"?
Else the doc should be changed.

At any rate, if there's a workaround to get a clean make distcheck with
a PDF-only manual with the currently released automake, we'd like to know.

Thanks,
Karl

bug#8326: can't override dvi: target, or others with -local

[Karl Berry]

do you have `-Wall -Werror'
in AM_INIT_AUTOMAKE, maybe?

You are absolutely right.  It did not occur to me to look for that.
Sorry for the noise.

Feel free to close this one.  Thanks much for all the hints.

bug#11146: texinfo: could automake start using the '--tidy' option in its dvi and pdf rules?

[Karl Berry]

Since the '--tidy' option has only been introduced in Texinfo
4.9

More ordinary English syntax would be:
  Since the '--tidy' option was introduced in Texinfo 4.9

(Though the meaning is clear in the original.)

The users should be warned about the planned behavioural change

I have the impression that Automake (mostly) uses American English,
rather than British English.  Since that's where it was created, after
all.  Hence, I suggest: behavioral.


The actual change seems fine to me, FWIW.

karl

bug#11239: aclocal-invocation

[Karl Berry]

Regarding automake.texi in 1.11.4.  The whole point of the "Individual
utilities" section is to have an entry for the actual command names.

I can understand the rationale of changing the "individual" automake to
automake-invocation, since the whole package is also named Automake.
However, there is no package named "aclocal", so can we again not have
the "-invocation" there, please?

Thanks,
karl


--- automake-1.11.4/doc/ORIG/automake.texi  2012-04-02 03:09:39.0 
-0700
+++ automake-1.11.4/doc/automake.texi   2012-04-13 10:06:57.0 -0700
@@ -47,3 +47,3 @@
 @direntry
-* aclocal-invocation: (automake)aclocal Invocation.   Generating aclocal.m4.
+* aclocal: (automake)aclocal Invocation.  Generating aclocal.m4.
 * automake-invocation: (automake)automake Invocation. Generating Makefile.in.

Diff finished at Fri Apr 13 10:07:19

bug#11803: missing:138 has trailing whitespace

[Karl Berry]

I saw there has been some discussion on bug-gnulib about removing
"missing" and some of the other "internal" autotools helper scripts from
gnulib.  That makes sense, but I didn't see a final conclusion to the
discussion?

Meanwhile, I have been unable to autoupdate missing from automake to
gnulib -- maybe it's just as well -- because there is a trailing space
on what is currently line 138, namely the "blank" line between these
other two:

  printf '%s\n' "'$1' is $msg."
 
  configure_deps="'configure.ac' or m4 files included by 'configure.ac'"

Best,
Karl

bug#12320: bison 2.6.2 contains stale info files

[Karl Berry]

So, Karl, Jim, and others, would you accept that gendocs.sh
stopped generating a compressed tarball of split info files,
but would rather ship a compressed --no-split file?

Well, I hope meeting you halfway is ok ... I just changed gendocs.sh to
default to --no-split (can be overridden with a new --info option).

However, I kept it generating a tarball even though usually it will be a
tarball of one file, because otherwise, it would be necessary to detect
when split output was being generated, etc., etc.  Didn't seem worth the
trouble.

At least once you remove the stray split files now, they shouldn't
reappear ...

k

bug#12967: Texinfo compile failure on IRIX 6.5 (was: Re: failure on IRIX 6.5)

[Karl Berry]

Has been IRIX discontinued?

According to Wikipedia, IRIX 6.5 will be retired as of December 2013.

k

bug#12967: Texinfo compile failure on IRIX 6.5

[Karl Berry]

I'll need access
to an IRIX system to do so myself.  

I will ask my friend at Utah for an account for you if you want to
pursue it.  Let me know.

bug#13324: Improvements to "dist" targets (was: Re: EXTRA_DIST, directories, tar --exclude-vcs)

[Karl Berry]

> that every tar (except maybe really ancient ones, can't remember, but we
> don't care) supports the -style.

It would be nice to verify this claim on as much systems as possible

Certainly POSIX has always required supporting -options, which is some
15 years old at least.  Or do I mean 25?  Either way ...  And in
practice, every system I've ever used has a system tar supporting
-options, not just "old-style" options without the -.

Thus I would still propose that Automake always use -options to tar in
its output, never old-style options.

As for tar-v7, tar-ustar, tar-pax ... I don't know.

k

bug#13324: Improvements to "dist" targets (was: Re: EXTRA_DIST, directories, tar --exclude-vcs)

[Karl Berry]

That is already possible:


I see.  Given this, I propose merely changing the definition of am__tar
to use variables.  Something like:

am__tar = $(TAR) $(TAR_OPTIONS) - "$$tardir"

where the actual definitions of TAR and TAR_OPTIONS remain as they are
now (except possibly always using -options, as I'm replying to
separately).  That would make it easy for people to change or add
anything they want to change, in various ways.

I'm not sure if "TAR" and "TAR_OPTIONS" would be the conventional
names; any names would do, as far as I'm concerned.

k

bug#13324: Improvements to "dist" targets (was: Re: EXTRA_DIST, directories, tar --exclude-vcs)

[Karl Berry]

OTOH, what about distribution "tarballs" in '.zip' format?  They don't
use tar at all ...  Time to deprecate them maybe?  Is anybody actually
using them?  And while at it, what about the even more obscure 'shar'
format?

FWIW, I think they should still be supported.  I see recent
distributions on ftp.gnu.org using both -- gzip and tar make shar
archives for the sake of bootstrapping, and some packages use zip to
make things easier for Windows users.

One could certainly make arguments about getting rid of them (especially
shar), nevertheless.  I personally wouldn't want to spend time engaging
in that debate :).

k

bug#17536: automake.texi typo fixes

[Karl Berry]

Should be self-explanatory ("whitespaces" is not a word, etc.), let me
know if questions.

Don't see any point in a huge changelog entry either ...

Karl Berry  

* automake.texi: fix a few typos, etc.

--- ORIG/automake.texi  2014-04-23 00:21:46.256673602 -0700
+++ automake.texi   2014-05-20 10:18:50.383562660 -0700
@@ -1833,3 +1833,3 @@
 Makefile constructs, so you're advised to avoid fancy constructs or
-``creative'' use of whitespaces.
+``creative'' use of whitespace characters.
 @c Keep this in sync with doc-parsing-buglets-tabs.sh
@@ -3278,3 +3278,3 @@
 files, but @emph{this usage is today discouraged}, since it causes
-@samp{$(prefix)} not to be thoroughly honoured (which violates the
+@samp{$(prefix)} not to be thoroughly honored (which violates the
 GNU Coding Standards), and a similar semantics can be better obtained
@@ -7856,3 +7856,3 @@
 that file will be automatically generated.  The file @file{version.texi}
-defines four Texinfo flag you can reference using
+defines four Texinfo flags you can reference using
 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
@@ -8458,3 +8458,3 @@
 
-@c The caveates described here should be documented in 'disthook.sh'.
+@c The caveats described here should be documented in 'disthook.sh'.
 @noindent
@@ -9449,3 +9449,3 @@
 count the test results when printing the testsuite summary, or to decide
-which tests to re-run upon @command{make reheck}.  Unrecognized metadata
+which tests to re-run upon @command{make recheck}.  Unrecognized metadata
 in a @file{.trs} file is currently ignored by the harness, but this might

Diff finished at Tue May 20 10:18:54

bug#20713: aclocal/tar.m4 and solaris 5.10

[Karl Berry]

Running a configure script on solaris 5.10 generated with automake-1.15,
I got these errors about id, which being pre-POSIX, does not support -u:

  id: illegal option -- u
  Usage: id [-ap] [user]
  id: illegal option -- g
  Usage: id [-ap] [user]
  checking whether UID 'unknown' is supported by ustar format... 
./configure: line 4190: test: unknown: integer expression expected
  no
  checking whether GID 'unknown' is supported by ustar format... 
./configure: line 4200: test: unknown: integer expression expected
  no

It comes from aclocal-1.15/tar.m4, which says:
  ... Errors in the 'id' calls
  # below are definitely unexpected, so allow the users to see them

Well, they are not "unexpected" on this system, so it's not especially
helpful to see them.  Still, I suppose it is not worth worrying about.
And I'm sure it is not worth parsing the output of this old id (with no
args passed) to get the info, but for the record, that would be:
uid=1053(karl) gid=1053(karl)

But what I do think would make sense is to avoid the subsequent error of
using a numeric test expression on a known non-numeric (the string
"unknown") when id fails.  After all, that much is tar.m4's own doing.
Perhaps simply change
  if test $am_uid -le $am_max_uid; then
to
  if test $am_uid != unknown && test $am_uid -le $am_max_uid; then
(and ditto gid).

Clearly nothing critical.  Just reporting ...

Best,
Karl

bug#32074: maintainer-clean and removing configure/Makefile.in/etc.

[Karl Berry]

Hi - the automake manual has (for many years) said:

@code{maintainer-clean} should not delete anything that needs to exist
in order to run @samp{./configure && make}.
@end itemize

We recommend that you follow this same set of heuristics in your
@file{Makefile.am}.

That heuristic made sense when Francois formulated it decades ago. But
nowadays, especially since autoreconf exists, it does not seem
unreasonable to me to want to delete Makefile.in, configure, etc. It is
just as easy to run autoreconf (or equivalent) as configure&&make, and
it feels nice to have such dependent files gone from the source tree,
especially when working on setting up a package with autotools.

I certainly don't suggest changing any behavior, but perhaps the manual
could mention that it could be done via maintainer-clean-local or
MAINTAINERCLEANFILES, e.g.:

MAINTAINERCLEANFILES = aclocal.m4 config.h.in configure \
   Makefile Makefile.in */Makefile */Makefile.in

Some maintainers might prefer to also remove build-aux or more; personally
that's one step too much for me. All the more reason not to change any
code :).

Just an idea ... --best, karl.

bug#32074: maintainer-clean and removing configure/Makefile.in/etc.

[Karl Berry]

Hi Mathieu,

Thanks for the quick reply.

What is not clear to me is the reasoning of that heuristic.  You seems
to suggest that it has been introduced to avoid having to know the order
in which autoconf, aclocal, automake, ... has to be run.  Have you any
reference regarding that?

I've been looking through my old mail about this. I can't reconstruct
the whole trail, but this message from rms to me seems to be the crux of
the "don't delete configure" special case (this is the whole message and
I have no other direct context, but still).

  Date: Sat, 19 Sep 92 23:42:28 -0400
  From: r...@gnu.ai.mit.edu (Richard Stallman)
  To: k...@cs.umb.edu
  Subject: realclean: rm configure

  You can't reconstruct configure with the makefile
  if there is no configure.

That was true in 1992 (no autoreconf :), but is routinely not true
today.

Francois, Tom Tromey, Akim Demaille, Jim Meyering, I, and others were
going through many iterations of what should be deleted in which target
in those years. I can't pin down the exact source of that heuristic
though.

I would guess that the reason is more that this command might be run
from a tarball 

I don't see why that's an issue. If an installer runs maintainer-clean
after unpacking a tarball, they are responsible for their own actions.
That's why the target is named *maintainer*-clean :).

https://www.gnu.org/prep/standards/html_node/Standard-Targets.html
talks about this in explicit detail. (It also implies that Makefile.in
files should be deleted, by the way. Hmm.)

and that if the package builder doesn't know that Autotools is now
needed as a dependency, that person is left without any instruction

There are always instructions ...

Can you explain why this step would be too much for you?

Because I might (and usually do) have newer versions of the common files
than what missing would copy (ie, updated since the last Automake
release). Regardless, if you want to put build-aux (or whatever) into
the example in the manual, I don't object.

Best,
Karl

bug#32074: maintainer-clean and removing configure/Makefile.in/etc.

[Karl Berry]

I think Automake shouldn't suggest something that is explicitly
discouraged by the GCS.

Good point. I agree.

I would suggest discussing it on ...

Perfectly reasonable, but I'm just too old to have the stomach for those
discussions any more :(. Hardly the most crucial suggestion in the
world, fine for it to be relegated to the dustheap of history :).

--all the best,
karl

bug#36966: install-sh -s on 555 executable fails

[Karl Berry]

(I'm not on this list, so please keep me in cc if need be.)

It seems that install-sh -s (what automake's install-strip target can
end up doing) fails if the original file doesn't have the owner-write
bit set:

cp /bin/cp /tmp/rx# any binary will do
chmod 555 /tmp/rx # make unwritable to owner
install-sh -s /tmp/rx /tmp/sx # try to install, with strip
-> strip: unable to copy file '/tmp/_inst.31092_'; reason: Permission denied
echo $?
-> 1

Although install-sh (version 2018-03-11.20, lines 224ff.) does some
stuff to ensure that umask will not clear an owner-writable bit in the
destination, that's not enough to make it owner-writable if it's not
already.

The only less-than-wonderful fix I could come up with is to explicitly
do chmod u+w if strip is being executed. I thought maybe it would be
worth trying the strip even if the chmod failed, hence the ; instead of
&&, but it's not something I feel strongly about. And maybe there is
some nicer way to do it altogether.

--- a/build-aux/install-sh
+++ b/build-aux/install-sh
@@ -461,7 +461,7 @@ do
 #
 { test -z "$chowncmd" || $doit $chowncmd "$dsttmp"; } &&
 { test -z "$chgrpcmd" || $doit $chgrpcmd "$dsttmp"; } &&
-{ test -z "$stripcmd" || $doit $stripcmd "$dsttmp"; } &&
+{ test -z "$stripcmd" || ($doit $chmodcmd u+w "$dsttmp"; $doit $stripcmd 
"$dsttmp") } &&
 { test -z "$chmodcmd" || $doit $chmodcmd $mode "$dsttmp"; } &&
 
 # If -C, don't bother to copy if it wouldn't change the file.


Wdyt? --thanks, karl.

bug#36921: texinfo: @setfilename is not mandatory

[Karl Berry]

I posted a patch to fix this issue: 
https://lists.gnu.org/archive/html/bug-automake/2019-01/msg2.html

Thanks Gavin. I hope Jim (Meyering) or I will install the patch soon,
although the timing of the next release is unknown at this point.

I'm just starting to get a grip on the development side of automake;
just trying to help since Jim doesn't have a lot of time right now and
all other am developers seem to have disappeared. (If you yourself have
any time/interest, help is greatly needed!) --best, karl.

bug#38139: Fwd: Likely bug: generating tags with Emacs Lisp sources present

[Karl Berry]

Hi Luca - not that I am an official automake maintainer, but thanks for
the report, and sorry for the lack of response. Your fix looks right to
me, FWIW. I hope Jim or I or someone will commit it soon. Creating the
test case will surely consume the most time. If you can easily make a
minimal Makefile.am that exhibits the problem, that would be great.
--thanks, karl.

bug#39078: Path.pm change -> deltree.pl -> t/uninstall-fail failure

[Karl Berry]

t/ax/deltree.pl is used in t/ax/test-lib.sh's rm_rf_ function to recursively
remove a directory tree, even given directories with zero permissions,
such as intentionally created by uninstall-failsh.

Version 2.15 of Perl's File::Path (released with perl-5.28.0) has
changed behavior such that this no longer works. The result is that the
test fails with these errors:

cannot chdir to child for t/uninstall-fail.dir/__inst-dir__/share: Permission 
denied at /u/karl/gnu/src/akarl/t/ax/deltree.pl line 29.
cannot remove directory for t/uninstall-fail.dir/__inst-dir__: Directory not 
empty at /u/karl/gnu/src/akarl/t/ax/deltree.pl line 29.
cannot remove directory for t/uninstall-fail.dir: Directory not empty at 
/u/karl/gnu/src/akarl/t/ax/deltree.pl line 29.

(That .../share dir is the one that is intentionally mode zero.)

The relevant change in Path.pm appears to be the one below. (I'll also
attach the two Path.pm's in full, for the record.) As you can see, it
mentions a CVE (CVE-2017-6512), and thus the change is presumably
entirely intentional. I find the new long condition hard to be sure of
without a lot of experimentation, but it appears to me it is
intentionally no longer changing the mode of directories. This
incompatibility seems highly unfortunate, but I doubt it is a mistake.

So, the question is what to do about this in Automake. One option would
be to make deltree.pl notice the failure and do the chmod itself in
Perl, then redo the rmtree. Or just do the chmod before the first
rmtree.

Then I wondered, why not just do the same in the shell:

  chmod -R u+rwx "$@" || true
  rm -rf "$@"
  # If don't want to rely on rm exit status,
  # could then check if any of "$@" still exist.

Looking at the ChangeLog, Stefano made the original switch to Perl was
precisely because it was "more reliable and portable" than the previous
shell implementation, but unfortunately this is no longer the case.  The
CL entry is also below.

Re use of find (in the CL entry) vs. chmod (above), personally I don't
see the need for the fancy find conditions, since all we're going to do
is remove everything anyway, so why not blindly u+rwx everything? The
Portable Shell node in the manual does not warn about chmod -R being
problematic, and afaik it's in POSIX, for whatever that may be
worth. But nevertheless we could use find if deemed better.

On the other hand, doing it in Perl also seems perfectly feasible. It
feels a bit simpler to me to do it in sh than to call a Perl helper
script that calls a Path.pm function, but I don't have strong feelings
about it. I don't see that there is an overwhelming technical argument
one way or the other.

Jim, anyone, wdyt? We have to do something ... --thanks, karl

-
2013-05-16  Stefano Lattarini  

tests: use perl, not find+rm, to remove temporary directories

The File::Path::rmtree function from perl, if used right, is
more reliable and more portable of our past idiom:

find $dirs -type d ! -perm -700 -exec chmod u+rwx {} ';';
rm -rf $$dirs || exit 1

at least of the face of unreadable dirs/files and other similar
permission issues (and we have those in our test directories).

In fact, this change fixes some spurious failures seen in
"make distcheck" on Solaris 10.

* t/ax/deltree.pl: New.
* Makefile.am (EXTRA_DIST): Add it.
(clean-local-check): Use it.
* t/ax/test-lib.sh (rm_rf_): Use it.
-


--- /usr/local/lib/perl5/5.24.0/File/Path.pm2016-11-13 09:06:35.640002177 
-0800
+++ /usr/local/lib/perl5/5.28.0/File/Path.pm2018-08-02 17:41:00.645374266 
-0700
@@ -354,29 +400,40 @@
 
 # see if we can escalate privileges to get in
 # (e.g. funny protection mask such as -w- instead of rwx)
-$perm &= oct '';
-my $nperm = $perm | oct '700';
-if (
-!(
-   $arg->{safe}
-or $nperm == $perm
-or chmod( $nperm, $root )
-)
-  )
-{
-_error( $arg,
-"cannot make child directory read-write-exec", $canon 
);
-next ROOT_DIR;
+# This uses fchmod to avoid traversing outside of the proper
+# location (CVE-2017-6512)
+my $root_fh;
+if (open($root_fh, '<', $root)) {
+my ($fh_dev, $fh_inode) = (stat $root_fh )[0,1];
+$perm &= oct '';
+my $nperm = $perm | oct '700';
+local $@;
+if (
+!(
+$data->{safe}
+   or $nperm == $perm
+   

bug#39078: Path.pm change -> deltree.pl -> t/uninstall-fail failure

[Karl Berry]

Regarding the new failure of Path.pm:rmtree to do removals, here is the
change I had in mind to use chmod and rm instead. The previously-"ERROR"
tests (uninstall-fail and instspc) work for me with this change.

Before I bother spending time on all the related overhead changes, any
objections, improvements, comments on this approach?

The rest of the patch is unrelated to the functional change: checking
for any of the elements existing after the purported removal. In my
testing I found it useful for this to be reported, and the abort to
occur, right away.

Then, the recursive ls report on failure might be overkill, but I found
it useful to understand the failing situation, so here it is for
consideration. (I guess it would be better to prepend the prefix to
every line of the ls output, which would be easy enough.)  --thanks, karl.

diff --git a/t/ax/test-lib.sh b/t/ax/test-lib.sh
index 57afc07..9312bbb 100644
--- a/t/ax/test-lib.sh
+++ b/t/ax/test-lib.sh
@@ -197,7 +197,18 @@ seq_ ()
 rm_rf_ ()
 {
   test $# -gt 0 || return 0
-  $PERL "$am_testaux_srcdir"/deltree.pl "$@"
+  chmod -R u+rwx "$@" || :
+  rm -rf "$@"
+  _am_rmrf_status=$?
+  for _am_rmrf_v
+  do
+if test -e "$_am_rmrf_v"; then
+  echo "$me (test-lib.sh:rm_rf_): tree not removed: $_am_rmrf_v" >&2
+  echo "$me (test-lib.sh:rm_rf_): $(ls -alR $_am_rmrf_v 2>&1)" >&2
+  _am_rmrf_status=2
+fi
+  done
+  return $_am_rmrf_status
 }
 
 commented_sed_unindent_prog='

bug#39078: Path.pm change -> deltree.pl -> t/uninstall-fail failure

[Karl Berry]

Pushed attached patch, closing here.



rmrf.diff
Description: Binary data

bug#32088: Python >=3.5 test suite failures

[Karl Berry]

instmany-python.sh from the somewhat arbitrary 2500 to 3200. Neverthlesss, 
maybe a more elegant solution is possible.

Seems fine to me. Thanks for finding the workaround.

2) The fix/patch of bug #38043 (Incorrect Python byte-compiling for
Python 3 and PyPy3), which we also carry, interferes with
t/py-compile-basedir.sh; the number of generated files (line 47
there) is then (only for recent Python 3) 6, not 4.

People will surely be running make check on older machines.

Maybe the simplest way is just to accept either 4 or 6 in the stated
 test $(echo "$files" | wc -l) -eq 4
as long as those are the only results ... so far ...

Jim, wdyt? --thanks, karl.

bug#32088: Python >=3.5 test suite failures

[Karl Berry]

Hi Andreas, Lukas, and all - I have pushed Lukas's two patches, tweaked
per Andreas's subsequent fixes, and also adjusted for the current sources.
Hope it flies, please reopen if problems. Thanks to all! --karl

bug#35848: Should automake use gmake by default if exists?

[Karl Berry]

Hi Libor - back on your improvement to the failed dependency tracking
message, from last May (sorry):

 From: Libor Bukata 
 Date: Thu, 23 May 2019 12:31:31 +0200
 ...
+AC_MSG_FAILURE([Something went wrong during bootstrapping of makefile
+fragments for automatic dependency tracking. If the GNU make is not
+used by default, consider to rerun the configure script with MAKE="gmake".
 ...

I've applied this patch, modulo a few tweaks to the wording. Thanks! -k

bug#40181: FAIL: t/tags-lisp-space.sh

[Karl Berry]

Hi Andreas,

/bin/sh: line 11: etags: command not found

I somehow thought presence of etags was already tested for, but
obviously not. Anyway, I'll look into it as soon as I can.
Thanks for the report. --karl

bug#40192: Please report to bug-automake@gnu.org

[Karl Berry]

FAIL: t/tags-lisp-space.sh
...
test-init.sh: etags: not found

Thanks for the report. Yeah, have to have etags (or maybe just a link to
/bin/true suffices? not sure) for the test to succeed at the
moment. Didn't realized that. Will put in a safeguard soon, but any new
release is probably a ways off. --best, karl.

bug#40181: FAIL: t/tags-lisp-space.sh

[Karl Berry]

I believe all that's needed is to set required=etags in
t/tags-lisp-space.sh. Sorry for my dumb mistake. Committed this:

--- a/t/tags-lisp-space.sh
+++ b/t/tags-lisp-space.sh
@@ -18,7 +18,7 @@
 # if there are CONFIG_HEADERS.
 # See automake bug#38139.

-required=''
+required=etags
 . test-init.sh

 # some AC_CONFIG_FILES header is needed to trigger the bug.

bug#40192: Please report to bug-automake@gnu.org

[Karl Berry]

I believe all that's needed is to set required=etags in
t/tags-lisp-space.sh. Sorry for my dumb mistake. Committed this:

--- a/t/tags-lisp-space.sh
+++ b/t/tags-lisp-space.sh
@@ -18,7 +18,7 @@
 # if there are CONFIG_HEADERS.
 # See automake bug#38139.

-required=''
+required=etags
 . test-init.sh

 # some AC_CONFIG_FILES header is needed to trigger the bug.

bug#10371: Broken links in the on-line automake manual

[Karl Berry]

Hi Stefano and all -- back on your report about broken urls from 2011 :) --

Date: Mon, 26 Dec 2011 22:03:50 +0100

Feeding the address of the on-line automake manual:
  

to the W3C linkchecker:
  

I've found the following *broken links*:
  
  ...

The particular urls you found at that time (all are GNU manuals) are
not a problem any more, due to the Texinfo htmlxref feature we invented
to handle references from one Texinfo manual to another.
(Doc on that, for the record: 
https://gnu.org/s/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html
 Current xref file: http://ftpmirror.gnu.org/texinfo/htmlxref.cnf)
So that is all fine.

However, I took the opportunity to rerun checklink on a single-file
automake.html (make AM_MAKEINFOHTMLFLAGS="--no-headers --no-split" html)
and found plenty of other problematic links in the manual (surprisingly,
there were none in automake-history.html).

I then made a few small changes to the W3C checklink script to eliminate
useless warnings and make exclude maintenance more convenience, and
called the resulting file checklinkx for (I hope) clarity. (Mostly I did
this because I hope to reuse this work for other documents and web pages
I maintain.)

The attached patch.gz fixes the urls in automake.texi, adds checklinkx
to the contrib/ subdirectory, and a new target in doc/local.mk to invoke
it for rechecking. Here's the ChangeLog entry I've got so far, for
convenience.

Comments/criticisms/suggestions/whatever? --karl
(With thanks to Jim for pre-reviewing this work and already suggesting
plenty of good improvements.)

-
[PATCH] doc: update urls in manual and include checklinkx script.

* doc/automake.texi: update many urls; http -> https,
search.cpan.org -> metacpan.org/pod/distribution, node names, etc.
Remove sourceware.org/cgi-bin/gnatsweb.pl and
miller.emu.id.au/pmiller/books/rmch/ as these are 404
and no good replacement is evident.
s/perl/Perl/ a couple times in text for good measure.
* contrib/checklinkx: new script, a small modification of
W3C checklink 
(W3C license, which is free software), starting from version 4.81
installed from CPAN:
https://metacpan.org/pod/distribution/W3C-LinkChecker/bin/checklink.pod
* doc/local.mk (checklinkx): new target to invoke it, with variables.
* Makefile.am (EXTRA_DIST): distribute it.



checklinkx.diff.gz
Description: Binary data

bug#18734: [PATCH] vala: Improper parsing of valac arguments leads to garbage in DIST_COMMON

[Karl Berry]

Hi Colomban - back on your automake bug report from six years ago (sorry!):

Date: Wed, 15 Oct 2014 17:17:00 +0200
From: Colomban Wendling

[...]
The problem is that parsing of valac flags uses a non-anchored pattern
and so any argument happening to be a subset of a parsed argument will
match it, e.g. `vapi` will match against `--vapi` or `--internal-vapi`.

[... patch ...]
--- a/bin/automake.in
+++ b/bin/automake.in
@@ -5436,8 +5436,8 @@ sub lang_vala_finish_target
   foreach my $flag ($flags->value_as_list_recursive)
{
- if (grep (/$lastflag/, ('-H', '-h', '--header', '--internal-header',
- '--vapi', '--internal-vapi', '--gir')))
+ if (grep (/^$lastflag$/, ('-H', '-h', '--header', '--internal-header',
+   '--vapi', '--internal-vapi', '--gir')))
{

Indeed. I don't see a problem with applying your patch, but before I do,
I just wondered if anything else had come up with vala that needs to be
fixed? Please advise if you can. I've never used vala myself, so
wouldn't know. --thanks, karl.

bug#10371: Broken links in the on-line automake manual

[Karl Berry]

The attached patch.gz fixes the urls in automake.texi, adds checklinkx
to the contrib/ subdirectory, and a new target in doc/local.mk to invoke
it for rechecking. 

Hearing no objection, I pushed this change (last night, belatedly
sending this mail, sorry) and am closing this bug. -k

bug#18734: [PATCH] vala: Improper parsing of valac arguments leads to garbage in DIST_COMMON

[Karl Berry]

- if (grep (/$lastflag/, ('-H', '-h', '--header', '--internal-header',
- '--vapi', '--internal-vapi', '--gir')))
+ if (grep (/^$lastflag$/, ('-H', '-h', '--header', '--internal-header',
+   '--vapi', '--internal-vapi', '--gir')))
{

I installed this change and am closing the bug. Thanks. --karl

bug#32100: [PATCH] automake: Remove duplicate words in aclocal.in

[Karl Berry]

Hi Samy - back on your report from July 2018 (sorry)
on a typo in bin/aclocal.in:

- # the destination file (rather than a temporary file) is
+ # destination file (rather than a temporary file) is

I've applied this patch and am closing the bug. Thanks! --karl

bug#7860: recursive autoreconf breaks AM_COND_IF conditionalization of AC_CONFIG_FILES

[Karl Berry]

As far as I can tell from
  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=7860
there is nothing left to do here. Please update if incorrect.
Closing via bcc. --karl

bug#22445: [PATCH] test-driver help message is wrong

[Karl Berry]

Hi - back on your report from January 2016 (sorry):

The test driver help message indicates that arguments are given using,
e.g., "--test-name=NAME", while it only recognizes "--test-name NAME".

Belated thanks. I installed your patch, am closing bug.
--happy hacking, karl.

bug#40699: "dist Hook" documentation in manual is incorrect or unclear about write permissions

[Karl Berry]

Hi Vincent,

So, if the subdirectories may not be writable, how can the rm in the
first example work without changing the permissions first?

[namely:]
dist-hook:
rm -rf `find $(distdir)/doc -type d -name .svn`

That example belongs to the preceding paragraph 
  (Occasionally it is useful to be able to change the distribution ...)
not the following paragraph that you quoted.

Also, not that I wrote any of this, but it seems to me that the
pervasive assumption is that the automake user in fact owns the file
trees in question. Thus rm -rf should work even if it's mode zero.
Of course it won't work on a read-only source tree, but, well, it's just
an example ... --thanks, karl.

bug#40699: "dist Hook" documentation in manual is incorrect or unclear about write permissions

[Karl Berry]

i.e. it does not change the permissions in order to make the removal
work recursively

Right, I see it now. Had been testing the wrong thing.

So, can you propose a specific change for the manual? -k

bug#40699: "dist Hook" documentation in manual is incorrect or unclear about write permissions

[Karl Berry]

+chmod -R u+w $(distdir)/doc
...
-echo "Distribution date: `date`" >> README
+echo "Distribution date: `date`" >> $(distdir)/README

Ok, pushed. Thanks.