gEDA-dev: What should be included in the dist file?

[Stuart Brorson]

Al --

Sorry for my late response.  Answering you was on my ToDo list, but
somehow went down a rathole.

On Wed, 16 Aug 2006, al davis wrote:

> I got only one response on the gnucap-devel list, and it really
> is a general question, so trying it here...
>
>
> 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:

0.0  Tex, Latex, or texi files if you already have them.  Why not
distribute them?  Just don't make the build dependent upon having the
build tools.  Build them only when --enable-maintainer-mode is set
during configure.

0.1  Man files.  Same as above.

> 1. HTML files?

Yes, definately.

> 2. DVI files?

Why?  This is generated from .tex, and is only used to generate ps and
pdf.  At one time you sent this file to a printer, but that was back
when I was a grad student, i.e. a loooooong time ago, when dinosaurs
roamed the earth.

It's just an intermediate file format, generated on the way from .tex
to .pdf.  Therefore, I think you should not distribute dvi.

> 3. PDF files?

Yes. Everybody has a reader now, and it's the universally accepted
format for distributing published documents (i.e. read only documents)
over the net.

(I expect I'll get flamed by somebody or another for this assertion.
But anybody who thinks otherwise is a kook, and I will not waste my
time arguing with them. Therefore, please don't bother arguing this
point unless you want to rant and foam alone -- I will not respond to
this point.)

> 4. PS files?

No.  Too large, and hard to read.  Yes, you can read it with
ghostview, but ghostview is a POS compared to pdf.  Why distribute .ps
if you are also distributing .pdf?

> My comment:  People should be able to read the docs doing
> anything else.  Requiring the tools to compile finished
> documentation adds another dependency.

Right on.  More dependencies = bad for end users.  Less dependencies =
good for end users.

> Does anyone use dvi files as anything but an intermediate
> format?  (either as a starting point or final product)

Not since the late 1980s, IIRC.

> Should there be another file, distributed next to the source
> one,  with finished docs?

Like what?

> 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.

No.  Too complicated.  Developers grabbing stuff out of CVS should be
expected to have all tools required for a build (i.e. all Latex stuff
and all other tools for building the docs from source).  Users,
however, who download distribution tarballs should be assumed to have
nothing beyond the bare minimum required to compile.  Having several
flavors or several tarballs of distributions is too complicated, and
some newbie will inevitably download the wrong tarball and it will
fail for him.  Then he will whine and complain.  Loudly.  On
geda-user.

KISS is the only way to minimize the chances this will happen.

> 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.
>
>
> What about regression test files?  (the test subdir).
>
> Does anyone actually use them?
> Does anyone else know how to interpret the results?

You do, I hope!

Actually, I have used some of your test files as examples when playing
around with making mods in gnucap.  Therefore, you should keep them.
But on the other hand, I am a developer. . . . .

> Comment:  With floating point, often you don't get an exact
> match.  I have seen it different between Intel and AMD
> processors.
>
> I looked at the GNU standards to see if there is a way they
> recommend.  I didn't see anything.
>
> What about generated "source" files?  These are files in C or
> whatever, that look like source, but are actually generated.
> My experience is that to include them tricks people into
> thinking they are source, causing more problems, but may allow
> them to build when a translation program (m4, awk,
> gnucap-modelgen, autoconf) is not available.
>
>
> I solicit opinions in this.  I have no bias toward any
> particular way of doing it.

Thanks!  I *do* have a bias:

*  For developers, you can require them to have all required build
tools, and they should grab the whole enchilada out of CVS.
Developers can be counted upon to be clueful.

*  For users, you should assume they don't have most tools, and the
source distribution tarballs should require only basic compilation
tools like gcc, make and all that.   Moreover, you should obey the
KISS principle for user distributions when thinking about what to
include, what to build, etc.

Of course, the reductio-ad-absurdium of my argument is that users
should just download .rpms or whatever.  And I do agree that if .rpm
(or whatever) was truly a cross-distro/cross-platform compatible
format, then it should be all that one should need.  Unfortunately,
it's not, so source tarballs remain as the one true cross-platform
method to distribute unix software.

Cheers,

Stuart