Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips
+File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems
+
+Coding System Properties
+------------------------
+
+`mnemonic'
+ String to be displayed in the modeline when this coding system is
+ active.
+
+`eol-type'
+ End-of-line conversion to be used. It should be one of the types
+ listed in *Note EOL Conversion::.
+
+`eol-lf'
+ The coding system which is the same as this one, except that it
+ uses the Unix line-breaking convention.
+
+`eol-crlf'
+ The coding system which is the same as this one, except that it
+ uses the DOS line-breaking convention.
+
+`eol-cr'
+ The coding system which is the same as this one, except that it
+ uses the Macintosh line-breaking convention.
+
+`post-read-conversion'
+ Function called after a file has been read in, to perform the
+ decoding. Called with two arguments, START and END, denoting a
+ region of the current buffer to be decoded.
+
+`pre-write-conversion'
+ Function called before a file is written out, to perform the
+ encoding. Called with two arguments, START and END, denoting a
+ region of the current buffer to be encoded.
+
+ The following additional properties are recognized if TYPE is
+`iso2022':
+
+`charset-g0'
+`charset-g1'
+`charset-g2'
+`charset-g3'
+ The character set initially designated to the G0 - G3 registers.
+ The value should be one of
+
+ * A charset object (designate that character set)
+
+ * `nil' (do not ever use this register)
+
+ * `t' (no character set is initially designated to the
+ register, but may be later on; this automatically sets the
+ corresponding `force-g*-on-output' property)
+
+`force-g0-on-output'
+`force-g1-on-output'
+`force-g2-on-output'
+`force-g3-on-output'
+ If non-`nil', send an explicit designation sequence on output
+ before using the specified register.
+
+`short'
+ If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $
+ B' on output in place of the full designation sequences `ESC $ (
+ @', `ESC $ ( A', and `ESC $ ( B'.
+
+`no-ascii-eol'
+ If non-`nil', don't designate ASCII to G0 at each end of line on
+ output. Setting this to non-`nil' also suppresses other
+ state-resetting that normally happens at the end of a line.
+
+`no-ascii-cntl'
+ If non-`nil', don't designate ASCII to G0 before control chars on
+ output.
+
+`seven'
+ If non-`nil', use 7-bit environment on output. Otherwise, use
+ 8-bit environment.
+
+`lock-shift'
+ If non-`nil', use locking-shift (SO/SI) instead of single-shift or
+ designation by escape sequence.
+
+`no-iso6429'
+ If non-`nil', don't use ISO6429's direction specification.
+
+`escape-quoted'
+ If non-`nil', literal control characters that are the same as the
+ beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in
+ particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3
+ (0x8F), and CSI (0x9B)) are "quoted" with an escape character so
+ that they can be properly distinguished from an escape sequence.
+ (Note that doing this results in a non-portable encoding.) This
+ encoding flag is used for byte-compiled files. Note that ESC is a
+ good choice for a quoting character because there are no escape
+ sequences whose second byte is a character from the Control-0 or
+ Control-1 character sets; this is explicitly disallowed by the ISO
+ 2022 standard.
+
+`input-charset-conversion'
+ A list of conversion specifications, specifying conversion of
+ characters in one charset to another when decoding is performed.
+ Each specification is a list of two elements: the source charset,
+ and the destination charset.
+
+`output-charset-conversion'
+ A list of conversion specifications, specifying conversion of
+ characters in one charset to another when encoding is performed.
+ The form of each specification is the same as for
+ `input-charset-conversion'.
+
+ The following additional properties are recognized (and required) if
+TYPE is `ccl':
+
+`decode'
+ CCL program used for decoding (converting to internal format).
+
+`encode'
+ CCL program used for encoding (converting to external format).
+
+ The following properties are used internally: EOL-CR, EOL-CRLF,
+EOL-LF, and BASE.
-Writing Clean Lisp Programs
-===========================
+\1f
+File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems
+
+Basic Coding System Functions
+-----------------------------
+
+ - Function: find-coding-system coding-system-or-name
+ This function retrieves the coding system of the given name.
+
+ If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply
+ returned. Otherwise, CODING-SYSTEM-OR-NAME should be a symbol.
+ If there is no such coding system, `nil' is returned. Otherwise
+ the associated coding system object is returned.
+
+ - Function: get-coding-system name
+ This function retrieves the coding system of the given name. Same
+ as `find-coding-system' except an error is signalled if there is no
+ such coding system instead of returning `nil'.
+
+ - Function: coding-system-list
+ This function returns a list of the names of all defined coding
+ systems.
+
+ - Function: coding-system-name coding-system
+ This function returns the name of the given coding system.
+
+ - Function: coding-system-base coding-system
+ Returns the base coding system (undecided EOL convention) coding
+ system.
- Here are some tips for avoiding common errors in writing Lisp code
-intended for widespread use:
-
- * Since all global variables share the same name space, and all
- functions share another name space, you should choose a short word
- to distinguish your program from other Lisp programs. Then take
- care to begin the names of all global variables, constants, and
- functions with the chosen prefix. This helps avoid name conflicts.
-
- This recommendation applies even to names for traditional Lisp
- primitives that are not primitives in XEmacs Lisp--even to `cadr'.
- Believe it or not, there is more than one plausible way to define
- `cadr'. Play it safe; append your name prefix to produce a name
- like `foo-cadr' or `mylib-cadr' instead.
-
- If you write a function that you think ought to be added to Emacs
- under a certain name, such as `twiddle-files', don't call it by
- that name in your program. Call it `mylib-twiddle-files' in your
- program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu'
- suggesting we add it to Emacs. If and when we do, we can change
- the name easily enough.
-
- If one prefix is insufficient, your package may use two or three
- alternative common prefixes, so long as they make sense.
-
- Separate the prefix from the rest of the symbol name with a hyphen,
- `-'. This will be consistent with XEmacs itself and with most
- Emacs Lisp programs.
-
- * It is often useful to put a call to `provide' in each separate
- library program, at least if there is more than one entry point to
- the program.
-
- * If a file requires certain other library programs to be loaded
- beforehand, then the comments at the beginning of the file should
- say so. Also, use `require' to make sure they are loaded.
-
- * If one file FOO uses a macro defined in another file BAR, FOO
- should contain this expression before the first use of the macro:
-
- (eval-when-compile (require 'BAR))
-
- (And BAR should contain `(provide 'BAR)', to make the `require'
- work.) This will cause BAR to be loaded when you byte-compile
- FOO. Otherwise, you risk compiling FOO without the necessary
- macro loaded, and that would produce compiled code that won't work
- right. *Note Compiling Macros::.
-
- Using `eval-when-compile' avoids loading BAR when the compiled
- version of FOO is _used_.
-
- * If you define a major mode, make sure to run a hook variable using
- `run-hooks', just as the existing major modes do. *Note Hooks::.
-
- * If the purpose of a function is to tell you whether a certain
- condition is true or false, give the function a name that ends in
- `p'. If the name is one word, add just `p'; if the name is
- multiple words, add `-p'. Examples are `framep' and
- `frame-live-p'.
-
- * If a user option variable records a true-or-false condition, give
- it a name that ends in `-flag'.
-
- * Please do not define `C-c LETTER' as a key in your major modes.
- These sequences are reserved for users; they are the *only*
- sequences reserved for users, so we cannot do without them.
-
- Instead, define sequences consisting of `C-c' followed by a
- non-letter. These sequences are reserved for major modes.
+ - Function: make-coding-system name type &optional doc-string props
+ This function registers symbol NAME as a coding system.
- Changing all the major modes in Emacs 18 so they would follow this
- convention was a lot of work. Abandoning this convention would
- make that work go to waste, and inconvenience users.
+ TYPE describes the conversion method used and should be one of the
+ types listed in *Note Coding System Types::.
- * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:'
- or `;' are also reserved for major modes.
-
- * Sequences consisting of `C-c' followed by any other punctuation
- character are allocated for minor modes. Using them in a major
- mode is not absolutely prohibited, but if you do that, the major
- mode binding may be shadowed from time to time by minor modes.
-
- * You should not bind `C-h' following any prefix character (including
- `C-c'). If you don't bind `C-h', it is automatically available as
- a help character for listing the subcommands of the prefix
- character.
-
- * You should not bind a key sequence ending in <ESC> except following
- another <ESC>. (That is, it is ok to bind a sequence ending in
- `<ESC> <ESC>'.)
-
- The reason for this rule is that a non-prefix binding for <ESC> in
- any context prevents recognition of escape sequences as function
- keys in that context.
-
- * Applications should not bind mouse events based on button 1 with
- the shift key held down. These events include `S-mouse-1',
- `M-S-mouse-1', `C-S-mouse-1', and so on. They are reserved for
- users.
-
- * Modes should redefine `mouse-2' as a command to follow some sort of
- reference in the text of a buffer, if users usually would not want
- to alter the text in that buffer by hand. Modes such as Dired,
- Info, Compilation, and Occur redefine it in this way.
-
- * When a package provides a modification of ordinary Emacs behavior,
- it is good to include a command to enable and disable the feature,
- Provide a command named `WHATEVER-mode' which turns the feature on
- or off, and make it autoload (*note Autoload::). Design the
- package so that simply loading it has no visible effect--that
- should not enable the feature. Users will request the feature by
- invoking the command.
-
- * It is a bad idea to define aliases for the Emacs primitives. Use
- the standard names instead.
-
- * Redefining an Emacs primitive is an even worse idea. It may do
- the right thing for a particular program, but there is no telling
- what other programs might break as a result.
-
- * If a file does replace any of the functions or library programs of
- standard XEmacs, prominent comments at the beginning of the file
- should say which functions are replaced, and how the behavior of
- the replacements differs from that of the originals.
-
- * Please keep the names of your XEmacs Lisp source files to 13
- characters or less. This way, if the files are compiled, the
- compiled files' names will be 14 characters or less, which is
- short enough to fit on all kinds of Unix systems.
-
- * Don't use `next-line' or `previous-line' in programs; nearly
- always, `forward-line' is more convenient as well as more
- predictable and robust. *Note Text Lines::.
-
- * Don't call functions that set the mark, unless setting the mark is
- one of the intended features of your program. The mark is a
- user-level feature, so it is incorrect to change the mark except
- to supply a value for the user's benefit. *Note The Mark::.
-
- In particular, don't use these functions:
-
- * `beginning-of-buffer', `end-of-buffer'
-
- * `replace-string', `replace-regexp'
-
- If you just want to move point, or replace a certain string,
- without any of the other features intended for interactive users,
- you can replace these functions with one or two lines of simple
- Lisp code.
-
- * Use lists rather than vectors, except when there is a particular
- reason to use a vector. Lisp has more facilities for manipulating
- lists than for vectors, and working with lists is usually more
- convenient.
-
- Vectors are advantageous for tables that are substantial in size
- and are accessed in random order (not searched front to back),
- provided there is no need to insert or delete elements (only lists
- allow that).
-
- * The recommended way to print a message in the echo area is with
- the `message' function, not `princ'. *Note The Echo Area::.
-
- * When you encounter an error condition, call the function `error'
- (or `signal'). The function `error' does not return. *Note
- Signaling Errors::.
-
- Do not use `message', `throw', `sleep-for', or `beep' to report
- errors.
-
- * An error message should start with a capital letter but should not
- end with a period.
-
- * Try to avoid using recursive edits. Instead, do what the Rmail `e'
- command does: use a new local keymap that contains one command
- defined to switch back to the old local keymap. Or do what the
- `edit-options' command does: switch to another buffer and let the
- user switch back at will. *Note Recursive Editing::.
-
- * In some other systems there is a convention of choosing variable
- names that begin and end with `*'. We don't use that convention
- in Emacs Lisp, so please don't use it in your programs. (Emacs
- uses such names only for program-generated buffers.) The users
- will find Emacs more coherent if all libraries use the same
- conventions.
-
- * Indent each function with `C-M-q' (`indent-sexp') using the
- default indentation parameters.
-
- * Don't make a habit of putting close-parentheses on lines by
- themselves; Lisp programmers find this disconcerting. Once in a
- while, when there is a sequence of many consecutive
- close-parentheses, it may make sense to split them in one or two
- significant places.
-
- * Please put a copyright notice on the file if you give copies to
- anyone. Use the same lines that appear at the top of the Lisp
- files in XEmacs itself. If you have not signed papers to assign
- the copyright to the Foundation, then place your name in the
- copyright notice in place of the Foundation's name.
+ DOC-STRING is a string describing the coding system.
+
+ PROPS is a property list, describing the specific nature of the
+ character set. Recognized properties are as in *Note Coding
+ System Properties::.
+
+ - Function: copy-coding-system old-coding-system new-name
+ This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME
+ does not name an existing coding system, a new one will be created.
+
+ - Function: subsidiary-coding-system coding-system eol-type
+ This function returns the subsidiary coding system of
+ CODING-SYSTEM with eol type EOL-TYPE.
\1f
-File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips
-
-Tips for Making Compiled Code Fast
-==================================
-
- Here are ways of improving the execution speed of byte-compiled Lisp
-programs.
-
- * Use the `profile' library to profile your program. See the file
- `profile.el' for instructions.
-
- * Use iteration rather than recursion whenever possible. Function
- calls are slow in XEmacs Lisp even when a compiled function is
- calling another compiled function.
-
- * Using the primitive list-searching functions `memq', `member',
- `assq', or `assoc' is even faster than explicit iteration. It may
- be worth rearranging a data structure so that one of these
- primitive search functions can be used.
-
- * Certain built-in functions are handled specially in byte-compiled
- code, avoiding the need for an ordinary function call. It is a
- good idea to use these functions rather than alternatives. To see
- whether a function is handled specially by the compiler, examine
- its `byte-compile' property. If the property is non-`nil', then
- the function is handled specially.
-
- For example, the following input will show you that `aref' is
- compiled specially (*note Array Functions::) while `elt' is not
- (*note Sequence Functions::):
-
- (get 'aref 'byte-compile)
- => byte-compile-two-args
-
- (get 'elt 'byte-compile)
- => nil
-
- * If calling a small function accounts for a substantial part of
- your program's running time, make the function inline. This
- eliminates the function call overhead. Since making a function
- inline reduces the flexibility of changing the program, don't do
- it unless it gives a noticeable speedup in something slow enough
- that users care about the speed. *Note Inline Functions::.
+File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems
+
+Coding System Property Functions
+--------------------------------
+
+ - Function: coding-system-doc-string coding-system
+ This function returns the doc string for CODING-SYSTEM.
+
+ - Function: coding-system-type coding-system
+ This function returns the type of CODING-SYSTEM.
+
+ - Function: coding-system-property coding-system prop
+ This function returns the PROP property of CODING-SYSTEM.
\1f
-File: lispref.info, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips
-
-Tips for Documentation Strings
-==============================
-
- Here are some tips for the writing of documentation strings.
-
- * Every command, function, or variable intended for users to know
- about should have a documentation string.
-
- * An internal variable or subroutine of a Lisp program might as well
- have a documentation string. In earlier Emacs versions, you could
- save space by using a comment instead of a documentation string,
- but that is no longer the case.
-
- * The first line of the documentation string should consist of one
- or two complete sentences that stand on their own as a summary.
- `M-x apropos' displays just the first line, and if it doesn't
- stand on its own, the result looks bad. In particular, start the
- first line with a capital letter and end with a period.
-
- The documentation string can have additional lines that expand on
- the details of how to use the function or variable. The
- additional lines should be made up of complete sentences also, but
- they may be filled if that looks good.
-
- * For consistency, phrase the verb in the first sentence of a
- documentation string as an infinitive with "to" omitted. For
- instance, use "Return the cons of A and B." in preference to
- "Returns the cons of A and B." Usually it looks good to do
- likewise for the rest of the first paragraph. Subsequent
- paragraphs usually look better if they have proper subjects.
-
- * Write documentation strings in the active voice, not the passive,
- and in the present tense, not the future. For instance, use
- "Return a list containing A and B." instead of "A list containing
- A and B will be returned."
-
- * Avoid using the word "cause" (or its equivalents) unnecessarily.
- Instead of, "Cause Emacs to display text in boldface," write just
- "Display text in boldface."
-
- * Do not start or end a documentation string with whitespace.
-
- * Format the documentation string so that it fits in an Emacs window
- on an 80-column screen. It is a good idea for most lines to be no
- wider than 60 characters. The first line can be wider if
- necessary to fit the information that ought to be there.
-
- However, rather than simply filling the entire documentation
- string, you can make it much more readable by choosing line breaks
- with care. Use blank lines between topics if the documentation
- string is long.
-
- * *Do not* indent subsequent lines of a documentation string so that
- the text is lined up in the source code with the text of the first
- line. This looks nice in the source code, but looks bizarre when
- users view the documentation. Remember that the indentation
- before the starting double-quote is not part of the string!
-
- * A variable's documentation string should start with `*' if the
- variable is one that users would often want to set interactively.
- If the value is a long list, or a function, or if the variable
- would be set only in init files, then don't start the
- documentation string with `*'. *Note Defining Variables::.
-
- * The documentation string for a variable that is a yes-or-no flag
- should start with words such as "Non-nil means...", to make it
- clear that all non-`nil' values are equivalent and indicate
- explicitly what `nil' and non-`nil' mean.
-
- * When a function's documentation string mentions the value of an
- argument of the function, use the argument name in capital letters
- as if it were a name for that value. Thus, the documentation
- string of the function `/' refers to its second argument as
- `DIVISOR', because the actual argument name is `divisor'.
-
- Also use all caps for meta-syntactic variables, such as when you
- show the decomposition of a list or vector into subunits, some of
- which may vary.
-
- * When a documentation string refers to a Lisp symbol, write it as it
- would be printed (which usually means in lower case), with
- single-quotes around it. For example: `lambda'. There are two
- exceptions: write t and nil without single-quotes. (In this
- manual, we normally do use single-quotes for those symbols.)
-
- * Don't write key sequences directly in documentation strings.
- Instead, use the `\\[...]' construct to stand for them. For
- example, instead of writing `C-f', write `\\[forward-char]'. When
- Emacs displays the documentation string, it substitutes whatever
- key is currently bound to `forward-char'. (This is normally `C-f',
- but it may be some other character if the user has moved key
- bindings.) *Note Keys in Documentation::.
-
- * In documentation strings for a major mode, you will want to refer
- to the key bindings of that mode's local map, rather than global
- ones. Therefore, use the construct `\\<...>' once in the
- documentation string to specify which key map to use. Do this
- before the first use of `\\[...]'. The text inside the `\\<...>'
- should be the name of the variable containing the local keymap for
- the major mode.
-
- It is not practical to use `\\[...]' very many times, because
- display of the documentation string will become slow. So use this
- to describe the most important commands in your major mode, and
- then use `\\{...}' to display the rest of the mode's keymap.
+File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems
+
+Encoding and Decoding Text
+--------------------------
+
+ - Function: decode-coding-region start end coding-system &optional
+ buffer
+ This function decodes the text between START and END which is
+ encoded in CODING-SYSTEM. This is useful if you've read in
+ encoded text from a file without decoding it (e.g. you read in a
+ JIS-formatted file but used the `binary' or `no-conversion' coding
+ system, so that it shows up as `^[$B!<!+^[(B'). The length of the
+ encoded text is returned. BUFFER defaults to the current buffer
+ if unspecified.
+
+ - Function: encode-coding-region start end coding-system &optional
+ buffer
+ This function encodes the text between START and END using
+ CODING-SYSTEM. This will, for example, convert Japanese
+ characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
+ encoding. The length of the encoded text is returned. BUFFER
+ defaults to the current buffer if unspecified.
\1f
-File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips
+File: lispref.info, Node: Detection of Textual Encoding, Next: Big5 and Shift-JIS Functions, Prev: Encoding and Decoding Text, Up: Coding Systems
-Tips on Writing Comments
-========================
+Detection of Textual Encoding
+-----------------------------
- We recommend these conventions for where to put comments and how to
-indent them:
-
-`;'
- Comments that start with a single semicolon, `;', should all be
- aligned to the same column on the right of the source code. Such
- comments usually explain how the code on the same line does its
- job. In Lisp mode and related modes, the `M-;'
- (`indent-for-comment') command automatically inserts such a `;' in
- the right place, or aligns such a comment if it is already present.
-
- This and following examples are taken from the Emacs sources.
-
- (setq base-version-list ; there was a base
- (assoc (substring fn 0 start-vn) ; version to which
- file-version-assoc-list)) ; this looks like
- ; a subversion
-
-`;;'
- Comments that start with two semicolons, `;;', should be aligned to
- the same level of indentation as the code. Such comments usually
- describe the purpose of the following lines or the state of the
- program at that point. For example:
-
- (prog1 (setq auto-fill-function
- ...
- ...
- ;; update modeline
- (redraw-modeline)))
-
- Every function that has no documentation string (because it is use
- only internally within the package it belongs to), should have
- instead a two-semicolon comment right before the function,
- explaining what the function does and how to call it properly.
- Explain precisely what each argument means and how the function
- interprets its possible values.
-
-`;;;'
- Comments that start with three semicolons, `;;;', should start at
- the left margin. Such comments are used outside function
- definitions to make general statements explaining the design
- principles of the program. For example:
-
- ;;; This Lisp code is run in XEmacs
- ;;; when it is to operate as a server
- ;;; for other processes.
-
- Another use for triple-semicolon comments is for commenting out
- lines within a function. We use triple-semicolons for this
- precisely so that they remain at the left margin.
-
- (defun foo (a)
- ;;; This is no longer necessary.
- ;;; (force-mode-line-update)
- (message "Finished with %s" a))
-
-`;;;;'
- Comments that start with four semicolons, `;;;;', should be aligned
- to the left margin and are used for headings of major sections of a
- program. For example:
-
- ;;;; The kill ring
-
-The indentation commands of the Lisp modes in XEmacs, such as `M-;'
-(`indent-for-comment') and <TAB> (`lisp-indent-line') automatically
-indent comments according to these conventions, depending on the number
-of semicolons. *Note Manipulating Comments: (emacs)Comments.
+ - Function: coding-category-list
+ This function returns a list of all recognized coding categories.
-\1f
-File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips
-
-Conventional Headers for XEmacs Libraries
-=========================================
-
- XEmacs has conventions for using special comments in Lisp libraries
-to divide them into sections and give information such as who wrote
-them. This section explains these conventions. First, an example:
-
- ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
-
- ;; Copyright (C) 1992 Free Software Foundation, Inc.
-
- ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
- ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
- ;; Created: 14 Jul 1992
- ;; Version: 1.2
- ;; Keywords: docs
-
- ;; This file is part of XEmacs.
- COPYING PERMISSIONS...
-
- The very first line should have this format:
-
- ;;; FILENAME --- DESCRIPTION
-
-The description should be complete in one line.
-
- After the copyright notice come several "header comment" lines, each
-beginning with `;; HEADER-NAME:'. Here is a table of the conventional
-possibilities for HEADER-NAME:
-
-`Author'
- This line states the name and net address of at least the principal
- author of the library.
-
- If there are multiple authors, you can list them on continuation
- lines led by `;;' and a tab character, like this:
-
- ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
- ;; Dave Sill <de5@ornl.gov>
- ;; Dave Brennan <brennan@hal.com>
- ;; Eric Raymond <esr@snark.thyrsus.com>
-
-`Maintainer'
- This line should contain a single name/address as in the Author
- line, or an address only, or the string `FSF'. If there is no
- maintainer line, the person(s) in the Author field are presumed to
- be the maintainers. The example above is mildly bogus because the
- maintainer line is redundant.
-
- The idea behind the `Author' and `Maintainer' lines is to make
- possible a Lisp function to "send mail to the maintainer" without
- having to mine the name out by hand.
-
- Be sure to surround the network address with `<...>' if you
- include the person's full name as well as the network address.
-
-`Created'
- This optional line gives the original creation date of the file.
- For historical interest only.
-
-`Version'
- If you wish to record version numbers for the individual Lisp
- program, put them in this line.
-
-`Adapted-By'
- In this header line, place the name of the person who adapted the
- library for installation (to make it fit the style conventions, for
- example).
-
-`Keywords'
- This line lists keywords for the `finder-by-keyword' help command.
- This field is important; it's how people will find your package
- when they're looking for things by topic area. To separate the
- keywords, you can use spaces, commas, or both.
-
- Just about every Lisp library ought to have the `Author' and
-`Keywords' header comment lines. Use the others if they are
-appropriate. You can also put in header lines with other header
-names--they have no standard meanings, so they can't do any harm.
-
- We use additional stylized comments to subdivide the contents of the
-library file. Here is a table of them:
-
-`;;; Commentary:'
- This begins introductory comments that explain how the library
- works. It should come right after the copying permissions.
-
-`;;; Change log:'
- This begins change log information stored in the library file (if
- you store the change history there). For most of the Lisp files
- distributed with XEmacs, the change history is kept in the file
- `ChangeLog' and not in the source file at all; these files do not
- have a `;;; Change log:' line.
-
-`;;; Code:'
- This begins the actual code of the program.
-
-`;;; FILENAME ends here'
- This is the "footer line"; it appears at the very end of the file.
- Its purpose is to enable people to detect truncated versions of
- the file from the lack of a footer line.
+ - Function: set-coding-priority-list list
+ This function changes the priority order of the coding categories.
+ LIST should be a list of coding categories, in descending order of
+ priority. Unspecified coding categories will be lower in priority
+ than all specified ones, in the same relative order they were in
+ previously.
+
+ - Function: coding-priority-list
+ This function returns a list of coding categories in descending
+ order of priority.
+
+ - Function: set-coding-category-system coding-category coding-system
+ This function changes the coding system associated with a coding
+ category.
+
+ - Function: coding-category-system coding-category
+ This function returns the coding system associated with a coding
+ category.
+
+ - Function: detect-coding-region start end &optional buffer
+ This function detects coding system of the text in the region
+ between START and END. Returned value is a list of possible coding
+ systems ordered by priority. If only ASCII characters are found,
+ it returns `autodetect' or one of its subsidiary coding systems
+ according to a detected end-of-line type. Optional arg BUFFER
+ defaults to the current buffer.
\1f
-File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top
+File: lispref.info, Node: Big5 and Shift-JIS Functions, Next: Predefined Coding Systems, Prev: Detection of Textual Encoding, Up: Coding Systems
+
+Big5 and Shift-JIS Functions
+----------------------------
+
+ These are special functions for working with the non-standard
+Shift-JIS and Big5 encodings.
-Building XEmacs; Allocation of Objects
-**************************************
+ - Function: decode-shift-jis-char code
+ This function decodes a JIS X 0208 character of Shift-JIS
+ coding-system. CODE is the character code in Shift-JIS as a cons
+ of type bytes. The corresponding character is returned.
- This chapter describes how the runnable XEmacs executable is dumped
-with the preloaded Lisp libraries in it and how storage is allocated.
+ - Function: encode-shift-jis-char character
+ This function encodes a JIS X 0208 character CHARACTER to
+ SHIFT-JIS coding-system. The corresponding character code in
+ SHIFT-JIS is returned as a cons of two bytes.
- There is an entire separate document, the `XEmacs Internals Manual',
-devoted to the internals of XEmacs from the perspective of the C
-programmer. It contains much more detailed information about the build
-process, the allocation and garbage-collection process, and other
-aspects related to the internals of XEmacs.
+ - Function: decode-big5-char code
+ This function decodes a Big5 character CODE of BIG5 coding-system.
+ CODE is the character code in BIG5. The corresponding character
+ is returned.
+
+ - Function: encode-big5-char character
+ This function encodes the Big5 character CHARACTER to BIG5
+ coding-system. The corresponding character code in Big5 is
+ returned.
+
+\1f
+File: lispref.info, Node: Predefined Coding Systems, Prev: Big5 and Shift-JIS Functions, Up: Coding Systems
+
+Coding Systems Implemented
+--------------------------
+
+ MULE initializes most of the commonly used coding systems at XEmacs's
+startup. A few others are initialized only when the relevant language
+environment is selected and support libraries are loaded. (NB: The
+following list is based on XEmacs 21.2.19, the development branch at the
+time of writing. The list may be somewhat different for other
+versions. Recent versions of GNU Emacs 20 implement a few more rare
+coding systems; work is being done to port these to XEmacs.)
+
+ Unfortunately, there is not a consistent naming convention for
+character sets, and for practical purposes coding systems often take
+their name from their principal character sets (ASCII, KOI8-R, Shift
+JIS). Others take their names from the coding system (ISO-2022-JP,
+EUC-KR), and a few from their non-text usages (internal, binary). To
+provide for this, and for the fact that many coding systems have
+several common names, an aliasing system is provided. Finally, some
+effort has been made to use names that are registered as MIME charsets
+(this is why the name 'shift_jis contains that un-Lisp-y underscore).
+
+ There is a systematic naming convention regarding end-of-line (EOL)
+conventions for different systems. A coding system whose name ends in
+"-unix" forces the assumptions that lines are broken by newlines (0x0A).
+A coding system whose name ends in "-mac" forces the assumptions that
+lines are broken by ASCII CRs (0x0D). A coding system whose name ends
+in "-dos" forces the assumptions that lines are broken by CRLF sequences
+(0x0D 0x0A). These subsidiary coding systems are automatically derived
+from a base coding system. Use of the base coding system implies
+autodetection of the text file convention. (The fact that the -unix,
+-mac, and -dos are derived from a base system results in them showing up
+as "aliases" in `list-coding-systems'.) These subsidiaries have a
+consistent modeline indicator as well. "-dos" coding systems have ":T"
+appended to their modeline indicator, while "-mac" coding systems have
+":t" appended (eg, "ISO8:t" for iso-2022-8-mac).
+
+ In the following table, each coding system is given with its mode
+line indicator in parentheses. Non-textual coding systems are listed
+first, followed by textual coding systems and their aliases. (The
+coding system subsidiary modeline indicators ":T" and ":t" will be
+omitted from the table of coding systems.)
+
+ ### SJT 1999-08-23 Maybe should order these by language? Definitely
+need language usage for the ISO-8859 family.
+
+ Note that although true coding system aliases have been implemented
+for XEmacs 21.2, the coding system initialization has not yet been
+converted as of 21.2.19. So coding systems described as aliases have
+the same properties as the aliased coding system, but will not be equal
+as Lisp objects.
+
+`automatic-conversion'
+`undecided'
+`undecided-dos'
+`undecided-mac'
+`undecided-unix'
+ Modeline indicator: `Auto'. A type `undecided' coding system.
+ Attempts to determine an appropriate coding system from file
+ contents or the environment.
+
+`raw-text'
+`no-conversion'
+`raw-text-dos'
+`raw-text-mac'
+`raw-text-unix'
+`no-conversion-dos'
+`no-conversion-mac'
+`no-conversion-unix'
+ Modeline indicator: `Raw'. A type `no-conversion' coding system,
+ which converts only line-break-codes. An implementation quirk
+ means that this coding system is also used for ISO8859-1.
+
+`binary'
+ Modeline indicator: `Binary'. A type `no-conversion' coding
+ system which does no character coding or EOL conversions. An
+ alias for `raw-text-unix'.
+
+`alternativnyj'
+`alternativnyj-dos'
+`alternativnyj-mac'
+`alternativnyj-unix'
+ Modeline indicator: `Cy.Alt'. A type `ccl' coding system used for
+ Alternativnyj, an encoding of the Cyrillic alphabet.
+
+`big5'
+`big5-dos'
+`big5-mac'
+`big5-unix'
+ Modeline indicator: `Zh/Big5'. A type `big5' coding system used
+ for BIG5, the most common encoding of traditional Chinese as used
+ in Taiwan.
+
+`cn-gb-2312'
+`cn-gb-2312-dos'
+`cn-gb-2312-mac'
+`cn-gb-2312-unix'
+ Modeline indicator: `Zh-GB/EUC'. A type `iso2022' coding system
+ used for simplified Chinese (as used in the People's Republic of
+ China), with the `ascii' (G0), `chinese-gb2312' (G1), and `sisheng'
+ (G2) character sets initially designated. Chinese EUC (Extended
+ Unix Code).
+
+`ctext-hebrew'
+`ctext-hebrew-dos'
+`ctext-hebrew-mac'
+`ctext-hebrew-unix'
+ Modeline indicator: `CText/Hbrw'. A type `iso2022' coding system
+ with the `ascii' (G0) and `hebrew-iso8859-8' (G1) character sets
+ initially designated for Hebrew.
+
+`ctext'
+`ctext-dos'
+`ctext-mac'
+`ctext-unix'
+ Modeline indicator: `CText'. A type `iso2022' 8-bit coding system
+ with the `ascii' (G0) and `latin-iso8859-1' (G1) character sets
+ initially designated. X11 Compound Text Encoding. Often
+ mistakenly recognized instead of EUC encodings; usual cause is
+ inappropriate setting of `coding-priority-list'.
+
+`escape-quoted'
+ Modeline indicator: `ESC/Quot'. A type `iso2022' 8-bit coding
+ system with the `ascii' (G0) and `latin-iso8859-1' (G1) character
+ sets initially designated and escape quoting. Unix EOL conversion
+ (ie, no conversion). It is used for .ELC files.
+
+`euc-jp'
+`euc-jp-dos'
+`euc-jp-mac'
+`euc-jp-unix'
+ Modeline indicator: `Ja/EUC'. A type `iso2022' 8-bit coding system
+ with `ascii' (G0), `japanese-jisx0208' (G1), `katakana-jisx0201'
+ (G2), and `japanese-jisx0212' (G3) initially designated. Japanese
+ EUC (Extended Unix Code).
+
+`euc-kr'
+`euc-kr-dos'
+`euc-kr-mac'
+`euc-kr-unix'
+ Modeline indicator: `ko/EUC'. A type `iso2022' 8-bit coding system
+ with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
+ Korean EUC (Extended Unix Code).
+
+`hz-gb-2312'
+ Modeline indicator: `Zh-GB/Hz'. A type `no-conversion' coding
+ system with Unix EOL convention (ie, no conversion) using
+ post-read-decode and pre-write-encode functions to translate the
+ Hz/ZW coding system used for Chinese.
+
+`iso-2022-7bit'
+`iso-2022-7bit-unix'
+`iso-2022-7bit-dos'
+`iso-2022-7bit-mac'
+`iso-2022-7'
+ Modeline indicator: `ISO7'. A type `iso2022' 7-bit coding system
+ with `ascii' (G0) initially designated. Other character sets must
+ be explicitly designated to be used.
+
+`iso-2022-7bit-ss2'
+`iso-2022-7bit-ss2-dos'
+`iso-2022-7bit-ss2-mac'
+`iso-2022-7bit-ss2-unix'
+ Modeline indicator: `ISO7/SS'. A type `iso2022' 7-bit coding
+ system with `ascii' (G0) initially designated. Other character
+ sets must be explicitly designated to be used. SS2 is used to
+ invoke a 96-charset, one character at a time.
+
+`iso-2022-8'
+`iso-2022-8-dos'
+`iso-2022-8-mac'
+`iso-2022-8-unix'
+ Modeline indicator: `ISO8'. A type `iso2022' 8-bit coding system
+ with `ascii' (G0) and `latin-iso8859-1' (G1) initially designated.
+ Other character sets must be explicitly designated to be used.
+ No single-shift or locking-shift.
+
+`iso-2022-8bit-ss2'
+`iso-2022-8bit-ss2-dos'
+`iso-2022-8bit-ss2-mac'
+`iso-2022-8bit-ss2-unix'
+ Modeline indicator: `ISO8/SS'. A type `iso2022' 8-bit coding
+ system with `ascii' (G0) and `latin-iso8859-1' (G1) initially
+ designated. Other character sets must be explicitly designated to
+ be used. SS2 is used to invoke a 96-charset, one character at a
+ time.
+
+`iso-2022-int-1'
+`iso-2022-int-1-dos'
+`iso-2022-int-1-mac'
+`iso-2022-int-1-unix'
+ Modeline indicator: `INT-1'. A type `iso2022' 7-bit coding system
+ with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
+ ISO-2022-INT-1.
+
+`iso-2022-jp-1978-irv'
+`iso-2022-jp-1978-irv-dos'
+`iso-2022-jp-1978-irv-mac'
+`iso-2022-jp-1978-irv-unix'
+ Modeline indicator: `Ja-78/7bit'. A type `iso2022' 7-bit coding
+ system. For compatibility with old Japanese terminals; if you
+ need to know, look at the source.
+
+`iso-2022-jp'
+`iso-2022-jp-2 (ISO7/SS)'
+`iso-2022-jp-dos'
+`iso-2022-jp-mac'
+`iso-2022-jp-unix'
+`iso-2022-jp-2-dos'
+`iso-2022-jp-2-mac'
+`iso-2022-jp-2-unix'
+ Modeline indicator: `MULE/7bit'. A type `iso2022' 7-bit coding
+ system with `ascii' (G0) initially designated, and complex
+ specifications to insure backward compatibility with old Japanese
+ systems. Used for communication with mail and news in Japan. The
+ "-2" versions also use SS2 to invoke a 96-charset one character at
+ a time.
+
+`iso-2022-kr'
+ Modeline indicator: `Ko/7bit' A type `iso2022' 7-bit coding
+ system with `ascii' (G0) and `korean-ksc5601' (G1) initially
+ designated. Used for e-mail in Korea.
+
+`iso-2022-lock'
+`iso-2022-lock-dos'
+`iso-2022-lock-mac'
+`iso-2022-lock-unix'
+ Modeline indicator: `ISO7/Lock'. A type `iso2022' 7-bit coding
+ system with `ascii' (G0) initially designated, using Locking-Shift
+ to invoke a 96-charset.
+
+`iso-8859-1'
+`iso-8859-1-dos'
+`iso-8859-1-mac'
+`iso-8859-1-unix'
+ Due to implementation, this is not a type `iso2022' coding system,
+ but rather an alias for the `raw-text' coding system.
+
+`iso-8859-2'
+`iso-8859-2-dos'
+`iso-8859-2-mac'
+`iso-8859-2-unix'
+ Modeline indicator: `MIME/Ltn-2'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-2' (G1) initially invoked.
+
+`iso-8859-3'
+`iso-8859-3-dos'
+`iso-8859-3-mac'
+`iso-8859-3-unix'
+ Modeline indicator: `MIME/Ltn-3'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-3' (G1) initially invoked.
+
+`iso-8859-4'
+`iso-8859-4-dos'
+`iso-8859-4-mac'
+`iso-8859-4-unix'
+ Modeline indicator: `MIME/Ltn-4'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-4' (G1) initially invoked.
+
+`iso-8859-5'
+`iso-8859-5-dos'
+`iso-8859-5-mac'
+`iso-8859-5-unix'
+ Modeline indicator: `ISO8/Cyr'. A type `iso2022' coding system
+ with `ascii' (G0) and `cyrillic-iso8859-5' (G1) initially invoked.
+
+`iso-8859-7'
+`iso-8859-7-dos'
+`iso-8859-7-mac'
+`iso-8859-7-unix'
+ Modeline indicator: `Grk'. A type `iso2022' coding system with
+ `ascii' (G0) and `greek-iso8859-7' (G1) initially invoked.
+
+`iso-8859-8'
+`iso-8859-8-dos'
+`iso-8859-8-mac'
+`iso-8859-8-unix'
+ Modeline indicator: `MIME/Hbrw'. A type `iso2022' coding system
+ with `ascii' (G0) and `hebrew-iso8859-8' (G1) initially invoked.
+
+`iso-8859-9'
+`iso-8859-9-dos'
+`iso-8859-9-mac'
+`iso-8859-9-unix'
+ Modeline indicator: `MIME/Ltn-5'. A type `iso2022' coding system
+ with `ascii' (G0) and `latin-iso8859-9' (G1) initially invoked.
+
+`koi8-r'
+`koi8-r-dos'
+`koi8-r-mac'
+`koi8-r-unix'
+ Modeline indicator: `KOI8'. A type `ccl' coding-system used for
+ KOI8-R, an encoding of the Cyrillic alphabet.
+
+`shift_jis'
+`shift_jis-dos'
+`shift_jis-mac'
+`shift_jis-unix'
+ Modeline indicator: `Ja/SJIS'. A type `shift-jis' coding-system
+ implementing the Shift-JIS encoding for Japanese. The underscore
+ is to conform to the MIME charset implementing this encoding.
+
+`tis-620'
+`tis-620-dos'
+`tis-620-mac'
+`tis-620-unix'
+ Modeline indicator: `TIS620'. A type `ccl' encoding for Thai. The
+ external encoding is defined by TIS620, the internal encoding is
+ peculiar to MULE, and called `thai-xtis'.
+
+`viqr'
+ Modeline indicator: `VIQR'. A type `no-conversion' coding system
+ with Unix EOL convention (ie, no conversion) using
+ post-read-decode and pre-write-encode functions to translate the
+ VIQR coding system for Vietnamese.
+
+`viscii'
+`viscii-dos'
+`viscii-mac'
+`viscii-unix'
+ Modeline indicator: `VISCII'. A type `ccl' coding-system used for
+ VISCII 1.1 for Vietnamese. Differs slightly from VSCII; VISCII is
+ given priority by XEmacs.
+
+`vscii'
+`vscii-dos'
+`vscii-mac'
+`vscii-unix'
+ Modeline indicator: `VSCII'. A type `ccl' coding-system used for
+ VSCII 1.1 for Vietnamese. Differs slightly from VISCII, which is
+ given priority by XEmacs. Use `(prefer-coding-system
+ 'vietnamese-vscii)' to give priority to VSCII.
+
+\1f
+File: lispref.info, Node: CCL, Next: Category Tables, Prev: Coding Systems, Up: MULE
+
+CCL
+===
+
+ CCL (Code Conversion Language) is a simple structured programming
+language designed for character coding conversions. A CCL program is
+compiled to CCL code (represented by a vector of integers) and executed
+by the CCL interpreter embedded in Emacs. The CCL interpreter
+implements a virtual machine with 8 registers called `r0', ..., `r7', a
+number of control structures, and some I/O operators. Take care when
+using registers `r0' (used in implicit "set" statements) and especially
+`r7' (used internally by several statements and operations, especially
+for multiple return values and I/O operations).
+
+ CCL is used for code conversion during process I/O and file I/O for
+non-ISO2022 coding systems. (It is the only way for a user to specify a
+code conversion function.) It is also used for calculating the code
+point of an X11 font from a character code. However, since CCL is
+designed as a powerful programming language, it can be used for more
+generic calculation where efficiency is demanded. A combination of
+three or more arithmetic operations can be calculated faster by CCL than
+by Emacs Lisp.
+
+ *Warning:* The code in `src/mule-ccl.c' and
+`$packages/lisp/mule-base/mule-ccl.el' is the definitive description of
+CCL's semantics. The previous version of this section contained
+several typos and obsolete names left from earlier versions of MULE,
+and many may remain. (I am not an experienced CCL programmer; the few
+who know CCL well find writing English painful.)
+
+ A CCL program transforms an input data stream into an output data
+stream. The input stream, held in a buffer of constant bytes, is left
+unchanged. The buffer may be filled by an external input operation,
+taken from an Emacs buffer, or taken from a Lisp string. The output
+buffer is a dynamic array of bytes, which can be written by an external
+output operation, inserted into an Emacs buffer, or returned as a Lisp
+string.
+
+ A CCL program is a (Lisp) list containing two or three members. The
+first member is the "buffer magnification", which indicates the
+required minimum size of the output buffer as a multiple of the input
+buffer. It is followed by the "main block" which executes while there
+is input remaining, and an optional "EOF block" which is executed when
+the input is exhausted. Both the main block and the EOF block are CCL
+blocks.
+
+ A "CCL block" is either a CCL statement or list of CCL statements.
+A "CCL statement" is either a "set statement" (either an integer or an
+"assignment", which is a list of a register to receive the assignment,
+an assignment operator, and an expression) or a "control statement" (a
+list starting with a keyword, whose allowable syntax depends on the
+keyword).
* Menu:
-* Building XEmacs:: How to preload Lisp libraries into XEmacs.
-* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
-* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
+* CCL Syntax:: CCL program syntax in BNF notation.
+* CCL Statements:: Semantics of CCL statements.
+* CCL Expressions:: Operators and expressions in CCL.
+* Calling CCL:: Running CCL programs.
+* CCL Examples:: The encoding functions for Big5 and KOI-8.
+
+\1f
+File: lispref.info, Node: CCL Syntax, Next: CCL Statements, Up: CCL
+
+CCL Syntax
+----------
+
+ The full syntax of a CCL program in BNF notation:
+
+CCL_PROGRAM :=
+ (BUFFER_MAGNIFICATION
+ CCL_MAIN_BLOCK
+ [ CCL_EOF_BLOCK ])
+
+BUFFER_MAGNIFICATION := integer
+CCL_MAIN_BLOCK := CCL_BLOCK
+CCL_EOF_BLOCK := CCL_BLOCK
+
+CCL_BLOCK :=
+ STATEMENT | (STATEMENT [STATEMENT ...])
+STATEMENT :=
+ SET | IF | BRANCH | LOOP | REPEAT | BREAK | READ | WRITE
+ | CALL | END
+
+SET :=
+ (REG = EXPRESSION)
+ | (REG ASSIGNMENT_OPERATOR EXPRESSION)
+ | integer
+
+EXPRESSION := ARG | (EXPRESSION OPERATOR ARG)
+
+IF := (if EXPRESSION CCL_BLOCK [CCL_BLOCK])
+BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
+LOOP := (loop STATEMENT [STATEMENT ...])
+BREAK := (break)
+REPEAT :=
+ (repeat)
+ | (write-repeat [REG | integer | string])
+ | (write-read-repeat REG [integer | ARRAY])
+READ :=
+ (read REG ...)
+ | (read-if (REG OPERATOR ARG) CCL_BLOCK CCL_BLOCK)
+ | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
+WRITE :=
+ (write REG ...)
+ | (write EXPRESSION)
+ | (write integer) | (write string) | (write REG ARRAY)
+ | string
+CALL := (call ccl-program-name)
+END := (end)
+
+REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
+ARG := REG | integer
+OPERATOR :=
+ + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
+ | < | > | == | <= | >= | != | de-sjis | en-sjis
+ASSIGNMENT_OPERATOR :=
+ += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
+ARRAY := '[' integer ... ']'
\1f
-File: lispref.info, Node: Building XEmacs, Next: Pure Storage, Up: Building XEmacs and Object Allocation
+File: lispref.info, Node: CCL Statements, Next: CCL Expressions, Prev: CCL Syntax, Up: CCL
-Building XEmacs
+CCL Statements
+--------------
+
+ The Emacs Code Conversion Language provides the following statement
+types: "set", "if", "branch", "loop", "repeat", "break", "read",
+"write", "call", and "end".
+
+Set statement:
+==============
+
+ The "set" statement has three variants with the syntaxes `(REG =
+EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'.
+The assignment operator variation of the "set" statement works the same
+way as the corresponding C expression statement does. The assignment
+operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=',
+and `>>=', and they have the same meanings as in C. A "naked integer"
+INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'.
+
+I/O statements:
===============
- This section explains the steps involved in building the XEmacs
-executable. You don't have to know this material to build and install
-XEmacs, since the makefiles do all these things automatically. This
-information is pertinent to XEmacs maintenance.
-
- The `XEmacs Internals Manual' contains more information about this.
-
- Compilation of the C source files in the `src' directory produces an
-executable file called `temacs', also called a "bare impure XEmacs".
-It contains the XEmacs Lisp interpreter and I/O routines, but not the
-editing commands.
-
- Before XEmacs is actually usable, a number of Lisp files need to be
-loaded. These define all the editing commands, plus most of the startup
-code and many very basic Lisp primitives. This is accomplished by
-loading the file `loadup.el', which in turn loads all of the other
-standardly-loaded Lisp files.
-
- It takes a substantial time to load the standard Lisp files.
-Luckily, you don't have to do this each time you run XEmacs; `temacs'
-can dump out an executable program called `xemacs' that has these files
-preloaded. `xemacs' starts more quickly because it does not need to
-load the files. This is the XEmacs executable that is normally
-installed.
-
- To create `xemacs', use the command `temacs -batch -l loadup dump'.
-The purpose of `-batch' here is to tell `temacs' to run in
-non-interactive, command-line mode. (`temacs' can _only_ run in this
-fashion. Part of the code required to initialize frames and faces is
-in Lisp, and must be loaded before XEmacs is able to create any frames.)
-The argument `dump' tells `loadup.el' to dump a new executable named
-`xemacs'.
-
- The dumping process is highly system-specific, and some operating
-systems don't support dumping. On those systems, you must start XEmacs
-with the `temacs -batch -l loadup run-temacs' command each time you use
-it. This takes a substantial time, but since you need to start Emacs
-once a day at most--or once a week if you never log out--the extra time
-is not too severe a problem. (In older versions of Emacs, you started
-Emacs from `temacs' using `temacs -l loadup'.)
-
- You are free to start XEmacs directly from `temacs' if you want,
-even if there is already a dumped `xemacs'. Normally you wouldn't want
-to do that; but the Makefiles do this when you rebuild XEmacs using
-`make all-elc', which builds XEmacs and simultaneously compiles any
-out-of-date Lisp files. (You need `xemacs' in order to compile Lisp
-files. However, you also need the compiled Lisp files in order to dump
-out `xemacs'. If both of these are missing or corrupted, you are out
-of luck unless you're able to bootstrap `xemacs' from `temacs'. Note
-that `make all-elc' actually loads the alternative loadup file
-`loadup-el.el', which works like `loadup.el' but disables the
-pure-copying process and forces XEmacs to ignore any compiled Lisp
-files even if they exist.)
-
- You can specify additional files to preload by writing a library
-named `site-load.el' that loads them. You may need to increase the
-value of `PURESIZE', in `src/puresize.h', to make room for the
-additional files. You should _not_ modify this file directly, however;
-instead, use the `--puresize' configuration option. (If you run out of
-pure space while dumping `xemacs', you will be told how much pure space
-you actually will need.) However, the advantage of preloading
-additional files decreases as machines get faster. On modern machines,
-it is often not advisable, especially if the Lisp code is on a file
-system local to the machine running XEmacs.
-
- You can specify other Lisp expressions to execute just before dumping
-by putting them in a library named `site-init.el'. However, if they
-might alter the behavior that users expect from an ordinary unmodified
-XEmacs, it is better to put them in `default.el', so that users can
-override them if they wish. *Note Start-up Summary::.
-
- Before `loadup.el' dumps the new executable, it finds the
-documentation strings for primitive and preloaded functions (and
-variables) in the file where they are stored, by calling
-`Snarf-documentation' (*note Accessing Documentation::). These strings
-were moved out of the `xemacs' executable to make it smaller. *Note
-Documentation Basics::.
-
- - Function: dump-emacs to-file from-file
- This function dumps the current state of XEmacs into an executable
- file TO-FILE. It takes symbols from FROM-FILE (this is normally
- the executable file `temacs').
-
- If you use this function in an XEmacs that was already dumped, you
- must set `command-line-processed' to `nil' first for good results.
- *Note Command Line Arguments::.
-
- - Function: run-emacs-from-temacs &rest args
- This is the function that implements the `run-temacs' command-line
- argument. It is called from `loadup.el' as appropriate. You
- should most emphatically _not_ call this yourself; it will
- reinitialize your XEmacs process and you'll be sorry.
-
- - Command: emacs-version
- This function returns a string describing the version of XEmacs
- that is running. It is useful to include this string in bug
- reports.
-
- (emacs-version)
- => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29)
- of Mon Apr 7 1997 on altair.xemacs.org"
-
- Called interactively, the function prints the same information in
- the echo area.
-
- - Variable: emacs-build-time
- The value of this variable is the time at which XEmacs was built
- at the local site.
-
- emacs-build-time "Mon Apr 7 20:28:52 1997"
- =>
-
- - Variable: emacs-version
- The value of this variable is the version of Emacs being run. It
- is a string, e.g. `"20.1 XEmacs Lucid"'.
-
- The following two variables did not exist before FSF GNU Emacs
-version 19.23 and XEmacs version 19.10, which reduces their usefulness
-at present, but we hope they will be convenient in the future.
-
- - Variable: emacs-major-version
- The major version number of Emacs, as an integer. For XEmacs
- version 20.1, the value is 20.
-
- - Variable: emacs-minor-version
- The minor version number of Emacs, as an integer. For XEmacs
- version 20.1, the value is 1.
+ The "read" statement takes one or more registers as arguments. It
+reads one byte (a C char) from the input into each register in turn.
+
+ The "write" takes several forms. In the form `(write REG ...)' it
+takes one or more registers as arguments and writes each in turn to the
+output. The integer in a register (interpreted as an Emchar) is
+encoded to multibyte form (ie, Bufbytes) and written to the current
+output buffer. If it is less than 256, it is written as is. The forms
+`(write EXPRESSION)' and `(write INTEGER)' are treated analogously.
+The form `(write STRING)' writes the constant string to the output. A
+"naked string" `STRING' is equivalent to the statement `(write
+STRING)'. The form `(write REG ARRAY)' writes the REGth element of the
+ARRAY to the output.
+
+Conditional statements:
+=======================
+
+ The "if" statement takes an EXPRESSION, a CCL BLOCK, and an optional
+SECOND CCL BLOCK as arguments. If the EXPRESSION evaluates to
+non-zero, the first CCL BLOCK is executed. Otherwise, if there is a
+SECOND CCL BLOCK, it is executed.
+
+ The "read-if" variant of the "if" statement takes an EXPRESSION, a
+CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. The
+EXPRESSION must have the form `(REG OPERATOR OPERAND)' (where OPERAND is
+a register or an integer). The `read-if' statement first reads from
+the input into the first register operand in the EXPRESSION, then
+conditionally executes a CCL block just as the `if' statement does.
+
+ The "branch" statement takes an EXPRESSION and one or more CCL
+blocks as arguments. The CCL blocks are treated as a zero-indexed
+array, and the `branch' statement uses the EXPRESSION as the index of
+the CCL block to execute. Null CCL blocks may be used as no-ops,
+continuing execution with the statement following the `branch'
+statement in the containing CCL block. Out-of-range values for the
+EXPRESSION are also treated as no-ops.
+
+ The "read-branch" variant of the "branch" statement takes an
+REGISTER, a CCL BLOCK, and an optional SECOND CCL BLOCK as arguments.
+The `read-branch' statement first reads from the input into the
+REGISTER, then conditionally executes a CCL block just as the `branch'
+statement does.
+
+Loop control statements:
+========================
+
+ The "loop" statement creates a block with an implied jump from the
+end of the block back to its head. The loop is exited on a `break'
+statement, and continued without executing the tail by a `repeat'
+statement.
+
+ The "break" statement, written `(break)', terminates the current
+loop and continues with the next statement in the current block.
+
+ The "repeat" statement has three variants, `repeat', `write-repeat',
+and `write-read-repeat'. Each continues the current loop from its
+head, possibly after performing I/O. `repeat' takes no arguments and
+does no I/O before jumping. `write-repeat' takes a single argument (a
+register, an integer, or a string), writes it to the output, then jumps.
+`write-read-repeat' takes one or two arguments. The first must be a
+register. The second may be an integer or an array; if absent, it is
+implicitly set to the first (register) argument. `write-read-repeat'
+writes its second argument to the output, then reads from the input
+into the register, and finally jumps. See the `write' and `read'
+statements for the semantics of the I/O operations for each type of
+argument.
+
+Other control statements:
+=========================
+
+ The "call" statement, written `(call CCL-PROGRAM-NAME)', executes a
+CCL program as a subroutine. It does not return a value to the caller,
+but can modify the register status.
+
+ The "end" statement, written `(end)', terminates the CCL program
+successfully, and returns to caller (which may be a CCL program). It
+does not alter the status of the registers.
+
+\1f
+File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL
+
+CCL Expressions
+---------------
+
+ CCL, unlike Lisp, uses infix expressions. The simplest CCL
+expressions consist of a single OPERAND, either a register (one of `r0',
+..., `r0') or an integer. Complex expressions are lists of the form `(
+EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not
+expressions.
+
+ In the following table, X is the target resister for a "set". In
+subexpressions, this is implicitly `r7'. This means that `>8', `//',
+`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since
+they return parts of their values in `r7'. Y may be an expression,
+register, or integer, while Z must be a register or an integer.
+
+Name Operator Code C-like Description
+CCL_PLUS `+' 0x00 X = Y + Z
+CCL_MINUS `-' 0x01 X = Y - Z
+CCL_MUL `*' 0x02 X = Y * Z
+CCL_DIV `/' 0x03 X = Y / Z
+CCL_MOD `%' 0x04 X = Y % Z
+CCL_AND `&' 0x05 X = Y & Z
+CCL_OR `|' 0x06 X = Y | Z
+CCL_XOR `^' 0x07 X = Y ^ Z
+CCL_LSH `<<' 0x08 X = Y << Z
+CCL_RSH `>>' 0x09 X = Y >> Z
+CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z
+CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF
+CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z
+CCL_LS `<' 0x10 X = (X < Y)
+CCL_GT `>' 0x11 X = (X > Y)
+CCL_EQ `==' 0x12 X = (X == Y)
+CCL_LE `<=' 0x13 X = (X <= Y)
+CCL_GE `>=' 0x14 X = (X >= Y)
+CCL_NE `!=' 0x15 X = (X != Y)
+CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z))
+ r[7] = LOWER_BYTE (SJIS (Y, Z)
+CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z))
+ r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
+
+ The CCL operators are as in C, with the addition of CCL_LSH8,
+CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The
+CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes
+as the high and low bytes of a two-byte character code. (SJIS stands
+for Shift JIS, an encoding of Japanese characters used by Microsoft.
+CCL_ENCODE_SJIS is a complicated transformation of the Japanese
+standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.)
+It is somewhat odd to represent the SJIS operations in infix form.
\1f
-File: lispref.info, Node: Pure Storage, Next: Garbage Collection, Prev: Building XEmacs, Up: Building XEmacs and Object Allocation
-
-Pure Storage
-============
-
- XEmacs Lisp uses two kinds of storage for user-created Lisp objects:
-"normal storage" and "pure storage". Normal storage is where all the
-new data created during an XEmacs session is kept; see the following
-section for information on normal storage. Pure storage is used for
-certain data in the preloaded standard Lisp files--data that should
-never change during actual use of XEmacs.
-
- Pure storage is allocated only while `temacs' is loading the
-standard preloaded Lisp libraries. In the file `xemacs', it is marked
-as read-only (on operating systems that permit this), so that the
-memory space can be shared by all the XEmacs jobs running on the machine
-at once. Pure storage is not expandable; a fixed amount is allocated
-when XEmacs is compiled, and if that is not sufficient for the preloaded
-libraries, `temacs' aborts with an error message. If that happens, you
-must increase the compilation parameter `PURESIZE' using the
-`--puresize' option to `configure'. This normally won't happen unless
-you try to preload additional libraries or add features to the standard
-ones.
-
- - Function: purecopy object
- This function makes a copy of OBJECT in pure storage and returns
- it. It copies strings by simply making a new string with the same
- characters in pure storage. It recursively copies the contents of
- vectors and cons cells. It does not make copies of other objects
- such as symbols, but just returns them unchanged. It signals an
- error if asked to copy markers.
-
- This function is a no-op except while XEmacs is being built and
- dumped; it is usually called only in the file
- `xemacs/lisp/prim/loaddefs.el', but a few packages call it just in
- case you decide to preload them.
-
- - Variable: pure-bytes-used
- The value of this variable is the number of bytes of pure storage
- allocated so far. Typically, in a dumped XEmacs, this number is
- very close to the total amount of pure storage available--if it
- were not, we would preallocate less.
-
- - Variable: purify-flag
- This variable determines whether `defun' should make a copy of the
- function definition in pure storage. If it is non-`nil', then the
- function definition is copied into pure storage.
-
- This flag is `t' while loading all of the basic functions for
- building XEmacs initially (allowing those functions to be sharable
- and non-collectible). Dumping XEmacs as an executable always
- writes `nil' in this variable, regardless of the value it actually
- has before and after dumping.
-
- You should not change this flag in a running XEmacs.
+File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL
+
+Calling CCL
+-----------
+
+ CCL programs are called automatically during Emacs buffer I/O when
+the external representation has a coding system type of `shift-jis',
+`big5', or `ccl'. The program is specified by the coding system (*note
+Coding Systems::). You can also call CCL programs from other CCL
+programs, and from Lisp using these functions:
+
+ - Function: ccl-execute ccl-program status
+ Execute CCL-PROGRAM with registers initialized by STATUS.
+ CCL-PROGRAM is a vector of compiled CCL code created by
+ `ccl-compile'. It is an error for the program to try to execute a
+ CCL I/O command. STATUS must be a vector of nine values,
+ specifying the initial value for the R0, R1 .. R7 registers and
+ for the instruction counter IC. A `nil' value for a register
+ initializer causes the register to be set to 0. A `nil' value for
+ the IC initializer causes execution to start at the beginning of
+ the program. When the program is done, STATUS is modified (by
+ side-effect) to contain the ending values for the corresponding
+ registers and IC.
+
+ - Function: ccl-execute-on-string ccl-program status string &optional
+ continue
+ Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is
+ a vector of compiled CCL code created by `ccl-compile'. STATUS
+ must be a vector of nine values, specifying the initial value for
+ the R0, R1 .. R7 registers and for the instruction counter IC. A
+ `nil' value for a register initializer causes the register to be
+ set to 0. A `nil' value for the IC initializer causes execution
+ to start at the beginning of the program. An optional fourth
+ argument CONTINUE, if non-`nil', causes the IC to remain on the
+ unsatisfied read operation if the program terminates due to
+ exhaustion of the input buffer. Otherwise the IC is set to the end
+ of the program. When the program is done, STATUS is modified (by
+ side-effect) to contain the ending values for the corresponding
+ registers and IC. Returns the resulting string.
+
+ To call a CCL program from another CCL program, it must first be
+registered:
+
+ - Function: register-ccl-program name ccl-program
+ Register NAME for CCL program CCL-PROGRAM in `ccl-program-table'.
+ CCL-PROGRAM should be the compiled form of a CCL program, or
+ `nil'. Return index number of the registered CCL program.
+
+ Information about the processor time used by the CCL interpreter can
+be obtained using these functions:
+
+ - Function: ccl-elapsed-time
+ Returns the elapsed processor time of the CCL interpreter as cons
+ of user and system time, as floating point numbers measured in
+ seconds. If only one overall value can be determined, the return
+ value will be a cons of that value and 0.
+
+ - Function: ccl-reset-elapsed-time
+ Resets the CCL interpreter's internal elapsed time registers.
\1f
-File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation
-
-Garbage Collection
-==================
-
- When a program creates a list or the user defines a new function
-(such as by loading a library), that data is placed in normal storage.
-If normal storage runs low, then XEmacs asks the operating system to
-allocate more memory in blocks of 2k bytes. Each block is used for one
-type of Lisp object, so symbols, cons cells, markers, etc., are
-segregated in distinct blocks in memory. (Vectors, long strings,
-buffers and certain other editing types, which are fairly large, are
-allocated in individual blocks, one per object, while small strings are
-packed into blocks of 8k bytes. [More correctly, a string is allocated
-in two sections: a fixed size chunk containing the length, list of
-extents, etc.; and a chunk containing the actual characters in the
-string. It is this latter chunk that is either allocated individually
-or packed into 8k blocks. The fixed size chunk is packed into 2k
-blocks, as for conses, markers, etc.])
-
- It is quite common to use some storage for a while, then release it
-by (for example) killing a buffer or deleting the last pointer to an
-object. XEmacs provides a "garbage collector" to reclaim this
-abandoned storage. (This name is traditional, but "garbage recycler"
-might be a more intuitive metaphor for this facility.)
-
- The garbage collector operates by finding and marking all Lisp
-objects that are still accessible to Lisp programs. To begin with, it
-assumes all the symbols, their values and associated function
-definitions, and any data presently on the stack, are accessible. Any
-objects that can be reached indirectly through other accessible objects
-are also accessible.
-
- When marking is finished, all objects still unmarked are garbage. No
-matter what the Lisp program or the user does, it is impossible to refer
-to them, since there is no longer a way to reach them. Their space
-might as well be reused, since no one will miss them. The second
-("sweep") phase of the garbage collector arranges to reuse them.
-
- The sweep phase puts unused cons cells onto a "free list" for future
-allocation; likewise for symbols, markers, extents, events, floats,
-compiled-function objects, and the fixed-size portion of strings. It
-compacts the accessible small string-chars chunks so they occupy fewer
-8k blocks; then it frees the other 8k blocks. Vectors, buffers,
-windows, and other large objects are individually allocated and freed
-using `malloc' and `free'.
-
- Common Lisp note: unlike other Lisps, XEmacs Lisp does not call
- the garbage collector when the free list is empty. Instead, it
- simply requests the operating system to allocate more storage, and
- processing continues until `gc-cons-threshold' bytes have been
- used.
-
- This means that you can make sure that the garbage collector will
- not run during a certain portion of a Lisp program by calling the
- garbage collector explicitly just before it (provided that portion
- of the program does not use so much space as to force a second
- garbage collection).
-
- - Command: garbage-collect
- This command runs a garbage collection, and returns information on
- the amount of space in use. (Garbage collection can also occur
- spontaneously if you use more than `gc-cons-threshold' bytes of
- Lisp data since the previous garbage collection.)
-
- `garbage-collect' returns a list containing the following
- information:
-
- ((USED-CONSES . FREE-CONSES)
- (USED-SYMS . FREE-SYMS)
- (USED-MARKERS . FREE-MARKERS)
- USED-STRING-CHARS
- USED-VECTOR-SLOTS
- (PLIST))
-
- => ((73362 . 8325) (13718 . 164)
- (5089 . 5098) 949121 118677
- (conses-used 73362 conses-free 8329 cons-storage 658168
- symbols-used 13718 symbols-free 164 symbol-storage 335216
- bit-vectors-used 0 bit-vectors-total-length 0
- bit-vector-storage 0 vectors-used 7882
- vectors-total-length 118677 vector-storage 537764
- compiled-functions-used 1336 compiled-functions-free 37
- compiled-function-storage 44440 short-strings-used 28829
- long-strings-used 2 strings-free 7722
- short-strings-total-length 916657 short-string-storage 1179648
- long-strings-total-length 32464 string-header-storage 441504
- floats-used 3 floats-free 43 float-storage 2044 markers-used 5089
- markers-free 5098 marker-storage 245280 events-used 103
- events-free 835 event-storage 110656 extents-used 10519
- extents-free 2718 extent-storage 372736
- extent-auxiliarys-used 111 extent-auxiliarys-freed 3
- extent-auxiliary-storage 4440 window-configurations-used 39
- window-configurations-on-free-list 5
- window-configurations-freed 10 window-configuration-storage 9492
- popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62
- toolbar-button-storage 4960 toolbar-datas-used 12
- toolbar-data-storage 240 symbol-value-buffer-locals-used 182
- symbol-value-buffer-local-storage 5824
- symbol-value-lisp-magics-used 22
- symbol-value-lisp-magic-storage 1496
- symbol-value-varaliases-used 43
- symbol-value-varalias-storage 1032 opaque-lists-used 2
- opaque-list-storage 48 color-instances-used 12
- color-instance-storage 288 font-instances-used 5
- font-instance-storage 180 opaques-used 11 opaque-storage 312
- range-tables-used 1 range-table-storage 16 faces-used 34
- face-storage 2584 glyphs-used 124 glyph-storage 4464
- specifiers-used 775 specifier-storage 43869 weak-lists-used 786
- weak-list-storage 18864 char-tables-used 40
- char-table-storage 41920 buffers-used 25 buffer-storage 7000
- extent-infos-used 457 extent-infos-freed 73
- extent-info-storage 9140 keymaps-used 275 keymap-storage 12100
- consoles-used 4 console-storage 384 command-builders-used 2
- command-builder-storage 120 devices-used 2 device-storage 344
- frames-used 3 frame-storage 624 image-instances-used 47
- image-instance-storage 3008 windows-used 27 windows-freed 2
- window-storage 9180 lcrecord-lists-used 15
- lcrecord-list-storage 360 hash-tables-used 631
- hash-table-storage 25240 streams-used 1 streams-on-free-list 3
- streams-freed 12 stream-storage 91))
-
- Here is a table explaining each element:
-
- USED-CONSES
- The number of cons cells in use.
-
- FREE-CONSES
- The number of cons cells for which space has been obtained
- from the operating system, but that are not currently being
- used.
-
- USED-SYMS
- The number of symbols in use.
-
- FREE-SYMS
- The number of symbols for which space has been obtained from
- the operating system, but that are not currently being used.
-
- USED-MARKERS
- The number of markers in use.
-
- FREE-MARKERS
- The number of markers for which space has been obtained from
- the operating system, but that are not currently being used.
-
- USED-STRING-CHARS
- The total size of all strings, in characters.
-
- USED-VECTOR-SLOTS
- The total number of elements of existing vectors.
-
- PLIST
- A list of alternating keyword/value pairs providing more
- detailed information. (As you can see above, quite a lot of
- information is provided.)
-
- - User Option: gc-cons-threshold
- The value of this variable is the number of bytes of storage that
- must be allocated for Lisp objects after one garbage collection in
- order to trigger another garbage collection. A cons cell counts
- as eight bytes, a string as one byte per character plus a few
- bytes of overhead, and so on; space allocated to the contents of
- buffers does not count. Note that the subsequent garbage
- collection does not happen immediately when the threshold is
- exhausted, but only the next time the Lisp evaluator is called.
-
- The initial threshold value is 500,000. If you specify a larger
- value, garbage collection will happen less often. This reduces the
- amount of time spent garbage collecting, but increases total
- memory use. You may want to do this when running a program that
- creates lots of Lisp data.
-
- You can make collections more frequent by specifying a smaller
- value, down to 10,000. A value less than 10,000 will remain in
- effect only until the subsequent garbage collection, at which time
- `garbage-collect' will set the threshold back to 10,000. (This does
- not apply if XEmacs was configured with `--debug'. Therefore, be
- careful when setting `gc-cons-threshold' in that case!)
-
- - Function: memory-limit
- This function returns the address of the last byte XEmacs has
- allocated, divided by 1024. We divide the value by 1024 to make
- sure it fits in a Lisp integer.
-
- You can use this to get a general idea of how your actions affect
- the memory usage.
-
- - Variable: pre-gc-hook
- This is a normal hook to be run just before each garbage
- collection. Interrupts, garbage collection, and errors are
- inhibited while this hook runs, so be extremely careful in what
- you add here. In particular, avoid consing, and do not interact
- with the user.
-
- - Variable: post-gc-hook
- This is a normal hook to be run just after each garbage collection.
- Interrupts, garbage collection, and errors are inhibited while
- this hook runs, so be extremely careful in what you add here. In
- particular, avoid consing, and do not interact with the user.
-
- - Variable: gc-message
- This is a string to print to indicate that a garbage collection is
- in progress. This is printed in the echo area. If the selected
- frame is on a window system and `gc-pointer-glyph' specifies a
- value (i.e. a pointer image instance) in the domain of the
- selected frame, the mouse cursor will change instead of this
- message being printed.
-
- - Glyph: gc-pointer-glyph
- This holds the pointer glyph used to indicate that a garbage
- collection is in progress. If the selected window is on a window
- system and this glyph specifies a value (i.e. a pointer image
- instance) in the domain of the selected window, the cursor will be
- changed as specified during garbage collection. Otherwise, a
- message will be printed in the echo area, as controlled by
- `gc-message'. *Note Glyphs::.
-
- If XEmacs was configured with `--debug', you can set the following
-two variables to get direct information about all the allocation that
-is happening in a segment of Lisp code.
-
- - Variable: debug-allocation
- If non-zero, print out information to stderr about all objects
- allocated.
-
- - Variable: debug-allocation-backtrace
- Length (in stack frames) of short backtrace printed out by
- `debug-allocation'.
+File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
+
+CCL Examples
+------------
+
+ This section is not yet written.
+
+\1f
+File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE
+
+Category Tables
+===============
+
+ A category table is a type of char table used for keeping track of
+categories. Categories are used for classifying characters for use in
+regexps--you can refer to a category rather than having to use a
+complicated [] expression (and category lookups are significantly
+faster).
+
+ There are 95 different categories available, one for each printable
+character (including space) in the ASCII charset. Each category is
+designated by one such character, called a "category designator". They
+are specified in a regexp using the syntax `\cX', where X is a category
+designator. (This is not yet implemented.)
+
+ A category table specifies, for each character, the categories that
+the character is in. Note that a character can be in more than one
+category. More specifically, a category table maps from a character to
+either the value `nil' (meaning the character is in no categories) or a
+95-element bit vector, specifying for each of the 95 categories whether
+the character is in that category.
+
+ Special Lisp functions are provided that abstract this, so you do not
+have to directly manipulate bit vectors.
+
+ - Function: category-table-p object
+ This function returns `t' if OBJECT is a category table.
+
+ - Function: category-table &optional buffer
+ This function returns the current category table. This is the one
+ specified by the current buffer, or by BUFFER if it is non-`nil'.
+
+ - Function: standard-category-table
+ This function returns the standard category table. This is the
+ one used for new buffers.
+
+ - Function: copy-category-table &optional category-table
+ This function returns a new category table which is a copy of
+ CATEGORY-TABLE, which defaults to the standard category table.
+
+ - Function: set-category-table category-table &optional buffer
+ This function selects CATEGORY-TABLE as the new category table for
+ BUFFER. BUFFER defaults to the current buffer if omitted.
+
+ - Function: category-designator-p object
+ This function returns `t' if OBJECT is a category designator (a
+ char in the range `' '' to `'~'').
+
+ - Function: category-table-value-p object
+ This function returns `t' if OBJECT is a category table value.
+ Valid values are `nil' or a bit vector of size 95.
\1f
-File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top
-
-Standard Errors
-***************
-
- Here is the complete list of the error symbols in standard Emacs,
-grouped by concept. The list includes each symbol's message (on the
-`error-message' property of the symbol) and a cross reference to a
-description of how the error can occur.
-
- Each error symbol has an `error-conditions' property that is a list
-of symbols. Normally this list includes the error symbol itself and
-the symbol `error'. Occasionally it includes additional symbols, which
-are intermediate classifications, narrower than `error' but broader
-than a single error symbol. For example, all the errors in accessing
-files have the condition `file-error'.
-
- As a special exception, the error symbol `quit' does not have the
-condition `error', because quitting is not considered an error.
-
- *Note Errors::, for an explanation of how errors are generated and
-handled.
-
-`SYMBOL'
- STRING; REFERENCE.
-
-`error'
- `"error"'
- *Note Errors::.
-
-`quit'
- `"Quit"'
- *Note Quitting::.
-
-`args-out-of-range'
- `"Args out of range"'
- *Note Sequences Arrays Vectors::.
-
-`arith-error'
- `"Arithmetic error"'
- See `/' and `%' in *Note Numbers::.
-
-`beginning-of-buffer'
- `"Beginning of buffer"'
- *Note Motion::.
-
-`buffer-read-only'
- `"Buffer is read-only"'
- *Note Read Only Buffers::.
-
-`cyclic-function-indirection'
- `"Symbol's chain of function indirections contains a loop"'
- *Note Function Indirection::.
-
-`domain-error'
- `"Arithmetic domain error"'
-`end-of-buffer'
- `"End of buffer"'
- *Note Motion::.
-
-`end-of-file'
- `"End of file during parsing"'
- This is not a `file-error'.
- *Note Input Functions::.
-
-`file-error'
- This error and its subcategories do not have error-strings,
- because the error message is constructed from the data items alone
- when the error condition `file-error' is present.
- *Note Files::.
-
-`file-locked'
- This is a `file-error'.
- *Note File Locks::.
-
-`file-already-exists'
- This is a `file-error'.
- *Note Writing to Files::.
-
-`file-supersession'
- This is a `file-error'.
- *Note Modification Time::.
-
-`invalid-byte-code'
- `"Invalid byte code"'
- *Note Byte Compilation::.
-
-`invalid-function'
- `"Invalid function"'
- *Note Classifying Lists::.
-
-`invalid-read-syntax'
- `"Invalid read syntax"'
- *Note Input Functions::.
-
-`invalid-regexp'
- `"Invalid regexp"'
- *Note Regular Expressions::.
-
-`mark-inactive'
- `"The mark is not active now"'
-`no-catch'
- `"No catch for tag"'
- *Note Catch and Throw::.
-
-`overflow-error'
- `"Arithmetic overflow error"'
-`protected-field'
- `"Attempt to modify a protected field"'
-`range-error'
- `"Arithmetic range error"'
-`search-failed'
- `"Search failed"'
- *Note Searching and Matching::.
-
-`setting-constant'
- `"Attempt to set a constant symbol"'
- *Note Variables that Never Change: Constant Variables.
-
-`singularity-error'
- `"Arithmetic singularity error"'
-`tooltalk-error'
- `"ToolTalk error"'
- *Note ToolTalk Support::.
-
-`undefined-keystroke-sequence'
- `"Undefined keystroke sequence"'
-`void-function'
- `"Symbol's function definition is void"'
- *Note Function Cells::.
-
-`void-variable'
- `"Symbol's value as variable is void"'
- *Note Accessing Variables::.
-
-`wrong-number-of-arguments'
- `"Wrong number of arguments"'
- *Note Classifying Lists::.
-
-`wrong-type-argument'
- `"Wrong type argument"'
- *Note Type Predicates::.
-
- These error types, which are all classified as special cases of
-`arith-error', can occur on certain systems for invalid use of
-mathematical functions.
-
-`domain-error'
- `"Arithmetic domain error"'
- *Note Math Functions::.
-
-`overflow-error'
- `"Arithmetic overflow error"'
- *Note Math Functions::.
-
-`range-error'
- `"Arithmetic range error"'
- *Note Math Functions::.
-
-`singularity-error'
- `"Arithmetic singularity error"'
- *Note Math Functions::.
-
-`underflow-error'
- `"Arithmetic underflow error"'
- *Note Math Functions::.
+File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top
+
+Tips and Standards
+******************
+
+ This chapter describes no additional features of XEmacs Lisp.
+Instead it gives advice on making effective use of the features
+described in the previous chapters.
+
+* Menu:
+
+* Style Tips:: Writing clean and robust programs.
+* Compilation Tips:: Making compiled code run fast.
+* Documentation Tips:: Writing readable documentation strings.
+* Comment Tips:: Conventions for writing comments.
+* Library Headers:: Standard headers for library packages.
projects / chise / xemacs-chise.git / blobdiff