GNU bug report logs - #20987
Replacing "15 Support for test suites" in the Automake manual

Previous Next

To reply to this bug, email your comments to 20987 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Arthur Schwarz" <aschwarz1309 <at> att.net>
To: <bug-automake <at> gnu.org>
Subject: Replacing "15 Support for test suites" in the Automake manual
Date: Sun, 5 Jul 2015 14:22:34 -0700

[Message part 1 (text/plain, inline)]

The existing Automake description is terse enough to be unreadable.
Significant issues are unaddressed or addressed in a manner which is more
confusing than enlightening. The replacement manual covers each test regime
fully (except for Dejagnu) and provides a introduction which gives a general
basis for understanding the material to follow. It is understood that
several sections in the introduction would be best presented as a general
introduction. However, Automake does not provide any insight into these
issues and any addressing of them in the Automake manual is scatter shot. 

You are welcome to use or not use the material. You are welcome to copy or
reference the material. And you are welcome to ignore everything in the
material or that I have said. The replacement manual is for your use or
non-use.

The Dejagnu test harness is not addressed. I'm exhausted and Dejagnu holds
little appeal. Sorry.
 
Note the TAP section covers all the materials needed to understand the
existing TAP implementation plus some new materials which represent the
replacement code sent in http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20986.

I recognize that files of this size present an issue for the servers but
have no other manner which will allow distribution of the document. I do not
have a web site. If you can suggest an alternative transmittal mechanism
then I will use it.

art

Maintenance turns design into chaos

[test.odt (application/vnd.oasis.opendocument.text, attachment)]

Message #12 received at 20987 <at> debbugs.gnu.org (full text, mbox):

From: Bogdan <bogdro <at> gmx.com>
To: 20987 <at> debbugs.gnu.org
Subject: [bug#20987] Replacing "15 Support for test suites" in the Automake
 manual
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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.