Re: INSTALL file. Comments.

Re: INSTALL file. Comments.

[David Kastrup]

"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.
>
>
> 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),
>
> No mention of debian/.deb on that page.

Is this a joke?  Use your package manager to install the package, for
example by saying

sudo apt-get install unifont

on a console, or by clicking System/Administration/Synaptic Package
manager or by doing whatever else is done to install a package on your
system.

It can't be the responsibility of INSTALL to teach you the minimal
working steps of your Linux distribution.

> <URL:http://openlab.ring.gr.jp/efont/> (packaged in Debian).
> Ditto, no mention of a debian package.

apt-cache search efont

spews out (among others)

xfonts-efont-unicode - /efont/ Unicode fonts for X which cover various scripts
xfonts-efont-unicode-ib - /efont/ Unicode fonts for X (italic and bold)

and of course, you can get similar information using Synaptic.  Again,
the Emacs INSTALL file can't be a 101 class on using your
distribution.

> General comment re fonts: No intimation of how emacs finds fonts,
> nor how they should be installed, either within the emacs code or
> how they are accessed from the system font locations.

Because just installing the packages will work.

> 3a) To build in the top-level Emacs source directory, go to that
> directory and run the program `configure' as follows:
>
>     ./configure [CONFIGURATION-NAME] [--OPTION[=VALUE]] ...
>
> Since there is a 'src' directory for source, perhaps a more accurate
> description would be
>
> 3) You can build Emacs in the top-level Emacs INSTALLTION directory
> or in a separate directory.

Wrong.  The installation directory is where things get installed.  The
src directory contains just C sources, which looking at it will
corroborate.

> 3a) To build in the top-level Emacs source directory, go to that
> directory and run the program `configure' as follows:
>
>     ./configure [CONFIGURATION-NAME] [--OPTION[=VALUE]] ...
>
>
> quote.
> If you don't want X support, specify `--with-x=no'.  If you omit this
> option, `configure' will try to figure out for itself whether your
> system has X, and arrange to use it if present.
>
> Not strictly true? X is only used if the dev libraries are present?
> My (as built) system had X, but no dev libraries.

Maybe.

> quote.
> To get more attractive menus, you can specify an X toolkit when you
> configure Emacs; use the option `--with-x-toolkit=TOOLKIT',
>
> Is that the whole story? Isn't it for more than 'attractive menus'?
> I.e. since there is no default (mentioned in INSTALL) am I right
> in thinking I'll build the nox version without this option?

No, you'll get a toolkit-less X compilation.

> Says, Use --without-sound to disable sound support.
> No mention of the --with-sound=yes option that was mentioned
> by a couple of people?

If you have the development libraries available, they will be used by
default.

> quote.
> If the description of the system configuration printed by `configure'
> is not right, or if it claims some of the features or libraries are not
> available when you know they are, look at the `config.log' file for
> the trace of the failed tests performed by `configure' to check
> whether these features are supported.
>
> This doesn't cover the case where the libraries are missing?

Why wouldn't it?

> Perhaps a note to indicate, for instance, what to look for when
> configure failed to find a library? Or even a simple statement,
> that, for instance 'nox will be built, since no X headers found' or
> some such?

Have you actually read the configure output?

> quote.
> 3b) To build in a separate directory, go to that directory
> and run the program `configure' as follows:
>
>     SOURCE-DIR/configure CONFIGURATION-NAME [--OPTION[=VALUE]] ...
>
>
> I'm not clear what is happening here. It *seems* to generate enough
> files to run make in the 'current' directory? I can run make from
> there quite happily?

Only from there.

> Does this mean that having built it, I can delete SOURCE-DIR
> completely?

You can always delete your source directories after installation if
you want to.  What is the point of your question?

> quote.
> 7) Run `make' in the top directory of the Emacs distribution
> This isn't true if I've run configure from another directory?
> Suggest  "Run 'make' from the directory in which you ran
> 'configure'"

Maybe.

> quote.
> 8) Check the file `dir' in your site's info directory (usually
> /usr/local/share/info) to make sure that it has a menu entry for the
> Emacs info files.
>
>
> suggest adding how this might be done?

