This is ../info/xemacs-faq.info, produced by makeinfo version 4.8 from
xemacs-faq.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* FAQ: (xemacs-faq).            XEmacs FAQ.
END-INFO-DIR-ENTRY


File: xemacs-faq.info,  Node: Q7.1.6,  Next: Q7.1.7,  Prev: Q7.1.5,  Up: Advanced

Q7.1.6: What is the typical misuse of `setq'?
---------------------------------------------

A typical misuse is probably `setq'ing a variable that was meant to be
local.  Such a variable will remain bound forever, never to be
garbage-collected.  For example, the code doing:

     (defun my-function (whatever)
       (setq a nil)
       ... build a large list ...
       ... and exit ...)

   does a bad thing, as `a' will keep consuming memory, never to be
unbound.  The correct thing is to do it like this:

     (defun my-function (whatever)
       (let (a)                              ; default initialization is to nil
         ... build a large list ...
         ... and exit, unbinding `a' in the process  ...)

   Not only is this prettier syntactically, but it makes it possible for
Emacs to garbage-collect the objects which `a' used to reference.

   Note that even global variables should not be `setq'ed without
`defvar'ing them first, because the byte-compiler issues warnings.  The
reason for the warning is the following:

     (defun flurgoze nil)                    ; ok, global internal variable
     ...

     (setq flurghoze t)                      ; ops!  a typo, but semantically correct.
                                             ; however, the byte-compiler warns.

     While compiling toplevel forms:
     ** assignment to free variable flurghoze


File: xemacs-faq.info,  Node: Q7.1.7,  Next: Q7.1.8,  Prev: Q7.1.6,  Up: Advanced

Q7.1.7: I like the `do' form of cl, does it slow things down?
-------------------------------------------------------------

It shouldn't.  Here is what Dave Gillespie has to say about cl.el
performance:

     Many of the advanced features of this package, such as `defun*',
     `loop', and `setf', are implemented as Lisp macros.  In
     byte-compiled code, these complex notations will be expanded into
     equivalent Lisp code which is simple and efficient.  For example,
     the forms

          (incf i n)
          (push x (car p))

     are expanded at compile-time to the Lisp forms

          (setq i (+ i n))
          (setcar p (cons x (car p)))

     which are the most efficient ways of doing these respective
     operations in Lisp.  Thus, there is no performance penalty for
     using the more readable `incf' and `push' forms in your compiled
     code.

     _Interpreted_ code, on the other hand, must expand these macros
     every time they are executed.  For this reason it is strongly
     recommended that code making heavy use of macros be compiled. A
     loop using `incf' a hundred times will execute considerably faster
     if compiled, and will also garbage-collect less because the macro
     expansion will not have to be generated, used, and thrown away a
     hundred times.

     You can find out how a macro expands by using the `cl-prettyexpand'
     function.


File: xemacs-faq.info,  Node: Q7.1.8,  Next: Q7.1.9,  Prev: Q7.1.7,  Up: Advanced

Q7.1.8: I like recursion, does it slow things down?
---------------------------------------------------

Yes.  The Emacs byte-compiler cannot do much to optimize recursion.  But
think well whether this is a real concern in Emacs.  Much of the Emacs
slowness comes from internal mechanisms such as redisplay, or from the
fact that it is an interpreter.

   Please try not to make your code much uglier to gain a very small
speed gain.  It's not usually worth it.


File: xemacs-faq.info,  Node: Q7.1.9,  Next: Q7.1.10,  Prev: Q7.1.8,  Up: Advanced

Q7.1.9: How do I put a glyph as annotation in a buffer?
-------------------------------------------------------

