Further developments w.r.t. KDevelop documentation nightmare.

[Paul Derbyshire]

At 02:50 AM 2/10/00 -0500, you wrote:
>The KDevelop binary RPM I got definitely didn't have its documentation...

Addendum: I've also discovered a few packages whose installation ignores
$KDEDIR and sticks the installed stuff in /opt/kde, when it should go in
$KDEDIR. Most packages DTRT but a few don't. Then you've got to issue a
bunch of mv's to transfer each subdirectory to $KDEDIR after installing one
of these packages. It would sure simplify things if mv had a command line
flag for recursive directory traversal that would create a target directory
for any source directory that didn't have one, and whether the target
directory existed beforehand or was created, recursively issue mv for all
files and directories therein...


>The en directory in the RPM itself has only a skeleton directory structure
>with no content -- no HTML files. I surmise this is an oversight made by the
>packager...

I'm not so sure now. I tried using symlinks to make the C/C++ reference
work at least and it won't. Suspicious, I investigated and sure enough,
there is a skeleton but no content. The C/C++ reference was downloaded
directly from the kdevelop team's own FTP site, so there are no middlemen
and hence cannot have been any errors by middlemen. This empty
documentation package was distributed directly by the kdevelop team. I
think that might be reasonably considered a dumbass error for which an
apology is owed.

In addition to indicating a path to working (i.e. at the very least not
corrupted with illegal characters!) sources for the most recent kdevelop to
work on kde 1.1.x/Qt 1.44, please also indicate paths to
* The C/C++ reference in a package (rpm preferred, otherwise tarball) that
  actually has content and not just a skeleton directory structure, and
* The Kdevelop user guide in a similar form, since it presumably doesn't come
  with the sources. Same requirement that the content actually be there.

No more documentation vaporware will be tolerated here, coming from anyone!

Do NOT tell me to go get the documentation packages, source packages, or
whatever from a) your FTP site or b) rpmfind.net, as clearly I can trust
neither. I have no way of telling which packages contain bad source files
and which contain no documentation content, and which actually work -- and
know of at least one package on each site that does not work. And I know of
no reason why there might not be many more broken packages with
missing/invalid files on either or both sites. I'm certainly not
downloading a package, rebooting quickly to Linux, installing it, finding
that that one doesn't work, rebooting very slowly to Windows, laboriously
downloading another alternative package, rebooting... for God only knows
how many cycles. And I think it's shameful that your prospective users find
themselves going through this sort of nonsense in the first place. I
understand your emphasis and focus with kdevelop work is on kdevelop itself
and not the installer and the packaging, but keep in mind that the
packaging and the installer are the first and second impressions of your
product that users will get. By common sense you should know the value of
making a good first (and second) impression. The most recent release of
kdevelop, and the most recent beta, both make very poor first impressions,
and neither I nor many developers will want to install and then put up with
the headaches of the unstable KDevelop 2 alpha (and the unstable KDE 2
alpha that is needed to run it) just to be able to read the freaking
documentation!

Tools should run and work perfectly out of the box; their sources should
configure and build out of the box. Even development tools. Even if the
vast majority of the pre-existing user base for the development tool in
question seems to be the team of hackers making KDE 2 who are thus experts
and very used to tweaking and cajoling stuff into building and finding
obscure stuff and trying and re-downloading stuff eight thousand times
over. If you want your user base to expand beyond the KDE core developers
themselves, you need a kdevelop that is easy to set up, and doesn't send
even the more stalwart would-be developers trying eight thousand things and
posting dozens of questions on the mailing lists while completely
frightening off the less stalwart. And if you want KDE to grow a large app
base you want your kdevelop user base to expand.

Of course, if you'd like KDE a year from now to still have a very tiny app
base, or want the existing KDE-core developers to have a monopoly on
providing KDE apps, then carry on the way things are going, and you can
guarantee that's what you'll get...


Special postscript for the kdevelop list:

I'd like to remind you of the kdevelop goals as stated on your own Web site.

"The goal of the KDevelop-Project is to provide an *easy to use* C/C++ IDE
(Integrated Development Enviroment) for Unix/X11/KDE. We all try to do our
best to reach this working together hand in hand, thus achieving the best
possible result for a working development environment to run under KDE."

(emphasis mine)

If the documentation is missing from many packages and the setup is
difficult in general, it's not easy to use. This needs work. And because
some people would like to start possibly developing some KDE apps
immediately without also migrating to the unstable KDE2, instead working
safely in KDE 1.1.x and thus using kdevelop 1.x, there needs to be some
improvement in the kdevelop 1.1.x package. I sure aren't sitting here in
this chair on this login screen tapping my foot, doing mailing list mail,
and occasionally grabbing a snack or a few hours of shuteye for four months
or a year or something until KDE2 is stable and safe enough to go into beta
testing!

I don't expect a major new 1.1.x release, just a maintenance pack that
addresses these issues/bugs/warts.

* Ship a source package that includes ALL the docs, except the kde-libs and Qt
  docs, which are generated anyways rather than prepackaged.
* Make sure the damned thing works! A serious fault like a non-ASCII character
  in a source file should certainly get discovered by even the most
preliminary
  testing. Test the install thoroughly. Make sure if a system has KDE 1.1.x,
  Qt 1.44, and the other requirements but no traces of kdevelop and the
  kdevelop package is untarred where it should be, then ./configure'd, make'd,
  and make install'd, the result is that kdevelop --setup works perfectly and
  subsequently kdevelop works perfectly including the documentation browser
  and the documentation itself is all there.
* Make sure the configure script creates a symlink /usr/doc/kde/HTML/default
  pointing to /usr/doc/kde/HTML/<the two letter code for the system locale>.
  If configure scripts can't determine the system locale, just use /en or
  prompt the guy who invoked the script for the two letter code. Using en
  should be safe, since English is the de facto lingua franca of the Internet.
  Prompting would be better just in case. Using the system locale setting, if
  you can, would be best.
* No /opt/kde nonsense. make install puts all the binaries in $KDEDIR/bin
  and the docs in /usr/doc/kde/HTML, while the shared stuff, such as icons,
  goes in $KDEDIR/share. Respect the $KDEDIR.
* For users of Debian and other distributions, issue a tarball, not a RPM;
  include an instruction file on the Web site and "next to" the tarball for
  where to untar it. Since everyone's using KDE and KFM and can browse into
the
  tarball before untarring it, you may put the instruction file in the
  tarball itself in its top level directory.
* Leave instructions for those that would redistribute it in RPMs, .debs,
  .pkgs, etc. to make damned sure they don't omit anything, mix in files from
  older versions, fail to respect $KDEDIR on install, or otherwise screw it
up.
  Obviously, packagers can't in general be trusted to DTRT on their own
without
  expert guidance from the authors that made whatever it is they are
packaging.

-- 
   .*.  "Clouds are not spheres, mountains are not cones, coastlines are not
-()  <  circles, and bark is not smooth, nor does lightning travel in a
   `*'  straight line."    -------------------------------------------------
        -- B. Mandelbrot  |http://surf.to/pgd.net derbyshire at globalserve.net
_____________________ ____|________                          Paul Derbyshire
Programmer & Humanist|ICQ: 10423848|