It depends on the distribution/info setup.  So actually using a text
editor is the most portable thing to do.

> quote.
> You can change where the build process installs Emacs and its data
> files by specifying values for `make' variables as part of the `make'
> command line.
>
> I think this needs disambiguating from the configure param
> --prefix='/wherever/to/install'

Maybe one should warn that this should not be interesting for the
normal user, but just for package creators.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: INSTALL file. Comments.

[Tim X]

"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

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

Re: INSTALL file. Comments.

[Eli Zaretskii]

> Date: Mon, 10 Sep 2007 11:16:19 +0100
> From: "Dave Pawson" <dave.pawson@gmail.com>
> 
> > 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

Nor should it be, IMO.  Building Emacs from sources is actually very
simple, so I'd object to saying otherwise and risking to avert users
for no good reason.

The real problem (and this case just demonstrated it again) is to
configure a system that has the various support packages required for
you to be able to build sophisticated GUI programs.  But this problem
has nothing to do with Emacs: it is common to all GUI packages, some
of them need even more prerequisites than Emacs.

If I were a user of such a system, I'd first spend some time
downloading and installing every library and development package in
sight, prior to building anything of my own.

Re: INSTALL file. Comments.

[Eli Zaretskii]

> From: Tim X <timx@nospam.dev.null>
> Date: Mon, 10 Sep 2007 18:23:35 +1000
> 
> A significant problem
> with open source is that developers are seldom interested in writing
> documentation and often, when they do, its not that good.

But Emacs does not belong to the so-called ``open source'' movement,
so fortunately the above is not true for it.  I think Emacs
documentation is actually quite good.

Of course, there's always place for improvement (specific suggestions
are most welcome), which is why it's important to hear newbies instead
of mocking them.

INSTALL file. Comments.

[Dave Pawson]

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


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

No mention of debian/.deb on that page.

<URL:http://openlab.ring.gr.jp/efont/> (packaged in Debian).
Ditto, no mention of a debian package.

General comment re fonts: No intimation of how emacs finds fonts,
nor how they should be installed, either within the emacs code
or how they are accessed from the system font locations.


Further mentions of emacs 21 are made.
e.g. On Debian, the
packages necessary to build the installed version should be
sufficient; they can be installed using `apt-get build-dep emacs21' in
Debian 3 and above.

quote.
3) You can build Emacs in the top-level Emacs source directory
or in a separate directory.

3a) To build in the top-level Emacs source directory, go to that
directory and run the program `configure' as follows:

    ./configure [CONFIGURATION-NAME] [--OPTION[=VALUE]] ...

Since there is a 'src' directory for source, perhaps a more accurate
description would be

3) You can build Emacs in the top-level Emacs  INSTALLTION directory
or in a separate directory.

3a) To build in the top-level Emacs source directory, go to that
directory and run the program `configure' as follows:

    ./configure [CONFIGURATION-NAME] [--OPTION[=VALUE]] ...


quote.
If you don't want X support, specify `--with-x=no'.  If you omit this
option, `configure' will try to figure out for itself whether your
system has X, and arrange to use it if present.

Not strictly true? X is only used if the dev libraries are present?
My (as built) system had X, but no dev libraries.

quote.
To get more attractive menus, you can specify an X toolkit when you
configure Emacs; use the option `--with-x-toolkit=TOOLKIT',

Is that the whole story? Isn't it for more than 'attractive menus'?
I.e. since there is no default (mentioned in INSTALL) am I right
in thinking I'll build the nox version without this option?

Says, Use --without-sound to disable sound support.
No mention of the --with-sound=yes option that was mentioned
by a couple of people?


quote.
If the description of the system configuration printed by `configure'
is not right, or if it claims some of the features or libraries are not
available when you know they are, look at the `config.log' file for
the trace of the failed tests performed by `configure' to check
whether these features are supported.

This doesn't cover the case where the libraries are missing?
Perhaps a note to indicate, for instance, what to look for
when configure failed to find a library? Or even a simple
statement, that, for instance 'nox will be built, since no X headers found'
or some such?


quote.
3b) To build in a separate directory, go to that directory
and run the program `configure' as follows:

    SOURCE-DIR/configure CONFIGURATION-NAME [--OPTION[=VALUE]] ...


