automake
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Automake Manuals (RANT)


From: Gavin Smith
Subject: Re: Automake Manuals (RANT)
Date: Sun, 26 Apr 2015 11:04:33 +0100

On 26 April 2015 at 01:25, Arthur Schwarz <address@hidden> wrote:
>
> Well, putting it gently you have a good product and one of (maybe, the)
> worst manual on earth describing it.

I'd like to see improvements as well, but calling other people's work
"the worst manual on earth" is not conducive to soliciting their
cooperation.

> You can’t argue that as a volunteer
> effort you depend on volunteers, because you have volunteers willing and
> wanting to put their backs to the wheel to improve your manual, e.g.,
> http://lists.gnu.org/archive/html/autoconf/2014-09/msg00000.html. My
> question is why don’t you use these ready hands or why don’t we see their
> result?

One of the maintainers has to take the time to review the suggestions.
In general, from what I can see, work on automake has been limited in
the last year or so. I am not an automake developer myself but I can
say that I didn't work through your initial email about the Test
Suites section in detail because I didn't have time.
(http://lists.gnu.org/archive/html/automake/2015-03/msg00077.html).

>
> Lest you think that I wail at others without efforts of myself, let me say
> “nay”. I am trying to help as best I can by rewriting all of Section 15
> Support for test suites. But I don't know Tex/LaTex/Texinfo and my efforts
> are restricted to Open Office/Adobe PDF and Open Office generated LaTex
> files - and others have commented on their inadequacy,
> http://lists.gnu.org/archive/html/automake/2015-04/msg00026.html.

One suggestion I have is that when you completely rewrite a section,
it takes effort to see what you have added, removed, and reordered,
and you have to guess at your reasons for doing so.

I expect it will be easier to get smaller changes accepted
incrementally. Are there any automake developers who would like to
work with Arthur, me and others on reviewing changes to the manual,
like the following suggestion:

  pg. 103 "When no test protocol is in use ..."
      Do you mean to say that script based testing does not use a test
protocol or that script based testing may or may not use a protocol but this
discussion centers on using script based testing without using a protocol?
Since no protocol is used, doesn't the exit status and its use constitute a
protocol? And what are we going to do about FAIL, PASS, SKIP ... previously
described. Are they protocols whereas exits statuses (stati sounds so
pretentious) of 0, 77 and 99 are not protocols?

I think that is a valid point: In the previous paragraph, we read: "By
default, only the exit statuses of the test scripts are considered
when determining the testsuite outcome.  But Automake allows also the
use of more complex test protocols,..." - which implies that the exit
status _is_ a protocol. Yes, the reader can work out what is meant;
but it does make it more difficult to read.

> My fondest hope is that the comments of others, as well as myself, are taken
> to heart and that you begin to solicit or perform needed document changes.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]