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