I'm not clear what is happening here. It *seems* to generate enough
files to run make in the 'current' directory? I can run make from
there quite happily?
Does this mean that having built it, I can delete SOURCE-DIR completely?
Would be useful if I've done a make install?
This just for clarification.


quote.
7) Run `make' in the top directory of the Emacs distribution
This isn't true if I've run configure from another directory?
Suggest  "Run 'make' from the directory in which you ran 'configure'"


quote.
8) Check the file `dir' in your site's info directory (usually
/usr/local/share/info) to make sure that it has a menu entry for the
Emacs info files.


suggest adding how this might be done?
$cat /usr/local/share/info/dir | grep Emacs:
should show something like
$ cat /usr/local/share/info/dir |grep Emacs:
* Emacs: (emacs).                       The extensible self-documenting text


quote.
You can change where the build process installs Emacs and its data
files by specifying values for `make' variables as part of the `make'
command line.

I think this needs disambiguating from the configure param
--prefix='/wherever/to/install'

I'm unclear what the difference is? One places 'source' files
ready for the build process, the other executable (and other files
used during execution perhaps)

quote.
`archlibdir' indicates where Emacs installs and expects the executable
	files and other architecture-dependent data it uses while
	running.  Its default value, based on `libexecdir' (which
	see),

Is that a typo? Xref missing?

Nice to have feature:
Re MAKE VARIABLES
It would be nice to see guidance for users putting 'another' emacs
on their system, perhaps to say how all the variables can be
set such that the new values point to some non-standard location
and it's subdirectories therefrom?

No comments on the dos versions. Not used.

HTH


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

Re: INSTALL file. Comments.

[Peter Dyballa]

Am 09.09.2007 um 16:29 schrieb Dave Pawson:

> <URL:http://openlab.ring.gr.jp/efont/> (packaged in Debian).
> Ditto, no mention of a debian package.

There are volunteers on the net that provide lists of packages of  
this or that format for this or that flavour or version of some Linux  
distribution. Do you have an idea how many GNU Emacs packages of only  
one GNU Emacs version might exist?

This is certainly a task for the user of a particular operating  
system. There might be an users group that might provide package  
information for some particular flavour of some version of an OS.

>
> General comment re fonts: No intimation of how emacs finds fonts,
> nor how they should be installed, either within the emacs code
> or how they are accessed from the system font locations.

X11. Unless otherwise stated (MS Windows variants, Mac OS variants,  
GEM, AmigaOS ... "Unicode Emacs").

>
> If you don't want X support, specify `--with-x=no'.  If you omit this
> option, `configure' will try to figure out for itself whether your
> system has X, and arrange to use it if present.
>
> Not strictly true? X is only used if the dev libraries are present?
> My (as built) system had X, but no dev libraries.

There are no dev libraries, at least I haven't found any, except when  
built for a special purpose (profiled, with extended debug content,  
for static linkage). Libraries are mostly shared libraries that are  
loaded once into memory and then used by a handful of programmes or  
applications at the same or at a different time.

X11 is probably the most widely used windowing system. It is  
something native to GNU Emacs, like Emacs Lisp.

>
> quote.
> To get more attractive menus, you can specify an X toolkit when you
> configure Emacs; use the option `--with-x-toolkit=TOOLKIT',
>
> Is that the whole story? Isn't it for more than 'attractive menus'?
> I.e. since there is no default (mentioned in INSTALL) am I right
> in thinking I'll build the nox version without this option?

There aren't so many other differences visible. Now that you know how  
to get and install necessary packages and how to configure and  
compile GNU Emacs you can create variants based on GTK, OSF/Motif  
(Lesstif), without Xaw3d, or using OpenLook (from Sun) ...

>
> Says, Use --without-sound to disable sound support.
> No mention of the --with-sound=yes option that was mentioned
> by a couple of people?

./configure --help gives a helpful general hint that --with- 
something=no can mean the same as --without-something. A look inside  
the configure script, or running it as in 'sh -x ./configure ...' can  
give some insight.

