Re: [Gnucap-devel] What should be included in the dist file?

[Dan McMahill]

al davis wrote:
> Considering a recent comment about pdf files, I ask...
>
> What should be included in the dist file?
>
> Obviously all source, including the manual.
>
> What about some things that are not source?
>
> Documentation:
>
> 1. HTML files?
>
> 2. DVI files?
>
> 3. PDF files?
>
> 4. PS files?
>
> My comment:  People should be able to read the docs doing 
> anything else.  Requiring the tools to compile finished 
> documentation adds another dependency.

My take is to include certainly 1-3.  I can go either way on #4.  We're 
only talking about 500 kB of extra stuff in the dist file which to me 
seems a small overhead considering the benefit.  But you probably 
already knew my opinion.


> Should there be another file, distributed next to the source 
> one,  with finished docs?  
>
> Should several options be offered:
> 1. complete (including processed docs)
> 2. source only
> 3. processed docs
> 4. testing files
> ---  this is 4 files offered for download.
>
> One common mistake I see is to give only short names for the 
> files, so I am not sure what I need.  So, I download them all 
> only to discover duplication.

If the docs were 10 Mb and the sources 1 Mb I might do this but with the 
current sizes it seems like multiple files just means more work for the 
users, developer, and maintainers of packages for the various packaging 
systems out there.

> What about regression test files?  (the test subdir).
>
> Does anyone actually use them?
> Does anyone else know how to interpret the results?
>
> Comment:  With floating point, often you don't get an exact 
> match.  I have seen it different between Intel and AMD 
> processors.

I'd like to find a way to be able to run the tests and do a sane diff. 
I have run them in the past and just manually tried to look at the diffs 
looking for gross errors (like a crash on my computer).  I've been 
meaning to hook up the regression tests to the automake build system so 
that 'make check' runs it but just haven't gotten around to it.

It seems like for most cases a simple rounding to some number of 
significant digits before a diff should work, but maybe not when the 
"answer" was supposed to be zero.  Maybe there needs to be a numerical 
diff which includes the concepts of both relative error and absolute 
error.  You'd declare a match if the either error is less than some 
values you pick and a match if both are out of spec.  This way 1.83e-15 
and -8.32e-16 could match as could 3.12345 and 3.124.

I wonder how much work it would be to code up that sort of diff in awk. 
 Of course then you have the issues with incompatible awk's if you're 
not careful.

I do think it gives people a level of confidence to be able to run the 
tests when building with perhaps a different compiler or on a platform 
which is likely not one which receives much testing.

-Dan