7:09 p.m.
Feedback from
/Install/index.html
I'm having to reinstall <again> due to an SSD drive failure.
So I upgraded to slackware64 14.0 while I was at it, on a new drive.
Now I have to reinstall software and reconfigure everything, etc.
I lost the HG access and all of XEmacs (still have all data, just not
the program).
First, I want to reinstall XEmacs to bring peace and tranquility to my
life again.
I am writing to express some thoughts about the install instructions,
to show you what I have problems with installing and some suggestions
for improving the page. I do not have write access to the web page
to suggest/implement changes myself, and would in any case need help
from more experienced guys to correct the things I have wrong still.
1. the second sentence says "these instructions result in a non-mule
XEmacs."
That is not strictly true as if you look down the page, it says
what downloads
to get for a mule-XEmacs and where they should be installed.
This sentence should be modified to be true, or removed.
2. the next paragraph says "If you already have a working XEmacs of
version
21.1 or greater around, you may want to install the XEmacs build
package."
A. I don't know what the XEmacs build package is exactly. Doubt
many new
users do. But help me to know the "why" I might want to do
that so I can
determine if that is what I want to do.
B. I don't know what they mean by "around". I have it on a cdrom
near my computer
and I have it on the computer next to me, which also runs
linux. What
do they mean by around? Do they mean previously installed?
Then I
suggest we say that directly instead of "around".
C. the statement I may want to install the build package has no
alternative
thing I might want to do. Is the alternative not installing
the build package?
or is the alternative just installing XEmacs without the
build package?
They do not give clear statements about what 2 alternatives
are being
suggested.
3. The next paragraph starts with "Its documentation..." which is
somewhat ambiguous,
because there were 2 items mentioned in the previous
paragraph: XEmacs 21.1
and the XEmacs build package. Is it XEmacs 21.4's
documentation that gives
me the better understanding of the build process? Or is it
the XEmacs build
package's documention that gives me the better understanding?
I suggest we make it clearer which is intended.
4. The same paragraph says "better understanding...on Unix and Windows
alike,"
I don't think it adds to Linux install instructions to mention
Windows in a section
who's very first line says it is the instructions for UNIX and
Linux systems.
I suggest the windows word be removed for clarity in
presenting UNIX/Linux only
directions.
5. The next item, right after that paragraph, is a list of enumerated
steps to do
something. The previous two paragraphs talk about the build
process and
getting understanding from some documentation, etc. So do you
think the
enumerated steps are for something to do with the the XEmacs
build system?
It doesn't seem so, it seems the list is steps to install
XEmacs itself. I am
suggesting that the list of steps be given a title of some
kind, such as
"Steps to installing XEmacs" or maybe better:
"Steps to installing XEmacs on a UNIX or Linux System"
to remove doubt about what the steps are to do. And also
specify whether
the steps are for a non-mule or mule install, or both.
6. Step 1 says "Check out the list of optional external libraries
<http://www.xemacs.org/Download/optLibs.html>used by XEmacs.
Obtain, build, and configure any you do not have." That this is
the first step
is counter-intuitive. Do you decide to install firefox, and
the first thing you do
is go scour the internet and download and install the plugins,
and only then
install Firefox itself? That is backward, though you can
install libflashplayer.so
before firefox if you know which directories to make to put it
where it needs to be.
I suggest the we change the first step to be something like:
Step 1. Locate and download the following files:
-XEmacs source code
-XEmacs (necessary) packages
-External libraries to work with XEmacs.
first download step,
the XEmacs source for which version you want to install.
latest stable version 21.1.14 (as of <a date in this
year, not one 10 years ago>) found here (link).
latest beta version. 21.5.32 found here (link)
latest gamma version found here (link)
<statement that in previous versions you needed to
install 3 files for the source:
Source Tarball: XEmacs-<VERSION>.tar.gz
Lisp Tarball: xemacs-<VERSION>-elc.tar.gz
Info Documents Tarball: xemacs-<VERSION>-info.tar.gz
<statement that now these three files are included in 1
tarball and don't need to be downloaded separately>
<statement about the differences between stable,beta, adn
gamma>
second download step,
XEmacs needs a few basic packages to install enough of the
package system
to enable you to download any additional packages you may want.
These are required:
efs-*-pkg.tar.gz found here (link)
xemacs-base-*-pkg.tar.gz found here (link)
If you want to build XEmacs with Mule support, also download:
mule-base-*-pkg.tar.gz found here (link)
<statement that these files are the same whether you
install the stable,beta, or gamma.>
Third Download step,
XEmacs will use external libraries to add functionality for
XEmacs.
For example, it will work with certain graphic files if a
library is installed for
that graphic file format.
There is a list of external libraries that XEmacs can use
here (link)
Check out that list and see which libraries you would like to
have xemacs work with.
Install and configure them.
Note: these libraries should be installed and configured
before installing XEmacs
itself, so XEmacs can find them during installation.
Step 2. Now that you have all the files you need downloaded, and in the
case of external libraries,
downloaded, and installed, we are ready to install from source.
A. make a directory in your home directory for unpacking the files:
such as /home/<username>/tmp_xemacs
Ex: mkdir /home/<username>/tmp_xemacs.
B. copy the files you downloaded into that directory from
wherever you downloaded them to.
C. unpack the files.
the file, |xemacs-<VERSION>.tar.gz will by default unpack
itself to /usr/src/xemacs...<wherever it does it>
and that can be changed in arguments to ./configure in the next
step.
A command to do that would look like this:
<command to unpack the source with paths spelled out>
| The file xemacs-base-<version here>-pkg.tar.tgz will by default
be unpacked to <path to where base files go> |
A command to do that would look like this:
|<command to unpack the source with paths spelled out>|
|
| The file efs-*-pkg.tar.gz will by default be unpacked to <path
to where mule files go> |
A command to do that would look like this:
|<command to unpack the source with paths spelled out>
|
If you would prefer to install the above 3 files a different
location,
set the EMACSPACKAGEPATH environment variable to your
preferred location. Then extract the files in that location.
Don't forget to export the variable, and to add it to the
appropriate start up script for your system!
And so on, but that organization of steps into download everything you
need, put them somewhere (make a temporary directory so instructions can
be unambiguous, and say why you are asking them to do that), unpack them
(with example commands).
7. it has "; make" on the same line as ./configure, I suggest that
though
that is allowed, for simplicity and clarity in someone asking
for help
debugging things going wrong in the install, that we have the
"make" be a step of it's own.
8. where it says "Expand the above files into the directory used for
compiling,
e.g: gzip -dc xemacs-<VERSION>.tar.gz | tar xf -
this implies there is only one directory used for compiling and
gives a command that doesn't even show where that directory is.
I'm suggesting changing "the directory used for compiling" to
something more specific.
I'm suggesting giving an example that has that path in it so which
directory is clear.
9. the step that says: "Change to the directory where you expanded the
files, e.g. cd /usr/src/xemacs-<VERSION>
Where you expanded the files should say which files it is
mentioning since it has already made the point that
the regular file go to one directory and mule files go to another
directory.
10. Step 5 on the list says that "(This step does not apply to a native
Windows build.) should be removed
as the first line of this says these are directions to install on
a UNIX/Linux system. If it is worth mentioning,
then we should put it in a section for installing in Windows--so
users who need to know that can find it without
them having to read the UNIX/Linux install section to understand
the windows install directions.
11. the second part of step 5 says "After reading about all the
available options printed by
./configure --help
type:
./configure
[--OPTION[=VALUE]
...] [CONFIGURATION]
This is nowhere clear enough to a new user installing Xemacs.
There needs to be at least some text
explaining that almost every user will need to specify *some*
options to ./configure. Many users including me
the first time, was unsure which options I needed assumed, do
dsif,"well I'll just try the defaults and see how it goes".
I ended up reinstalling 2 more times to get the options right,
options I needed, while I didn't understand I needed *any*
options. I needed 4-5 options by the time I got it sorted out.
It would not be a bad idea to have an example configure
line showing what works for a good majority of people. Not for
them to copy directly, but a more wordy guide
with the example. And if that is too much for some, then at least
a line telling them that several options are required
for most people so they don;'t think they can get by without any.
12. Step 6 says to switch to the root account and type make install.
No mention has been made up to this point whether we are
installing for a single user or installing system wide.
I'm suggesting that somewhere in these instructions we say which
way these instructions are intended to install
and perhaps a sentence of how to install for the other choice (1
user or all users).
13. Step 6 also says "If you don't have root privilege, you may run
XEmacs in-placeafter typing 'make all'".
Why would I want to run XEmacs in place--is that the same as
running installed for a single user? or is running
in place something you do for troubleshooting the installation?
I suggest inserting a statement of at least one
reason to explain why you would want to run in place. And any
consequences of doing so.
14. Step 7 says "Fetch any of the above packages as documented in our
Release Notice Archive
<http://www.xemacs.org/Releases/index.html#Packages>." but if you go to
the link, it is just a list of change logs about 2 pages long.
How is a new user to easily find the how to fetch
the packages listed above? Navigating away from the page during
install instructions to a large list of other
text files seems to make the user "have to work for it" and make
it uphill to even get XEmacs installed.
since the download is on your own site, can you put a link
directly to it? like: found here <link> ?
15. Step 9 says "If you're trying XEmacs without installing it (|make
all|), start it with |./src/xemacs|from the
top-level directory in the XEmacs source tree.
since I am not clear on how to install this for 1 user vs for
all users, when it says trying Xemacs without installing it,
It seems I have already downloaded source files, unpacked them
and ./configure them, ran make,
and NOW I am trying it without installing it? I suggest that
the text be changed to include a cd <directory> example
to show where to change to before issuing the command
./src/xemacs. Sure, they could have changed that during the
install, but a statement like "top level in the XEmacs source
tree (by default /usr/src/xemacs-*-whatever)" might be
a good idea.
16. step 10 has comments about add download site vs set download site,
That's fine, but i suggest that most everybody installing
at this point in history is probably installing the 24.1 or
newer, so this step should have the directions saying directly to do
that, and
if someone thinks it is a good idea to include info about older
versions, they should be the aside, not what is instructions for current
versions.
17. Step 10 and 11 seem to be describing what to do after you have
installed XEmacs, that is, setting a download site and getting a list of
additional packages to install. As integral or necessary these
extra packages are for additional functionality, I suggest a statement
saying
that XEmacs is now installed, and something to the effect that
we are now going to install some extra packages, to mark the transition from
installing XEmacs directly to downloading and installing
additional packages beyond what was done in the install steps.
18. Just after step 15. it mentions that an easy way to get a
full-featured XEmacs you can download a sumo tarball. I heard tarballs
are not
distributed any more, so I am not sure that these directions
are still correct for a UNIX/Linux install.
In any case I suggest the words "full-featured" be replaced
with "an XEmacs with all packages installed" so we don't seem to be saying
that the other method does not create a less full-featured
Xemacs. Another point about the sumo tar-balls, is if this is really an
acceptable
alternative to installing from source, would it not be better
to tell the user doing the installing at the TOP of the install
instructions,
that there are 2 ways to install, instead of mentioning it here
at the end, after they have already done it the hard way. Raises feelings
"why didn't you tell me there was an easy way before I was done
with all the steps?
19. next paragraph after step 15 and the sumo stuff, says" The Sumo
tarballs are available from the same FTP directory as all the other XEmacs
packages." I suggest that a statement be added to say where
they are talking about, such as (by default install, that is
/usr/lib/wherever.
20. last paragraph, "To install the Sumo tarballs, simply unpack them
to: |/usr/local/lib/xemacs/" It would be nice if they had an
example command to do that|listed there, I am suggesting adding an
example command to the end of that section.
21. at the top of the page it has a date that is 10 years old. after
we update these directions, we should update the date on the directions.
at least 2 places on this page.
I apologize for my misspellings, miss-wordings, wrong path names, and
wrong-headed ideas. Feel free to correct me in my errors, and point out
paths I got wrong, procedures I have not yet understood, and everything
else I have not got right. I just want it to be easy for new users to
read the install instructions and get it right without troubles.
Steve Mitchell
_______________________________________________
XEmacs-Beta mailing list
XEmacs-Beta(a)xemacs.org
http://lists.xemacs.org/mailman/listinfo/xemacs-beta