Here is a solution that will insert the glyph annotation at the
beginning of buffer:

     (make-annotation (make-glyph '([FORMAT :file FILE]
                                    [string :data "fallback-text"]))
                      (point-min)
                      'text
                      (current-buffer))

   Replace `FORMAT' with an unquoted symbol representing the format of
the image (e.g. `xpm', `xbm', `gif', `jpeg', etc.)  Instead of `FILE',
use the image file name (e.g.
`/usr/local/lib/xemacs-21.4/etc/recycle.xpm').

   You can turn this to a function (that optionally prompts you for a
file name), and inserts the glyph at `(point)' instead of `(point-min)'.


File: xemacs-faq.info,  Node: Q7.1.10,  Next: Q7.1.11,  Prev: Q7.1.9,  Up: Advanced

Q7.1.10: `map-extents' won't traverse all of my extents!
--------------------------------------------------------

I tried to use `map-extents' to do an operation on all the extents in a
region.  However, it seems to quit after processing a random number of
extents.  Is it buggy?

   No.  The documentation of `map-extents' states that it will iterate
across the extents as long as FUNCTION returns `nil'.  Unexperienced
programmers often forget to return `nil' explicitly, which results in
buggy code.  For instance, the following code is supposed to delete all
the extents in a buffer, and issue as many `fubar!' messages.

     (map-extents (lambda (ext ignore)
                    (delete-extent ext)
                    (message "fubar!")))

   Instead, it will delete only the first extent, and stop right there -
because `message' will return a non-nil value.  The correct code is:

     (map-extents (lambda (ext ignore)
                    (delete-extent ext)
                    (message "fubar!")
                    nil))


File: xemacs-faq.info,  Node: Q7.1.11,  Next: Q7.2.1,  Prev: Q7.1.10,  Up: Advanced

Q7.1.11: My elisp program is horribly slow.  Is there an easy way to find out where it spends time?
---------------------------------------------------------------------------------------------------

Hrvoje Niksic <hniksic@xemacs.org> writes:

     Under XEmacs 20.4 and later you can use `M-x profile-key-sequence',
     press a key (say <RET> in the Gnus Group buffer), and get the
     results using `M-x profile-results'.  It should give you an idea of
     where the time is being spent.

7.2: Mathematics
================


File: xemacs-faq.info,  Node: Q7.2.1,  Next: Q7.2.2,  Prev: Q7.1.11,  Up: Advanced

Q7.2.1: What are bignums, ratios, and bigfloats in Lisp?
--------------------------------------------------------

Thanks to Jerry James <james@xemacs.org>, XEmacs 21.5.18 and later can
use the capabilities of multiple-precision libraries that may be
available for your platform.  The GNU Multiple Precision (GMP),
Multiple Precision Integers and Rationals (MPIR), and BSD Multiple
Precision (MP) libraries are supported.  GMP and MPIR give you
"bignums" (arbitrary precision integers), "ratios" (arbitrary precision
fractions), and "bigfloats" (arbitrary precision floating point
numbers).  GMP and MPIR are better-supported by XEmacs.  BSD MP support
does not include ratios or bigfloats.

   In most cases, bignum support should be transparent to users and Lisp
programmers.  A bignum-enabled XEmacs will automatically convert from
fixnums to bignums and back in pure integer arithmetic, and for GMP and
MPIR, from floats to bigfloats.  (Bigfloats must be explicitly coerced
to other types, even if they are exactly representable by less precise
types.)  The Lisp reader and printer have been enhanced to handle
bignums, as have the mathematical functions.  Rationals (fixnums,
bignums, and ratios) are printed using the `%d', `%o', `%x', and `%u'
format conversions.  The read syntax for ratios is `3/5'.

   User-visible changes in behavior include (in probable order of
annoyance)

   * Arithmetic can cause a segfault, depending on your MP library
     *Note XEmacs segfaults when I use very big numbers!: Q7_2_2.

   * Terminology is not Common-Lisp-conforming.  For example, "integer"
     for Emacs Lisp means what Common Lisp calls "fixnum".  This issue
     is being investigated, but the use of "integer" for fixnum is
     pervasive and may cause backward-compatibility and
     GNU-Emacs-compatibility problems.

   * Many operations that used to cause a range error now succeed, with
     intermediate results and return values coerced to bignums as
     needed.

   * An atom with ratio read syntax now returns a number, not a symbol.

   * The `%u' format conversion will now give an error if its argument
     is negative.  (Without MP, it prints a number which Lisp can't
     read.)

   _Surgeon General's Warning_: The automatic conversions cannot be
disabled at runtime.  New functions have been added which produce
ratios, so there should be few surprises with type conflicts, but they
can't be ruled out.  "Arbitrary" precision means precisely what it
says.  If you work with extremely large numbers, your machine may
arbitrarily decide to hand you an unpleasant surprise rather than a
bignum *Note XEmacs segfaults when I use very big numbers!: Q7_2_2.

   To configure with GMP, add `--enable-bignum=gmp' to your invocation
of `configure'.  For MPIR, use `--enable-bignum=mpir'.  For BSD MP, use
`--enable-bignum=mp'.


File: xemacs-faq.info,  Node: Q7.2.2,  Next: Q7.2.3,  Prev: Q7.2.1,  Up: Advanced

Q7.2.2: XEmacs segfaults when I use very big numbers!
-----------------------------------------------------

GMP by default allocates temporaries on the stack.  If you run out of
stack space, you're dead; there is no way that we know of to reliably
detect this condition, because `alloca' is typically implemented to be
_fast_ rather than robust.  If you just need a little more oomph, use a
bigger stack (_e.g._, the `ulimit -s' command in bash(1)).  If you want
robustness at the cost of speed, configure GMP with `--disable-alloca'
and rebuild the GMP library.

   We do not know whether BSD MP uses `alloca' or not.  Please send any
information you have as a bug report (`M-x report-xemacs-bug <RET>'),
which will give us platform information.  (We do know that BSD MP
implementations vary across vendors, but how much, we do not know yet.)


File: xemacs-faq.info,  Node: Q7.2.3,  Next: Q7.2.4,  Prev: Q7.2.2,  Up: Advanced

Q7.2.3: Bignums are really slow!
--------------------------------

Many Unix and Linux distributions compile all packages for a generic
version of the supported CPU, and this is costly.  An optimized version
can improve responiveness dramatically; see
`http://gmplib.org/gmpbench.html'.)


File: xemacs-faq.info,  Node: Q7.2.4,  Prev: Q7.2.3,  Up: Advanced

Q7.2.4: Equal bignums don't compare as equal!  What gives?
----------------------------------------------------------

Ah, Grasshopper, I see you are using `(eq x y)'.  The Bodhisattva CLTL2
warned of the illusion that equal numbers would be `eq'!  Meditate on
the deeper truths of `eql', in which numbers of the same type which
have equal values compare equal, and `=', which does any necessary type
coercions before comparing for equality.

   Yeah, yeah, it has always worked for integer types, because fixnums
and characters have an immediate representation.  Sorry about that;
arbitrary precision obviously requires consing new objects because the
objects are "large" and of variable size, and the definition of `eq'
does not permit different objects to compare as equal.


File: xemacs-faq.info,  Node: Other Packages,  Next: Current Events,  Prev: Advanced,  Up: Top

8 Other External Packages
*************************

This is part 8 of the XEmacs Frequently Asked Questions list.  This
section is devoted to miscellaneous external packages not covered
elsewhere in XEmacs.

* Menu:

8.0: TeX
* Q8.0.1::    Is there something better than LaTeX mode?
* Q8.0.2::    What is AUCTeX?  Where do you get it?
* Q8.0.3::    Problems installing AUCTeX.
* Q8.0.4::    How do I turn off current chapter from AUCTeX modeline?

8.1: Other Unbundled Packages
* Q8.1.1::    Is there a reason for an Emacs package not to be included in XEmacs?
* Q8.1.2::    Are there any Emacs Lisp Spreadsheets?
* Q8.1.3::    Is there a MatLab mode?

8.2: Environments Built Around XEmacs
* Q8.2.1::    What are SPARCworks, EOS, and WorkShop?
* Q8.2.2::    How do I start the Sun Workshop support in XEmacs 21?
* Q8.2.3::    What is/was Energize?
* Q8.2.4::    What is Infodock?

8.0: TeX
========


File: xemacs-faq.info,  Node: Q8.0.1,  Next: Q8.0.2,  Prev: Other Packages,  Up: Other Packages

Q8.0.1: Is there something better than LaTeX mode?
--------------------------------------------------

David Kastrup <dak@fsnif.neuroinformatik.ruhr-uni-bochum.de> writes:

     The standard TeX modes leave much to be desired, and are somewhat
     leniently maintained.  Serious TeX users use AUCTeX (*note What is
     AUCTeX? Where do you get it?: Q8_0_2.).


File: xemacs-faq.info,  Node: Q8.0.2,  Next: Q8.0.3,  Prev: Q8.0.1,  Up: Other Packages

Q8.0.2: What is AUCTeX?  Where do you get it?
---------------------------------------------

AUCTeX is a complex and sophisticated editing package dedicated to TeX
and related text formatting languages, including LaTeX and Texinfo.  It
provides support for running TeX on a file or part of a file, include
files, and of course shortcuts for entering common TeX macros, LaTeX
environments, etc, and for fontlock.

   AUCTeX is a standard package provided by XEmacs.  You can get it as
usual through the `M-x list-packages' interface.  It is also included
in the (non-Mule) SUMO package.  The AUCTeX XEmacs package is
maintained by Uwe Brauer <GET MAIL ADDRESS>.

   AUCTeX is extremely complicated, and its developers primarily use
GNU Emacs.  Not all features of the bleeding edge version of AUCTeX are
immediately ported to XEmacs; if you need these, you may be better off
getting the most recent versions from the GNU AUCTeX project on
`http://savannah.gnu.org'.


File: xemacs-faq.info,  Node: Q8.0.3,  Next: Q8.0.4,  Prev: Q8.0.2,  Up: Other Packages

Q8.0.3: Problems installing AUCTeX.
-----------------------------------

Jan Vroonhof <vroonhof@math.ethz.ch> writes:

     AUCTeX works fine on both stock Emacs and XEmacs has been doing so
     for a very very long time. This is mostly due to the work of Per
     Abrahamsen <abraham@dina.kvl.dk> (clap clap) in particular his
     `easymenu' package.  Which leads to what is probably the problem...

   Most problems with AUCTeX are one of two things:

   * The TeX-lisp-directory in `tex-site.el' and the makefile don't
     match.

     Fix: make sure you configure AUCTeX properly *before* installing.

   * You have an old version of easymenu.el in your path.

     Fix: use `locate-library' and remove old versions to make sure it
     *only* finds the one that came with XEmacs.


File: xemacs-faq.info,  Node: Q8.0.4,  Next: Q8.1.1,  Prev: Q8.0.3,  Up: Other Packages

Q8.0.4: How do I turn off current chapter from AUCTeX modeline?
---------------------------------------------------------------

With AUCTeX, fast typing is hard because the current chapter, section
etc. are given in the modeline.  How can I turn this off?

   It's not AUCTeX, it comes from `func-menu' in `func-menu.el'.

   David Hughes <dhughes@origin-at.co.uk> writes:

     Try this; you'll still get the function name displayed in the
     modeline, but it won't attempt to keep track when you modify the
     file. To refresh when it gets out of synch, you simply need click
     on the `Rescan Buffer' option in the function-menu.

          (setq-default fume-auto-rescan-buffer-p nil)

8.1: Other Unbundled Packages
=============================


File: xemacs-faq.info,  Node: Q8.1.1,  Next: Q8.1.2,  Prev: Q8.0.4,  Up: Other Packages

Q8.1.1: Is there a reason for an Emacs package not to be included in XEmacs?
----------------------------------------------------------------------------

The reason for an Emacs package not to be included in XEmacs is usually
one or more of the following:

  1. The package has not been ported to XEmacs.  This will typically
     happen when it uses GNU-Emacs-specific features, which make it
     fail under XEmacs.

     Porting a package to XEmacs can range from a trivial amount of
     change to a partial or full rewrite.  Fortunately, the authors of
     modern packages usually choose to support both Emacsen themselves.

  2. The package has been decided not to be appropriate for XEmacs.  It
     may have an equivalent or better replacement within XEmacs, in
     which case the developers may choose not to burden themselves with
     supporting an additional package.

     Each package bundled with XEmacs means more work for the
     maintainers, whether they want it or not.  If you are ready to
     take over the maintenance responsibilities for the package you
     port, be sure to say so--we will more likely include it.

  3. The package simply hasn't been noted by the XEmacs development.  If
     that's the case, the messages like yours are very useful for
     attracting our attention.

  4. The package was noted by the developers, but they simply haven't
     yet gotten around to including/porting it.  Wait for the next
     release or, even better, offer your help.  It will be gladly
     accepted and appreciated.


File: xemacs-faq.info,  Node: Q8.1.2,  Next: Q8.1.3,  Prev: Q8.1.1,  Up: Other Packages

Q8.1.2: Are there any Emacs Lisp Spreadsheets?
----------------------------------------------

Yes.  Check out "dismal" (which stands for Dis' Mode Ain't Lotus) at
`http://acs.ist.psu.edu/dismal/dismal.html'.


File: xemacs-faq.info,  Node: Q8.1.3,  Next: Q8.2.1,  Prev: Q8.1.2,  Up: Other Packages

Q8.1.3: Is there a MatLab mode?
-------------------------------

Yes, a matlab mode and other items are available at the
`http://www.mathworks.com/matlabcentral/files/104/matlab.el'.

8.2: Environments Built Around XEmacs
=====================================


File: xemacs-faq.info,  Node: Q8.2.1,  Next: Q8.2.2,  Prev: Q8.1.3,  Up: Other Packages

Q8.2.1: What are SPARCworks, EOS, and WorkShop?
-----------------------------------------------

SPARCworks was a development environment from Sun (circa 1993-1996) and
consisted of compilers (C, C++, FORTRAN 77, Fortran 90, Ada, and
Pascal), a debugger, and other tools such as TeamWare (for
configuration management), MakeTool, etc.

   EOS is the integration of XEmacs with the SPARCworks debugger.  It
allows one to use an XEmacs frame to view code (complete with
fontification, etc.), set breakpoints, print variables, etc., while
using the SPARCworks debugger.

   EOS stands for "Era on SPARCworks"; Era stood for "Emacs Rewritten
Again" and was the name used by Sun for its modified version of Lucid
Emacs (later XEmacs) in the early-mid 90's.  This is documented in more
detail in the history section of the XEmacs About page.

   EOS was replaced around 1996 with a newer graphical development
environment called Sun WorkShop.  The current status of this is unknown.


File: xemacs-faq.info,  Node: Q8.2.2,  Next: Q8.2.3,  Prev: Q8.2.1,  Up: Other Packages

Q8.2.2: How do I start the Sun Workshop support in XEmacs 21?
-------------------------------------------------------------

Add the switch --with-workshop to the configure command when building
XEmacs and put the following in one of your startup files (e.g.
site-start.el or .emacs):

     (when (featurep 'tooltalk)
       (load "tooltalk-macros")
       (load "tooltalk-util")
       (load "tooltalk-init"))
     (when (featurep 'sparcworks)
       (load "sunpro-init")
       (load "ring")
       (load "comint")
       (load "annotations")
       (sunpro-startup))

   If you are not using the latest Workshop (5.0) you have to apply the
following patch:

-- /opt/SUNWspro/lib/eserve.el.ORIG    Fri May 14 15:23:26 1999
+++ /opt/SUNWspro/lib/eserve.el Fri May 14 15:24:54 1999
@@ -42,7 +42,7 @@
 (defvar running-xemacs nil "t if we're running XEmacs")
 (defvar running-emacs  nil "t if we're running GNU Emacs 19")

-(if (string-match "^\\(19\\|20\\)\..*\\(XEmacs\\|Lucid\\)" emacs-version)
+(if (string-match "\\(XEmacs\\|Lucid\\)" emacs-version)
     (setq running-xemacs t)
     (setq running-emacs  t))


File: xemacs-faq.info,  Node: Q8.2.3,  Next: Q8.2.4,  Prev: Q8.2.2,  Up: Other Packages

Q8.2.3: What is/was Energize?
-----------------------------

The "Energize Programming System" was a C and C++ development
environment sold by Lucid, Inc.  It was the reason why Lucid Emacs, now
XEmacs, was created in the first place.  Unfortunately, Lucid went out
of business in 1994.  The rights to sell it in Japan were purchased by
INS Engineering (which briefly employed Stig Hackvan aka Jonathan
Stigelman to work on Japanese support for XEmacs, in late 1994 and
early 1995) and Tartan bought the rights to sell it in the rest of the
world.  However, INS is not selling Energize at this point and may or
may not have ever done so; Tartan certainly never did.


File: xemacs-faq.info,  Node: Q8.2.4,  Prev: Q8.2.3,  Up: Other Packages

Q8.2.4: What is Infodock?
-------------------------

InfoDock (http://sourceforge.net/projects/infodock/) is an integrated
productivity toolset, mainly aimed at technical people, hosted at
SourceForge.

   InfoDock is built atop the XEmacs variant of GNU Emacs and so has
all of the power of Emacs, but with an easier to use and more
comprehensive menu-based user interface.  The bottom portion of this
text describes how it differs from XEmacs and GNU Emacs from the Free
Software Foundation.

   InfoDock is aimed at people who want a free, turn-key productivity
environment.  Although InfoDock is customizable, it is not intended for
people who like basic versions of Emacs which need to be customized
extensively for local use; standard Emacs distributions are better for
such uses.  InfoDock is for those people who want a complete,
pre-customized environment in one package, which they need not touch
more than once or twice a year to update to new revisions.

   InfoDock is pre-built for SPARC SunOS/Solaris systems, PA-RISC HP-UX,
and Intel Linux systems.  It is intended for use on a color display,
although most features will work on monochrome monitors.  Simply unpack
InfoDock according to the instructions in the ID-INSTALL file and you
are ready to run.

   The InfoDock Manual is concise, yet sufficient as a user guide for
users who have never used an Emacs-type editor before.  For users who
are already familiar with Emacs, it supplements the information in the
GNU Emacs Manual.

   InfoDock menus are much more extensive and more mature than standard
Emacs menus.  Each menu offers a `Manual' item which displays
documentation associated with the menu's functions.

Four types of menubars are provided:
  1. An extensive menubar providing access to global InfoDock commands.

  2. Mode-specific menubars tailored to the current major mode.

  3. A simple menubar for basic editing to help novices get started
     with InfoDock.

  4. The standard XEmacs menubar.

   Most modes also include mode-specific popup menus.  Additionally,
region and rectangle popup menus are included.

   `Hyperbole', the everyday information manager, is a core part of
InfoDock.  This provides context-sensitive mouse keys, a rolodex-type
contact manager, programmable hypertext buttons, and an autonumbered
outliner with embedded hyperlink anchors.

   The `OO-Browser', a multi-language object-oriented code browser, is a
standard part of InfoDock.

   InfoDock saves a more extensive set of user options than other Emacs
versions.

   InfoDock inserts a useful file header in many file types, showing the
author, summary, and last modification time of each file.  A summary
program can then be used to summarize all of the files in a directory,
for easy MANIFEST file creation.

   Your working set of buffers is automatically saved and restored (if
you answer yes to a prompt) between InfoDock sessions.

   Refined color choices for code highlighting are provided for both
dark and light background display frames.

   The `C-z' key prefix performs frame-based commands which parallel the
`C-x' key prefix for window-based commands.

   The Smart Menu system is included for producing command menus on dumb
terminals.

   Lisp libraries are better categorized according to function.

   Extensions and improvements to many areas of Emacs are included,
such as: paragraph filling, mail reading with Rmail, shell handling,
outlining, code highlighting and browsing, and man page browsing.

   InfoDock questions, answers and discussion should go to the mail list
<infodock@infodock.com>.  Use <infodock-request@infodock.com> to be
added or removed from the list.  Always include your InfoDock version
number when sending help requests.


File: xemacs-faq.info,  Node: Current Events,  Next: Legacy Versions,  Prev: Other Packages,  Up: Top

9 What the Future Holds
***********************

This is part 9 of the XEmacs Frequently Asked Questions list.  This
section will change frequently, and (in theory) should contain any
interesting items that have transpired recently. (But in practice it's
not getting updated like this.)

   This section also contains descriptions of the new features in all
the recent releases of XEmacs.  For the most part, the information
below is a synopsis of the more complete information that can be found
in the file `NEWS' in the `etc' directory of the XEmacs distribution.
You can view this file in XEmacs using `C-h n' or the `Help' menu.

   Information on older versions of XEmacs can be find in `ONEWS' in
the same directory, or `OONEWS' for really old versions.

* Menu:

9.0: Changes
* Q9.0.1::    What new features will be in XEmacs soon?
* Q9.0.2::    What's new in XEmacs 21.4?
* Q9.0.3::    What's new in XEmacs 21.1?
* Q9.0.4::    What's new in XEmacs 20.4?
* Q9.0.5::    What's new in XEmacs 20.3?
* Q9.0.6::    What's new in XEmacs 20.2?

9.0: Changes
============


File: xemacs-faq.info,  Node: Q9.0.1,  Next: Q9.0.2,  Prev: Current Events,  Up: Current Events

Q9.0.1: What new features will be in XEmacs soon?
-------------------------------------------------

#### Write me.


File: xemacs-faq.info,  Node: Q9.0.2,  Next: Q9.0.3,  Prev: Q9.0.1,  Up: Current Events

Q9.0.2: What's new in XEmacs 21.4?
----------------------------------

21.4 was the "stable" version of the 21.2 series, which was considered
"experimental" throughout its life; thus there were no "official"
releases at all.  In essence, XEmacs is now following the "alternating"
scheme of Linux, where at any point there are at least two different
development branches, one "stable" and one "experimental".  Periodic
releases happen in both branches, but those in the experimental branch
are not tested as well, and there's no guarantee they will work at all.
The experimental branch is open to any and all code that's acceptable
to the developers; the stable branch, however, is in general limited
only to bug fixes, and all contributions are carefully reviewed to make
sure they will increase and not decrease stability.

   21.3 never existed at all; it was decided to follow the Linux scheme
exactly, where odd-numbered series are experimental and even-numbered
ones stable.

   The following lists summarizes the essential changes made in this
version.  For a fuller list, see the `NEWS' in the `etc' directory of
the XEmacs distribution, or use `C-h n' or the `Help' menu to view this
file inside of XEmacs.

User-visible changes in XEmacs 21.4
...................................

   * The delete key now deletes forward by default.

   * Shifted motion keys now select text by default.

   * You can now build XEmacs with support for GTK+ widget set.

   * ~/.xemacs/init.el is now the preferred location for the init file.
     (XEmacs now supports a `~/.xemacs/init.el' startup file. Custom
     file will move to ~/.xemacs/custom.el.)

   * Much-improved sample init.el, showing how to use many useful
     features.

   * XEmacs support for menu accelerators has been much improved.

   * Default menubar improvements. (Default menubar has many new
     commands and better organization.  The font-menu is now available
     under MS Windows.)

   * Dialog box improvements, including a real file dialog box. (XEmacs
     now has a proper file dialog box under MS Windows (and GTK)!  The
     old clunky file dialog box is improved.  Keyboard traversal now
     works correctly in MS Windows dialog boxes.  There is a Search
     dialog box available from `Edit->Find...')

   * New buffer tabs.

   * There is a new MS Windows installer, netinstall, ported from
     Cygwin.

   * The subprocess quote-handling mechanism under Windows is much
     improved.

   * Printing support now available under MS Windows.

   * Selection improvements. (Kill and yank now interact with the
     clipboard under Windows.  MS Windows support for selection is now
     much more robust.  Motif selection support is now more correct
     (but slower).)

   * Mail spool locking now works correctly.

   * International support changes. (The default coding-priority-list
     is now safer.  International keysyms are now supported under X.
     MS Windows 1251 code page now supported.  Czech, Thai,
     Cyrillic-KOI8, Vietnamese, Ethiopic now supported.  Proper support
     for words in Latin 3 and Latin 4.)

   * Help buffers contain hyperlinks, and other changes.

   * The modeline's text is now scrollable.

   * The mouse wheel under MS Windows now functions correctly.

   * Interactive searching and matching case improvements. (Incremental
     search will now highlight all visible matches.  Interactive
     searches always respect uppercase characters.)

   * Rectangle functions rewritten to avoid inserting extra spaces.

   * New command `kill-entire-line' that always kills the entire line.

   * Default values correctly stored in minibuffer histories.

   * You can now create "indirect buffers", like in GNU Emacs.

   * Pixel-based scrolling has been implemented.

   * Operation progress can be displayed using graphical widgets.

   * User names following a tilde can now be completed at file name
     prompts.

   * XEmacs can now play sound using Enlightenment Sound Daemon (ESD).

   * X-Face support is now available under MS Windows.

   * The PostgreSQL Relational Database Management System is now
     supported.

   * Indentation no longer indents comments that begin at column zero.

   * Face and variable settings can have comments in Customize.

   * New locations for early package hierarchies.

   * The `auto-save' library has been greatly improved.

   * New variable `mswindows-alt-by-itself-activates-menu'.

   * Other init-file-related changes. (Init file in your home directory
     may be called `.emacs.el'.  New command-line switches
     -user-init-file and -user-init-directory.)

   * Etags changes.  See `NEWS' for full details.

Lisp and internal changes in XEmacs 21.4
........................................

Not yet written.


File: xemacs-faq.info,  Node: Q9.0.3,  Next: Q9.0.4,  Prev: Q9.0.2,  Up: Current Events

Q9.0.3: What's new in XEmacs 21.1?
----------------------------------

21.1 was the "stable" version of "experimental" 21.0 series.  *Note
What's new in XEmacs 21.4?: Q9_0_2.

   The following lists summarizes the essential changes made in this
version.  For a fuller list, see the `NEWS' in the `etc' directory of
the XEmacs distribution, or use `C-h n' or the `Help' menu to view this
file inside of XEmacs.

User-visible changes in XEmacs 21.1
...................................

   * XEmacs is now supported under Microsoft Windows 95/98 and Windows
     NT/2000/XP operating systems.  To discuss Windows-specific issues,
     subscribe to the mailing list at <xemacs-winnt-request@xemacs.org>.

   * XEmacs has been unbundled into constituent installable packages.

   * *Other notable changes*: The `Options' menu has been ported to
     Custom; XEmacs now is able to choose X visuals and use private
     colormaps; You can drag the vertical divider of "horizontally"
     (side-by-side) split windows.

   * *Building changes*: XEmacs can be built with support for 31-bit
     Lisp integers and 32-bit pointers (previously, it was 28-bit
     integers and pointers); XEmacs can be built with LDAP support;
     `dir' files can be removed in the Info subsystem, and will be
     regenerated on-the-fly.

   * *New packages*: `imenu', `popper', `gdb-highlight'

   * *Package changes*: Many changes to `cc-mode', `gnus', `gnuclient'.
     See `NEWS' for full details.

   * *New commands, variables and functions*: `center-to-window-line'
     (like `recenter' but doesn't force a redisplay); variable
     `user-full-name' (customize what your full name looks like in
     mail); `M-x customize-changed-options' (customize options whose
     default values changes because you upgraded your XEmacs); `M-x
     add-log-convert' (converts an old-style ChangeLog buffer to
     new-style); `M-x zap-up-to-char' (like `zap-to-char' but doesn't
     delete the char searched for); commands to store, retrieve and
     increment numbers in registers, useful for macros.

   * *Changes to commands, variables, and functions*: `M-x
     query-replace' and friends operate only on the region when it's
     active; `echo-keystrokes' can now be a floating-point number; `M-.'
     searches exact tag matches before inexact ones; function
     `user-full-name' with no arguments returns the var
     `user-full-name'; a prefix arg to `M-:' and `C-h c' inserts the
     result in the current buffer.

   * *Other changes*: Under X, new application class `XEmacs';
     byte-compilation of user-specs now works.

   * *XEmacs/Mule (internationalization) changes*: Mule support now
     works on TTY's; Egg/SJ3 input method now officially supported
     (Quail and Egg/Skk already available through LEIM since 20.3);
     localized Japanese menubars if XEmacs is built with the right
     support.