>
> quote.
> If the description of the system configuration printed by `configure'
> is not right, or if it claims some of the features or libraries are  
> not
> available when you know they are, look at the `config.log' file for
> the trace of the failed tests performed by `configure' to check
> whether these features are supported.
>
> This doesn't cover the case where the libraries are missing?

It does.

> Perhaps a note to indicate, for instance, what to look for
> when configure failed to find a library?

This is exactly indicated by configure's use of a set of two letters:  
'no.'

> Or even a simple statement, that, for instance 'nox will be built,  
> since no X headers found' or some such?

That's as clear as in 'when the sun is not found shining, it's not  
bright outside.' Then it's night (mostly). A natural state. (The  
other case is a natural state, too.)

>
> quote.
> 3b) To build in a separate directory, go to that directory
> and run the program `configure' as follows:
>
>     SOURCE-DIR/configure CONFIGURATION-NAME [--OPTION[=VALUE]] ...
>
>
> I'm not clear what is happening here. It *seems* to generate enough
> files to run make in the 'current' directory? I can run make from
> there quite happily?

Cd into the mac directory and see the script make-package. In case  
you can create a virtual Darwin guest inside your Ubuntu (or Fedora  
Core) PC you can start to compile another variant of GNU Emacs to see  
that ...

> Does this mean that having built it, I can delete SOURCE-DIR  
> completely?

... it is needed. The compiler reads the C source files from the  
original directory and only puts its output into the new side  
directory. (Carbon Emacs for Mac OS X won't be compiled because the  
free Darwin OS does not contain the proprietary Carbon API. Darwin  
uses X11 as windowing system.)

> Would be useful if I've done a make install?

Yes, of course. Therefore most UNIX distributions offer to use  
packages. This even saves you from removing a whole tree of software.

>
> quote.
> 7) Run `make' in the top directory of the Emacs distribution
> This isn't true if I've run configure from another directory?
> Suggest  "Run 'make' from the directory in which you ran 'configure'"
>

Somehow 'going to school' also includes visiting a college – at least  
in the U.S.A.

>
> Nice to have feature:
> Re MAKE VARIABLES
> It would be nice to see guidance for users putting 'another' emacs
> on their system, perhaps to say how all the variables can be
> set such that the new values point to some non-standard location
> and it's subdirectories therefrom?

It is expected that those who try to experiment with configure  
options have some experience and enough phantasy to imagine the  
consequences of their deeds.


It would make more sense to describe how to create a (local) package  
from the compiled software. This is a more sensible use of a packages  
oriented OS (I did so in Solaris and Fedora Core 1). This way the  
package management can be kept from removing or updating some shared  
library some application uses. It can also make compilation easier  
(in Mac OS X I have a few versions of libfreetype; packages that  
depend on a particular version of libfreetype have the proper paths  
set automatically; non-packaged software like xdvipdfmx or xetex are  
not so easy to satisfy and to compile).

--
Greetings

   Pete

"America believes in education: the average professor earns more money
in a year than a professional athlete earns in a whole week." – Evan
Esar

Re: INSTALL file. Comments.

[Dave Pawson]

[-- Attachment #1: Type: text/plain, Size: 5407 bytes --]

On 09/09/2007, Peter Dyballa <Peter_Dyballa@web.de> wrote:
>
> Am 09.09.2007 um 16:29 schrieb Dave Pawson:
>
> > <URL:http://openlab.ring.gr.jp/efont/> (packaged in Debian).
> > Ditto, no mention of a debian package.
>
> There are volunteers on the net that provide lists of packages of
> this or that format for this or that flavour or version of some Linux
> distribution. Do you have an idea how many GNU Emacs packages of only
> one GNU Emacs version might exist?

Please don't infer what I have not written.
I stated that the document was incorrect. What inferences you make is
your issue.
If you wish to tell readers to seek a package for the fonts, say so.
It is factually wrong.


> >
> > General comment re fonts: No intimation of how emacs finds fonts,
> > nor how they should be installed, either within the emacs code
> > or how they are accessed from the system font locations.
>
> X11. Unless otherwise stated (MS Windows variants, Mac OS variants,
> GEM, AmigaOS ... "Unicode Emacs").

This information is omitted from the document.
It would be helpful IMHO.


>
> >
> > If you don't want X support, specify `--with-x=no'.  If you omit this
> > option, `configure' will try to figure out for itself whether your
> > system has X, and arrange to use it if present.
> >
> > Not strictly true? X is only used if the dev libraries are present?
> > My (as built) system had X, but no dev libraries.
>
> There are no dev libraries, at least I haven't found any, except when
> built for a special purpose (profiled, with extended debug content,
> for static linkage). Libraries are mostly shared libraries that are
> loaded once into memory and then used by a handful of programmes or
> applications at the same or at a different time.

The document tells half a tale. I'd suggest that the user needs
to be informed that 'some' libraries are needed for X support.




> >
> > quote.
> > To get more attractive menus, you can specify an X toolkit when you
> > configure Emacs; use the option `--with-x-toolkit=TOOLKIT',
> >
> > Is that the whole story? Isn't it for more than 'attractive menus'?
> > I.e. since there is no default (mentioned in INSTALL) am I right
> > in thinking I'll build the nox version without this option?
>
> There aren't so many other differences visible. Now that you know how
> to get and install necessary packages and how to configure and
> compile GNU Emacs you can create variants based on GTK, OSF/Motif
> (Lesstif), without Xaw3d, or using OpenLook (from Sun) ...

