Subject: [bug#20987] Replacing "15 Support for test suites" in the Automake manual

From: Bogdan <[email-masked]>
Date: Mon, 10 Apr 2023 15:02:11 +0200

Hello.

  Thank you for the great amount of work you put into the document. 
You explain a lot of things in great detail on those 63 pages. Really 
impressive.
  I haven't read every single word in the document, I've just browsed 
it, but I've found some issues which would need to be addressed:

1) Although you chose the open ODT format (respect for that!), the 
Automake documentation is in the Texinfo format and the recommended 
way of submitting changes is using a patch file (see the "HACKING" 
file, e.g. https://git.savannah.gnu.org/cgit/automake.git/tree/HACKING).

2) The document you have provided contains symbols (like the Greek 
letter Sigma), tables and diagrams which may be hard to put in the 
Texinfo file so that they look good in both an 80-column terminal 
window (the 'info' command) and in HTML (or other formats).

3) The document contains language issues which need to be fixed. Examples:
   - repetitions like "the the",
   - "back slash" (I believe it should be "backslash"),

4) Writing "${ AWK }" etc. is an error because of the whitespace. The 
correct syntax is just "${AWK}". Just checked with GNU make.

5) Commands like "configure && make" or "configure && make && make 
install" will not work for people who don't have the current directory 
in their $PATH. It should say "./configure ..." (the dot-slash at the 
beginning).

6) I believe "make dist-xz" would make a product-0.5.tar.xz file, not 
a product-0.5.xz file.

7) The "tar xfa" command: BSD tar says "tar: Option -a is not 
permitted in mode -x". GNU tar accepts it, but some other 'tar' 
implementations (in some modes, perhaps) expect the filename to always 
immediately follow the 'f' command, so e.g. "tar xfa foo.tar.gz" 
doesn't work, because it looks for a file literally called "a" (the 
one after the "f").

8) Other cosmetic issues like:
   - "Perl" is the name of the language and "perl" is the name of the 
interpreter for the language Perl,
   - write "Perl interpreter" instead of "perl compiler".

Someone who is native in English, and preferably also technical, 
should do an even deeper review of the file. My knowledge about 
testing is also limited.

-- 
Regards - Bogdan ('bogdro') D.                 (GNU/Linux & FreeDOS)
X86 assembly (DOS, GNU/Linux):    http://bogdro.evai.pl/index-en.php
Soft(EN): http://bogdro.evai.pl/soft  http://bogdro.evai.pl/soft4asm
www.Xiph.org  www.TorProject.org  www.LibreOffice.org  www.GnuPG.org