Lisp and internal changes in XEmacs 21.1
........................................

   * *Specifier changes*: The window locale now has a higher precedence
     than the buffer locale when instantiating; new macro
     `let-specifier'; new specifiers `vertical-scrollbar-visible-p',
     horizontal-scrollbar-visible-p', `scrollbar-on-left-p',
     `scrollbar-on-top-p', `vertical-divider-always-visible-p',
     `vertical-divider-shadow-thickness',
     `vertical-divider-line-width', `vertical-divider-spacing';
     specifiers and symbols whose value is a specifier allowed as
     modeline specifications.

   * *Frame focus changes*: `focus-follows-mouse' works like FSF,
     prevents any attempt to permanently change the selected frame; new
     function `focus-frame' sets the window system focus a frame; new
     macros `save-selected-frame' and `with-selected-frame'.

   * *Window function changes*: `select-window' now has optional
     argument NORECORD to inhibit recording a buffer change;
     `vertical-motion' now correctly handles optional WINDOW argument
     and has new optional argument PIXELS, to have the returned values
     be in pixels; new function `vertical-motion-pixels'; new functions
     `window-text-area-pixel-{width,height,edges}'; new functions
     `shrink-window-pixels' and `enlarge-window-pixels'; new function
     `window-displayed-text-pixel-height'.

   * *Other function changes*: Arithmetic comparison functions `<',
     `>', `=', `/=' now accept a variable number of arguments;
     hashtables now have a consistent read/print syntax; keyword
     symbols cannot be set to a value other than themselves; `concat' no
     longer accepts integer arguments; new function `string', like
     `list', `vector', etc.; new function `temp-directory'
     (OS-independent way to get a temp directory); `load-average' has
     optional argument USE-FLOATS; `make-event' implemented completely;
     new function `function-interactive' (returns a function's
     interactive spec); new functions `lmessage', `lwarn' (printf-like
     versions of `display-wessage', `display-warning'); new keyword
     `:version' to `defcustom'.

   * *Performance*: when the new GNU Malloc aka Doug Lea Malloc is
     available, it will be used (better performance on libc6 Linux
     systems); tracking line-numbers in modeline is now efficient;
     profiling records a call-count of all called functions,
     retrievable through `profile-call-count-results'.

   * *Startup and path searching*: code to assemble paths at startup
     rewritten for new package system; new function `split-path' (splits
     by `path-separator'); `Info-default-directory-list' obsolete, use
     `Info-directory-list' instead; site-lisp is deprecated and no
     longer on the load-path by default.



File: xemacs-faq.info,  Node: Q9.0.4,  Next: Q9.0.5,  Prev: Q9.0.3,  Up: Current Events

Q9.0.4: What's new in XEmacs 20.4?
----------------------------------

XEmacs 20.4 is a bugfix release with no user-visible changes.


File: xemacs-faq.info,  Node: Q9.0.5,  Next: Q9.0.6,  Prev: Q9.0.4,  Up: Current Events

Q9.0.5: What's new in XEmacs 20.3?
----------------------------------

XEmacs 20.3 was released in November 1997. It contains many bugfixes,
and a number of new features, including Autoconf 2 based configuration,
additional support for Mule (Multi-language extensions to Emacs), many
more customizations, multiple frames on TTY-s, support for multiple info
directories, an enhanced gnuclient, improvements to regexp matching,
increased MIME support, and many, many synches with GNU Emacs 20.

   The XEmacs/Mule support has been only seriously tested in a Japanese
locale, and no doubt many problems still remain.  The support for
ISO-Latin-1 and Japanese is fairly strong.  MULE support comes at a
price--about a 30% slowdown from 19.16.  We're making progress on
improving performance and XEmacs 20.3 compiled without Mule (which is
the default) is definitely faster than XEmacs 19.16.

   XEmacs 20.3 is the first non-beta v20 release, and will be the basis
for all further development.


File: xemacs-faq.info,  Node: Q9.0.6,  Prev: Q9.0.5,  Up: Current Events

Q9.0.6: What's new in XEmacs 20.2?
----------------------------------

The biggest changes in 20.2 include integration of EFS (the next
generation of ange-ftp) and AUC Tex (the Emacs subsystem that includes a
major mode for editing Tex and LaTeX, and a lot of other stuff).  Many
bugs from 20.0 have been fixed for this release.  20.2 also contains a
new system for customizing XEmacs options, invoked via `M-x customize'.

   XEmacs 20.2 is the development release (20.0 was beta), and is no
longer considered unstable.

   For older news, see the file `ONEWS' in the `etc' directory of the
XEmacs distribution.


File: xemacs-faq.info,  Node: Legacy Versions,  Next: Bleeding Edge,  Prev: Current Events,  Up: Top

10 New information about old XEmacsen
*************************************

This is part 10 of the XEmacs Frequently Asked Questions list.  It will
occasionally be updated to reflect new information about versions which
are no longer being revised by the XEmacs Project.  The primary purpose
is advice on compatibility of older XEmacsen with new packages and
updated versions of packages, but bug fixes (which will not be applied
to released XEmacsen, but users can apply themselves) are also accepted.

* Menu:

10.0: XEmacs 21.1
* Q10.0.1::   Gnus 5.10 won't display smileys in XEmacs 21.1.
* Q10.0.2::   XEmacs won't start on Windows in XEmacs 21.1.

10.0: XEmacs 21.1
=================


File: xemacs-faq.info,  Node: Q10.0.1,  Next: Q10.0.2,  Prev: Legacy Versions,  Up: Legacy Versions

Q10.0.1: Gnus 5.10 won't display smileys in XEmacs 21.1.
--------------------------------------------------------

Eric Eide <eeide@cs.utah.edu> wrote:

     Previously I wrote:

     Eric> Summary: with Gnus 5.10.1 in XEmacs 21.1.14, I don't see
     Eric> any smileys :-(.

     After a bit of sleuthing, I discovered the essence of the problem.
     For me, the form:

              	(with-temp-buffer
              	  (insert-file-contents "foo.xpm")
              	  (buffer-string))

     returns the empty string.  This is because something somewhere
     replaces the XPM data with a glyph -- I haven't figured out where
     this occurs.

   Kyle Jones <kyle_jones@wonderworks.com> replies:

     Do this:

              (setq format-alist nil)

     The image-mode stuff is gone from format-alist in the 21.4 branch,
     praise be.


File: xemacs-faq.info,  Node: Q10.0.2,  Prev: Q10.0.1,  Up: Legacy Versions

Q10.0.2: XEmacs won't start on Windows in XEmacs 21.1.
------------------------------------------------------

XEmacs relies on a process called "dumping" to generate a working
executable. Under MS-Windows this process effectively fixes the memory
addresses of information in the executable. When XEmacs starts up it
tries to reserve these memory addresses so that the dumping process can
be reversed - putting the information back at the correct addresses.
Unfortunately some .DLLs (for instance the soundblaster driver) occupy
memory addresses that can conflict with those needed by the dumped
XEmacs executable. In this instance XEmacs will fail to start without
any explanation. Note that this is extremely machine specific.

   21.1.10 includes a fix for this that makes more intelligent guesses
about which memory addresses will be free, and this should cure the
problem for most people.  21.4 implements "portable dumping", which
eliminates the problem altogether.  We recommend you use the 21.4
binaries, but you can use the 21.1 binaries if you are very paranoid
about stability.  *Note Are binaries available?: Q1_1_2.


File: xemacs-faq.info,  Node: Bleeding Edge,  Prev: Legacy Versions,  Up: Top

10 Working with XEmacs Source Code Repositories.
************************************************

This is part 11 of the XEmacs Frequently Asked Questions list.  The
primary purpose is advice on use of the version control systems used to
keep the history of XEmacs development.

* Menu:

11.0: The XEmacs repositories
* Q11.0.1::   Where is the most recent XEmacs development code?
* Q11.0.2::   Where is the most recent XEmacs stable code?
* Q11.0.3::   Where is the most recent XEmacs package code?
* Q11.0.4::   Why isn't PACKAGE available? and what to do about it.
* Q11.0.5::   How do I get commit access?

11.1: Working with CVS
* Q11.1.1::   How do I keep cool using CVS?

11.2: Working with Mercurial
* Q11.2.1::   What is Mercurial?
* Q11.2.2::   Where do I get Mercurial?
* Q11.2.3::   Do I really have to waste space on history?
* Q11.2.4::   `hg diff' gives bizarre output.
* Q11.2.5::   How do I recover from a bad commit?  (I already pushed.)
* Q11.2.6::   How do I recover from a bad commit?  (I haven't pushed yet.)
* Q11.2.7::   Testing patches with Mercurial Queues.

11.0: The XEmacs repositories
=============================


File: xemacs-faq.info,  Node: Q11.0.1,  Next: Q11.0.2,  Prev: Bleeding Edge,  Up: Bleeding Edge

Where is the most recent XEmacs development code?
-------------------------------------------------

The most recent XEmacs _development_ code is kept in a Mercurial
repository, hosted by the Debian project.  The read-only URL, for
anybody who doesn't intend to push upstream directly, is

     http://hg.debian.org/hg/xemacs/xemacs

   The read-write URL for committers is

     ssh://sperber-guest@hg.debian.org//hg/xemacs/xemacs

   Yes, Virginia, that doubled slash is correct.

   *Note How do I get commit access?: Q11_0_5.

   *Note What is Mercurial?: Q11_2_1.


File: xemacs-faq.info,  Node: Q11.0.2,  Next: Q11.0.3,  Prev: Q11.0.1,  Up: Bleeding Edge

Where is the most recent XEmacs stable code?
--------------------------------------------

The most recent XEmacs _stable_ code is kept in a Mercurial repository,
hosted by the Debian project.  The read-only URL is

     http://hg.debian.org/hg/xemacs/xemacs-21.4

   If you're _not_ Vin, you don't need commit access.  If you _are_
Vin, you shouldn't need to refer to this FAQ.

   *Note What is Mercurial?: Q11_2_1.


File: xemacs-faq.info,  Node: Q11.0.3,  Next: Q11.0.4,  Prev: Q11.0.2,  Up: Bleeding Edge

Where is the most recent XEmacs package code?
---------------------------------------------

The most recent XEmacs _packages_ code is kept in a CVS repository,
hosted by the Debian project.  The read-only `CVSROOT', for anybody who
doesn't intend to push upstream directly, is

     CVSROOT=:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/xemacs

   The read-write `CVSROOT' for committers is

     CVSROOT=:ext:ALIOTHUSER@cvs.alioth.debian.org:/cvsroot/xemacs

   where ALIOTHUSER is your account on `alioth.debian.org'.  Then

     cvs checkout packages

   as usual.  For more information, see XEmacs CVS Archive
(http://www.xemacs.org/Develop/cvsaccess.html) on the website.

   *Note How do I stay cool using CVS?: Q11_1_1.

   *Note How do I get commit access?: Q11_0_5.


File: xemacs-faq.info,  Node: Q11.0.4,  Next: Q11.0.5,  Prev: Q11.0.3,  Up: Bleeding Edge

Why isn't PACKAGE available? and what to do about it.
-----------------------------------------------------

If a package isn't available from the Packages repository, probably
nobody has shown enough interest to add it yet.  (Occasionally, there is
a better package already in the XEmacs repository, of course.)

   The first step is to ask about it, and propose addition, on the
XEmacs Contributors list <xemacs-beta@xemacs.org>.

   Most regular XEmacs contributors already shoulder primary
responsibility for several packages, and contribute to maintenance of
the rest, so you are unlikely to get a massively enthusiastic response
unless you volunteer to become the maintainer of the version packaged
for XEmacs yourself.  The duties are not terribly onerous if you're an
active user of the package *Note (xemacs-devguide)XEmacs Package
Maintainer::.


File: xemacs-faq.info,  Node: Q11.0.5,  Next: Q11.1.1,  Prev: Q11.0.4,  Up: Bleeding Edge

How do I get commit access?
---------------------------

To get commit access to XEmacs code, write to the XEmacs Review Board
<xemacs-review@xemacs.org> and request it.  Once approved, for the
development code, you also need to send Michael Sperber
<mike@xemacs.org> your SSH v2 RSA key (Alioth policy; v1 and DSA keys
aren't acceptable).  A CC to the XEmacs Services team
<xemacs-services@xemacs.org> is a good idea, although not absolutely
necessary.  You should also get an Alioth account so that you can
publish branches for review.

   For packages code, you must get an Alioth account.  Send your account
name information to the XEmacs Services team
<xemacs-services@xemacs.org>.

   The stable repository is gated; only the gatekeeper (currently Vin
Shelton) has commit access.  Patches for the stable repository should be
submitted to XEmacs Patches <xemacs-patches@xemacs.org>, as usual.

   XEmacs Mercurial Archive
(http://www.xemacs.org/Develop/hgaccess.html)

   XEmacs CVS Archive (http://www.xemacs.org/Develop/cvsaccess.html)

   *Note How do I stay cool using CVS?: Q11_1_1.

   *Note What is Mercurial?: Q11_2_1.

11.1: Working with CVS
======================


File: xemacs-faq.info,  Node: Q11.1.1,  Next: Q11.2.1,  Prev: Q11.0.5,  Up: Bleeding Edge

How do I keep cool using CVS?
-----------------------------

You don't.  CVS is just basically and in detail _un_-cool.

   What would be really cool is if you would help us out in moving the
packages repository to Mercurial.  Volunteer on the XEmacs Contributors
list <xemacs-beta@xemacs.org>.  What's needed is to figure out how to
provide a one step checkout for the whole package hierarchy, while
restricting commits to one package at a time.

   For help using CVS, Google or ask on <xemacs-beta@xemacs.org>.
Please update this FAQ with one or two of the best references you find.

11.1: Working with Mercurial
============================


File: xemacs-faq.info,  Node: Q11.2.1,  Next: Q11.2.2,  Prev: Q11.1.1,  Up: Bleeding Edge

What is Mercurial?
------------------

Mercurial is a "distributed version control system", or DVCS.  This
means that versioning information can be easily exchanged between
different lines of development, even if located on different hosts.  In
the older "centralize version control system" model, when you "commit"
a change, it is immediately reflected in the public repository.  In a
DVCS, each user has a "local repository", and the commit operation
creates a version in that repository.  To communicate with the public
repository, a separate "push" operation must be executed.  The DVCS
model is more appropriate for open source development.

   * The VCS model mirrors the development organization, where
     developers tend to work independently or in very small groups.

   * Users without commit access can conveniently manage their local
     changes.

   * Developers can work, and commit changes, while disconnected from
     the Internet.  Then they merge and push their changes later.

   Use of a DVCS does require some changes in workflow, but the XEmacs
developers consider that inconvenience to be far more than balanced by
the advantages.


File: xemacs-faq.info,  Node: Q11.2.2,  Next: Q11.2.3,  Prev: Q11.2.1,  Up: Bleeding Edge

Where do I get Mercurial?
-------------------------

Most OS distributions (including add-on distributions like Cygwin
(http://www.cygwin.com/) and MacPorts (http://www.macports.org/))
include Mercurial packages.  Of course, you can get the source
distribution, as well as pre-built packages for most major platforms,
from the Mercurial developers (http://mercurial.selenic.com/wiki/).


File: xemacs-faq.info,  Node: Q11.2.3,  Next: Q11.2.4,  Prev: Q11.2.2,  Up: Bleeding Edge

Do I really have to waste space on history?
-------------------------------------------

Yes, you do.  It's really not that much, though.  In one of my current
workspaces, I see

`XEmacs source files (and other cruft, such as editor backups)'
     115464KB

`Build products'
     49676

`Mercurial control files and history'
     25644

   That really does include all of the history available in the main
XEmacs development branch, and the build products are near twice the
size of all of the Mercurial-specific information.


File: xemacs-faq.info,  Node: Q11.2.4,  Next: Q11.2.5,  Prev: Q11.2.3,  Up: Bleeding Edge

`hg diff' gives bizarre output.
-------------------------------

You may see an unreasonable diff (often large) that doesn't seem to
reflect your work.

   This is usually due to using `hg diff' on a "merge commit".  That
means the commit has multiple parents, and joins together two lines of
development that occurred concurrently.

   You're diffing against the "wrong" one; try the other one.  You get
the relevant revision number or ID from `hg log'.  In more detail:

   When there is a merge in Mercurial, it will often be the case that
one of the parents is the immediate predecessor of the merge commit.
`hg log' will report something like

         changeset:   4789:56049bea9231    # revision D, below
         parent:      4788:5cca06f930ea    # your commit
         parent:      4787:6e6f7b79c1fc    # diff against this
         user:        you (or somebody else)

         changeset:   4788:5cca06f930ea    # revision B, below
         parent:      4760:217abcf015c4    # revision A, below
         user:        you

         changeset:   4787:6e6f7b79c1fc    # revision C, below
         parent:      4786:d6cfba1cc388
         user:        somebody else

   Note that the divergence took place a long time ago (r4760).  It's
natural to diff against (tip - 1), in the example above, `hg diff -r
4788'.  But this will give unexpected output!

   A picture of this history looks something like

           B --- D
          /     /
         A ... C

   where A is the common ancestor, B is the commit you did, C is the
mainline at the time of the merge, and D is the merge commit.  The
three dots between A and C can represent many commits, and a lot of
work.  Given no conflicts in the merge, `hg diff -r C -r D' is the same
as `hg diff -r A -r B', _i.e._, it shows your work.  Similarly, `hg
diff -r B -r D' is the same as `hg diff -r A -r C'.  This latter diff
is likely to be quite large, and it doesn't show your work.
Unfortunately, that is the typical result of diffing against the
"previous" commit.


File: xemacs-faq.info,  Node: Q11.2.5,  Next: Q11.2.6,  Prev: Q11.2.4,  Up: Bleeding Edge

How do I recover from a bad commit?  (I already pushed.)
--------------------------------------------------------

Once upon a time, an XEmacs developer wrote:

   > GAAAAK!  What's the best way to restore ChangeLog and its history?

   He had just inadvertently pushed a commit which deleted
`src/ChangeLog'!  The history is still there, not to worry.  (In this
case, another developer had restored src/ChangeLog already.)  The best
way depends on a number of things.  First, let's look at the log and
the state of the DAG (the graph of commits).  Here's the log, formatted
somewhat differently from the usual output for compactness.

     5025    anne    Restore src/ChangeLog.
     5024    barb    merge
             parents: 5023 5010
     5023    barb    Error-checking.
     5020    barb    merge
             parents: 5019 5006
     5019    barb    Fix non-Mule build.
     5011    barb    Some internals-manual updates.
             parents: 5002
     5010    cary    Windows fixes for Visual Studio 6.
             parents: 5008 5009
     5009    cary    Miscellaneous small fixes to Windows VS6 build.
             parents: 5006
     5008    dana    Add license information.
     5007    dana    Relicense emodules.texi.
     5006    cary    Instantiate compile fix for nt.c.
     5005    edna    Cast correctly.
     5003    edna    #'union doesn't preserve relative order
     5002    barb    Fix some compile bugs.

   (The gaps at 5003...5005, 5011...5019, and 5020...5023 are filled
with sequences of commits by the same developers.)  Let's visualize
this as a graph.  Time increases to the right, the leading "50" is
omitted for brevity, and the dotted links indicate that several
irrelevant commits were omitted, also for brevity.

                             ,------ 09 -----.
                            /                 \
     02 --- 03 ... 05 --- 06 --- 07 --- 08 --- 10 --- 24 --- 25
       \                    \                        /
        `-- 11 ... 19 -------`-- 20 ... 23 ---------'

   The "problem commit" is 5010, which merges 5008 with 5009, and
somehow managed to "lose" `src/ChangeLog'.  The unobvious consequence is
that, although the _other_ changes made in 5007 and 5008 were
successfully merged and are present in 5010, the log entry made by Dana
for 5008 "just disappeared".  (The log entry for 5007 is in a different
`ChangeLog', so it's safe.)

The safe and simple way for Cary
................................

To recover state file-by-file (also for whole directories), use `hg
revert'.  This does not change the "current" version, _i.e._, the
commit that will be the parent for your next commit.

   If it's not a merge commit, it's simple to restore the ChangeLog.
It's best to do it before making any other commits in your own
workspace, and before pulling in new commits from others.  If there are
a lot of such commits in your workspace already, ask for help.  But in
this case, there was no such problem.  Just

     hg revert -r 5009 src/ChangeLog
     # Add Dana's log entry by hand.
     hg commit -m "Restore src/ChangeLog."

   5009 is the revision id of the most recent commit that had the
correct version of the file.  You get that from the "parent" field in
`hg log', or from the DAG browser (`hg view', requires `hgk' extension
enabled).

   Alternatively, Cary could revert from 5008.  This would leave her
with _her_ log entry for 5009 missing, and that would have to be added
by hand.

   Note that in the actual history, Cary didn't realize that Dana's log
went missing, so Anne had to pick up the slack in 5025.

Recovery by another developer
.............................

Another way to recover earlier state is with `hg checkout' (or `hg
update', which is another way to spell the same command).  This changes
the version that hg sees as "current", as well as reverting the
workspace.

   A common scenario is that another developer, such as Barb in the log
above, was already working on `src/ChangeLog', saves her copy, then
tries to merge.  She would then get a modify/delete conflict.  It's
tempting to just resolve that in favor of keeping the file, and commit.
This often works, but an alternative way uses the VCS:

     hg checkout 5010
     hg revert -r 5009 src/ChangeLog
     # Add Dana's log entry by hand.
     hg commit -m "Restore src/ChangeLog."

   to get the same effect as described above, then

     hg merge

   (making her changes "float to the top" of the log) or

     hg checkout 5023
     hg merge

   (putting the Cary's branch at the top of the log).  This assumes she
has no other heads in her workspace.  If she does have other heads she
would have to use an explicit argument to `hg merge'.

   Note that in the actual history, Barb didn't realize that Dana's log
went missing, so Anne (or somebody) had to pick up the slack in 5025.

The hard but accurate way
.........................

Suppose Barb did `hg pull -u', but notices the problem before resolving
conflicts and committing the merge.  Assume Barb was fully committed
before doing `hg pull -u'.

     # Restore the ChangeLog, "covering up" the broken commit.
     # Check out Cary's head.  This nukes the merged files in the workspace,
     # but _the history and versions in Barb's rev. 5023 are preserved
     # in the repository_.  The -C is necessary to overwrite files.
     hg checkout -C 5010
     hg revert -r 5009 src/ChangeLog
     # Merge Dana's branch (yes, again).
     # The repeated merge outside of src/ChangeLog should resolve to a
     # no-op, but the ChangeLog probably conflicts.
     # The -f is needed because revert leaves uncommitted changes.
     hg merge -f 5008
     hg commit -m "Re-merge Dana's branch to recover her logs."
     # Merge Barb's work.
     # If Barb has only two heads, which seems likely, the argument to
     # merge is optional.
     hg merge 5023
     hg commit -m merge

   Visualizing this with a graph, we have:

                             ,------ 09 -----.
                            /                 \
     02 --- 03 ... 05 --- 06 --- 07 --- 08 --- 10 *** 24 --- 25
       \                    \             \          /      /
        \                    \             `--------'      /
         \                    \                           /
          `-- 11 ... 19 -------`-- 20 ... 23 ------------'

   Note that the versions 5024 and 5025 in this graph denote
_different_ versions from the actual history.  The starred link means
that editing work (aside from resolving conflicts) was done, on top of
the merge.  However, the editing work is actually done by Mercurial
(the revert command)!


File: xemacs-faq.info,  Node: Q11.2.6,  Next: Q11.2.7,  Prev: Q11.2.5,  Up: Bleeding Edge

How do I recover from a bad commit?  (I haven't pushed yet.)
------------------------------------------------------------

If you hadn't yet pushed the commit you now regret, and realize it
before doing further commits, you can use `hg strip tip'.  Then just
redo the commit, possibly with additional changes before committing.

   `hg strip' is dangerous; for practical purposes it destroys history,
and it also reverts the files in your workspace.  It's probably
possible to recover the history, but I don't know how.  And any
uncommitted changes that might be lost are gone forever.  However, it
is useful in cases like this.

   When in doubt, use the safer method *Note Q11.2.5::.


File: xemacs-faq.info,  Node: Q11.2.7,  Prev: Q11.2.6,  Up: Bleeding Edge

Testing patches with Mercurial Queues.
--------------------------------------

When testing a patch proposed on xemacs-beta or xemacs-patches,
conflicts or new heads often appear later, when using `hg pull -u'.

   There are both theoretical and practical reasons why this happens,
and it's unlikely to change.  The current workflow of XEmacs is also
unlikely to change soon; testing patches is also probably going to
remain necessary.  One way to avoid this issue is to use Mercurial
Queues (mq), an extension distributed with Mercurial.

   Enable mq by adding

         [extensions]

         hgext.mq =

   to your `~/.hgrc'.  (Yes, the right hand side is empty.)  If you
already have an `[extensions]' section, don't repeat it.  Add `hgext.mq
=' to the existing extensions section.

   When you want to test a patch, you need an hg workspace with no
uncommitted changes.  If you already have some uncommitted changes, you
can preserve them with mq as follows:

         $ hg qnew -f -m "Preserve local changes." local-changes

   The `-m' flag specifies the commit message for the new patch.  The
`-f' flag "forces" qnew to put all of the uncommitted local changes
into an mq patch, and commits it (you will see a commit with summary
"Preserve local changes." if you do an `hg log' now).  "local-changes"
is the name of the patch.

   Now, create an mq patch for the test patch (which we assume was saved
to `/tmp/xemacs.patch'):

   $ hg qimport -P -n test-xemacs-patch /tmp/xemacs.patch

   The `-n' flag specifies the name of the patch.  Give it a name
sufficiently explicit so you'll know what it is later.  Remember, it
may take several weeks for the patch to be pushed to the public
mainline.  The `-P' flag says "apply this patch to the workspace now".

   When you want to update the workspace, you need to remove the mq
commits, update, and restore your local changes and the test patch.
You do it this way:

         $ hg qpop --all
         $ hg pull -u                # use your usual method, hg fetch etc.
         $ hg qpush --all

   `hg qpop --all' undoes all the mq commits, but leaves the patches in
`.hg/patches'.  `hg qpush --all' reapplies the patches and restores the
mq commits.  Of course you hope that the patch will be committed
upstream.  When it is, you do this:

         $ hg qpop --all
         $ hg pull -u
         $ hg qdelete test-xemacs-patch
         $ hg qpush --all

   and you're back in business with the official version of the patch
you tested, and all your local changes applied.

   It's also possible to split your local changes into smaller mq
patches, but that's out of scope for this answer.


