Re: [FYI] {master} docs: fix unportable example of AM_TESTS_ENVIRONMENT usage

[Stefano Lattarini]

On Thursday 30 June 2011, Ralf Wildenhues wrote:
> * Stefano Lattarini wrote on Thu, Jun 30, 2011 at 10:45:02PM CEST:
> > On Thursday 30 June 2011, Ralf Wildenhues wrote:
> > > I'm fairly sure that's only with historic shells and not an
> > > issue in practice any more (Sven Mascheck's pages will have the details
> > > for the curious).
> 
> > Anyway, I do think that Eric's original proposal of extending the 
> > parallel-tests
> > harness to allow arbitrary and portable fd redirections is the way to go
> > eventually;
> 
> Link?
>
I'll post that tomorrow, if I manage to find it again -- I can't even remember
on which list it was :-(

> > here are my reasons:
> >  - it would be pretty easy to implement and document;
> >  - the testsuite harness is being revamped anyway;
> >  - that change would also benefit all the future custom and built-in test
> >    drivers;
> >  - the current hack with "TESTS_ENVIRONMENTS = ...; 9>&2", while continuing 
> > to
> >    work, will prevent the use of AM_TESTS_ENVIRONMENT :-(
> > 
> > > > In each case, the user's namespace is invaded, and we go against our own
> > > > advice (in [1] we violate the "always terminate AM_TESTS_ENVIRONMENT 
> > > > with
> > > > a semicolon" rule, in [2] we violate "don't define TESTS_ENVIRONMENT in
> > > > the Makefile.am, it's user-reserved" rule).
> > > > 
> > > > Also, the example above belongs IMHO more in a FAQ rather than in a
> > > > reference manual.
> > > 
> > > Are you volunteering to update the FAQ?  ;-)
> > >
> > Oh no ;-)  Not this summer at least.
> 
> That's a pretty strong statement, and when accompanied by a
> documentation regression (if I may exaggerate a bit), I'm not too happy
> when I read this.  Please do not consider documentation work as second
> class citicen.
>
Believe me, I don't; so far, for what concerns the test-protocols branch,
I've spent more time writing documentation (and test cases checking examples
in there) than I've spent writing code.

> Actually, writing (at least a sketch of) the
> documentation before implementing a feature is a very good way to get
> more organized and better design, IMVHO.
>
I heartily agree (and what I've done so far confirms it clearly).  The
point is, I really think I won't have time, in the short term, to write
any decent FAQ content, if I'm going to have to write decent reference
documetation, decent code and decent tests in time.

Regards,
  Stefano