Re: INSTALL file. Comments.

[Dave Pawson]

On 10/09/2007, Tim X <timx@nospam.dev.null> wrote:
> "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.

<chuckles/> Yep. Often the devs find it hard to take a newbie viewpoint.
Someone else suggested doing battle on the emacs-devel list.
>From the cracks I've had here I'm not tempted.


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'd suggest that's a general truth. Viewing a technology from n years
experience of in-depth use is quite different from a new users viewpoint.


>
> 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.

I quoted one Tim? from the INSTALL document?
<quote>To take proper advantage of Emacs 21's mule-unicode charsets, you need
a suitable font.  For `Unicode' (ISO 10646) fonts for X, see
<URL:http://czyborra.com/unifont/> (packaged in Debian),</quote>

I interpret that as 'go to this uri and you'll find debian packaged fonts.
3 people on this list seem to interpret that differently.



 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.

I'm happy with that. IMHO it might answer the question 'how do I get
these fonts'
to which a distro neutral answer could be generated.


>  There also has to be a certain level of assumed
> knowledge.

Which seems to be the confrontational issue on this list?
Lots of people presume all users know most things about their own distro.
I'd suggest such a group are a minority today. Certainly decreasing.
If that's an assumption, list the areas of assumption in the document
and warn users of the consequences "don't come to this list for help,
you'll get abused soundly"

 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.

Not made clear in any emacs docs IMHO


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).

In which case simple pointers would suffice.
The decision then is how wide to take that advice. I'd suggest it needs
to be as wide as the build process takes it.  How long would the list
of pointers be? Ten lines?

>
> 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.

Until this morning I was prepared to re-install Ubuntu and document
the experience. I'm far less tempted now.


 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.

Echoing Davids remarks. Unfortunately, for me to learn enough to document
it I needed help which this list has provided - for which I'm grateful.
It seems I disturbed the calm with my ignorance.

 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.

Quite agree. Having written before (isbn0-596-00355-2) I know the
loops! The harder part is retaining the standpoint of the fresh face
at the task. The more times
round the loop, the more the perspective moves towards that of you guys.


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.

Outline.
Overview.
Table of mappings from missing items to packages, 1 col per distro known
procedure.
steps
options.

Probably taking the INSTALL file approach, basics, then links to indepth
sections. I.e. the INSTALL file, in html, with links out to extra pages.
  configure options
  make options
  overall choices (graphics choice for example)
  distro pages.
    specifics for a particular distro, including the gotchas



>
> 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.

I thought that's what I'd done. Seems I'm judged wrong in that.
No devs on this list I guess?
Ah well.

Your gentler input appreciated Tim

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk