steven Mitchell writes:
First, in your email you wrote:
For the record, I believe that
(1) people who are stopped by something as small as the
allow-remote-paths bug or separate installation of XEmacs and the
packages are extremely unlikely to become developers
(2) ditto CUA keymap
I hadn't realized that the allow-remote-paths was part of a_
new-developer-test_.
It's not part of any test, and it's unfair to imply that I ever meant
that. I don't recall the thread in full, but that kind of statement
is invariably an answer to somebody who is suggesting that XEmacs
would be much more popular if we (ie, *not* the person making the
suggestion) would just fix X and Y.
Now, such bugs are worth fixing *because they're bugs*[1]. However,
that's all; I do not believe fixing them will improve developer
recruitment more than fixing any other bugs, and I object to people
lobbying for *others* to work on certain bugs on the grounds that it
would be good for XEmacs as a whole if *those* bugs were fixed at the
expense of other work that could be done, when I'm quite sure it's not.
I don't even think they'll help recruit non-developer *contributors*
very much (eg, people who rarely if ever contribute core code but do
contribute init file snippets and help people workaround known bugs on
the mailing list).
Later you go on to identify a class of bugs that I *do* consider more
important than other bugs: lack of and/or inaccurate documentation.
My first step after getting the message about allow-remote-paths
was to get help on the variable name. But the variable name was
not there. Tried the help on the menu which had different
keystrokes and still not there.
I'm not sure what you mean by "different keystrokes".[2]
But, yup. This is a problem with package systems in general. If you
don't have the package, you won't have the docs. This is very
frustrating when you're dealing with a variable like
`allow-remote-paths'. But at least XEmacs always distributes docs
with the package (if available)! Many OS distros don't. :-(
I was a little put out about the fact that the package system was
not part of the main XEmacs distribution at first, enough to get
the rest of the packages at least, but then read the counter
arguments (some from you) and was persuaded that the packages to
install the rest of the package system probably should not be
in the main distribution itself.
Well, no, that's not my argument. The question is "how big is the
fix?" In my estimate, a real fix would be quite large because it
involves fixing or working around some poor design decisions.
Eg, it would be easy enough to just drop some or all packages into the
source tarball, but that begs the question of where to install them.
The answer to that question currently is "that depends", so there will
need to be some more or less tricky logic in the configure script and
makefiles to get it to work smoothly. If it doesn't work smoothly,
the poor user is just playing the "mole" role in Whack-a-Mole. My
preference is to admit it's broken until it's fixed from the user's
point of view, rather than to fix symptoms and hope the problem won't
then pop up elsewhere. (Especially since we know it's a vain hope.)
that other people are at fault. I'm asking myself why *I* have
this problem and what is it that I do not know that is stopping me?
Uh, but you *didn't* let it stop you. *That* is the test.
I'm saying if the documentation was better, instead of written
for a certain minimum knowledge of XEmacs stuff, it would
put the cookies on the bottom shelf.
Sure, but you're preaching to the choir. In the last ten years I've
[re]written more documentation and tests for XEmacs than I have code,
and more documentation than anybody except Ben Wing. Writing usable
documentation is much harder than writing usable code[3], and getting
many developers to write any documentation at all is close to
impossible: they just disappear if you threaten not to apply their
patches without documentation.
First, information. I found a magnifying glass in the posts I
read, to help me find the clue I need: XEmacs -debug-paths.
That gives me a page of paths to different things. But the
missing information is a simple ASCII chart that shows where
XEmacs puts the various files.
There isn't such a chart for most systems because it's not simple
(there are 16 configure options to control the installation of the
XEmacs core documented in INSTALL, and a few more for packages),
unless you use the Windows installer. The installation locations can
be very flexibly configured, and in fact AFAIK the majority of actual
installations do not use the defaults.[4]
We do describe the defaults in the INSTALL file, in the "Configuring
the Installation Layout" and (strangely enough) "RUNNING MAKE"
sections. While that file could be better organized, I don't think
it's unreasonable to ask you to read the whole thing if you're having
problems installing (which includes getting XEmacs to run correctly
the first time, IMO YMMV).
An example of the fog of documentation is the term sumo tarballs.
I read and clearly remember the documentation saying we used to
distribute sumo tarballs (and my first windows installation 8-10
years ago was such a tarball, source + packages),
That timing doesn't make sense to me. From version 20.4 released in
February 1998 (almost 14 years ago), packages were distributed
separately from source. We still had a few binary kits up to that
time, but since then only Windows has had installers made. But the
Windows installers always include both a selection of packages and a
runnable XEmacs binary and auxiliary binaries. The selection of Lisp
packages has varied over time.
but we no longer distribute sumo tarballs, the editor and packages
are separate. OK got it.
That's weird. AFAICR, "sumo" was never used to refer to the GNU-style
editor bundled with all application libraries (used in XEmacs 19 and
20), at least not after the release of 20.4. From the first it was a
reference to the tarballs containing the full suite of packages, and
we've always provided those, except for some problems with hosting.
But this, and the next few things you refer to (required packages
missing from the list, references to outdated versions), are just
bugs. The people who actually know the package system well have done
some documentation, but more would be useful and the first drafts
weren't terribly helpful to beginners. I've done a little bit of work
on it myself, but it's hard work due to the historical confusion of
Unix-style installations and a lack of a coherent explanation of the
current design (which is a patch on the original design, and may be
hard to explain coherently...).
The point I am making is that the "people who are stopped by
something as small as the allow-remote-paths bug" don't have
the tools to solve the problem,
The most important tool is an email account, to ask for help on
xemacs-beta, though. When I talk about people allowing themselves to
be stopped, I'm referring to the people who Andreas says give up at
the installation stage or first-try stage, without even posting a
message to xemacs-beta.
I know, I know, who is going to contribute those things? It *is* a
bit of work.
It's more than just a bit of work, though. Stuff like Phil Sung's
Guided Tour is a labor of love. And you're very right about this:
And it is not *coding* work that the people who get past the
allow-remote-paths bug are more interested in.
Yeah, well, who *is* interested in doing that? We've got the Guided
Tour (and yes, I installed that, with a lot of encouragement from the
reviewers and xemacs-beta posters). But Sung is the only person I
know who has done anything like this for Emacsen.
on that too. I created an account, but when I try to upload an ssh
key they will not take one I created by copy/pasting it in and when
I browse to it instead of pasting, it does not take that ssh key
either and says invalid key both times.
That was a pain in the neck. I think it's a browser issue in part.
What I ended up doing was copy/pasting, and doing a little bit of
editing to get rid of (1) a leading space (I have no idea where that
came from), (2) a trailing newline because I dragged too far when
highlighting the region, and (3) some backslashes that came from the
terminal to indicate a wrapped line. But browsing to the file didn't
work, even trying several different files (maybe there were trailing
newlines in them, I didn't check to see if I could force Bitbucket to
take a file). I haven't tried to document it because it seems to work
for other people and I don't understand what went wrong.
So when I get past "something so small as the
allow-remote-paths"
problem, I will be working on learning some about ssh keys and what
makes one created on my machine be declared invalid. Are there
different kinds/levels?
I mention this as the kind of thing that is tripping me up.
Yeah, but it's not something *we* can do much about, except complain to
Bitbucket (which I've done with no change yet). Every host we've had
has caused this kind of problem.
ftp.xemacs.org currently has a
broken passive FTP setup.
cvs.debian.org doesn't work at all and
Debian has made no move to fix it; fortunately we could still checkout
from
anonscm.debian.org and move our CVS stuff to Mercurial.
Sourceforge kept losing our requests for more space, and broke various
of our more tricky configurations about twice a year by moving hosts
or changing their configuration or prohibiting shell logins, etc. And
on and on.
The best host we had was sunsite.dk but they went out of the business
of hosting open source (and even when they were operating they got hit
by lightning remarkably often!)
I guess one final point that I am trying to make is that the things
on your list that are holding people back (4 of them) are probably
not the things that are holding me back.
I didn't say they were holding people back, let alone any one person;
I said they were holding the project back. If I see on xemacs-beta
that something is holding at least a handful of people back, I'll
change my opinion about that, but in general I think individuals
should just post their problems to xemacs-beta.
I may not be typical, I just don't think I am alone and I
don't
think it is a small problem.
Again, that's unfair. I don't claim that it's a small problem. I've
always believed that documentation is a *big* problem, despite the
fact that documentation for Emacsen is actually better in most
respects you mention that for most open source software. Have you
ever tried to find how to configure something that isn't in the
preferences dialog in Firefox, or remove only selected cached
documents? Get OpenOffice to stop trying to restore documents that
(a) were on a removably disk in the first place and (b) since have
been renamed? Do *anything* with gconf? Figure out how anything
documented via gtkdoc works internally (vs learning APIs, which gtkdoc
is quite good at supporting IME)?
As far as I can tell, *all* open source projects have the problem that
documentation is mostly useful to those who already know how things
work.
XEmacs at least has two tutorials for users (TUTORIAL and the Guided
Tour), a User Guide, a Lisp Reference, and an Internals Manual (very
incomplete, but it's still the best reference available to both XEmacs
and GNU Emacs internals).
"/usr/local/lib/XEmacs-21.5-b31/x86_64-unknown-linux/"
Where did the unknown-linux come from?
config.guess in the source directory. This is the standard
CPU-VENDOR-OS architecture identifier used by all systems that use
configure scripts generated by autoconf.
Most modern GUI apps just use the app name and version to distinguish
their $prefix/lib subtrees, but XEmacs has historically had an
important use case where multiple versions for multiple platforms are
installed simultaneously on the same file system (perhaps mounted on
NFS), so we install into an architecture-specific directory by default.
But I have no standard directories and list of what-gets-put-where,
Again, try the INSTALL file.
Footnotes:
[1] If they are; these days I'm inclined to accept the argument that
defaulting to the traditional Emacs keymap vs. CUA is a bug, but in
1995 it was not, and even today there are a lot of Emacs users who
believe that the Emacs keymap is more efficient than CUA, so new users
should be "encouraged" to use traditional Emacs keymaps.
[2] My best guess is that the direct M-<letter> and the menu
accelerator Alt <letter> use different letters. This is a common
problem for menu accelerator systems[5], and AFAICS it's insoluble
because we basically map everything in the Meta map, often to actions
that might take several keystrokes via menu accelerators. Meta
letters will collide with the "intuitive" initials generally used in
the accelerator system.
[3] Although writing *good* code is harder than writing good
documentation.
[4] I don't know what they actually use, and I'm doubtful that there
are defaults that would work for a majority of installations, ie,
conforming to the various vendors' policies. :-(
[5] Keystrokes used to activate, navigate, and select actions from
GUI keymaps. "Accelerator" is a poor name with confusing connotations.
_______________________________________________
XEmacs-Beta mailing list
XEmacs-Beta(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-beta