Mercurial > hg > xemacs-beta
changeset 1135:9eddcb9548e2
[xemacs-hg @ 2002-12-02 17:56:58 by stephent]
texinfo improvements <87d6okxq4i.fsf@tleepslib.sk.tsukuba.ac.jp>
| author | stephent |
|---|---|
| date | Mon, 02 Dec 2002 17:57:09 +0000 |
| parents | dd61dd14b2a4 |
| children | 14f3ffacd8be |
| files | man/ChangeLog man/internals/internals.texi man/lispref/specifiers.texi man/lispref/toolbar.texi man/xemacs-faq.texi |
| diffstat | 5 files changed, 523 insertions(+), 100 deletions(-) [+] |
line wrap: on
line diff
--- a/man/ChangeLog Mon Dec 02 12:33:32 2002 +0000 +++ b/man/ChangeLog Mon Dec 02 17:57:09 2002 +0000 @@ -1,4 +1,27 @@ -2002-10-29 Stephen J. Turnbull <steve@tleepslib.sk.tsukuba.ac.jp> +2002-11-29 Stephen Turnbull <stephen@xemacs.org> + + * lispref/specifiers.texi (Simple Specifier Usage): New node. + (Specifiers): Adjust node pointers. + (Simple Specifier Usage): Revise. Adjust node pointers. + + * lispref/toolbar.texi (Creating Toolbar): Xref specifier example. + +2002-10-20 Stephen Turnbull <stephen@xemacs.org> + + * xemacs-faq.texi (Q3.2.7): New FAQ on displaying non-ASCII. + (Q3.5.7, Q1.3.3): Cross-reference it. + +2002-10-20 Stephen Turnbull <stephen@xemacs.org> + + * xemacs-faq.texi (Q2.1.1): Mention bug report commands. + (Q2.0.9): Note how out-of-date the entry is. + (Q1.3.1, Q1.3.2, Q1.3.3, Q1.3.4, Q1.3.5, Q1.3.6): Revise/update. + (Q1.2.1): Fix typo. + + * internals/internals.texi (Regression Testing XEmacs): Thorough + rewrite, documenting macros explicitly. + +2002-10-29 Stephen J. Turnbull <stephen@xemacs.org> * lispref/compile.texi (Compilation Options): New node. (Byte Compilation): Add it to menu. @@ -7,12 +30,12 @@ (Dynamic Loading): Document some variable defaults. -2002-11-07 Stephen J. Turnbull <steve@tleepslib.sk.tsukuba.ac.jp> +2002-11-07 Stephen J. Turnbull <stephen@xemacs.org> * internals/internals.texi (Low-Level Modules): Add urefs to Doug Lea's and Wolfram Gloger's home pages. -2002-10-18 Stephen J. Turnbull <steve@tleepslib.sk.tsukuba.ac.jp> +2002-10-18 Stephen J. Turnbull <stephen@xemacs.org> * xemacs-faq.texi (Q2.0.16): New FAQ on "no cygXpm-noX" fatal error. (Q6.1.4): Document cygXpm-noX.
--- a/man/internals/internals.texi Mon Dec 02 12:33:32 2002 +0000 +++ b/man/internals/internals.texi Mon Dec 02 17:57:09 2002 +0000 @@ -3470,11 +3470,20 @@ $ xemacs -batch -l test-harness.elc -f batch-test-emacs TEST-FILE @end example -If something goes wrong, you can run the test suite interactively by -loading @file{test-harness.el} into a running XEmacs and typing -@kbd{M-x test-emacs-test-file RET <filename> RET}. You will see a log of -passed and failed tests, which should allow you to investigate the -source of the error and ultimately fix the bug. +If a test fails and you need more information, you can run the test +suite interactively by loading @file{test-harness.el} into a running +XEmacs and typing @kbd{M-x test-emacs-test-file RET <filename> RET}. +You will see a log of passed and failed tests, which should allow you to +investigate the source of the error and ultimately fix the bug. If you +are not capable of, or don't have time for, debugging it yourself, +please do report the failures using @kbd{M-x report-emacs-bug} or +@kbd{M-x build-report}. + +@deffn Command test-emacs-test-file file +Runs the tests in @var{file}. @file{test-harness.el} must be loaded. +Defines all the macros described in this node, and undefines them when +done. +@end deffn Adding a new test file is trivial: just create a new file here and it will be run. There is no need to byte-compile any of the files in @@ -3484,7 +3493,34 @@ Look at the existing test cases for the examples of coding test cases. It all boils down to your imagination and judicious use of the macros @code{Assert}, @code{Check-Error}, @code{Check-Error-Message}, and -@code{Check-Message}. +@code{Check-Message}. Note that all of these macros are defined only +for the duration of the test: they do not exist in the global +environment. + +@deffn Macro Assert expr +Check that @var{expr} is non-nil at this point in the test. +@end deffn + +@deffn Macro Check-Error expected-error body +Check that execution of @var{body} causes @var{expected-error} to be +signaled. @var{body} is a @code{progn}-like body, and may contain +several expressions. @var{expected-error} is a symbol defined as +an error by @code{define-error}. +@end deffn + +@deffn Macro Check-Error-Message expected-error expected-error-regexp body +Check that execution of @var{body} causes @var{expected-error} to be +signaled, and generate a message matching @var{expected-error-regexp}. +@var{body} is a @code{progn}-like body, and may contain several +expressions. @var{expected-error} is a symbol defined as an error +by @code{define-error}. +@end deffn + +@deffn Macro Check-Message expected-message body +Check that execution of @var{body} causes @var{expected-message} to be +generated (using @code{message} or a similar function). @var{body} is a +@code{progn}-like body, and may contain several expressions. +@end deffn Here's a simple example checking case-sensitive and case-insensitive comparisons from @file{case-tests.el}. @@ -3509,37 +3545,78 @@ (Assert (eq (search-forward "Test Buffer" nil t) 12)))) @end example -This example could be inserted in a file in @file{tests/automated}, and -it would be a complete test, automatically executed when you run +This example could be saved in a file in @file{tests/automated}, and it +would constitute a complete test, automatically executed when you run @kbd{make check} after building XEmacs. More complex tests may require substantial temporary scaffolding to create the environment that elicits -the bugs, but the top-level Makefile and @file{test-harness.el} handle -the running and collection of results from the @code{Assert}, +the bugs, but the top-level @file{Makefile} and @file{test-harness.el} +handle the running and collection of results from the @code{Assert}, @code{Check-Error}, @code{Check-Error-Message}, and @code{Check-Message} macros. +Don't suppress tests just because they're due to known bugs not yet +fixed---use the @code{Known-Bug-Expect-Failure} wrapper macro to mark +them. + +@deffn Macro Known-Bug-Expect-Failure body +Arrange for failing tests in @var{body} to generate messages prefixed +with "KNOWN BUG:" instead of "FAIL:". @var{body} is a @code{progn}-like +body, and may contain several tests. +@end deffn + +A lot of the tests we run push limits; suppress Ebola warning messages +with the @code{Ignore-Ebola} wrapper macro. + +@deffn Macro Ignore-Ebola body +Suppress Ebola warning messages while running tests in @var{body}. +@var{body} is a @code{progn}-like body, and may contain several tests. +@end deffn + +Both macros are defined temporarily within the test function. Simple +examples: + +@example +;; Apparently Ignore-Ebola is a solution with no problem to address. +;; There are no examples in 21.5, anyway. + +;; from regexp-tests.el +(Known-Bug-Expect-Failure + (Assert (not (string-match "\\b" ""))) + (Assert (not (string-match " \\b" " ")))) +@end example + In general, you should avoid using functionality from packages in your tests, because you can't be sure that everyone will have the required package. However, if you've got a test that works, by all means add it. Simply wrap the test in an appropriate test, add a notice that the test -was skipped, and update the @code{skipped-test-reasons} hashtable. -Here's an example from @file{syntax-tests.el}: +was skipped, and update the @code{skipped-test-reasons} hashtable. The +wrapper macro @code{Skip-Test-Unless} is provided to handle common +cases. + +@defvar skipped-test-reasons +Hash table counting the number of times a particular reason is given for +skipping tests. This is only defined within @code{test-emacs-test-file}. +@end defvar + +@deffn Macro Skip-Test-Unless prerequisite reason description body +@var{prerequisite} is usually a feature test (@code{featurep}, +@code{boundp}, @code{fboundp}). @var{reason} is a string describing the +prerequisite; it must be unique because it is used as a hash key in a +table of reasons for skipping tests. @var{description} describes the +tests being skipped, for the test result summary. @var{body} is a +@code{progn}-like body, and may contain several tests. +@end deffn + +@code{Skip-Test-Unless} is defined temporarily within the test function. +Here's an example of usage from @file{syntax-tests.el}: @example ;; Test forward-comment at buffer boundaries (with-temp-buffer - ;; try to use exactly what you need: featurep, boundp, fboundp - (if (not (fboundp 'c-mode)) - - ;; We should provide a standard function for this boilerplate, - ;; probably called `Skip-Test' -- check for that API with C-h f - (let* ((reason "c-mode unavailable") - (count (gethash reason skipped-test-reasons))) - (puthash reason (if (null count) 1 (1+ count)) - skipped-test-reasons) - (Print-Skip "comment and parse-partial-sexp tests" reason)) - + (Skip-Test-Unless (fboundp 'c-mode) + "c-mode unavailable" + "comment and parse-partial-sexp tests" ;; and here's the test code (c-mode) (insert "// comment\n") @@ -3553,11 +3630,11 @@ (parse-partial-sexp point (point-max))))) @end example -@code{Skip-Test} is intended for use with features that are normally +@code{Skip-Test-Unless} is intended for use with features that are normally present in typical configurations. For truly optional features, or tests that apply to one of several alternative implementations (eg, to GTK widgets, but not Athena, Motif, MS Windows, or Carbon), simply -silently omit the test. +silently suppress the test if the feature is not available. @node CVS Techniques, A Summary of the Various XEmacs Modules, Regression Testing XEmacs, Top
--- a/man/lispref/specifiers.texi Mon Dec 02 12:33:32 2002 +0000 +++ b/man/lispref/specifiers.texi Mon Dec 02 17:57:09 2002 +0000 @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the XEmacs Lisp Reference Manual. @c Copyright (C) 1995, 1996 Ben Wing. +@c Copyright (C) 2002 Free Software Foundation, Inc. @c See the file lispref.texi for copying conditions. @setfilename ../../info/specifiers.info @node Specifiers, Faces and Window-System Objects, Extents, top @@ -8,14 +9,13 @@ @cindex specifier A specifier is an object used to keep track of a property whose value -may vary depending on the particular situation (e.g. particular buffer -displayed in a particular window) that it is used in. The value of many -built-in properties, such as the font, foreground, background, and such -properties of a face and variables such as -@code{modeline-shadow-thickness} and @code{top-toolbar-height}, is -actually a specifier object. The specifier object, in turn, is -``instanced'' in a particular situation to yield the real value -of the property in that situation. +should vary according to @emph{display context}, a window, a frame, or +device. The value of many built-in properties, such as the font, +foreground, background, and such properties of a face and variables +such as @code{modeline-shadow-thickness} and +@code{top-toolbar-height}, is actually a specifier object. The +specifier object, in turn, is ``instanced'' in a particular situation +to yield the real value of the property in the current context. @defun specifierp object This function returns non-@code{nil} if @var{object} is a specifier. @@ -26,6 +26,7 @@ display and other properties to vary (under user control) in a wide variety of contexts. +* Simple Specifier Usage:: Getting started with specifiers. * Specifiers In-Depth:: Gory details about specifier innards. * Specifier Instancing:: Instancing means obtaining the ``value'' of a specifier in a particular context. @@ -48,14 +49,16 @@ @node Introduction to Specifiers @section Introduction to Specifiers -Sometimes you may want the value of a property to vary depending on -the context the property is used in. A simple example of this in XEmacs -is buffer-local variables. For example, the variable +Perhaps the most useful way to explain specifiers is via an analogy. +Emacs Lisp programmers are used to @emph{buffer-local variables} +@ref{buffer-local variables}. For example, the variable @code{modeline-format}, which controls the format of the modeline, can have different values depending on the particular buffer being edited. The variable has a default value which most modes will use, but a -specialized package such as Calendar might change the variable so -as to tailor the modeline to its own purposes. +specialized package such as Calendar might change the variable so as +to tailor the modeline to its own purposes. Other variables are +perhaps best thought of as ``mode local,'' such as font-lock keywords, +but they are implemented as buffer locals. Other properties (such as those that can be changed by the @code{modify-frame-parameters} function, for example the color of the @@ -70,11 +73,41 @@ displayed in all other frames on any mono (two-color, e.g. black and white only) displays, and a default value in all other circumstances. -A @dfn{specifier} is a generalization of this, allowing a great deal -of flexibility in controlling exactly what value a property has in which -circumstances. It is most commonly used for display properties, such as -an image or the foreground color of a face. As a simple example, you can -specify that the foreground of the default face be +Specifiers generalize both buffer- and frame-local properties. +Specifiers vary according to the @emph{display} context. Font-lock +keywords in a buffer will be the same no matter which window the +buffer is displayed in, but windows on TTY devices will simply not be +capable of the flexibility that windows on modern GUI devices are. +Specifiers provide a way for the programmer to @emph{declare} that a +emphasized text should be italic on GUI devices and inverse video on +TTYs. They also provide a way for the programmer to declare +fallbacks, so that a color specified as ``chartreuse'' where possible +can fall back to ``yellow'' on devices where only ANSI (4-bit) color +is available. The complex calculations and device querying are +transparent to both user and programmer. You ask for what you want; +it's up to XEmacs to provide it, or a reasonable approximation. + +We call such a declaration a @dfn{specification}. A @dfn{specification} +applies in a particular @dfn{locale}, which is a window, buffer, frame, +device, or the global locale. The value part of the specification is +called an @dfn{instantiator}. The process of determining the value in a +particular context, or @dfn{domain}, is called @dfn{instantiation} or +@dfn{instancing}. A domain is a window, frame, or device. + +The difference between @dfn{locale} and @dfn{domain} is somewhat subtle. +You may think of a locale as a class of domains, which may span +different devices. Since the specification is abstract (a Lisp form), +you can state it without reference to a device. On the other hand, when +you instantiate a specification, you must know the type of the device. +It is useless to specify that ``blue mean italic'' on a monochrome +device. Thus instantiation requires specification of the device on +which it will be rendered. + +Thus a @dfn{specifier} allows a great deal of flexibility in +controlling exactly what value a property has in which circumstances. +It is most commonly used for display properties, such as an image or +the foreground color of a face. As a simple example, you can specify +that the foreground of the default face be @itemize @bullet @item @@ -98,6 +131,150 @@ white for all other buffers @end itemize +@node Simple Specifier Usage +@section Simple Specifier Usage +@cindex specifier examples +@cindex examples, specifier +@cindex adding a button to a toolbar +@cindex toolbar button, adding + +A useful specifier application is adding a button to a toolbar. XEmacs +provides several toolbars, one along each edge of the frame. Normally +only one is used at a time, the default. The default toolbar is +actually a specifier object which is the value of @code{default-toolbar}. + +The specification of a toolbar is simple: it is a list of buttons. +Each button is a vector with four elements: an icon, a command, the +enabled flag, and a help string. Let's retrieve the instance of the +toolbar you see in the selected frame. + +@example +(specifier-instance default-toolbar) +@end example + +The value returned is, as promised, a list of vectors. Now let's build +up a button, and add it to the toolbar. Our button will invoke the last +defined keyboard macro. This is an alternative to +@code{name-last-kbd-macro} for creating a persistent macro, rather than +an alias for @kbd{C-x e}. + +A toolbar button icon can be quite sophisticated, with different images +for button up, button down, and disabled states, and a similar set with +captions. We'll use a very simple icon, but we have to jump through a +few non-obvious hoops designed to support the sophisticated applications. +The rest of the button descriptor is straightforward. + +@example +(setq toolbar-my-kbd-macro-button + `[ (list (make-glyph "MyKbdMac")) + (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) + t + "Execute a previously defined keyboard macro." ]) + +(set-specifier default-toolbar + (cons toolbar-my-kbd-macro-button + (specifier-specs default-toolbar 'global)) + 'global) +@end example + +To remove the button, just substitute the function @code{delete} for the +@code{cons} above. + +What is the difference between @code{specifier-instance}, which we used +in the example of retrieving the toolbar descriptor, and +@code{specifier-specs}, which was used in the toolbar manipulating code? +@code{specifier-specs} retrieves a copy of the instantiator, which is +abstract and does not depend on context. @code{specifier-instance}, on +the other hand, actually instantiates the specification, and returns the +result for the given context. Another way to express this is: +@code{specifier-specs} takes a @emph{locale} as an argument, while +@code{specifier-instance} takes a @emph{domain}. The reason for +providing @code{specifier-instance} is that sometimes you wish to see +the object that XEmacs will actually use. @code{specifier-specs}, on +the other hand, shows you what the programmer (or user) requested. When +a program manipulates specifications, clearly it's the latter that is +desirable. + +In the case of the toolbar descriptor, it turns out that these are the +same: the instancing process is trivial. However, many specifications +have non-trivial instancing. Compare the results of the following forms +on my system. (The @samp{(cdr (first ...))} form is due to my use of +Mule. On non-Mule XEmacsen, just use @code{specifier-specs}.) + +@example +(cdr (first (specifier-specs (face-font 'default) 'global))) +=> "-*--14-*jisx0208*-0" + +(specifier-instance (face-font 'default)) +#<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b> +@end example + +In this case, @code{specifier-instance} returns an opaque object; +programs can't work on it, they can only pass it around. Worse, in some +environments the instantiation will fail, resulting in a different value +(when another instantiation succeeds), or worse yet, an error, if all +attempts to instance the specifier fail. @code{specifier-instance} is +context-dependent, even for the exact same specification. +@code{specifier-specs} is deterministic, and only depends on the +specifications. + +Note that in the toolbar-changing code we operate in the global locale. +This means that narrower locales, if they have specifications, will +shadow our changes. (Specifier instancing does not merge +specifications. It selects the "highest-priority successful +specification" and instances that.) + +In fact, in our example, it seems pretty likely that different buffers +@emph{should} have different buttons. (The icon can be the same, but +the keyboard macro you create in a Dired buffer is highly unlikely to be +useful in a LaTeX buffer!) Here's one way to implement this: + +@example +(setq toolbar-my-kbd-macro-button + `[ (list (make-glyph "MyKbdMac")) + (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) + t + "Execute a previously defined keyboard macro." ]) + +(set-specifier default-toolbar + (cons toolbar-my-kbd-macro-button + (cond ((specifier-specs default-toolbar + (current-buffer))) + ((specifier-specs default-toolbar + 'global))) + (current-buffer)) +@end example + +Finally, a cautionary note: the use of @code{specifier-specs} in the +code above is for expository purposes. Don't use it in production code. +In fact, the @code{set-specifier} form above is likely to fail +occasionally, because you can add many specifications for the same +locale. + +In these cases, @code{specifier-specs} will return a list. A further +refinement is that a specification may be associated with a set of +@dfn{specifier tags}. If the list of specifier tags is non-nil, then +@code{specifier-specs} will return a cons of the tag set and the +instantiator. Evidently @code{specifier-specs} is a bit unreliable. +(For toolbars, the code above should work 99% of the time, because +toolbars are rarely changed. Since instantiation is trivial, multiple +specs are not useful---the first one always succeeds.) + +In fact, @code{specifier-specs} is intended to be used to display specs +to humans with a minimum of clutter. The robust way to access +specifications is via @code{specifier-spec-list}. @xref{Adding +Specifications}, for the definition of @dfn{spec-list}. +@xref{Retrieving Specifications} for documentation of +@code{specifier-specs} and @code{specifier-spec-list}. To get the +desired effect, replace the form @code{(specifier-spec default-toolbar +'global)} with + +@example +(cdr (second (first (specifier-spec-list default-toolbar 'global)))) +@end example + +(It should be obvious why the example uses the lazy unreliable method!) + @node Specifiers In-Depth @section In-Depth Overview of a Specifier @cindex specification (in a specifier) @@ -121,12 +298,36 @@ @cindex specifier, tag @cindex specifier, tag set -A specifier object encapsulates a set of @dfn{specifications}, each of -which says what its value should be if a particular condition applies. +Having variables vary according the editing context is very useful, and +the buffer is the natural ``atomic'' unit of editing context. In a GUI +environment, it can be similarly useful to have variables whose values +vary according to display context. The atomic unit of display context +is the Emacs window. Buffers are cleanly grouped by modes, but windows +are not so easily pigeonholed. On the one hand, a window displays a +buffer, and thus one possible hierarchy is window, buffer, mode. On the +other, a window is a component of a frame. This generates the window, +frame, device hierarchy. Finally, there are objects such as toolbars +whose properties are described by specifiers. These do not fit +naturally into either hierarchy. This problem is as yet not cleanly +solved. + +Another potential source of conceptual confusion is the instantiation +process. Instantiating a buffer-local variable is simple: at any given +point in time there is a current buffer, and its local values are used +and set whenever the variable is accessed, unless the programmer goes to +some special effort (uses @code{default-value} and @code{set-default}. +However, a specifier object encapsulates a set of @dfn{specifications}, +each of which says what its value should be if a particular condition +applies. Several such conditions might apply simultaneously in a given +window. + For example, one specification might be ``The value should be darkseagreen2 on X devices'' another might be ``The value should be blue -in the *Help* buffer''. In specifier terminology, these conditions are -called @dfn{locales} and the values are called @dfn{instantiators}. +in the *Help* buffer''. So what do we do for "the *Help* buffer on an X +device"? The answer is simple: give each type of locale a priority and +check them in priority order, returning the first instantiator that +successfully instantiates a value. + Given a specifier, a logical question is ``What is its value in a particular situation?'' This involves looking through the specifications to see which ones apply to this particular situation, and perhaps @@ -140,6 +341,13 @@ window; in other words, it asks the specifier, ``What is your value in this window?''. +Note that the redisplay example is in a sense canonical. That is, +specifiers are designed to present a uniform and @emph{efficient} API +to redisplay. It is the efficiency constraint that motivates the +introduction of specifier tags, and many restrictions on access (for +example, a buffer is not a domain, and you cannot instantiate a +specifier over a buffer). + More specifically, a specifier contains a set of @dfn{specifications}, each of which associates a @dfn{locale} (a window object, a buffer object, a frame object, a device object, or the symbol @code{global}) @@ -160,8 +368,9 @@ device. (If a tag does not have a predicate, it matches all devices.) All tags in a tag set must match a device for the associated inst-pair to be instantiable over that device. (A null tag set is perfectly -valid.) +valid, and trivially matches all devices.) +@c #### don't we have more device types now, gtk, ms-windows, mac-carbon? The valid device types (normally @code{x}, @code{tty}, and @code{stream}) and device classes (normally @code{color}, @code{grayscale}, and @code{mono}) can always be used as tags, and match
--- a/man/lispref/toolbar.texi Mon Dec 02 12:33:32 2002 +0000 +++ b/man/lispref/toolbar.texi Mon Dec 02 17:57:09 2002 +0000 @@ -80,6 +80,10 @@ of the exact format. @end defun +The default toolbar is created in @file{toolbar-items.el}. An example +which modifies an existing toolbar (by adding a button) is presented in +the specifier section @xref{Simple Specifier Usage}. + @node Toolbar Descriptor Format @section Toolbar Descriptor Format
--- a/man/xemacs-faq.texi Mon Dec 02 12:33:32 2002 +0000 +++ b/man/xemacs-faq.texi Mon Dec 02 17:57:09 2002 +0000 @@ -7,7 +7,7 @@ @finalout @titlepage @title XEmacs FAQ -@subtitle Frequently asked questions about XEmacs @* Last Modified: $Date: 2002/10/18 05:43:35 $ +@subtitle Frequently asked questions about XEmacs @* Last Modified: $Date: 2002/12/02 17:56:58 $ @sp 1 @author Tony Rossini <rossini@@biostat.washington.edu> @author Ben Wing <ben@@xemacs.org> @@ -794,7 +794,7 @@ @end html -@item @email{turnbull@@sk.tsukuba.ac.jp, Steven Turnbull} +@item @email{stephen@@xemacs.org, Stephen Turnbull} @item @email{ben@@xemacs.org, Ben Wing} @@ -912,10 +912,12 @@ @unnumberedsubsec Q1.3.1: What is the status of internationalization support aka MULE (including Asian language support? Both the stable and development versions of XEmacs include -internationalization support (aka MULE). MULE currently works on UNIX -and Linux systems; work for supporting MULE on Windows operating systems -is in progress. Binaries compiled without MULE support run faster than -MULE capable XEmacsen. +internationalization support (aka MULE). MULE currently (21.4) works on +UNIX and Linux systems. It is possible to build with MULE on Windows +systems, but if you really need MULE on Windows, it is recommended that +you build and use the development (21.5) version, and deal with the +instability of the development tree. Binaries compiled without MULE +support run faster than MULE capable XEmacsen. @node Q1.3.2, Q1.3.3, Q1.3.1, Introduction @unnumberedsubsec Q1.3.2: How can I help with internationalization? @@ -925,20 +927,31 @@ people who speak/write languages other than English, who are willing to use XEmacs/MULE regularly, and have some experience with Elisp. +Translations of the TUTORIAL and man page are welcome, and XEmacs does +support multilingual menus, but we have few current translations. + @xref{Q1.1.2}. @node Q1.3.3, Q1.3.4, Q1.3.2, Introduction @unnumberedsubsec Q1.3.3: How do I type non-ASCII characters? -See question 3.5.7 (@pxref{Q3.5.7}) in part 3 of this FAQ. +See question 3.5.7 (@pxref{Q3.5.7}) in part 3 of this FAQ for some +simple methods that also work in non-MULE builds of XEmacs (but only for +one-octet coded character sets, and mostly for ISO 8859/1). Many of the +methods available for Cyrillic (@pxref{Q1.3.7}) work without MULE. +MULE has more general capabilities. @xref{Q1.3.5}. + +@xref{Q3.2.7}, which covers display of non-ASCII characters. @node Q1.3.4, Q1.3.5, Q1.3.3, Introduction @unnumberedsubsec Q1.3.4: Can XEmacs messages come out in a different language? -The message-catalog support has mostly been written but doesn't -currently work. The first release of XEmacs 20 will @emph{not} support -it. However, menubar localization @emph{does} work. To -enable it, add to your @file{Emacs} file entries like this: +The message-catalog support was written but is badly bit-rotted. XEmacs +20 and 21 did @emph{not} support it, and early releases of XEmacs 22 +will not either. + +However, menubar localization @emph{does} work. To enable it, add to +your @file{Emacs} file entries like this: @example Emacs*XlwMenu.resourceLabels: True @@ -952,30 +965,73 @@ @node Q1.3.5, Q1.3.6, Q1.3.4, Introduction @unnumberedsubsec Q1.3.5: Please explain the various input methods in MULE/XEmacs -@email{morioka@@jaist.ac.jp, MORIOKA Tomohiko} writes: - -@quotation -Original Mule supports the following input methods: Wnn4, Wnn6, Canna, SJ3 -and XIM. Interfaces for Wnn and SJ3 uses the @code{egg} user -interface. Interface for Canna does not use @samp{egg}. I don't know -about XIM. It is to support ATOK, of course, it may work for another -servers. +Mule supports a wide variety of input methods. There are three basic +classes: Lisp implementations, generic platform support, and library +interfaces. + +@emph{Lisp implementations} include Quail, which provides table-driven input +methods for almost all the character sets that Mule supports (including +all of the ISO 8859 family, the Indic languages, Thai, and so on), and +SKK, for Japanese. (SKK also supports an interface to an external +"dictionary server" process.) Quail supports both typical "dead-key" +methods (eg, in the "latin-1-prefix" method, @kbd{" a} produces ä, LATIN +SMALL LETTER A WITH DIAERESIS), and the complex dictionary-based phonetic +methods used for Asian ideographic languages like Chinese. + +Lisp implementations can be less powerful (but they are not perceptibly +inefficient), and of course are not portable to non-Emacs applications. +The incompatibility can be very annoying. On the other hand, they +require no special platform support or external libraries, so if you can +display the characters, Mule can input them for you and you can edit, +anywhere. + +@emph{Generic platform support} is currently limited to the X Input +Method (XIM) framework, although support for MSIME (for MS Windows) is +planned, and IIIMF (Sun's Internet-Intranet Input Method Framework) +support is extremely desirable. XIM is enabled at build time by use of +the @samp{--with-xim} flag to @code{configure}. For use of XIM, see +your platform documentation. However, normally the input method you use +is specified via the @samp{LANG} and @samp{XMODIFIERS} environment +variables. + +Of course, input skills are portable across most applications. However, +especially in modern GUI systems the habit of using bucky bits has +fallen into sad disuse, and many XIM systems are poorly configured for +use with Emacs. For example, the kinput2 input manager (a separate +process providing an interface between Japanese dictionary servers such +as Canna and Wnn, and the application) tends to gobble up keystrokes +generating Meta characters. This means that to edit while using an XIM +input method, you must toggle the input method off every time you want +to use @kbd{M-f}. Your mileage may vary. + +@emph{Library interfaces} are most common for Japanese, although Wnn +supports Chinese (traditional and simplified) and Korean. There are +Chinese and Korean input servers available, but we do not know of any +patches for XEmacs to use them directly. You can use them via +IM-enabled terminals, by manipulating the terminal coding systems. We +describe only the Japanese-oriented systems here. The advantage of +these systems is that they are very powerful, and on platforms where +they are available there is typically a wide range of applications that +support them. Thus your input skills are portable across applications. + +Mule provides built-in interfaces to the following input methods: Wnn4, +Wnn6, Canna, and SJ3. These can be configured at build time. There are +patches available (no URL, sorry) to support the SKK server, as well. +Wnn and SJ3 use the @code{egg} user interface. The interface for Canna +is specialized to Canna. Wnn supports Japanese, Chinese and Korean. It is made by OMRON and Kyôto -university. It is a powerful and complex system. Wnn4 is free and Wnn6 -is not free. - -Canna supports only Japanese. It is made by NEC. It is a simple and -powerful system. Canna uses only grammar (Wnn uses grammar and -probability between words), so I think Wnn is cleverer than Canna, -however Canna users made a good grammar and dictionary. So for standard -modern Japanese, Canna seems cleverer than Wnn4. In addition, the UNIX -version of Canna is free (now there is a Microsoft Windows version). - -SJ3 supports only Japanese. It is made by Sony. XIM supports was made -to use ATOK (a major input method in personal computer world). XIM is -the standard for accessing input methods bundled in Japanese versions of -Solaris. (XEmacs 20 will support XIM input). +University. It is a powerful and complex system. Wnn4 is free and Wnn6 +is not. Wnn uses grammatical hints and probability of word association, +so in principle Wnn can be cleverer than other methods. + +Canna, made by NEC, supports only Japanese. It is a simple and powerful +system. Canna uses only grammar, but its grammar and dictionary are +quite sophisticated. So for standard modern Japanese, Canna seems +cleverer than Wnn4. In addition, the UNIX version of Canna is free (now +there is a Microsoft Windows version). + +SJ3, by Sony, supports only Japanese. Egg consists of following parts: @@ -986,35 +1042,50 @@ @item Kana/PinYin/Hangul to Kanji transfer layer. -It is interface layer for network Kana-Kanji server (Wnn and Sj3). +The interface layer to network Kana-Kanji server (Wnn and Sj3). @end enumerate -These input methods are modal, namely there are mode, alphabet mode and -Kana-Kanji transfer mode. However there are mode-less input methods for -Egg and Canna. @samp{Boiled-egg} is a mode-less input method running on -Egg. For Canna, @samp{canna.el} has a tiny boiled-egg like command, -@code{(canna-boil)}, and there are some boiled-egg like utilities. In -addition, it was planned to make an abstraction for all transfer type -input methods. However authors of input methods are busy, so maybe this -plan is stopped. Perhaps after Mule merged GNU Emacs will be released, -it will be continued. -@end quotation +These input methods are modal. They have a raw (alphabet) mode, a +phonetic input mode, and Kana-Kanji transfer mode. However there are +mode-less input methods for Egg and Canna. @samp{boiled-egg} is a +mode-less input method running on Egg. For Canna, @samp{canna.el} has a +tiny boiled-egg-like command, @code{(canna-boil)}, and there are some +boiled-egg-like utilities. + +Much of this information was provided by @email{morioka@@jaist.ac.jp, +MORIOKA Tomohiko}. @node Q1.3.6, Q1.3.7, Q1.3.5, Introduction @unnumberedsubsec Q1.3.6: How do I portably code for MULE/XEmacs? +MULE has evolved rapidly over the last few years, and the original third +party patch (for GNU Emacs 19), GNU Emacs 20+, and XEmacs 20+ have quite +different implementations. The APIs also vary although recent versions +of XEmacs have tended to converge to the GNU Emacs standard. + +MULE implementations are going to continue to evolve. Both GNU Emacs +and XEmacs are working hard on Unicode support, which will involve new +APIs and probably variations on old ones. For XEmacs 22, the old ISO +2022-based system for recognizing encodings will be replaced by a much +more flexible system, which should improve accuracy of automatic coding +detections, but will also involve new APIs. + @email{morioka@@jaist.ac.jp, MORIOKA Tomohiko} writes: @quotation -MULE and XEmacs are quite different. So the application -implementor must write separate code for these mule variants. +The application implementor must write separate code for these mule +variants. [Please don't hesitate to report these variants to us; they +are not, strictly speaking, bugs, but they give third-party developers +the same kind of creepy-crawly feeling. We'll do what we can. -- Ed.] MULE and the next version of Emacs are similar but the symbols are very different---requiring separate code as well. Namely we must support 3 kinds of mule variants and 4 or 5 or 6 kinds of emacs variants... (;_;) I'm shocked, so I wrote a wrapper package called -@code{emu} to provide a common interface. +@code{emu} to provide a common interface. [There is an XEmacs package +of APEL which provides much more comprehensive coverage. Be careful, +however; APEL has problems of its own. -- Ed.] I have the following suggestions about dealing with mule variants: @@ -1508,6 +1579,9 @@ @* @end iftex @uref{ftp://ftp.xemacs.org/pub/xemacs/aux/}. +[These tarballs and this FAQ are wa-a-ay out of date. Sorry, I'm not +currently network-capable, and I will probably forgot to update this +before submitting the patch. -- Ed.] @c Changed June Link above, <URL:ftp://ftp.xemacs.org/pub/aux/> was dead. @c This list is a pain in the you-know-what to keep in synch with the @@ -1780,6 +1854,12 @@ If the problem happened on a tty, please include the terminal type. @end enumerate +Much of the information above is automatically generated by @kbd{M-x +report-emacs-bug}. Even more, and often useful, information can be +generated by redirecting the output of @code{make} and @code{make check} +to a file (@file{beta.err} is the default used by @code{build-report}), +and executing @kbd{M-x build-report}. + @node Q2.1.2, Q2.1.3, Q2.1.1, Installation @unnumberedsubsec Q2.1.2: Cryptic Minibuffer messages. @@ -2939,7 +3019,7 @@ (set-device-class nil 'color)) @end lisp -@node Q3.2.6, Q3.3.1, Q3.2.5, Customization +@node Q3.2.6, Q3.2.7, Q3.2.5, Customization @unnumberedsubsec Q3.2.6: Can I have pixmap backgrounds in XEmacs? @c New @email{jvillaci@@wahnsinnig.extreme.indiana.edu, Juan Villacis} writes: @@ -2967,7 +3047,34 @@ @end quotation -@node Q3.3.1, Q3.3.2, Q3.2.6, Customization +@node Q3.2.7, Q3.3.1, Q3.2.6, Customization +@unnumberedsubsec Q3.2.7: How do I display non-ASCII characters? +@c New + +If you're using a Mule-enabled XEmacs, then display is automatic. If +you're not seeing the characters you expect, either (1) you don't have +appropriate fonts available or (2) XEmacs did not correctly detect the +coding system (@pxref{Recognize Coding, , , xemacs}). In case (1), +install fonts as is customary for your platform. In case (2), you +need to tell XEmacs explicitly what coding systems you're using. +@ref{Specify Coding, , , xemacs}. + +If your XEmacs is not Mule-enabled, and for some reason getting a +Mule-enabled XEmacs seems like the wrong thing to do, all is not lost. +You can arrange it by brute force. In @file{event-Xt.c} (suppress the +urge to look in this file---play Doom instead, because you'll survive +longer), it is written: + +@quotation +In a non-Mule world, a user can still have a multi-lingual editor, by +doing @code{(set-face-font "-*-iso8859-2" (current-buffer))} for all +their Latin-2 buffers, etc. +@end quotation + +For the related problem of @emph{inputting} non-ASCII characters in a +non-Mule XEmacs, @xref{Q3.5.7}. + +@node Q3.3.1, Q3.3.2, Q3.2.7, Customization @unnumberedsec 3.3: The Modeline @unnumberedsubsec Q3.3.1: How can I make the modeline go away? @@ -3326,6 +3433,9 @@ Running @samp{xmodmap -pk} will list all of the defined keysyms. @end quotation +For the related problem of @emph{displaying} non-ASCII characters in a +non-Mule XEmacs, @xref{Q3.2.7}. + @node Q3.5.8, Q3.5.9, Q3.5.7, Customization @unnumberedsubsec Q3.5.8: [This question intentionally left blank]