Mercurial > hg > xemacs-beta
changeset 2028:2ba4f06a264d
[xemacs-hg @ 2004-04-19 08:02:27 by stephent]
texi doc improvements <87zn98wg4q.fsf@tleepslib.sk.tsukuba.ac.jp>
| author | stephent |
|---|---|
| date | Mon, 19 Apr 2004 08:02:38 +0000 |
| parents | 71477bc21fe8 |
| children | 7a9919388e87 |
| files | man/ChangeLog man/internals/internals.texi man/lispref/glyphs.texi man/lispref/gutter.texi man/lispref/lispref.texi man/lispref/numbers.texi man/lispref/specifiers.texi man/widget.texi |
| diffstat | 8 files changed, 1007 insertions(+), 253 deletions(-) [+] |
line wrap: on
line diff
--- a/man/ChangeLog Mon Apr 19 06:40:45 2004 +0000 +++ b/man/ChangeLog Mon Apr 19 08:02:38 2004 +0000 @@ -1,3 +1,73 @@ +2004-04-18 Stephen J. Turnbull <stephen@xemacs.org> + + * internals/internals.texi (Object-Oriented Techniques in XEmacs): + New node. + (The XEmacs Object System (Abstractly Speaking)): + Reorder the list of objects somewhat. + Add brief descriptions of the arbitrary-precision number types. + (Writing Good Comments): Slight revision, recommend @xemacs alias. + (Character-Related Data Types): Add a few comments re Unicode. + (Working With Character and Byte Positions): Ditto. + (General Guidelines for Writing Mule-Aware Code): Query. + (Conversion to and from External Data): Ditto. + (Techniques for XEmacs Developers): Typo. + (Modules for Regression Testing): Add an xref. + (Overview): Note that dump file is now inside the executable. + (Remaining issues): Mention ExecShield vs. pdumper. + (Searching and Matching): Mention UTF-8 wrt Mule. + +2004-02-22 Stephen J. Turnbull <stephen@xemacs.org> + + * widget.texi (Introduction): Update historical references a bit. + Fix many typos and grammatical problems. + (User Interface): Fix typo. + +2004-04-09 Stephen J. Turnbull <turnbull@sk.tsukuba.ac.jp> + + * lispref/numbers.texi (Numbers): Describe bignums, ratios, and + bigfloats briefly. + (Integer Basics): We've had 31-bit integers for a while. Fix the + statement of minimum available precision and the examples. + Document most-positive-fixnum and most-negative-fixnum. Add a + pointer to the node "The Bignum Extension". + (Float Basics): Document most-positive-float, most-negative-float, + least-positive-float, least-positive-normalized-float, + least-negative-float, and least-negative-normalized-float. Add a + pointer to the node "The Bignum Extension". + (Comparison of Numbers): Update for bignums. + + (The Bignum Extension): + (Bignum Basics): + (Ratio Basics): + (Bigfloat Basics): + (Contagion and Canonicalization): + (Compatibility Issues): + New nodes. + + * lispref/lispref.texi (Top): + * lispref/numbers.texi (Numbers): + Add nodes "Ratio Basics" and "The Bignum Extension" to menus. + +2004-01-26 Stephen J. Turnbull <stephen@xemacs.org> + + * lispref/specifiers.texi: Update FSF copyright. + (Specifier Compatibility Notes): New node. + + * lispref/glyphs.texi (Glyph Properties): Fix typo. + (Glyphs): + (Native GUI Widgets): New node. + + * lispref/gutter.texi (Gutter Descriptor Format): Node deleted. + (Gutter): + (Gutter Intro): + (Creating Gutter): + (Specifying a Gutter): + Pluralize node name to Creating Gutters. + (Creating Gutters): Improve explanation of gutter descriptors. + (Other Gutter Variables): Remove extraneous text. + (Common Gutter Widgets): In lieu of real documentation, at least + point to gutter-items.el. + 2004-04-06 Stephen J. Turnbull <turnbull@sk.tsukuba.ac.jp> Lightly revised from <psr7v1j039.fsf@diannao.ittc.ku.edu>.
--- a/man/internals/internals.texi Mon Apr 19 06:40:45 2004 +0000 +++ b/man/internals/internals.texi Mon Apr 19 08:02:38 2004 +0000 @@ -1487,14 +1487,9 @@ @table @code @item integer -28 or 31 bits of precision, or 60 or 63 bits on 64-bit machines; the +31 bits of precision, or 63 bits on 64-bit machines; the reason for this is described below when the internal Lisp object representation is described. -@item float -Same precision as a double in C. -@item cons -A simple container for two Lisp objects, used to implement lists and -most other data structures in Lisp. @item char An object representing a single character of text; chars behave like integers in many ways but are logically considered text rather than @@ -1511,27 +1506,42 @@ different types @code{eq}. The reason for this monstrosity is compatibility with existing code; the separation of char from integer came fairly recently.) +@item float +Same precision as a double in C. +@item bignum +@itemx ratio +@itemx bigfloat +As build-time options, arbitrary-precision numbers are available. +Bignums are integers, and when available they remove the restriction on +buffer size. Ratios are non-integral rational numbers. Bigfloats are +arbitrary-precision floating point numbers, with precision specified at +runtime. @item symbol An object that contains Lisp objects and is referred to by name; symbols are used to implement variables and named functions and to provide the equivalent of preprocessor constants in C. -@item vector -A one-dimensional array of Lisp objects providing constant-time access -to any of the objects; access to an arbitrary object in a vector is -faster than for lists, but the operations that can be done on a vector -are more limited. @item string Self-explanatory; behaves much like a vector of chars but has a different read syntax and is stored and manipulated more compactly. @item bit-vector A vector of bits; similar to a string in spirit. +@item vector +A one-dimensional array of Lisp objects providing constant-time access +to any of the objects; access to an arbitrary object in a vector is +faster than for lists, but the operations that can be done on a vector +are more limited. @item compiled-function An object containing compiled Lisp code, known as @dfn{byte code}. @item subr A Lisp primitive, i.e. a Lisp-callable function implemented in C. +@item cons +A simple container for two Lisp objects, used to implement lists and +most other data structures in Lisp. @end table +Objects which are not conses are called atoms. + @cindex closure Note that there is no basic ``function'' type, as in more powerful versions of Lisp (where it's called a @dfn{closure}). XEmacs Lisp does @@ -1695,7 +1705,7 @@ deleted. (This happens as a result of restoring a window configuration.) @cindex read syntax - Note that many types of objects have a @dfn{read syntax}, i.e. a way of + Many types of objects have a @dfn{read syntax}, i.e. a way of specifying an object of that type in Lisp code. When you load a Lisp file, or type in code to be evaluated, what really happens is that the function @code{read} is called, which reads some text and creates an object @@ -1716,6 +1726,14 @@ converts to an integer whose value is 17297. @example +355/113 +@end example + +converts to a ratio commonly used to approximate @emph{pi} when ratios +are configured, and otherwise to a symbol whose name is ``355/113'' (for +backward compatibility). + +@example 1.983e-4 @end example @@ -2261,6 +2279,7 @@ @menu * A Reader's Guide to XEmacs Coding Conventions:: * General Coding Rules:: +* Object-Oriented Techniques for C:: * Writing Lisp Primitives:: * Writing Good Comments:: * Adding Global Lisp Variables:: @@ -2481,6 +2500,109 @@ @code{LIST_LOOP_DELETE_IF} delete elements from a lisp list satisfying some predicate. +@node Object-Oriented Techniques for C +@section Object-Oriented Techniques for C +@cindex coding rules, object-oriented +@cindex object-oriented techniques + +At the lowest levels, XEmacs makes heavy use of object-oriented +techniques to promote code-sharing and uniform interfaces for different +devices and platforms. Commonly, but not always, such objects are +``wrapped'' and exported to Lisp as Lisp objects. Usually they use +the internal structures developed for Lisp objects (the @samp{lrecord} +structure) in order to take advantage of Lisp memory management. +Unfortunately, XEmacs was originally written in C, so these techniques +are based on heavy use of C macros. Since XEmacs has been rewritten in +``Clean C,'' @emph{i.e.}, it compiles under both C and C++, it should be +possible to migrate to C++. It is hoped this documentation will help +encourage this process. + +@c You can't use @var{} for type below, because case is important. +A module defining a class is likely to use most of the following +declarations and macros. In the following, the notation @samp{<type>} +will stand for the full name of the class, and will be capitalized in +the way normal for its context. The notation @samp{<typ>} will stand +for the abbreviated form commonly used in macro names, while @samp{ty} +will be used as the typical name for instances of the class. (See the +entry for @samp{MAYBE_<TY>METH} below for an example using all three +notations.) + +In the interface (@file{.h} file), the following declarations are used +often. Others may be used in for particular modules. Since they're +quite short in most cases, the definitions are given as well. The +generic macros used are defined in @file{lisp.h} or @file{lrecord.h}. + +@c #### reorganize this table into stuff used in general code, and stuff +@c used only in declarations or initializations +@table @samp +@c #### declaration +@item typedef struct Lisp_<Type> Lisp_<Type> +This refers to the internal structure used by C code. The XEmacs coding +style now forbids passing pointers to @samp{Lisp_<Type>} structures into +or out of a function; instead, a @samp{Lisp_Object} should be passed or +returned (created using @samp{wrap_<type>}, if necessary). + +@c #### declaration +@item DECLARE_LRECORD (<type>, Lisp_<Type>) +Declares an @samp{lrecord} for @samp{<Type>}, which is the unit of +allocation. + +@item #define X<TYPE>(x) XRECORD (x, <type>, Lisp_<Type>) +Turns a @code{Lisp_Object} into a pointer to @samp{struct Lisp_<Type>}. + +@item #define wrap_<type>(p) wrap_record (p, <type>) +Turns a pointer to @samp{struct Lisp_<Type>} into a @code{Lisp_Object}. + +@item #define <TYPE>P(x) RECORDP (x, <type>) +Tests whether a given @code{Lisp_Object} is of type @samp{Lisp_<Type>}. +Returns a C int, not a Lisp Boolean value. + +@item #define CHECK_<TYPE>(x) CHECK_RECORD (x, <type>) +@itemx #define CONCHECK_<TYPE>(x) CONCHECK_RECORD (x, <type>) +Tests whether a given @code{Lisp_Object} is of type @samp{Lisp_<Type>}, +and signals a Lisp error if not. The @samp{CHECK} version of the macro +never returns if the type is wrong, while the @samp{CONCHECK} version +can return if the user catches it in the debugger and explicitly +requests a return. + +@item #define RAW_<TYP>METH(ty, m) ((ty)->methods->m##_method) +Return a function pointer for the method for an object @var{TY} of class +@samp{Lisp_<Type>}, or @samp{NULL} if there is none for this type. + +@item #define HAS_<TYP>METH_P(ty, m) (!!RAW_<TYP>METH (ty, m)) +Test whether the class that @var{TY} is an instance of has the method. + +@item #define <TYP>METH(ty, m, args) ((RAW_<TYP>METH (ty, m)) args) +Call the method on @samp{args}. @samp{args} must be enclosed in +parentheses in the call. It is the programmer's responsibility to +ensure that the method is available. The standard convenience macro +@samp{MAYBE_<TYP>METH} is often provided for the common case where a +void-returning method of @samp{Type} is called. + +@item #define MAYBE_<TYP>METH(ty, m, args) do @{ ... @} while (0) +Call a void-returning @samp{<Type>} method, if it exists. Note the use +of the @samp{do ... while (0)} idiom to give the macro call C statement +semantics. The full definition is equally idiomatic: + +@example +#define MAYBE_<TYP>METH(ty, m, args) do @{ \ + Lisp_<Type> *maybe_<typ>meth_ty = (ty); \ + if (HAS_<TYP>METH_P (maybe_<typ>meth_ty, m)) \ + <TYP>METH (maybe_<typ>meth_ty, m, args); \ +@} while (0) +@end example +@end table + +The use of macros for invoking an object's methods makes life a bit +difficult for the student or maintainer when browsing the code. In +particular, calls are of the form @samp{<TYP>METH (ty, some_method, (x, +y))}, but definitions typically are for @samp{<subtype>_some_method}. +Thus, when you are trying to find calls, you need to grep for +@samp{some_method}, but this will also catch calls and definitions of +that method for instances of other subtypes of @samp{<Type>}, and there +may be a rather large number of them. + + @node Writing Lisp Primitives @section Writing Lisp Primitives @cindex writing Lisp primitives @@ -2760,22 +2882,22 @@ later on lost or unavailable to the person doing the update.) When putting in an explicit opinion in a comment, you should -@emph{always} attribute it with your name, and optionally the date. -This also goes for long, complex comments explaining in detail the -workings of something -- by putting your name there, you make it -possible for someone who has questions about how that thing works to -determine who wrote the comment so they can write to them. Preferably, -use your actual name and not your initials, unless your initials are -generally recognized (e.g. @samp{jwz}). You can use only your first -name if it's obvious who you are; otherwise, give first and last name. -If you're not a regular contributor, you might consider putting your -email address in -- it may be in the ChangeLog, but after awhile -ChangeLogs have a tendency of disappearing or getting -muddled. (E.g. your comment may get copied somewhere else or even into -another program, and tracking down the proper ChangeLog may be very -difficult.) - -If you come across an opinion that is not or no longer valid, or you +@emph{always} attribute it with your name and the date. This also goes +for long, complex comments explaining in detail the workings of +something -- by putting your name there, you make it possible for +someone who has questions about how that thing works to determine who +wrote the comment so they can write to them. Use your actual name or +your alias at xemacs.org, and not your initials or nickname, unless that +is generally recognized (e.g. @samp{jwz}). Even then, please consider +requesting a virtual user at xemacs.org (forwarding address; we can't +provide an actual mailbox). Otherwise, give first and last name. If +you're not a regular contributor, you might consider putting your email +address in -- it may be in the ChangeLog, but after awhile ChangeLogs +have a tendency of disappearing or getting muddled. (E.g. your comment +may get copied somewhere else or even into another program, and tracking +down the proper ChangeLog may be very difficult.) + +If you come across an opinion that is not or is no longer valid, or you come across any comment that no longer applies but you want to keep it around, enclose it in @samp{[[ } and @samp{ ]]} marks and add a comment afterwards explaining why the preceding comment is no longer valid. Put @@ -2934,10 +3056,16 @@ Obviously, the equality between characters and bytes is lost in the Mule world. Characters can be represented by one or more bytes in the buffer, and @code{Ichar} is a C type large enough to hold any -character. +character. (This currently isn't quite true for ISO 10646, which +defines a character as a 31-bit non-negative quantity, while XEmacs +characters are only 30-bits. This is irrelevant, unless you are +considering using the ISO 10646 private groups to support really large +private character sets---in particular, the Mule character set!---in +a version of XEmacs using Unicode internally.) Without Mule support, an @code{Ichar} is equivalent to an -@code{unsigned char}. +@code{unsigned char}. [[This doesn't seem to be true; @file{lisp.h} +unconditionally @samp{typedef}s @code{Ichar} to @code{int}.]] @item Ibyte @cindex Ibyte @@ -2954,7 +3082,11 @@ One character can correspond to one or more @code{Ibyte}s. In the current Mule implementation, an ASCII character is represented by the same @code{Ibyte}, and other characters are represented by a sequence -of two or more @code{Ibyte}s. +of two or more @code{Ibyte}s. (This will also be true of an +implementation using UTF-8 as the internal encoding. In fact, only code +that implements character code conversions and a very few macros used to +implement motion by whole characters will notice the difference between +UTF-8 and the Mule encoding.) Without Mule support, there are exactly 256 characters, implicitly Latin-1, and each character is represented using one @code{Ibyte}, and @@ -3046,7 +3178,10 @@ a @code{Bytecount} value. In the current Mule implementation, @code{MAX_ICHAR_LEN} equals 4. -Without Mule, it is 1. +Without Mule, it is 1. In a mature Unicode-based XEmacs, it will also +be 4 (since all Unicode characters can be encoded in UTF-8 in 4 bytes or +less), but some versions may use up to 6, in order to use the large +private space provided by ISO 10646 to ``mirror'' the Mule code space. @item itext_ichar @itemx set_itext_ichar @@ -3184,6 +3319,9 @@ Format used for the external Unix environment---@code{argv[]}, stuff from @code{getenv()}, stuff from the @file{/etc/passwd} file, etc. This is encoded according to the encoding specified by the current locale. +[[This is dangerous; current locale is user preference, and the system +is probably going to be something else. Is there anything we can do +about it?]] @item Qfile_name Format used for filenames. This is normally the same as @code{Qnative}, @@ -3373,7 +3511,10 @@ prefix and have string arguments of type @code{Ibyte *}, and you can pass internally encoded data to them, often from a Lisp string using @code{XSTRING_DATA}. (A better design might be to provide versions that -accept Lisp strings directly.) +accept Lisp strings directly.) [[Really? Then they'd either take +@code{Lisp_Object}s and need to check type, or they'd take +@code{Lisp_String}s, and violate the rules about passing any of the +specific Lisp types.]] Also note that many internal functions, such as @code{make_string}, accept Ibytes, which removes the need for them to convert the data they @@ -3490,7 +3631,7 @@ You simply can't dump Quantified and Purified images (unless using the portable dumper). Purify gets confused when xemacs frees memory in one process that was allocated in a @emph{different} process on a different -machine!. Run it like so: +machine! Run it like so: @example temacs -batch -l loadup.el run-temacs @var{xemacs-args...} @end example @@ -5774,7 +5915,7 @@ @file{test-harness.el} defines the macros @code{Assert}, @code{Check-Error}, @code{Check-Error-Message}, and @code{Check-Message}. The other files are test files, testing various -XEmacs facilities. +XEmacs facilities. @xref{Regression Testing XEmacs}. @@ -7124,6 +7265,9 @@ data. Also, rebuild all the quickly rebuildable data. @end enumerate +Note: As of 21.5.18, the dump file has been moved inside of the +executable, although there are still problems with this on some systems. + @node Data descriptions @section Data descriptions @cindex dumping data descriptions @@ -7427,7 +7571,8 @@ The build process will have to start a post-dump xemacs, ask it the loading address (which will, hopefully, be always the same between -different xemacs invocations) and relocate the file to the new address. +different xemacs invocations) [[unfortunately, not true on Linux with +the ExecShield feature]] and relocate the file to the new address. This way the object relocation phase will not have to be done, which means no writes in the objects and that, because of the use of mmap, the dumped data will be shared between all the xemacs running on the @@ -8698,6 +8843,9 @@ swallow whole characters. This is handled using the same basic macros that are used for buffer and string movements. +This will also be true if a UTF-8 representation is used for the +internal encoding. + The complex algorithms for searching are for simple string searches. In particular, the algorithm used for fast string searching is Boyer-Moore. This algorithm is based on the idea that if you have a mismatch at a
--- a/man/lispref/glyphs.texi Mon Apr 19 06:40:45 2004 +0000 +++ b/man/lispref/glyphs.texi Mon Apr 19 08:02:38 2004 +0000 @@ -34,6 +34,7 @@ * Glyph Types:: Each glyph has a particular type. * Mouse Pointer:: Controlling the mouse pointer. * Redisplay Glyphs:: Glyphs controlling various redisplay functions. +* Native GUI Widgets:: Complex active images treated as a single glyph. * Subwindows:: Inserting an externally-controlled subwindow into a buffer. * Glyph Examples:: Examples of how to work with glyphs. @@ -347,7 +348,7 @@ instantiator. In such a case, the instantiator used to create that instance object will be used (for example, if you set a font-instance object as the value of the @code{font} property, then the font name used -to create that object will be used instead). If some cases, however, +to create that object will be used instead). In some cases, however, doing this conversion does not make sense, and this will be noted in the documentation for particular types of instance objects. @@ -1204,7 +1205,6 @@ be non-@code{nil} for colorized mono pixmaps and for pointers.) @end defun - @node Glyph Types @section Glyph Types @@ -1374,6 +1374,200 @@ This variable specifies what to use as an arrow for control characters. @end defvr +@node Native GUI Widgets +@section Native GUI Widgets +@cindex native widget + +A ``native widget'' is a primitive GUI object defined either by the host +GUI platform or an external toolkit, and accessed from Lisp as a +``glyph.'' + +@menu +* Introduction to Widgets:: Native widgets provide tight integration of + GUI features with the platform GUI. +* Lisp API to Native Widgets:: Native widgets are glyphs. +* Layouts:: Specifying composite widgets from Lisp. +* Primitive Widgets:: Catalogue of available native widgets. +@end menu + +@node Introduction to Widgets +@subsection Introduction to Native Widgets and Subwindow Glyphs + +Traditionally Emacsen have hidden the GUI apparatus from the Lisp +programmer, but in XEmacs 21.4 the ability to embed autonomous GUI +objects, called @dfn{native widgets}, in text was added to Lisp. They +are handled as @emph{glyphs}. Unlike traditional XEmacs +glyphs such images and strings, native widgets are opaque to XEmacs, and +must be able to redraw themselves because they are implemented as +subwindows, not as graphics drawn by XEmacs into the text window. + +Primitive widgets are coded in C using the underlying GUI toolkit, and +thus are beyond the scope of the @emph{XEmacs Lisp Reference Manual}. +However, composite widgets can be created in Lisp using ``layouts,'' +which are horizontal or vertical arrays of subwidgets. For example, the +search dialog is formatted using layouts. + +@node Lisp API to Native Widgets +@subsection Lisp API to Native Widgets + +Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}). Thus +they are created using @code{make-glyph}, with a format of one of the +widget types and a @code{:data} property specific to the widget being +instanced. + +However, there is a technical difference between widgets and other kinds +of glyphs that is theoretically important, which is that because widgets +are active (that is, they can respond to user input events themselves), +it is possible for the user to become aware that two appearances of the +``same'' glyph are actually separate instances. For example, if a user +changes an image glyph from red to blue, and the buffer containing the +glyph appears in more than one window, the user will perceive all the +appearances to change from red to blue simultaneously. However, suppose +the glyph is a button glyph (@emph{e.g.}, as used in the Customize +buffer for the Set, Save, and Done buttons). Then if the Customize +buffer appears in several windows at the same time, and the user clicks +on the button, she will only perceive the button to be depressed in the +window where she clicked the button. + +It seems from this example that it is unlikely to be a problem in +practice. When the user is faced with an active widget, it seems likely +that attention will focus on the widget being manipulated, and having +other instances of the widget respond simultaneously might be more +disconcerting than the actual case. + +@node Layouts +@subsection Layouts + +An XEmacs @dfn{layout} is a one-dimensional array of glyphs. It is a +widget for controlling the positioning of children underneath it. +Through the use of nested layouts, a widget hierarchy can be created +which can have the appearance of any standard dialog box or similar +arrangement; all of this is counted as one "glyph" and could appear in +many of the places that expect a single glyph. + +(There are also @dfn{native layouts}, but I don't know what these are or +how they are used.) + +A layout descriptor is an image instantiator, @emph{i.e.}, a vector of +the form @samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format +@code{layout}, and properties + +@c #### need defaults for these +@table @code +@item :orientation +Specifies the orientation of the contained array of glyphs. The value +must be one of the symbols @code{horizontal} or @code{vertical}. + +@item :horizontally-justify +Specifies the horizontal justification of the items in the array. The +value must be one of the symbols @code{:right}, @code{:center}, or +@code{:left}. + +@item :vertically-justify +Specifies the vertical justification of the items in the array. The +value must be one of the symbols @code{:center}, @code{:center}, or +@code{:bottom}. + +@item :justify +Specifies justification. #### not understood. + +@item :border +A glyph to place in the border. The value must be an image +instantiator. + +@item :items +The glyphs controlled by the layout. The value must be a list of image +instantiators. +@end table + +Here is the specification of the search dialog widget created by +@code{make-search-dialog} in the @file{dialog-items} library, which +makes use of recursive layouts. + +@example +(make-glyph + `[layout + :orientation horizontal + :vertically-justify top + :horizontally-justify center + :border [string :data "Search"] + :items + ([layout :orientation vertical + :justify top ; implies left also + :items + ([string :data "Search for:"] + [button :descriptor "Match Case" + :style toggle + :selected (not case-fold-search) + :callback (setq case-fold-search + (not case-fold-search))] + [button :descriptor "Regular Expression" + :style toggle + :selected search-dialog-regexp + :callback (setq search-dialog-regexp + (not search-dialog-regexp))] + [button :descriptor "Forwards" + :style radio + :selected search-dialog-direction + :callback (setq search-dialog-direction t)] + [button :descriptor "Backwards" + :style radio + :selected (not search-dialog-direction) + :callback (setq search-dialog-direction nil)] + )] + [layout :orientation vertical + :vertically-justify top + :horizontally-justify right + :items + ([edit-field :width 15 :descriptor "" :active t + :initial-focus t] + [button :width 10 :descriptor "Find Next" + :callback-ex + (lambda (image-instance event) + (search-dialog-callback ,parent + image-instance + event))] + [button :width 10 :descriptor "Cancel" + :callback-ex + (lambda (image-instance event) + (isearch-dehighlight) + (delete-frame + (event-channel event)))])])]) +@end example + +@node Primitive Widgets +@subsection Primitive Widgets + +@c #### the following table should be replaced with a menu of nodes +@table @code +@item button +A button widget; either a push button, radio button or toggle +button. + +@item combo-box +A drop list of selectable items in a widget, for editing text. + +@item edit-field +A text editing widget. + +@item label +A static, text-only, widget; for displaying text. + +@item progress-gauge +A sliding widget, for showing progress. + +@item tab-control +A tab widget; a series of user selectable tabs. + +@item tree-view +A folding widget. + +@item scrollbar +A scrollbar widget. (#### Probably not the same as the scrollbar +controlling an Emacs window.) +@end table + + @node Subwindows @section Subwindows
--- a/man/lispref/gutter.texi Mon Apr 19 06:40:45 2004 +0000 +++ b/man/lispref/gutter.texi Mon Apr 19 08:02:38 2004 +0000 @@ -14,15 +14,13 @@ @menu * Gutter Intro:: An introduction. -* Creating Gutter:: How to create a gutter. -* Gutter Descriptor Format:: Accessing and modifying a gutter's - properties. +* Creating Gutters:: How to create a gutter. * Specifying a Gutter:: Setting a gutter's contents. * Other Gutter Variables:: Controlling the size of gutters. * Common Gutter Widgets:: Things to put in gutters. @end menu -@node Gutter Intro, Creating Gutter, Gutter, Gutter +@node Gutter Intro, Creating Gutters, Gutter, Gutter @section Gutter Intro A @dfn{gutter} is a rectangle displayed along one edge of a frame. It @@ -37,7 +35,7 @@ be per-buffer, per-frame, etc., using specifiers (@pxref{Specifiers}). Normally, there is one gutter displayed in a frame. Usually, this is -the default gutter, containing buffer tabs, but modes cab override this +the default gutter, containing buffer tabs, but modes can override this and substitute their own gutter. This default gutter is usually positioned along the top of the frame, but this can be changed using @code{set-default-gutter-position}. @@ -59,8 +57,8 @@ the user sets the default gutter to the same position, it will just not be visible. -@node Creating Gutter, Gutter Descriptor Format, Gutter Intro, Gutter -@section Creating Gutter +@node Creating Gutters, Specifying a Gutter, Gutter Intro, Gutter +@section Creating Gutters @defun make-gutter-specifier spec-list @@ -75,9 +73,15 @@ @code{left-gutter}, @code{right-gutter}, and @code{bottom-gutter} are always gutter specifiers. -Valid gutter instantiators are called "gutter descriptors" and are -either strings or property-lists of strings. See @code{default-gutter} -for a description of the exact format. +Valid gutter instantiators are called ``gutter descriptors.'' A gutter +descriptor may be a string, a property-list with symbol keys and string +values, or @code{nil}. If @code{nil}, nothing will be displayed in the +gutter. If a string, the string will be displayed, with text properties +such as faces and additional glyphs taken from the extents in the +string, if any. If a property-list of strings, the string values will +be conditionally concatenated according to the contents of the +corresponding @samp{gutter-visible} variable, and displayed according to +any text properties they contain. @end defun @defun make-gutter-size-specifier spec-list @@ -88,16 +92,19 @@ or a list of instantiators. @xref{Specifiers}, for more information about specifiers. -Gutter-size specifiers are used to specify the size of a gutter. The -values of the variables @code{default-gutter-size}, -@code{top-gutter-size}, @code{left-gutter-size}, -@code{right-gutter-size}, and @code{bottom-gutter-size} are always -gutter-size specifiers. +Gutter-size specifiers are used to specify the size of a gutter. +The width of top and bottom gutters and the height of left and right +gutters are always adjusted to the size of the frame, so ``size'' means +``thickness,'' @emph{i.e.}, height for top and bottom gutters and width +for left and right gutters. The values of the variables +@code{default-gutter-size}, @code{top-gutter-size}, +@code{left-gutter-size}, @code{right-gutter-size}, and +@code{bottom-gutter-size} are always gutter-size specifiers. Valid gutter-size instantiators are either integers or the special -symbol @code{autodetect}. If a gutter-size is set to @code{autodetect} +symbol @code{autodetect}. If a gutter-size is set to @code{autodetect} them the size of the gutter will be adjusted to just accommodate the -gutters contents. @code{autodetect} only works for top and bottom +gutter's contents. @code{autodetect} only works for top and bottom gutters. @end defun @@ -117,125 +124,12 @@ Valid gutter-visible instantiators are @code{t}, @code{nil} or a list of symbols. If a gutter-visible instantiator is set to a list of symbols, -and the corresponding gutter specification is a property-list strings, -then elements of the gutter specification will only be visible if the -corresponding symbol occurs in the gutter-visible instantiator. +and the corresponding gutter specification is a property-list of strings, +then property values of the gutter specification will only be visible if the +corresponding key occurs in the gutter-visible instantiator. @end defun -@node Gutter Descriptor Format, Specifying a Gutter, Creating Gutter, Gutter -@section Gutter Descriptor Format - - The contents of a gutter are specified using a @dfn{gutter descriptor}. -The format of a gutter descriptor is a list of @dfn{gutter button -descriptors}. Each gutter button descriptor is a vector in one of the -following formats: - -@itemize @bullet -@item -@code{[@var{glyph-list} @var{function} @var{enabled-p} @var{help}]} -@item -@code{[:style @var{2d-or-3d}]} -@item -@code{[:style @var{2d-or-3d} :size @var{width-or-height}]} -@item -@code{[:size @var{width-or-height} :style @var{2d-or-3d}]} -@end itemize - - Optionally, one of the gutter button descriptors may be @code{nil} -instead of a vector; this signifies the division between the gutter -buttons that are to be displayed flush-left, and the buttons to be -displayed flush-right. - - The first vector format above specifies a normal gutter button; -the others specify blank areas in the gutter. - - For the first vector format: - -@itemize @bullet -@item -@var{glyph-list} should be a list of one to six glyphs (as created by -@code{make-glyph}) or a symbol whose value is such a list. The first -glyph, which must be provided, is the glyph used to display the gutter -button when it is in the ``up'' (not pressed) state. The optional -second glyph is for displaying the button when it is in the ``down'' -(pressed) state. The optional third glyph is for when the button is -disabled. The last three glyphs are for displaying the button in the -``up'', ``down'', and ``disabled'' states, respectively, but are used -when the user has called for captioned gutter buttons (using -@code{gutter-buttons-captioned-p}). The function -@code{gutter-make-button-list} is useful in creating these glyph lists. - -@item -Even if you do not provide separate down-state and disabled-state -glyphs, the user will still get visual feedback to indicate which -state the button is in. Buttons in the up-state are displayed -with a shadowed border that gives a raised appearance to the -button. Buttons in the down-state are displayed with shadows that -give a recessed appearance. Buttons in the disabled state are -displayed with no shadows, giving a 2-d effect. - -@item -If some of the gutter glyphs are not provided, they inherit as follows: - -@example - UP: up - DOWN: down -> up - DISABLED: disabled -> up - CAP-UP: cap-up -> up - CAP-DOWN: cap-down -> cap-up -> down -> up - CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up -@end example - -@item -The second element @var{function} is a function to be called when the -gutter button is activated (i.e. when the mouse is released over the -gutter button, if the press occurred in the gutter). It can be any -form accepted by @code{call-interactively}, since this is how it is -invoked. - -@item -The third element @var{enabled-p} specifies whether the gutter button -is enabled (disabled buttons do nothing when they are activated, and are -displayed differently; see above). It should be either a boolean or a -form that evaluates to a boolean. - -@item -The fourth element @var{help}, if non-@code{nil}, should be a string. -This string is displayed in the echo area when the mouse passes over the -gutter button. -@end itemize - - For the other vector formats (specifying blank areas of the gutter): - -@itemize @bullet -@item -@var{2d-or-3d} should be one of the symbols @code{2d} or @code{3d}, -indicating whether the area is displayed with shadows (giving it a -raised, 3-d appearance) or without shadows (giving it a flat -appearance). - -@item -@var{width-or-height} specifies the length, in pixels, of the blank -area. If omitted, it defaults to a device-specific value (8 pixels for -X devices). -@end itemize - -@defun gutter-make-button-list up &optional down disabled cap-up cap-down cap-disabled -This function calls @code{make-glyph} on each arg and returns a list of -the results. This is useful for setting the first argument of a gutter -button descriptor (typically, the result of this function is assigned -to a symbol, which is specified as the first argument of the gutter -button descriptor). -@end defun - -@defun check-gutter-button-syntax button &optional noerror -Verify the syntax of entry @var{button} in a gutter description list. -If you want to verify the syntax of a gutter description list as a -whole, use @code{check-valid-instantiator} with a specifier type of -@code{gutter}. -@end defun - -@node Specifying a Gutter, Other Gutter Variables, Gutter Descriptor Format, Gutter +@node Specifying a Gutter, Other Gutter Variables, Creating Gutters, Gutter @section Specifying a Gutter In order to specify the contents of a gutter, set one of the specifier @@ -315,7 +209,7 @@ This function returns non-@code{nil} if @var{object} is a gutter specifier. Gutter specifiers are the actual objects contained in the gutter variables described above, and their valid instantiators are -gutter descriptors (@pxref{Gutter Descriptor Format}). +gutter descriptors. @end defun @node Other Gutter Variables, Common Gutter Widgets, Specifying a Gutter, Gutter @@ -397,6 +291,7 @@ @code{default-gutter-visible-p} and all of the position-specific gutter visibility specifiers have a fallback value of true. +@c #### is this true? Internally, gutter thickness and visibility specifiers are instantiated in both window and frame domains, for different purposes. The value in the domain of a frame's selected window specifies the actual gutter @@ -415,18 +310,6 @@ selected window specifies that the left gutter is not visible, so it is expanded to take up the slack. -@defvr Specifier gutter-buttons-captioned-p -Whether gutter buttons are captioned. This affects which glyphs from a -gutter button descriptor are chosen. @xref{Gutter Descriptor Format}. -@end defvr - - You can also reset the gutter to what it was when XEmacs started up. - -@defvr Constant initial-gutter-spec -The gutter descriptor used to initialize @code{default-gutter} at -startup. -@end defvr - @node Common Gutter Widgets, , Other Gutter Variables, Gutter @section Common Gutter Widgets @@ -439,20 +322,26 @@ A more common use for the gutter is to hold some kind of active widget. The buffer-tab facility, available in all XEmacs frames, creates an array of file-folder-like tabs, which the user can click with -the mouse to switch buffers. W3 uses a progress-bar widget in the +the mouse to switch buffers. W3 and font-lock use progress-bar widgets in the bottom gutter to give a visual indication of the progress of -time-consuming operations like downloading. +time-consuming operations like downloading and syntax highlighting. + +@c #### Remove the following sentence when the subnodes are created. +These widgets are currently documented only in the library +@file{gutter-items}. @menu * Buffer Tabs:: Tabbed divider index metaphor for switching buffers. * Progress Bars:: Visual indication of operation progress. @end menu + @node Buffer Tabs, Progress Bars, ,Common Gutter Widgets @subsection Buffer Tabs Not documented yet. + @node Progress Bars, , Buffer Tabs, Common Gutter Widgets @subsection Progress Bars
--- a/man/lispref/lispref.texi Mon Apr 19 06:40:45 2004 +0000 +++ b/man/lispref/lispref.texi Mon Apr 19 08:02:38 2004 +0000 @@ -328,7 +328,9 @@ Numbers * Integer Basics:: Representation and range of integers. +* Ratio Basics:: Representation and range of rational numbers. * Float Basics:: Representation and range of floating point. +* The Bignum Extension:: Arbitrary precision integers, ratios, and floats. * Predicates on Numbers:: Testing for numbers. * Comparison of Numbers:: Equality and inequality predicates. * Arithmetic Operations:: How to add, subtract, multiply and divide.
--- a/man/lispref/numbers.texi Mon Apr 19 06:40:45 2004 +0000 +++ b/man/lispref/numbers.texi Mon Apr 19 08:02:38 2004 +0000 @@ -8,9 +8,14 @@ @cindex integers @cindex numbers - XEmacs supports two numeric data types: @dfn{integers} and -@dfn{floating point numbers}. Integers are whole numbers such as -@minus{}3, 0, #b0111, #xFEED, #o744. Their values are exact. The + XEmacs supports two to five numeric data types. @dfn{Integers} and +@dfn{floating point numbers} are always supported. As a build-time +option, @dfn{bignums}, @dfn{ratios}, and @dfn{bigfloats} may be +enabled on some platforms. + + Integers, which are what Common Lisp calls +@dfn{fixnums}, are whole numbers such as @minus{}3, 0, #b0111, #xFEED, +#o744. Their values are exact, and their range is limited. The number prefixes `#b', `#o', and `#x' are supported to represent numbers in binary, octal, and hexadecimal notation (or radix). Floating point numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or @@ -19,12 +24,43 @@ power, and is multiplied by 1.5. Floating point values are not exact; they have a fixed, limited amount of precision. + Bignums are arbitrary precision integers. When supported, XEmacs can +handle any integral calculations you have enough virtual memory to +store. (More precisely, on current architectures the representation +allows integers whose storage would exhaust the address space.) They +are notated in the same way as other integers (fixnums). XEmacs +automatically converts results of computations from fixnum to bignum, +and back, depending on the storage required to represent the number. +Thus use of bignums are entirely transparent to the user, except for a +few special applications that expect overflows. Ratios are rational +numbers with arbitrary precision. (In theory fixed-size rationals could +be supported, but for almost all applications floats are a reasonable +substitute for fixed-precision rationals.) They are notated in the +usual way with the solidus, for example 5/3 or @minus{}22/7. Bigfloats +are floating point numbers with arbitrary precision. Unlike integers, +which are always infinitely precise if they can be represented, floating +point numbers are inherently imprecise. Therefore XEmacs automatically +converts @emph{from float to bigfloat} when floats and bigfloats are +mixed in an expression, but a bigfloat will never be converted to a +float unless the user explicitly coerces the value. Nor will the result +of a float operation be converted to bigfloat, except for ``contagion'' +from another operand that is already a bigfloat. + + Note that the term ``integer'' is used throughout the XEmacs +documentation and code to mean ``fixnum''. This is inconsistent with +Common Lisp, and likely to cause confusion. Similarly, ``float'' is +used to mean ``fixed precision floating point number'', and the Common +Lisp distinctions among @dfn{short-floats}, @dfn{long-floats}, and +bigfloats are not reflected in XEmacs terminology. + @menu * Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. +* Rational Basics:: Representation and range of rational numbers. +* Float Basics:: Representation and range of floating point. +* The Bignum Extension:: Arbitrary precision integers, ratios, and floats. * Predicates on Numbers:: Testing for numbers. * Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. +* Numeric Conversions:: Converting float to integer and vice versa. * Arithmetic Operations:: How to add, subtract, multiply and divide. * Rounding Operations:: Explicitly rounding floating point numbers. * Bitwise Operations:: Logical and, or, not, shifting. @@ -35,25 +71,51 @@ @node Integer Basics @section Integer Basics - The range of values for an integer depends on the machine. The -minimum range is @minus{}134217728 to 134217727 (28 bits; i.e., + The range of values for an integer depends on the machine. If a +multiple-precision arithmetic library is available on your platform, +support for bignums, that is, integers with arbitrary precision, maybe +compiled in to your XEmacs. The rest of this section assumes that the +bignum extension is @emph{not} available. The bignum extension and the +user-visible differences in normal integer arithmetic are discussed in a +separate section @ref{The Bignum Extension}. + +The minimum range is @minus{}1073741824 to 1073741823 (31 bits; i.e., @ifinfo --2**27 +-2**30 @end ifinfo @tex -$-2^{27}$ +$-2^{30}$ @end tex to @ifinfo -2**27 - 1), +2**30 - 1), @end ifinfo @tex -$2^{27}-1$), +$2^{30}-1$), @end tex but some machines may provide a wider range. Many examples in this -chapter assume an integer has 28 bits. +chapter assume an integer has 31 bits. @cindex overflow +The range of fixnums is available to Lisp programs: + +@defvar most-positive-fixnum +The fixed-precision integer closest in value to positive infinity. +@end defvar + +@defvar most-negative-fixnum +The fixed-precision integer closest in value to negative infinity. +@end defvar + +Here is a common idiom to temporarily suppress garbage collection: +@example +(garbage-collect) +(let ((gc-cons-threshold most-positive-fixnum)) + ;; allocation-intensive computation + ) +(garbage-collect) +@end example + The Lisp reader reads an integer as a sequence of digits with optional initial sign and optional final period. @@ -62,7 +124,7 @@ 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 268435457 ; @r{Also the integer 1, due to overflow.} + 2147483648 ; @r{Read error, due to overflow.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -71,10 +133,10 @@ bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. - In 28-bit binary, the decimal integer 5 looks like this: + In 31-bit binary, the decimal integer 5 looks like this: @example -0000 0000 0000 0000 0000 0000 0101 +000 0000 0000 0000 0000 0000 0000 0101 @end example @noindent @@ -84,12 +146,12 @@ The integer @minus{}1 looks like this: @example -1111 1111 1111 1111 1111 1111 1111 +111 1111 1111 1111 1111 1111 1111 1111 @end example @noindent @cindex two's complement -@minus{}1 is represented as 28 ones. (This is called @dfn{two's +@minus{}1 is represented as 31 ones. (This is called @dfn{two's complement} notation.) The negative integer, @minus{}5, is creating by subtracting 4 from @@ -97,27 +159,27 @@ @minus{}5 looks like this: @example -1111 1111 1111 1111 1111 1111 1011 +111 1111 1111 1111 1111 1111 1111 1011 @end example - In this implementation, the largest 28-bit binary integer is the -decimal integer 134,217,727. In binary, it looks like this: + In this implementation, the largest 31-bit binary integer is the +decimal integer 1,073,741,823. In binary, it looks like this: @example -0111 1111 1111 1111 1111 1111 1111 +011 1111 1111 1111 1111 1111 1111 1111 @end example Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 134,217,727, the value is the -negative integer @minus{}134,217,728: +outside their range, when you add 1 to 1,073,741,823, the value is the +negative integer @minus{}1,073,741,824: @example -(+ 1 134217727) - @result{} -134217728 - @result{} 1000 0000 0000 0000 0000 0000 0000 +(+ 1 1073741823) + @result{} -1073741824 + @result{} 100 0000 0000 0000 0000 0000 0000 0000 @end example - Many of the following functions accept markers for arguments as well + Many of the arithmetic functions accept markers for arguments as well as integers. (@xref{Markers}.) More precisely, the actual arguments to such functions may be either integers or markers, which is why we often give these arguments the name @var{int-or-marker}. When the argument @@ -129,12 +191,28 @@ floating point numbers. @end ignore + +@node Ratio Basics +@section Ratio Basics + +Ratios (built-in rational numbers) are available only when the bignum +extension is built into your XEmacs. This facility is new and +experimental. It is discussed in a separate section for convenience of +updating the documentation @ref{The Bignum Extension}. + + @node Float Basics @section Floating Point Basics XEmacs supports floating point numbers. The precise range of floating point numbers is machine-specific; it is the same as the range of the C -data type @code{double} on the machine in question. +data type @code{double} on the machine in question. If a +multiple-precision arithmetic library is available on your platform, +support for bigfloats, that is, floating point numbers with arbitrary +precision, maybe compiled in to your XEmacs. The rest of this section +assumes that the bignum extension is @emph{not} available. The bigfloat +extension and the user-visible differences in normal float arithmetic +are discussed in a separate section @ref{The Bignum Extension}. The printed representation for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or @@ -169,6 +247,293 @@ down to an integer. @end defun +The range of floats is available to Lisp programs: + +@defvar most-positive-float +The fixed-precision floating-point-number closest in value to positive +infinity. +@end defvar + +@defvar most-negative-float +The fixed-precision floating point number closest in value to negative +infinity. +@end defvar + +@defvar least-positive-float +The positive float closest in value to 0. May not be normalized. +@end defvar + +@defvar least-negative-float +The positive float closest in value to 0. Must be normalized. +@end defvar + +@defvar least-positive-normalized-float +The negative float closest in value to 0. May not be normalized. +@end defvar + +@defvar least-negative-normalized-float +The negative float closest in value to 0. Must be normalized. +@end defvar + +Note that for floating point numbers there is an interesting limit on +how small they can get, as well as a limit on how big they can get. In +some representations, a floating point number is @dfn{normalized} if the +leading digit is non-zero. This allows representing numbers smaller +than the most-negative exponent can express, by having fractional +mantissas. This means that the number is less precise than a normalized +floating point number, so Lisp programs can detect loss of precision due +to unnormalized floats by checking whether the number is between +@code{least-positive-float} and @code{least-positive-normalized-float}. + + +@node The Bignum Extension +@section The Bignum Extension + + In XEmacs 21.5.18, an extension was added by @email{james@@xemacs.org, +Jerry James} to allow linking with arbitrary-precision arithmetic +libraries if they are available on your platform. ``Arbitrary'' +precision means precisely what it says. Your ability to work with large +numbers is limited only by the amount of virtual memory (and time) you +can throw at them. + + As of 09 April 2004, support for the GNU Multiple Precision +arithmetic library (GMP) is nearly complete, and support for the BSD +Multiple Precision arithmetic library (MP) is being debugged. To enable +bignum support using GMP (respectively MP), invoke configure with your +usual options, and add @samp{--use-number-lib=gmp} (respectively +@samp{--use-number-lib=mp}). The default is to disable bignum support, +but if you are using a script to automate the build process, it may be +convenient to explicitly disable support by @emph{appending} +@samp{--use-number-lib=no} to your invocation of configure. GMP has an +MP compatibility mode, but it is not recommended, as there remain poorly +understood bugs (even more so than for other vendors' versions of MP). + + With GMP, exact arithmetic with integers and ratios of arbitrary +precision and approximate (``floating point'') arithmetic of arbitrary +precision are implemented efficiently in the library. (Note that +numerical implementations are quite delicate and sensitive to +optimization. If the library was poorly optimized for your hardware, as +is often the case with Linux distributions for 80x86, you may achieve +gains of @emph{several orders of magnitude} by rebuilding the MP +library. See @uref{http://www.swox.com/gmp/gmp-speed.html}.) The MP +implementation provides arbitrary precision integers, but ratios were +implemented by the XEmacs implementer, Jerry James, who is not a +numerical analyst. Arbitrary precision floats are not available with +MP. + + The XEmacs bignum facility implements the Common Lisp notion of +@dfn{contagion}, so that integers are always represented using the +``smallest'' representation that is exact, and integral ratios are +converted to integers. Since floating point arithmetic is inherently +imprecise, numbers are implicitly coerced to bigfloats only if other +operands in the expression are bigfloat, and bigfloats are only coerced +to other numerical types by explicit calls to the function @code{coerce}. + + Bignum support is incomplete. If you would like to help with bignum +support, especially on BSD MP, please subscribe to the +@uref{http://www.xemacs.org/Lists/#xemacs-beta, XEmacs Beta mailing +list}, and book up on @file{number-gmp.h} and @file{number-mp.h}. Jerry +has promised to write internals documentation eventually, but if your +skills run more to analysis and documentation than to writing new code, +feel free to fill in the gap! + +@menu +* Bignum Basics:: Representation and range of integers. +* Ratio Basics:: Representation and range of rational numbers. +* Bigfloat Basics:: Representation and range of floating point. +* Contagion and Canonicalization:: Automatic coercion to other types. +* Compatibility Issues:: Changes in fixed-precision arithmetic. +@end menu + + +@node Bignum Basics +@subsection Bignum Basics + +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 GNU MP, +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 @samp{%d}, @samp{%o}, +@samp{%x}, and @samp{%u} format conversions. + + +@node Ratio Basics +@subsection Ratio Basics + +Ratios, when available have the read syntax and print representation +@samp{3/5}. Like other rationals (fixnums and bignums), they are +printed using the @samp{%d}, @samp{%o}, @samp{%x}, and @samp{%u} format +conversions. + + +@node Bigfloat Basics +@subsection Bigfloat Basics + +Bigfloats, when available, have the same read syntax and print +representations as fixed-precision floats. + + +@node Contagion and Canonicalization +@subsection Contagion + +@dfn{Contagion} is one way to address the requirement that an arithmetic +operation should not fail because of differing types of the operands, or +insufficient precision in the representation. With bignum support, we +can represent @code{(+ most-positive-fixnum most-positive-fixnum)} (or +@code{(* most-positive-fixnum most-positive-fixnum)}, for that matter) +@emph{exactly}. There should be no overflow or ``wrap-around,'' and the +computation should not be interrupted by an error. Contagion is the +idea that less precise operands are converted to the more precise type, +and then the operation is performed. This involves no loss of +information, and therefore it is safe to do it automatically. + +In XEmacs, the following rules of contagion are used: + +@c #### this probably wants names for each rule +@enumerate +@item +If a fixnum operation would overflow or underflow, the operands are +promoted to bignums and the operation is performed. + +@item +If a fixnum and a bignum are the operands, the fixnum is promoted to +bignum, and the operation is performed. + +@c #### seems plausible +@item +If a float operation would overflow or underflow (@emph{i.e.}, produce +an unrepresentably small but non-zero result), the operands are +converted to bigfloats and the operation performed. + +@c #### seems likely.... +@item +If an expression mixes a rational type (fixnum, bignum, or ratio) with a +float, the rational operand is converted to a float and the operation +performed if the result would fit in a float, otherwise both operands +are promoted to bigfloat, and the operation performed. + +@item +If an expression mixes any other type with a bigfloat, the other operand +is converted to bigfloat and the operation performed. +@end enumerate + +Note that there is @emph{no} contagion with ratios. Integer-to-integer +arithmetic with truncation or rounding is useful, and familiar. +Therefore instead of converting the result of @code{/} to ratio if it is +non-integral, the traditional definition is maintained, and a new +function @code{div} is provided to give a ratio result if a division +does not come out evenly. + +On the other hand, the representation of arbitrary precision numbers is +inefficient in both space and time. The principle of +@dfn{canonicalization} addresses this issue. The idea of +canonicalization is that when no information is lost, the representation +should be demoted to the more efficient (smaller) representation. Note +that the inefficiency is likely to be greater than you might think. +Experience with numerical analysis shows that in very precise +calculations, precision tends to increase. Thus it is typically wasted +effort to attempt to convert to smaller representations, as the number +is often reused and requires a larger representation. However, XEmacs +Lisp presumes that calculations using bignums are the exception, so it +applies canonicalization. The rules are + +@enumerate +@item +If a ratio is integral, demote it to a bignum. (In XEmacs Lisp all +ratios are arbitrary precision numbers.) + +@item +If a bignum is small enough to fit in a fixnum, demote it to fixnum. +@end enumerate + +Note that there are no rules to canonicalize floats or bigfloats. This +might seem surprising, but in both cases information will be lost. Any +floating point representation is implicitly approximate. A conversion +to a rational type, even if it seems exact, loses this information. +More subtly, demoting a bigfloat to a smaller bigfloat or to a float +would lose information about the precision of the result, and thus some +information about the accuracy. Thus floating point numbers are always +already in canonical form. + +Of course the programmer can explicitly request canonicalization, or +more coercion to another type. Coercion uses the Common Lisp +compatibility function @code{coerce} from the @file{cl-extra.el} +library. A number can be explicitly converted to canonical form +according to the above rules using + +@defun canonicalize-number number +Return the canonical form of @var{number}. +@end defun + + +@node Compatibility Issues +@subsection Compatibility Issues + + @emph{Surgeon General's Warning}: The automatic conversions cannot be +disabled at runtime. Old functions will not produce ratios unless there +is a ratio operand, so there should be few surprises with type +conflicts (the contagion rules are quite natural for Lisp programmers +used to the behavior of integers and floats in pre-21.5.18 XEmacsen), +but they can't be ruled out. Also, if you work with extremely large +numbers, your machine may arbitrarily decide to hand you an unpleasant +surprise rather than a bignum. + +User-visible changes in behavior include (in probable order of annoyance) + +@itemize +@item +Arithmetic can cause a segfault, depending on your MP library. + +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 @samp{alloca} is typically implemented to +be @emph{fast} rather than robust. If you just need a little more +oomph, use a bigger stack (@emph{e.g.}, the @file{ulimit -s} command in +bash(1)). If you want robustness at the cost of speed, configure GMP +with @samp{--disable-alloca} and rebuild the GMP library. + +We do not know whether BSD MP uses @samp{alloca} or not. Please send +any information you have as a bug report (@kbd{M-x report-xemacs-bug +@key{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.) + +@item +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. +There are similar issues for floating point numbers. Since Emacs Lisp +has not had a ratio type before, there should be no problems there. + +@item +An atom with ratio read syntax now returns a number, not a symbol. + +@item +Many operations that used to cause a range error now succeed, with +intermediate results and return values coerced to bignums as needed. + +@item +The @samp{%u} format conversion will now give an error if its argument +is negative. (Without MP, it prints a number which Lisp can't read.) +@end itemize + + This is not a compatibility issue in the sense of specification, but +careless programmers who have taken advantage of the immediate +representation for numbers and written @code{(eq x y)} are in for a +surprise. This doesn't work with bignums, even if both arguments are +bignums! Arbitrary precision obviously requires consing new objects +because the objects are ``large'' and of variable size, and the +definition of @samp{eq} does not permit different objects to compare as +equal. Instead of @code{eq}, use @code{eql}, in which numbers of the +same type which have equal values compare equal, or @code{=}, which does +any necessary type coercions before comparing for equality +@ref{Comparison of Numbers}. + + @node Predicates on Numbers @section Type Predicates for Numbers @@ -224,15 +589,16 @@ @emph{object}. By contrast, @code{=} compares only the numeric values of the objects. - At present, each integer value has a unique Lisp object in XEmacs Lisp. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing an -unknown value with an integer, because @code{eq} does not report an -error if the unknown value is not a number---it accepts arguments of any -type. By contrast, @code{=} signals an error if the arguments are not -numbers or markers. However, it is a good idea to use @code{=} if you -can, even for comparing integers, just in case we change the -representation of integers in a future XEmacs version. + In versions before 21.5.18, each integer value had a unique Lisp +object in XEmacs Lisp. Therefore, @code{eq} was equivalent to @code{=} +where integers are concerned. Even with the introduction of bignums, it +is sometimes convenient to use @code{eq} for comparing an unknown value +with an integer, because @code{eq} does not report an error if the +unknown value is not a number---it accepts arguments of any type. By +contrast, @code{=} signals an error if the arguments are not numbers or +markers. However, it is a good idea to use @code{=} if you can, even +for comparing exact values, because two bignums or ratios with the same +value will often not be the same object. There is another wrinkle: because floating point arithmetic is not exact, it is often a bad idea to check for equality of two floating
--- a/man/lispref/specifiers.texi Mon Apr 19 06:40:45 2004 +0000 +++ b/man/lispref/specifiers.texi Mon Apr 19 08:02:38 2004 +0000 @@ -44,6 +44,8 @@ Validating the components of a specifier. * Other Specification Functions:: Other ways of working with specifications. +* Specifier Compatibility Notes:: + Backward compatibility and GNU Emacs. @end menu @node Introduction to Specifiers @@ -1104,7 +1106,7 @@ @defun specifier-matching-instance specifier matchspec &optional domain default no-fallback This function returns an instance for @var{specifier} in @var{domain} that matches @var{matchspec}. If no instance can be generated for -@var{domain}, return @var{default}. +@var{domain}, return @var{default}. @xref{Specifier Compatibility Notes}. This function is identical to @code{specifier-instance} except that a specification will only be considered if it matches @var{matchspec}. @@ -1339,17 +1341,7 @@ Note that since specifiers generalize both frame-local and buffer-local variables in a sensible way, XEmacs is not likely to put a high priority -on implementing frame-local variables. -@c Thanks to Jerry James for the following explanation. He is not -@c responsible for its use here, Stephen Turnbull is. -In fact, some developers think that frame-local variables are evil for -the same reason that buffer-local variables are evil: the declaration is -both global and invisible. That is, you cannot tell whether a variable -is ``normal,'' buffer-local, or frame-local just by looking at it. So -if you have namespace management problems, and some other Lisp package -happens to use a variable name that you already declared frame- or -buffer-local, weird stuff happens, and it is extremely hard to track -down. +on implementing frame-local variables @ref{Specifier Compatibility Notes}. @node Creating Specifiers @@ -1603,3 +1595,88 @@ @defun specifier-locale-type-from-locale locale Given a specifier @var{locale}, this function returns its type. @end defun + +@node Specifier Compatibility Notes +@section Specifier Compatibility Notes + +This node describes compatibility issues in the use of specifiers known +as of 2004-01-22. +@c I considered basing the main text on 21.4, but then future +@c maintenance of this documentation would be a pain. +The main text refers to XEmacs 21.5.16. + +Effort will be made to describe changes in the API or semantics between +XEmacs versions accurately. Any inaccuracy or missing information about +backward and forward compatibility is a bug, and we greatly appreciate +your reports, whether you can provide a patch or not. + +A change is reported as @dfn{changed} when we believe that the new or +changed API will cause old code to malfunction. When old code is +believed to be upward compatible with the changed API, the change is +reported as @dfn{added}. + +We would like to also describe compatibility with GNU Emacs, but this is +not so high a priority. Inaccuracies or omissions will be addressed at +the priority of a feature request, and as such processing will be +greatly expedited if you can provide a patch. +@c #### xref here to bug reporting and patch submissions + +@c #### write and xref a file on compatibility policy + +@subsection Compatibility with GNU Emacs + +Specifiers are not used in GNU Emacs. If your program depends on +specifers, you will probably have to rewrite the functionality +completely for GNU Emacs. If you wish to maximize portability, you +should plan to encapsulate use of specifiers. + +GNU Emacs provides two features for context-sensitive variables, +buffer-local variables and frame-local variables. XEmacs implements +buffer-local variables 100%-compatibly with GNU Emacs. If buffer-local +variables will server your purpose and portability is a major concern, +consider using them instead of specifiers. + +XEmacs does not implement frame-local variables at all. In this case +specifiers must be used to provide equivalent functionality. + +It is not clear whether XEmacs will provide this feature in the future. +@c Thanks to Jerry James for the following explanation. He is not +@c responsible for its use here, Stephen Turnbull is. +In fact, some core XEmacs developers think that both frame-local +variables and buffer-local variables are evil, because the declaration +is both global and invisible. That is, you cannot tell whether a +variable is ``normal,'' buffer-local, or frame-local just by looking at +it. So if you have namespace management problems, and some other Lisp +package happens to use a variable name that you already declared frame- +or buffer-local, weird stuff happens, and it is extremely hard to track +down. +@c #### Direct comments to xemacs-design? + +@subsection Backwards Compatibility with XEmacs 21.4 + +Sorry, I'm unwilling to find out exactly when these changes were made. + +Changed by 21.5.16: the second argument of +@code{specifier-matching-instance} is now a cons of a charset and a +boolean value. Previously it was a charset or a symbol (a name of a +charset). It was not documented in Info. + +Changed by 21.5.16: the specifier-specific error symbols +@code{specifier_syntax_error}, @code{specifier_argument_error}, and +@code{specifier_change_error} were removed. (This probably only +affected internal code.) + +Added by 21.5.16: @code{map-specifier} got two new arguments, +@code{ms-tag-set} and @code{ms-exact-p}. + +Added by 21.5.16: when skipping instantiators, XEmacs warns at level +`debug'. + +Added by 21.5.16: new convenience APIs: +@code{instance-to-instantiator}, +@code{device-type-matches-spec}, +@code{add-tag-to-inst-list}, +@code{derive-domain-from-locale}, +@code{derive-device-type-from-tag-set}, +@code{derive-device-type-from-locale-and-tag-set}, and +@code{derive-specifier-specs-from-locale}.
--- a/man/widget.texi Mon Apr 19 06:40:45 2004 +0000 +++ b/man/widget.texi Mon Apr 19 08:02:38 2004 +0000 @@ -40,15 +40,20 @@ @comment node-name, next, previous, up @section Introduction -Most graphical user interface toolkits, such as Motif and XView, provide +@c XEmacs changes to reflect history, native widgets, and GTK +Most graphical user interface toolkits, since Motif and XView, provide a number of standard user interface controls (sometimes known as -`widgets' or `gadgets'). Emacs doesn't really support anything like -this, except for an incredible powerful text ``widget''. On the other -hand, Emacs does provide the necessary primitives to implement many -other widgets within a text buffer. The @code{widget} package -simplifies this task. +`widgets' or `gadgets'). Historically, Emacs didn't support anything like +this, except for its incredible powerful text ``widget''. However, +since XEmacs 21.4, XEmacs has supported ``native'' widgets (GUI controls +implemented as Lisp APIs in C for the MS Windows, Motif, Athena, and GTK +toolkits) and libglade (GUI controls with an XML API for the GTK +toolkit). On the other hand, Emacs does provide the necessary +primitives to implement many other widgets within a text buffer, and of +course this is the only way to implement self-contained controls in a +text terminal. The @code{widget} package simplifies this task. -The basic widgets are: +Examples of some basic widgets include: @table @code @item link @@ -83,7 +88,7 @@ Now of what possible use can support for widgets be in a text editor? I'm glad you asked. The answer is that widgets are useful for -implementing forms. A @dfn{form} in emacs is a buffer where the user is +implementing forms. A @dfn{form} in Emacs is a buffer where the user is supposed to fill out a number of fields, each of which has a specific meaning. The user is not supposed to change or delete any of the text between the fields. Examples of forms in Emacs are the @file{forms} @@ -100,19 +105,22 @@ You can give the user immediate feedback if he enters invalid data in a text field, and sometimes prevent entering invalid data. @item -You can have fixed sized fields, thus allowing multiple field to be +You can have fixed sized fields, thus allowing multiple fields to be lined up in columns. @item It is simple to query or set the value of a field. @item -Editing happens in buffer, not in the mini-buffer. +Editing happens in a normal buffer, not in the mini-buffer. @item -Packages using the library get a uniform look, making them easier for +Packages using the library get a uniform look-and-feel, making them easier for the user to learn. @item -As support for embedded graphics improve, the widget library will +As support for embedded graphics has improved, the widget library will extended to support it. This means that your code using the widget -library will also use the new graphic features by automatic. +library will also use the new graphic features automatically. +@item +A widget specification is implemented as a class, and new subclasses can +be derived from any class, by restricting or extending the behavior. @end enumerate In order to minimize the code that is loaded by users who does not @@ -120,10 +128,10 @@ @table @file @item widget.el -This will declare the user variables, define the function -@code{define-widget}, and autoload the function @code{widget-create}. +This declares the user variables, defines the function +@code{define-widget}, and autoloads the function @code{widget-create}. @item wid-edit.el -Everything else is here, there is no reason to load it explicitly, as +Everything else is here. Do not load it explicitly, as it will be autoloaded when needed. @end table @@ -168,7 +176,7 @@ @b{[Apply Form]} @b{[Reset Form]} @end example -The top level widgets in is example are tagged @samp{Name}, +The top level widgets in this example are tagged @samp{Name}, @samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers}, @samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and @samp{[Reset Form]}. There are basically two thing the user can do within