[RFC] The documentation of general portability problems (make, shell, etc) should be in a separate manual

[Stefano Lattarini]

Hello autoconfers.

Recently, various improvements and extensions have been committed to the section
of the Autoconf manual dealing with Shell portability problems ("Shellology").

Unfortunately, these improvements don't yet appear in the version of the manual
available on the web.  That's not easily fixable: we cannot simply update the
web manual tout-court to publish those recent improvements, since doing so would
also entail publishing documentation for features and behaviours that are only
in the unreleased, development version of Autoconf.

As you might have surmised from the subject of my mail, my opinion is that the
best course of action to avoid this situation in the future is to split the
parts of the autoconf manual that speak of portability problems not directly
related to Autoconf into a separate manual of its own ("GNU portability manual"
perhaps?).

This would have also the advantage of enhancing the visibility of such
documentation outside the GNU and/or Autotools world, especially among
projects that aim at being portable but, for one reason or the other, does
not use autoconf and so do not draw from the Autoconf manual.

As example of such a project, think of Git: its build system is based on
GNU make, but its testsuite is composed of portable shell scripts targeting
the POSIX shell, so the Git developers/contributors could definitely use the
impressive documentation about shell portability currently contained in the
Autoconf manual.

To back up my assertion with a couple of examples:

 <http://article.gmane.org/gmane.comp.version-control.git/178910/>
 <http://article.gmane.org/gmane.comp.version-control.git/183714/>

As you can see, I was able to give some help a little by just quoting the
autoconf manual.

Thanks,
  Stefano