I'm writing about a few things I noticed in the INSTALL file that is often included at the top level of packages. A copy of this is kept in the gnulib repository, but as far as I can tell, the master is kept in autoconf. Please point me in the right direction if I'm writing to the wrong list. https://git.savannah.gnu.org/cgit/autoconf.git/tree/doc/install.texi * Use of Info cross references: There are currently several uses of Info cross-references in INSTALL; for example: Use or omit PACKAGE when building. *Note Optional Features::. It makes no sense to include the Info cross-reference beginning "*note" in a plain text file (and the fact nobody seems to have complained about this makes me sceptical that many people are actually reading this INSTALL file). It is not clear that these are references to other sections of the INSTALL file. I suggest that the "autoconf" flag could be used to give alternative text here, as was done in the recent autoconf commit d8ca8b3238. (link https://git.savannah.gnu.org/cgit/autoconf.git/commit/?id=d8ca8b323873e5cd9d969a062f70b31db450ba53). * The INSTALL file that's generated from this uses non-ASCII quotes, unnecessarily: The following more-detailed instructions are generic; see the ‘README’ file for instructions specific to this package Using ASCII quotes, like 'README', would be just as good here. This can be enabled with appropriate options to texi2any, although it depends on the version. From texi2any 7.0 onwards, you can pass "-c ASCII_PUNCTUATION=1". For older texi2any, you can pass "-c OPEN_QUOTE_SYMBOL=\' -c CLOSE_QUOTE_SYMBOL=\'". It seems that people are more likely to be have broken or unusual setups when reading an INSTALL file than when reading other text files, making UTF-8 more of a potential problem. * A "bootstrap" command is recommended as the first step: The following shell commands: test -f configure || ./bootstrap ./configure make make install should configure, build, and install this package. However, a "bootstrap" command does not exist in all packages (and isn't specified by the GNU coding standards(*)), making this INSTALL file less useful to include in other packages. (*) https://www.gnu.org/prep/standards/html_node/Managing-Releases.html#Managing-Releases). The text also says, several paragraphs later, that the "bootstrap" command can download data from a network, which is not respecting the user's privacy and the other downsides of network access (expense, reliability). I suggest that the use of a "bootstrap" command is kept in INSTALL, but it is not recommended as a the first command a user should run. It should be discussed as an optional extra, especially for the use of developers, with the possibility of network access discussed up front. Perhaps some of the information about "bootstrap" could be included in the more detailed list of instructions, under "The simplest way to compile this package is"? Thanks for your attention.