"Now that I know" being the operative phrase?
I'm reviewing this as a user who doesn't know, I.e. as I first came to it.


>
> >
> > Says, Use --without-sound to disable sound support.
> > No mention of the --with-sound=yes option that was mentioned
> > by a couple of people?
>
> ./configure --help gives a helpful general hint that --with-
> something=no can mean the same as --without-something. A look inside
> the configure script, or running it as in 'sh -x ./configure ...' can
> give some insight.

Again my comment was against the document. It informs of a negative
option. IMHO it should document the positive one too to inform the user.
There is no mention of, for instance, we expect you to be familiar with
configure options.


>
> >
> > quote.
> > If the description of the system configuration printed by `configure'
> > is not right, or if it claims some of the features or libraries are
> > not
> > available when you know they are, look at the `config.log' file for
> > the trace of the failed tests performed by `configure' to check
> > whether these features are supported.
> >
> > This doesn't cover the case where the libraries are missing?
>
> It does.

My experience is that it does not.


>
> > Perhaps a note to indicate, for instance, what to look for
> > when configure failed to find a library?
>
> This is exactly indicated by configure's use of a set of two letters:
> 'no.'

I'd suggest the caveat is 'if you've been there and done that'.
Interpreting the no is a whole new ball game.


>
> > Or even a simple statement, that, for instance 'nox will be built,
> > since no X headers found' or some such?
>
> That's as clear as in 'when the sun is not found shining, it's not
> bright outside.' Then it's night (mostly). A natural state. (The
> other case is a natural state, too.)

In which case tell the user what the 'natural state' is.



> > Does this mean that having built it, I can delete SOURCE-DIR
> > completely?
>
> ... it is needed. The compiler reads the C source files from the
> original directory and only puts its output into the new side
> directory. (Carbon Emacs for Mac OS X won't be compiled because the
> free Darwin OS does not contain the proprietary Carbon API. Darwin
> uses X11 as windowing system.)

But post make it can be deleted? Space saver?
Unclear IMHO



> >
> > quote.
> > 7) Run `make' in the top directory of the Emacs distribution
> > This isn't true if I've run configure from another directory?
> > Suggest  "Run 'make' from the directory in which you ran 'configure'"
> >
>
> Somehow 'going to school' also includes visiting a college – at least
> in the U.S.A.

The document is incorrect and has nowt to do with the us.



>
>
> It would make more sense to describe how to create a (local) package
> from the compiled software.


Possibly. I wouldn't know Peter.



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

[-- Attachment #2: Type: text/plain, Size: 152 bytes --]

_______________________________________________
help-gnu-emacs mailing list
help-gnu-emacs@gnu.org
http://lists.gnu.org/mailman/listinfo/help-gnu-emacs