Survex 1.0.39 released

[Andy Waddington]

On Wednesday 2006-01-18 14:06, Wookey wrote:

> It is difficult for the survex authors to adequately document the changing
> needs of all the software survex builds on. We barely have time to write and
> document survex itself. Expecting us to document the configuration issues of
> gtk, wxwindows, X etc, is probably going too far, convenient as it might be
> for you.

My main issue is that the download page purports to tell you what you need
to download and build, with a link to a source RPM which doesn't involve
you in visiting the wxwindows site at all, so you are never pointed at the
documentation for that. A sentence or two indicating that this stuff may
have dependencies not met by a base install of your platform and an
explicit link to the docs (or home page) for the wx stuff would be all
that was needed.

> Anyone building survex from source needs to know that they need 
> -dev packages. You can get a good idea which ones by looking at the survex
> debian packages, which do specify their build-dependencies. (surely rpms
> must have a mechanism for recording/reporting build-deps?)

Well binary RPMS seem quite good, (although often they will note a
dependency on a particular file, with no clue as to which package
might contain it). Building from source is presumably harder in
that you can build against numerous different versions (or even
different programs in some cases). The ./configure goes about
checking for what versions it has, but is not very good at telling
you what to do when it fails - this is, of course, nothing to do
with Survex, but a general failing in the RPM build system - it
is aimed more at developers than end users. In this case, it says
it is looking for a package which I do have, by searching for a
particular file which I don't. Presumably a package has been split
into smaller chunks ... this is clearly a problem that wxwindows
needs to address, not survex.

However, survex is only available as source for some platforms
(indeed it's available as binaries for very few Unices), whilst
these same platforms are striving towards a larger market share
in a user-space unfamiliar with building-from-source as an idiom.
One of the major obtacles to that market penetration is that people
read what appear to be simple instructions and believe that, OK, yes,
that sounds not too difficult, I'll try ... but when something goes
wrong there are no clues as to what to do next.

I'm not suggesting that Survex be accompanied by a forty page
HOWTO covering every conceivable problem (that would put the sort
of potential users we are discussing off completely), but when an
instruction says to download something external to a project, it
would be useful to point to places where more information could be
obtained. By pointing to the external project's documents, you are
not doing their documenting for them, and the requirement to keep
the link up to date is hardly more onerous than keeping the link to
the source RPM up to date.

Otherwise you are getting into the sort of user-friendliness
beloved of Microsoft whose instructions consist of "do this, it will
work"; "if it doesn't work, reboot your system yet again and retry";
"if the problem persists, ask your system administrator". Most computers
used for cave surveying are systems whose main user is also its system
administrator ... and the duplication of effort represented by each
and every one of them having to do a google search for help on how to
make some component of the system work, instead of following a single
link to useful documentation is exactly the sort of thing that hinders
take-up of open source. And when we do the google search, we find
bits of mailing lists where people have said "such-and-such doesn't
work, please help". Very few of these threads contain the answers,
which also makes it look as though the entire process is "difficult".
Sometimes there are no answers, you might eventually get to a
document which says, in effect, "this is a known issue and there are
no known solutions". But it may take two days of googling to find
things that hard ... if a problem is fundamentally a matter of
something simple like installing the right -devel packages, then
it should be easy to provide a pointer to positive-sounding docs
which will help.

Trying to second guess RPM package names from Debian ones in the debian
package dependencies is presumably just as difficult as trying it the
other way round ? I can do "rpm - --whatprovides <missing-file>" on a
system where that file isn't missing (if I am fortunate enough to have
more than one system, on one of which Survex or whatever I'm building
already works...) but that doesn't tell me the name of the debian package,
'cos these always seem to be subtly different. A better clue is probably
to use rpmsearch or rpmfind websites to look for packages containing the
relevant file ...

> If you want to write something in the light of what you have discovered for
> building survex 1.1 on RPM-based distros, then I'm sure we'd be happy to
> include it in the docs, but it will of course be wrong again in 6 months
> time.

Hopefully, providing a list of links to external docs would be no more
likely to be out of date than the link to the source RPM itself ... I'll
see what I can do, if I manage to build the program at all ...

but right now, I'm going to add "-v" and "-h" functionality at the command
line to an X program I develop, lest I seem terribly hypocritical ;-) I
probably ought to write a man page for it too, since the extensive html
documentation isn't much use when you're not running a windowing system...
My defence is that the program is a long way from even a beta release state.

Andy