Re: INSTALL file. Comments.

[Tim X <timx@nospam.dev.null>]

"Dave Pawson" <dave.pawson@gmail.com> writes:

> To take proper advantage of Emacs 21's mule-unicode charsets,
> This in the 22.1 version of emacs INSTALL file.
>

OK, thats not very helpful. It would seem the INSTALL file needs more work
to update it to emacs 22. Possibly worth a report to emacs-devel, or maybe
even the submission of a new or additional document. A significant problem
with open source is that developers are seldom interested in writing
documentation and often, when they do, its not that good. The problem is
that writing good documentation requires skill and practice - just because
your good at writing code doesn't mean your good at writing
documentation. There is a school of thought that argues that developers are
precisely the wrong people to write documentation because they are too
close to the system and have a familiarity which makes it difficult to
know/understand what others who don't have that familiarity will find
difficult.

I do think a few of your comments are misplaced/misdirected. For one thing,
you won't find any mention of deb or any other package system and nor
should you. The INSTALL docs in a source tree have to be distribution
neutral - there are too many different distros out there to be covered and
they change too often. There also has to be a certain level of assumed
knowledge. It could be argued that the current level is too high (I
personally don't think so), but there is a need for some assumed
knowledge. building form sources is not for the faint of hart and it is the
responsability of the person trying to build from source to know their
distribution and its package management system. I also think there is an
obligation to be familiar with the basic tools (make, configure, autoconf
etc) and the process. (configuring, compiling, linking etc). If the
documentation tried to cover all of this, its unlikely anyone would read it
because it would just be too vast (plus it would be impossible to keep up
to date). 

Given where you have come from and the freshness of your experience trying
to build from sources, I would *strongly* recommend you write a BEGINNERS
file and submit it to the emacs devel team for inclusion in the source
distribution. This would be a valuable contribution which could help others
in your position and a lot more valuable than posts to a newsgroup or
another webpage. It is likely you will be required to revise it a number of
times before it will be accepted, but if you can sustain the effort, it
could be very useful. You could even put the initial draft up on the emacs
wiki - maybe others will then contribute. I would suggest avoiding a step
by step guide as this is likely to get out of date very fast. What would
probably be more useful would be explinations and pointers to more
background information that a beginner could use to 'get up to speed' and
make more out of the INSTALL file. 

If you don't have the time/energy, I would still strongly encourage you to
send a post to the devel group with details of parts of the INSTALL file
which no longer seem relevant or appear to be only relevant to emacs
21 or which are a bit confusing. This is the area emacs needs help, but it
needs to be more than just pointing out the bits that are
wrong/outdated. Try to provide alternatives and corrections - this will
make it more likely that some/all will actually get into the file. Just
pointing out what is wrong/outdated is probably of no real help - the devel
team probably already knows about it, but lacks the resources to fix it. 

Tim

-- 
tcross (at) rapttech dot com dot au