Foundation instead of in the original English.
\1f
+File: internals.info, Node: Working With Character and Byte Positions, Next: Conversion to and from External Data, Prev: Character-Related Data Types, Up: Coding for Mule
+
+Working With Character and Byte Positions
+-----------------------------------------
+
+ Now that we have defined the basic character-related types, we can
+look at the macros and functions designed for work with them and for
+conversion between them. Most of these macros are defined in
+`buffer.h', and we don't discuss all of them here, but only the most
+important ones. Examining the existing code is the best way to learn
+about them.
+
+`MAX_EMCHAR_LEN'
+ This preprocessor constant is the maximum number of buffer bytes to
+ represent an Emacs character in the variable width internal
+ encoding. It is useful when allocating temporary strings to keep
+ a known number of characters. For instance:
+
+ {
+ Charcount cclen;
+ ...
+ {
+ /* Allocate place for CCLEN characters. */
+ Bufbyte *buf = (Bufbyte *)alloca (cclen * MAX_EMCHAR_LEN);
+ ...
+
+ If you followed the previous section, you can guess that,
+ logically, multiplying a `Charcount' value with `MAX_EMCHAR_LEN'
+ produces a `Bytecount' value.
+
+ In the current Mule implementation, `MAX_EMCHAR_LEN' equals 4.
+ Without Mule, it is 1.
+
+`charptr_emchar'
+`set_charptr_emchar'
+ The `charptr_emchar' macro takes a `Bufbyte' pointer and returns
+ the `Emchar' stored at that position. If it were a function, its
+ prototype would be:
+
+ Emchar charptr_emchar (Bufbyte *p);
+
+ `set_charptr_emchar' stores an `Emchar' to the specified byte
+ position. It returns the number of bytes stored:
+
+ Bytecount set_charptr_emchar (Bufbyte *p, Emchar c);
+
+ It is important to note that `set_charptr_emchar' is safe only for
+ appending a character at the end of a buffer, not for overwriting a
+ character in the middle. This is because the width of characters
+ varies, and `set_charptr_emchar' cannot resize the string if it
+ writes, say, a two-byte character where a single-byte character
+ used to reside.
+
+ A typical use of `set_charptr_emchar' can be demonstrated by this
+ example, which copies characters from buffer BUF to a temporary
+ string of Bufbytes.
+
+ {
+ Bufpos pos;
+ for (pos = beg; pos < end; pos++)
+ {
+ Emchar c = BUF_FETCH_CHAR (buf, pos);
+ p += set_charptr_emchar (buf, c);
+ }
+ }
+
+ Note how `set_charptr_emchar' is used to store the `Emchar' and
+ increment the counter, at the same time.
+
+`INC_CHARPTR'
+`DEC_CHARPTR'
+ These two macros increment and decrement a `Bufbyte' pointer,
+ respectively. They will adjust the pointer by the appropriate
+ number of bytes according to the byte length of the character
+ stored there. Both macros assume that the memory address is
+ located at the beginning of a valid character.
+
+ Without Mule support, `INC_CHARPTR (p)' and `DEC_CHARPTR (p)'
+ simply expand to `p++' and `p--', respectively.
+
+`bytecount_to_charcount'
+ Given a pointer to a text string and a length in bytes, return the
+ equivalent length in characters.
+
+ Charcount bytecount_to_charcount (Bufbyte *p, Bytecount bc);
+
+`charcount_to_bytecount'
+ Given a pointer to a text string and a length in characters,
+ return the equivalent length in bytes.
+
+ Bytecount charcount_to_bytecount (Bufbyte *p, Charcount cc);
+
+`charptr_n_addr'
+ Return a pointer to the beginning of the character offset CC (in
+ characters) from P.
+
+ Bufbyte *charptr_n_addr (Bufbyte *p, Charcount cc);
+
+\1f
File: internals.info, Node: Conversion to and from External Data, Next: General Guidelines for Writing Mule-Aware Code, Prev: Working With Character and Byte Positions, Up: Coding for Mule
Conversion to and from External Data
* Modules for Internationalization::
\1f
-File: internals.info, Node: Low-Level Modules, Next: Basic Lisp Modules, Prev: A Summary of the Various XEmacs Modules, Up: A Summary of the Various XEmacs Modules
+File: internals.info, Node: Low-Level Modules, Next: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules
Low-Level Modules
=================
redisplay mechanism or the code for particular object types such as
scrollbars.
-\1f
-File: internals.info, Node: Modules for other Display-Related Lisp Objects, Next: Modules for the Redisplay Mechanism, Prev: Modules for the Basic Displayable Lisp Objects, Up: A Summary of the Various XEmacs Modules
-
-Modules for other Display-Related Lisp Objects
-==============================================
-
- faces.c
- faces.h
-
- bitmaps.h
- glyphs-eimage.c
- glyphs-msw.c
- glyphs-msw.h
- glyphs-widget.c
- glyphs-x.c
- glyphs-x.h
- glyphs.c
- glyphs.h
-
- objects-msw.c
- objects-msw.h
- objects-tty.c
- objects-tty.h
- objects-x.c
- objects-x.h
- objects.c
- objects.h
-
- menubar-msw.c
- menubar-msw.h
- menubar-x.c
- menubar.c
- menubar.h
-
- scrollbar-msw.c
- scrollbar-msw.h
- scrollbar-x.c
- scrollbar-x.h
- scrollbar.c
- scrollbar.h
-
- toolbar-msw.c
- toolbar-x.c
- toolbar.c
- toolbar.h
-
- font-lock.c
-
- This file provides C support for syntax highlighting--i.e.
-highlighting different syntactic constructs of a source file in
-different colors, for easy reading. The C support is provided so that
-this is fast.
-
- dgif_lib.c
- gif_err.c
- gif_lib.h
- gifalloc.c
-
- These modules decode GIF-format image files, for use with glyphs.
-These files were removed due to Unisys patent infringement concerns.
-
-\1f
-File: internals.info, Node: Modules for the Redisplay Mechanism, Next: Modules for Interfacing with the File System, Prev: Modules for other Display-Related Lisp Objects, Up: A Summary of the Various XEmacs Modules
-
-Modules for the Redisplay Mechanism
-===================================
-
- redisplay-output.c
- redisplay-msw.c
- redisplay-tty.c
- redisplay-x.c
- redisplay.c
- redisplay.h
-
- These files provide the redisplay mechanism. As with many other
-subsystems in XEmacs, there is a clean separation between the general
-and device-specific support.
-
- `redisplay.c' contains the bulk of the redisplay engine. These
-functions update the redisplay structures (which describe how the screen
-is to appear) to reflect any changes made to the state of any
-displayable objects (buffer, frame, window, etc.) since the last time
-that redisplay was called. These functions are highly optimized to
-avoid doing more work than necessary (since redisplay is called
-extremely often and is potentially a huge time sink), and depend heavily
-on notifications from the objects themselves that changes have occurred,
-so that redisplay doesn't explicitly have to check each possible object.
-The redisplay mechanism also contains a great deal of caching to further
-speed things up; some of this caching is contained within the various
-displayable objects.
-
- `redisplay-output.c' goes through the redisplay structures and
-converts them into calls to device-specific methods to actually output
-the screen changes.
-
- `redisplay-x.c' and `redisplay-tty.c' are two implementations of
-these redisplay output methods, for X frames and TTY frames,
-respectively.
-
- indent.c
-
- This module contains various functions and Lisp primitives for
-converting between buffer positions and screen positions. These
-functions call the redisplay mechanism to do most of the work, and then
-examine the redisplay structures to get the necessary information. This
-module needs work.
-
- termcap.c
- terminfo.c
- tparam.c
-
- These files contain functions for working with the termcap
-(BSD-style) and terminfo (System V style) databases of terminal
-capabilities and escape sequences, used when XEmacs is displaying in a
-TTY.
-
- cm.c
- cm.h
-
- These files provide some miscellaneous TTY-output functions and
-should probably be merged into `redisplay-tty.c'.
-
Foundation instead of in the original English.
\1f
+File: internals.info, Node: Modules for other Display-Related Lisp Objects, Next: Modules for the Redisplay Mechanism, Prev: Modules for the Basic Displayable Lisp Objects, Up: A Summary of the Various XEmacs Modules
+
+Modules for other Display-Related Lisp Objects
+==============================================
+
+ faces.c
+ faces.h
+
+ bitmaps.h
+ glyphs-eimage.c
+ glyphs-msw.c
+ glyphs-msw.h
+ glyphs-widget.c
+ glyphs-x.c
+ glyphs-x.h
+ glyphs.c
+ glyphs.h
+
+ objects-msw.c
+ objects-msw.h
+ objects-tty.c
+ objects-tty.h
+ objects-x.c
+ objects-x.h
+ objects.c
+ objects.h
+
+ menubar-msw.c
+ menubar-msw.h
+ menubar-x.c
+ menubar.c
+ menubar.h
+
+ scrollbar-msw.c
+ scrollbar-msw.h
+ scrollbar-x.c
+ scrollbar-x.h
+ scrollbar.c
+ scrollbar.h
+
+ toolbar-msw.c
+ toolbar-x.c
+ toolbar.c
+ toolbar.h
+
+ font-lock.c
+
+ This file provides C support for syntax highlighting--i.e.
+highlighting different syntactic constructs of a source file in
+different colors, for easy reading. The C support is provided so that
+this is fast.
+
+ dgif_lib.c
+ gif_err.c
+ gif_lib.h
+ gifalloc.c
+
+ These modules decode GIF-format image files, for use with glyphs.
+These files were removed due to Unisys patent infringement concerns.
+
+\1f
+File: internals.info, Node: Modules for the Redisplay Mechanism, Next: Modules for Interfacing with the File System, Prev: Modules for other Display-Related Lisp Objects, Up: A Summary of the Various XEmacs Modules
+
+Modules for the Redisplay Mechanism
+===================================
+
+ redisplay-output.c
+ redisplay-msw.c
+ redisplay-tty.c
+ redisplay-x.c
+ redisplay.c
+ redisplay.h
+
+ These files provide the redisplay mechanism. As with many other
+subsystems in XEmacs, there is a clean separation between the general
+and device-specific support.
+
+ `redisplay.c' contains the bulk of the redisplay engine. These
+functions update the redisplay structures (which describe how the screen
+is to appear) to reflect any changes made to the state of any
+displayable objects (buffer, frame, window, etc.) since the last time
+that redisplay was called. These functions are highly optimized to
+avoid doing more work than necessary (since redisplay is called
+extremely often and is potentially a huge time sink), and depend heavily
+on notifications from the objects themselves that changes have occurred,
+so that redisplay doesn't explicitly have to check each possible object.
+The redisplay mechanism also contains a great deal of caching to further
+speed things up; some of this caching is contained within the various
+displayable objects.
+
+ `redisplay-output.c' goes through the redisplay structures and
+converts them into calls to device-specific methods to actually output
+the screen changes.
+
+ `redisplay-x.c' and `redisplay-tty.c' are two implementations of
+these redisplay output methods, for X frames and TTY frames,
+respectively.
+
+ indent.c
+
+ This module contains various functions and Lisp primitives for
+converting between buffer positions and screen positions. These
+functions call the redisplay mechanism to do most of the work, and then
+examine the redisplay structures to get the necessary information. This
+module needs work.
+
+ termcap.c
+ terminfo.c
+ tparam.c
+
+ These files contain functions for working with the termcap
+(BSD-style) and terminfo (System V style) databases of terminal
+capabilities and escape sequences, used when XEmacs is displaying in a
+TTY.
+
+ cm.c
+ cm.h
+
+ These files provide some miscellaneous TTY-output functions and
+should probably be merged into `redisplay-tty.c'.
+
+\1f
File: internals.info, Node: Modules for Interfacing with the File System, Next: Modules for Other Aspects of the Lisp Interpreter and Object System, Prev: Modules for the Redisplay Mechanism, Up: A Summary of the Various XEmacs Modules
Modules for Interfacing with the File System
* Compiled Function::
\1f
-File: internals.info, Node: Introduction to Allocation, Next: Garbage Collection, Prev: Allocation of Objects in XEmacs Lisp, Up: Allocation of Objects in XEmacs Lisp
+File: internals.info, Node: Introduction to Allocation, Next: Garbage Collection, Up: Allocation of Objects in XEmacs Lisp
Introduction to Allocation
==========================
* sweep_bit_vectors_1::
\1f
-File: internals.info, Node: Invocation, Next: garbage_collect_1, Prev: Garbage Collection - Step by Step, Up: Garbage Collection - Step by Step
+File: internals.info, Node: Invocation, Next: garbage_collect_1, Up: Garbage Collection - Step by Step
Invocation
----------
signals, as for example the ones raised by every `QUIT'-macro triggered
after pressing Ctrl-g.
-\1f
-File: internals.info, Node: garbage_collect_1, Next: mark_object, Prev: Invocation, Up: Garbage Collection - Step by Step
-
-`garbage_collect_1'
--------------------
-
- We can now describe exactly what happens after the invocation takes
-place.
- 1. There are several cases in which the garbage collector is left
- immediately: when we are already garbage collecting
- (`gc_in_progress'), when the garbage collection is somehow
- forbidden (`gc_currently_forbidden'), when we are currently
- displaying something (`in_display') or when we are preparing for
- the armageddon of the whole system (`preparing_for_armageddon').
-
- 2. Next the correct frame in which to put all the output occurring
- during garbage collecting is determined. In order to be able to
- restore the old display's state after displaying the message, some
- data about the current cursor position has to be saved. The
- variables `pre_gc_cursor' and `cursor_changed' take care of that.
-
- 3. The state of `gc_currently_forbidden' must be restored after the
- garbage collection, no matter what happens during the process. We
- accomplish this by `record_unwind_protect'ing the suitable function
- `restore_gc_inhibit' together with the current value of
- `gc_currently_forbidden'.
-
- 4. If we are concurrently running an interactive xemacs session, the
- next step is simply to show the garbage collector's cursor/message.
-
- 5. The following steps are the intrinsic steps of the garbage
- collector, therefore `gc_in_progress' is set.
-
- 6. For debugging purposes, it is possible to copy the current C stack
- frame. However, this seems to be a currently unused feature.
-
- 7. Before actually starting to go over all live objects, references to
- objects that are no longer used are pruned. We only have to do
- this for events (`clear_event_resource') and for specifiers
- (`cleanup_specifiers').
-
- 8. Now the mark phase begins and marks all accessible elements. In
- order to start from all slots that serve as roots of
- accessibility, the function `mark_object' is called for each root
- individually to go out from there to mark all reachable objects.
- All roots that are traversed are shown in their processed order:
- * all constant symbols and static variables that are registered
- via `staticpro' in the dynarr `staticpros'. *Note Adding
- Global Lisp Variables::.
-
- * all Lisp objects that are created in C functions and that
- must be protected from freeing them. They are registered in
- the global list `gcprolist'. *Note GCPROing::.
-
- * all local variables (i.e. their name fields `symbol' and old
- values `old_values') that are bound during the evaluation by
- the Lisp engine. They are stored in `specbinding' structs
- pushed on a stack called `specpdl'. *Note Dynamic Binding;
- The specbinding Stack; Unwind-Protects::.
-
- * all catch blocks that the Lisp engine encounters during the
- evaluation cause the creation of structs `catchtag' inserted
- in the list `catchlist'. Their tag (`tag') and value (`val'
- fields are freshly created objects and therefore have to be
- marked. *Note Catch and Throw::.
-
- * every function application pushes new structs `backtrace' on
- the call stack of the Lisp engine (`backtrace_list'). The
- unique parts that have to be marked are the fields for each
- function (`function') and all their arguments (`args').
- *Note Evaluation::.
-
- * all objects that are used by the redisplay engine that must
- not be freed are marked by a special function called
- `mark_redisplay' (in `redisplay.c').
-
- * all objects created for profiling purposes are allocated by C
- functions instead of using the lisp allocation mechanisms. In
- order to receive the right ones during the sweep phase, they
- also have to be marked manually. That is done by the function
- `mark_profiling_info'
-
- 9. Hash tables in XEmacs belong to a kind of special objects that
- make use of a concept often called 'weak pointers'. To make a
- long story short, these kind of pointers are not followed during
- the estimation of the live objects during garbage collection. Any
- object referenced only by weak pointers is collected anyway, and
- the reference to it is cleared. In hash tables there are different
- usage patterns of them, manifesting in different types of hash
- tables, namely 'non-weak', 'weak', 'key-weak' and 'value-weak'
- (internally also 'key-car-weak' and 'value-car-weak') hash tables,
- each clearing entries depending on different conditions. More
- information can be found in the documentation to the function
- `make-hash-table'.
-
- Because there are complicated dependency rules about when and what
- to mark while processing weak hash tables, the standard `marker'
- method is only active if it is marking non-weak hash tables. As
- soon as a weak component is in the table, the hash table entries
- are ignored while marking. Instead their marking is done each
- separately by the function `finish_marking_weak_hash_tables'. This
- function iterates over each hash table entry `hentries' for each
- weak hash table in `Vall_weak_hash_tables'. Depending on the type
- of a table, the appropriate action is performed. If a table is
- acting as `HASH_TABLE_KEY_WEAK', and a key already marked,
- everything reachable from the `value' component is marked. If it is
- acting as a `HASH_TABLE_VALUE_WEAK' and the value component is
- already marked, the marking starts beginning only from the `key'
- component. If it is a `HASH_TABLE_KEY_CAR_WEAK' and the car of
- the key entry is already marked, we mark both the `key' and
- `value' components. Finally, if the table is of the type
- `HASH_TABLE_VALUE_CAR_WEAK' and the car of the value components is
- already marked, again both the `key' and the `value' components
- get marked.
-
- Again, there are lists with comparable properties called weak
- lists. There exist different peculiarities of their types called
- `simple', `assoc', `key-assoc' and `value-assoc'. You can find
- further details about them in the description to the function
- `make-weak-list'. The scheme of their marking is similar: all weak
- lists are listed in `Qall_weak_lists', therefore we iterate over
- them. The marking is advanced until we hit an already marked pair.
- Then we know that during a former run all the rest has been marked
- completely. Again, depending on the special type of the weak list,
- our jobs differ. If it is a `WEAK_LIST_SIMPLE' and the elem is
- marked, we mark the `cons' part. If it is a `WEAK_LIST_ASSOC' and
- not a pair or a pair with both marked car and cdr, we mark the
- `cons' and the `elem'. If it is a `WEAK_LIST_KEY_ASSOC' and not a
- pair or a pair with a marked car of the elem, we mark the `cons'
- and the `elem'. Finally, if it is a `WEAK_LIST_VALUE_ASSOC' and
- not a pair or a pair with a marked cdr of the elem, we mark both
- the `cons' and the `elem'.
-
- Since, by marking objects in reach from weak hash tables and weak
- lists, other objects could get marked, this perhaps implies
- further marking of other weak objects, both finishing functions
- are redone as long as yet unmarked objects get freshly marked.
-
- 10. After completing the special marking for the weak hash tables and
- for the weak lists, all entries that point to objects that are
- going to be swept in the further process are useless, and
- therefore have to be removed from the table or the list.
-
- The function `prune_weak_hash_tables' does the job for weak hash
- tables. Totally unmarked hash tables are removed from the list
- `Vall_weak_hash_tables'. The other ones are treated more carefully
- by scanning over all entries and removing one as soon as one of
- the components `key' and `value' is unmarked.
-
- The same idea applies to the weak lists. It is accomplished by
- `prune_weak_lists': An unmarked list is pruned from
- `Vall_weak_lists' immediately. A marked list is treated more
- carefully by going over it and removing just the unmarked pairs.
-
- 11. The function `prune_specifiers' checks all listed specifiers held
- in `Vall_specifiers' and removes the ones from the lists that are
- unmarked.
-
- 12. All syntax tables are stored in a list called
- `Vall_syntax_tables'. The function `prune_syntax_tables' walks
- through it and unlinks the tables that are unmarked.
-
- 13. Next, we will attack the complete sweeping - the function
- `gc_sweep' which holds the predominance.
-
- 14. First, all the variables with respect to garbage collection are
- reset. `consing_since_gc' - the counter of the created cells since
- the last garbage collection - is set back to 0, and
- `gc_in_progress' is not `true' anymore.
-
- 15. In case the session is interactive, the displayed cursor and
- message are removed again.
-
- 16. The state of `gc_inhibit' is restored to the former value by
- unwinding the stack.
-
- 17. A small memory reserve is always held back that can be reached by
- `breathing_space'. If nothing more is left, we create a new reserve
- and exit.
-
-\1f
-File: internals.info, Node: mark_object, Next: gc_sweep, Prev: garbage_collect_1, Up: Garbage Collection - Step by Step
-
-`mark_object'
--------------
-
- The first thing that is checked while marking an object is whether
-the object is a real Lisp object `Lisp_Type_Record' or just an integer
-or a character. Integers and characters are the only two types that are
-stored directly - without another level of indirection, and therefore
-they don't have to be marked and collected. *Note How Lisp Objects Are
-Represented in C::.
-
- The second case is the one we have to handle. It is the one when we
-are dealing with a pointer to a Lisp object. But, there exist also three
-possibilities, that prevent us from doing anything while marking: The
-object is read only which prevents it from being garbage collected,
-i.e. marked (`C_READONLY_RECORD_HEADER'). The object in question is
-already marked, and need not be marked for the second time (checked by
-`MARKED_RECORD_HEADER_P'). If it is a special, unmarkable object
-(`UNMARKABLE_RECORD_HEADER_P', apparently, these are objects that sit
-in some const space, and can therefore not be marked, see
-`this_one_is_unmarkable' in `alloc.c').
-
- Now, the actual marking is feasible. We do so by once using the macro
-`MARK_RECORD_HEADER' to mark the object itself (actually the special
-flag in the lrecord header), and calling its special marker "method"
-`marker' if available. The marker method marks every other object that
-is in reach from our current object. Note, that these marker methods
-should not call `mark_object' recursively, but instead should return
-the next object from where further marking has to be performed.
-
- In case another object was returned, as mentioned before, we
-reiterate the whole `mark_object' process beginning with this next
-object.
-
Foundation instead of in the original English.
\1f
+File: internals.info, Node: garbage_collect_1, Next: mark_object, Prev: Invocation, Up: Garbage Collection - Step by Step
+
+`garbage_collect_1'
+-------------------
+
+ We can now describe exactly what happens after the invocation takes
+place.
+ 1. There are several cases in which the garbage collector is left
+ immediately: when we are already garbage collecting
+ (`gc_in_progress'), when the garbage collection is somehow
+ forbidden (`gc_currently_forbidden'), when we are currently
+ displaying something (`in_display') or when we are preparing for
+ the armageddon of the whole system (`preparing_for_armageddon').
+
+ 2. Next the correct frame in which to put all the output occurring
+ during garbage collecting is determined. In order to be able to
+ restore the old display's state after displaying the message, some
+ data about the current cursor position has to be saved. The
+ variables `pre_gc_cursor' and `cursor_changed' take care of that.
+
+ 3. The state of `gc_currently_forbidden' must be restored after the
+ garbage collection, no matter what happens during the process. We
+ accomplish this by `record_unwind_protect'ing the suitable function
+ `restore_gc_inhibit' together with the current value of
+ `gc_currently_forbidden'.
+
+ 4. If we are concurrently running an interactive xemacs session, the
+ next step is simply to show the garbage collector's cursor/message.
+
+ 5. The following steps are the intrinsic steps of the garbage
+ collector, therefore `gc_in_progress' is set.
+
+ 6. For debugging purposes, it is possible to copy the current C stack
+ frame. However, this seems to be a currently unused feature.
+
+ 7. Before actually starting to go over all live objects, references to
+ objects that are no longer used are pruned. We only have to do
+ this for events (`clear_event_resource') and for specifiers
+ (`cleanup_specifiers').
+
+ 8. Now the mark phase begins and marks all accessible elements. In
+ order to start from all slots that serve as roots of
+ accessibility, the function `mark_object' is called for each root
+ individually to go out from there to mark all reachable objects.
+ All roots that are traversed are shown in their processed order:
+ * all constant symbols and static variables that are registered
+ via `staticpro' in the dynarr `staticpros'. *Note Adding
+ Global Lisp Variables::.
+
+ * all Lisp objects that are created in C functions and that
+ must be protected from freeing them. They are registered in
+ the global list `gcprolist'. *Note GCPROing::.
+
+ * all local variables (i.e. their name fields `symbol' and old
+ values `old_values') that are bound during the evaluation by
+ the Lisp engine. They are stored in `specbinding' structs
+ pushed on a stack called `specpdl'. *Note Dynamic Binding;
+ The specbinding Stack; Unwind-Protects::.
+
+ * all catch blocks that the Lisp engine encounters during the
+ evaluation cause the creation of structs `catchtag' inserted
+ in the list `catchlist'. Their tag (`tag') and value (`val'
+ fields are freshly created objects and therefore have to be
+ marked. *Note Catch and Throw::.
+
+ * every function application pushes new structs `backtrace' on
+ the call stack of the Lisp engine (`backtrace_list'). The
+ unique parts that have to be marked are the fields for each
+ function (`function') and all their arguments (`args').
+ *Note Evaluation::.
+
+ * all objects that are used by the redisplay engine that must
+ not be freed are marked by a special function called
+ `mark_redisplay' (in `redisplay.c').
+
+ * all objects created for profiling purposes are allocated by C
+ functions instead of using the lisp allocation mechanisms. In
+ order to receive the right ones during the sweep phase, they
+ also have to be marked manually. That is done by the function
+ `mark_profiling_info'
+
+ 9. Hash tables in XEmacs belong to a kind of special objects that
+ make use of a concept often called 'weak pointers'. To make a
+ long story short, these kind of pointers are not followed during
+ the estimation of the live objects during garbage collection. Any
+ object referenced only by weak pointers is collected anyway, and
+ the reference to it is cleared. In hash tables there are different
+ usage patterns of them, manifesting in different types of hash
+ tables, namely 'non-weak', 'weak', 'key-weak' and 'value-weak'
+ (internally also 'key-car-weak' and 'value-car-weak') hash tables,
+ each clearing entries depending on different conditions. More
+ information can be found in the documentation to the function
+ `make-hash-table'.
+
+ Because there are complicated dependency rules about when and what
+ to mark while processing weak hash tables, the standard `marker'
+ method is only active if it is marking non-weak hash tables. As
+ soon as a weak component is in the table, the hash table entries
+ are ignored while marking. Instead their marking is done each
+ separately by the function `finish_marking_weak_hash_tables'. This
+ function iterates over each hash table entry `hentries' for each
+ weak hash table in `Vall_weak_hash_tables'. Depending on the type
+ of a table, the appropriate action is performed. If a table is
+ acting as `HASH_TABLE_KEY_WEAK', and a key already marked,
+ everything reachable from the `value' component is marked. If it is
+ acting as a `HASH_TABLE_VALUE_WEAK' and the value component is
+ already marked, the marking starts beginning only from the `key'
+ component. If it is a `HASH_TABLE_KEY_CAR_WEAK' and the car of
+ the key entry is already marked, we mark both the `key' and
+ `value' components. Finally, if the table is of the type
+ `HASH_TABLE_VALUE_CAR_WEAK' and the car of the value components is
+ already marked, again both the `key' and the `value' components
+ get marked.
+
+ Again, there are lists with comparable properties called weak
+ lists. There exist different peculiarities of their types called
+ `simple', `assoc', `key-assoc' and `value-assoc'. You can find
+ further details about them in the description to the function
+ `make-weak-list'. The scheme of their marking is similar: all weak
+ lists are listed in `Qall_weak_lists', therefore we iterate over
+ them. The marking is advanced until we hit an already marked pair.
+ Then we know that during a former run all the rest has been marked
+ completely. Again, depending on the special type of the weak list,
+ our jobs differ. If it is a `WEAK_LIST_SIMPLE' and the elem is
+ marked, we mark the `cons' part. If it is a `WEAK_LIST_ASSOC' and
+ not a pair or a pair with both marked car and cdr, we mark the
+ `cons' and the `elem'. If it is a `WEAK_LIST_KEY_ASSOC' and not a
+ pair or a pair with a marked car of the elem, we mark the `cons'
+ and the `elem'. Finally, if it is a `WEAK_LIST_VALUE_ASSOC' and
+ not a pair or a pair with a marked cdr of the elem, we mark both
+ the `cons' and the `elem'.
+
+ Since, by marking objects in reach from weak hash tables and weak
+ lists, other objects could get marked, this perhaps implies
+ further marking of other weak objects, both finishing functions
+ are redone as long as yet unmarked objects get freshly marked.
+
+ 10. After completing the special marking for the weak hash tables and
+ for the weak lists, all entries that point to objects that are
+ going to be swept in the further process are useless, and
+ therefore have to be removed from the table or the list.
+
+ The function `prune_weak_hash_tables' does the job for weak hash
+ tables. Totally unmarked hash tables are removed from the list
+ `Vall_weak_hash_tables'. The other ones are treated more carefully
+ by scanning over all entries and removing one as soon as one of
+ the components `key' and `value' is unmarked.
+
+ The same idea applies to the weak lists. It is accomplished by
+ `prune_weak_lists': An unmarked list is pruned from
+ `Vall_weak_lists' immediately. A marked list is treated more
+ carefully by going over it and removing just the unmarked pairs.
+
+ 11. The function `prune_specifiers' checks all listed specifiers held
+ in `Vall_specifiers' and removes the ones from the lists that are
+ unmarked.
+
+ 12. All syntax tables are stored in a list called
+ `Vall_syntax_tables'. The function `prune_syntax_tables' walks
+ through it and unlinks the tables that are unmarked.
+
+ 13. Next, we will attack the complete sweeping - the function
+ `gc_sweep' which holds the predominance.
+
+ 14. First, all the variables with respect to garbage collection are
+ reset. `consing_since_gc' - the counter of the created cells since
+ the last garbage collection - is set back to 0, and
+ `gc_in_progress' is not `true' anymore.
+
+ 15. In case the session is interactive, the displayed cursor and
+ message are removed again.
+
+ 16. The state of `gc_inhibit' is restored to the former value by
+ unwinding the stack.
+
+ 17. A small memory reserve is always held back that can be reached by
+ `breathing_space'. If nothing more is left, we create a new reserve
+ and exit.
+
+\1f
+File: internals.info, Node: mark_object, Next: gc_sweep, Prev: garbage_collect_1, Up: Garbage Collection - Step by Step
+
+`mark_object'
+-------------
+
+ The first thing that is checked while marking an object is whether
+the object is a real Lisp object `Lisp_Type_Record' or just an integer
+or a character. Integers and characters are the only two types that are
+stored directly - without another level of indirection, and therefore
+they don't have to be marked and collected. *Note How Lisp Objects Are
+Represented in C::.
+
+ The second case is the one we have to handle. It is the one when we
+are dealing with a pointer to a Lisp object. But, there exist also three
+possibilities, that prevent us from doing anything while marking: The
+object is read only which prevents it from being garbage collected,
+i.e. marked (`C_READONLY_RECORD_HEADER'). The object in question is
+already marked, and need not be marked for the second time (checked by
+`MARKED_RECORD_HEADER_P'). If it is a special, unmarkable object
+(`UNMARKABLE_RECORD_HEADER_P', apparently, these are objects that sit
+in some const space, and can therefore not be marked, see
+`this_one_is_unmarkable' in `alloc.c').
+
+ Now, the actual marking is feasible. We do so by once using the macro
+`MARK_RECORD_HEADER' to mark the object itself (actually the special
+flag in the lrecord header), and calling its special marker "method"
+`marker' if available. The marker method marks every other object that
+is in reach from our current object. Note, that these marker methods
+should not call `mark_object' recursively, but instead should return
+the next object from where further marking has to be performed.
+
+ In case another object was returned, as mentioned before, we
+reiterate the whole `mark_object' process beginning with this next
+object.
+
+\1f
File: internals.info, Node: gc_sweep, Next: sweep_lcrecords_1, Prev: mark_object, Up: Garbage Collection - Step by Step
`gc_sweep'
* Remaining issues::
\1f
-File: internals.info, Node: Overview, Next: Data descriptions, Prev: Dumping, Up: Dumping
+File: internals.info, Node: Overview, Next: Data descriptions, Up: Dumping
Overview
========
starting address if needed, and reinitialize all pointers to this
data. Also, rebuild all the quickly rebuildable data.
-\1f
-File: internals.info, Node: Data descriptions, Next: Dumping phase, Prev: Overview, Up: Dumping
-
-Data descriptions
-=================
-
- The more complex task of the dumper is to be able to write lisp
-objects (lrecords) and C structs to disk and reload them at a different
-address, updating all the pointers they include in the process. This
-is done by using external data descriptions that give information about
-the layout of the structures in memory.
-
- The specification of these descriptions is in lrecord.h. A
-description of an lrecord is an array of struct lrecord_description.
-Each of these structs include a type, an offset in the structure and
-some optional parameters depending on the type. For instance, here is
-the string description:
-
- static const struct lrecord_description string_description[] = {
- { XD_BYTECOUNT, offsetof (Lisp_String, size) },
- { XD_OPAQUE_DATA_PTR, offsetof (Lisp_String, data), XD_INDIRECT(0, 1) },
- { XD_LISP_OBJECT, offsetof (Lisp_String, plist) },
- { XD_END }
- };
-
- The first line indicates a member of type Bytecount, which is used by
-the next, indirect directive. The second means "there is a pointer to
-some opaque data in the field `data'". The length of said data is
-given by the expression `XD_INDIRECT(0, 1)', which means "the value in
-the 0th line of the description (welcome to C) plus one". The third
-line means "there is a Lisp_Object member `plist' in the Lisp_String
-structure". `XD_END' then ends the description.
-
- This gives us all the information we need to move around what is
-pointed to by a structure (C or lrecord) and, by transitivity,
-everything that it points to. The only missing information for dumping
-is the size of the structure. For lrecords, this is part of the
-lrecord_implementation, so we don't need to duplicate it. For C
-structures we use a struct struct_description, which includes a size
-field and a pointer to an associated array of lrecord_description.
-
-\1f
-File: internals.info, Node: Dumping phase, Next: Reloading phase, Prev: Data descriptions, Up: Dumping
-
-Dumping phase
-=============
-
- Dumping is done by calling the function pdump() (in dumper.c) which
-is invoked from Fdump_emacs (in emacs.c). This function performs a
-number of tasks.
-
-* Menu:
-
-* Object inventory::
-* Address allocation::
-* The header::
-* Data dumping::
-* Pointers dumping::
-
-\1f
-File: internals.info, Node: Object inventory, Next: Address allocation, Prev: Dumping phase, Up: Dumping phase
-
-Object inventory
-----------------
-
- The first task is to build the list of the objects to dump. This
-includes:
-
- * lisp objects
-
- * C structures
-
- We end up with one `pdump_entry_list_elmt' per object group (arrays
-of C structs are kept together) which includes a pointer to the first
-object of the group, the per-object size and the count of objects in the
-group, along with some other information which is initialized later.
-
- These entries are linked together in `pdump_entry_list' structures
-and can be enumerated thru either:
-
- 1. the `pdump_object_table', an array of `pdump_entry_list', one per
- lrecord type, indexed by type number.
-
- 2. the `pdump_opaque_data_list', used for the opaque data which does
- not include pointers, and hence does not need descriptions.
-
- 3. the `pdump_struct_table', which is a vector of
- `struct_description'/`pdump_entry_list' pairs, used for non-opaque
- C structures.
-
- This uses a marking strategy similar to the garbage collector. Some
-differences though:
-
- 1. We do not use the mark bit (which does not exist for C structures
- anyway); we use a big hash table instead.
-
- 2. We do not use the mark function of lrecords but instead rely on the
- external descriptions. This happens essentially because we need to
- follow pointers to C structures and opaque data in addition to
- Lisp_Object members.
-
- This is done by `pdump_register_object()', which handles Lisp_Object
-variables, and `pdump_register_struct()' which handles C structures,
-which both delegate the description management to
-`pdump_register_sub()'.
-
- The hash table doubles as a map object to pdump_entry_list_elmt (i.e.
-allows us to look up a pdump_entry_list_elmt with the object it points
-to). Entries are added with `pdump_add_entry()' and looked up with
-`pdump_get_entry()'. There is no need for entry removal. The hash
-value is computed quite simply from the object pointer by
-`pdump_make_hash()'.
-
- The roots for the marking are:
-
- 1. the `staticpro''ed variables (there is a special
- `staticpro_nodump()' call for protected variables we do not want
- to dump).
-
- 2. the variables registered via `dump_add_root_object' (`staticpro()'
- is equivalent to `staticpro_nodump()' + `dump_add_root_object()').
-
- 3. the variables registered via `dump_add_root_struct_ptr', each of
- which points to a C structure.
-
- This does not include the GCPRO'ed variables, the specbinds, the
-catchtags, the backlist, the redisplay or the profiling info, since we
-do not want to rebuild the actual chain of lisp calls which end up to
-the dump-emacs call, only the global variables.
-
- Weak lists and weak hash tables are dumped as if they were their
-non-weak equivalent (without changing their type, of course). This has
-not yet been a problem.
-
-\1f
-File: internals.info, Node: Address allocation, Next: The header, Prev: Object inventory, Up: Dumping phase
-
-Address allocation
-------------------
-
- The next step is to allocate the offsets of each of the objects in
-the final dump file. This is done by `pdump_allocate_offset()' which
-is called indirectly by `pdump_scan_by_alignment()'.
-
- The strategy to deal with alignment problems uses these facts:
-
- 1. real world alignment requirements are powers of two.
-
- 2. the C compiler is required to adjust the size of a struct so that
- you can have an array of them next to each other. This means you
- can have an upper bound of the alignment requirements of a given
- structure by looking at which power of two its size is a multiple.
-
- 3. the non-variant part of variable size lrecords has an alignment
- requirement of 4.
-
- Hence, for each lrecord type, C struct type or opaque data block the
-alignment requirement is computed as a power of two, with a minimum of
-2^2 for lrecords. `pdump_scan_by_alignment()' then scans all the
-`pdump_entry_list_elmt''s, the ones with the highest requirements
-first. This ensures the best packing.
-
- The maximum alignment requirement we take into account is 2^8.
-
- `pdump_allocate_offset()' only has to do a linear allocation,
-starting at offset 256 (this leaves room for the header and keeps the
-alignments happy).
-
-\1f
-File: internals.info, Node: The header, Next: Data dumping, Prev: Address allocation, Up: Dumping phase
-
-The header
-----------
-
- The next step creates the file and writes a header with a signature
-and some random information in it. The `reloc_address' field, which
-indicates at which address the file should be loaded if we want to avoid
-post-reload relocation, is set to 0. It then seeks to offset 256 (base
-offset for the objects).
-
-\1f
-File: internals.info, Node: Data dumping, Next: Pointers dumping, Prev: The header, Up: Dumping phase
-
-Data dumping
-------------
-
- The data is dumped in the same order as the addresses were allocated
-by `pdump_dump_data()', called from `pdump_scan_by_alignment()'. This
-function copies the data to a temporary buffer, relocates all pointers
-in the object to the addresses allocated in step Address Allocation,
-and writes it to the file. Using the same order means that, if we are
-careful with lrecords whose size is not a multiple of 4, we are ensured
-that the object is always written at the offset in the file allocated
-in step Address Allocation.
-
-\1f
-File: internals.info, Node: Pointers dumping, Prev: Data dumping, Up: Dumping phase
-
-Pointers dumping
-----------------
-
- A bunch of tables needed to reassign properly the global pointers are
-then written. They are:
-
- 1. the pdump_root_struct_ptrs dynarr
-
- 2. the pdump_opaques dynarr
-
- 3. a vector of all the offsets to the objects in the file that
- include a description (for faster relocation at reload time)
-
- 4. the pdump_root_objects and pdump_weak_object_chains dynarrs.
-
- For each of the dynarrs we write both the pointer to the variables
-and the relocated offset of the object they point to. Since these
-variables are global, the pointers are still valid when restarting the
-program and are used to regenerate the global pointers.
-
- The `pdump_weak_object_chains' dynarr is a special case. The
-variables it points to are the head of weak linked lists of lisp objects
-of the same type. Not all objects of this list are dumped so the
-relocated pointer we associate with them points to the first dumped
-object of the list, or Qnil if none is available. This is also the
-reason why they are not used as roots for the purpose of object
-enumeration.
-
- Some very important information like the `staticpros' and
-`lrecord_implementations_table' are handled indirectly using
-`dump_add_opaque' or `dump_add_root_struct_ptr'.
-
- This is the end of the dumping part.
-
-\1f
-File: internals.info, Node: Reloading phase, Next: Remaining issues, Prev: Dumping phase, Up: Dumping
-
-Reloading phase
-===============
-
-File loading
-------------
-
- The file is mmap'ed in memory (which ensures a PAGESIZE alignment, at
-least 4096), or if mmap is unavailable or fails, a 256-bytes aligned
-malloc is done and the file is loaded.
-
- Some variables are reinitialized from the values found in the header.
-
- The difference between the actual loading address and the
-reloc_address is computed and will be used for all the relocations.
-
-Putting back the pdump_opaques
-------------------------------
-
- The memory contents are restored in the obvious and trivial way.
-
-Putting back the pdump_root_struct_ptrs
----------------------------------------
-
- The variables pointed to by pdump_root_struct_ptrs in the dump phase
-are reset to the right relocated object addresses.
-
-Object relocation
------------------
-
- All the objects are relocated using their description and their
-offset by `pdump_reloc_one'. This step is unnecessary if the
-reloc_address is equal to the file loading address.
-
-Putting back the pdump_root_objects and pdump_weak_object_chains
-----------------------------------------------------------------
-
- Same as Putting back the pdump_root_struct_ptrs.
-
-Reorganize the hash tables
---------------------------
-
- Since some of the hash values in the lisp hash tables are
-address-dependent, their layout is now wrong. So we go through each of
-them and have them resorted by calling `pdump_reorganize_hash_table'.
-
-\1f
-File: internals.info, Node: Remaining issues, Prev: Reloading phase, Up: Dumping
-
-Remaining issues
-================
-
- The build process will have to start a post-dump xemacs, ask it the
-loading address (which will, hopefully, be always the same between
-different xemacs invocations) and relocate the file to the new address.
-This way the object relocation phase will not have to be done, which
-means no writes in the objects and that, because of the use of mmap, the
-dumped data will be shared between all the xemacs running on the
-computer.
-
- Some executable signature will be necessary to ensure that a given
-dump file is really associated with a given executable, or random
-crashes will occur. Maybe a random number set at compile or configure
-time thru a define. This will also allow for having
-differently-compiled xemacsen on the same system (mule and no-mule
-comes to mind).
-
- The DOC file contents should probably end up in the dump file.
-
Foundation instead of in the original English.
\1f
+File: internals.info, Node: Data descriptions, Next: Dumping phase, Prev: Overview, Up: Dumping
+
+Data descriptions
+=================
+
+ The more complex task of the dumper is to be able to write lisp
+objects (lrecords) and C structs to disk and reload them at a different
+address, updating all the pointers they include in the process. This
+is done by using external data descriptions that give information about
+the layout of the structures in memory.
+
+ The specification of these descriptions is in lrecord.h. A
+description of an lrecord is an array of struct lrecord_description.
+Each of these structs include a type, an offset in the structure and
+some optional parameters depending on the type. For instance, here is
+the string description:
+
+ static const struct lrecord_description string_description[] = {
+ { XD_BYTECOUNT, offsetof (Lisp_String, size) },
+ { XD_OPAQUE_DATA_PTR, offsetof (Lisp_String, data), XD_INDIRECT(0, 1) },
+ { XD_LISP_OBJECT, offsetof (Lisp_String, plist) },
+ { XD_END }
+ };
+
+ The first line indicates a member of type Bytecount, which is used by
+the next, indirect directive. The second means "there is a pointer to
+some opaque data in the field `data'". The length of said data is
+given by the expression `XD_INDIRECT(0, 1)', which means "the value in
+the 0th line of the description (welcome to C) plus one". The third
+line means "there is a Lisp_Object member `plist' in the Lisp_String
+structure". `XD_END' then ends the description.
+
+ This gives us all the information we need to move around what is
+pointed to by a structure (C or lrecord) and, by transitivity,
+everything that it points to. The only missing information for dumping
+is the size of the structure. For lrecords, this is part of the
+lrecord_implementation, so we don't need to duplicate it. For C
+structures we use a struct struct_description, which includes a size
+field and a pointer to an associated array of lrecord_description.
+
+\1f
+File: internals.info, Node: Dumping phase, Next: Reloading phase, Prev: Data descriptions, Up: Dumping
+
+Dumping phase
+=============
+
+ Dumping is done by calling the function pdump() (in dumper.c) which
+is invoked from Fdump_emacs (in emacs.c). This function performs a
+number of tasks.
+
+* Menu:
+
+* Object inventory::
+* Address allocation::
+* The header::
+* Data dumping::
+* Pointers dumping::
+
+\1f
+File: internals.info, Node: Object inventory, Next: Address allocation, Up: Dumping phase
+
+Object inventory
+----------------
+
+ The first task is to build the list of the objects to dump. This
+includes:
+
+ * lisp objects
+
+ * C structures
+
+ We end up with one `pdump_entry_list_elmt' per object group (arrays
+of C structs are kept together) which includes a pointer to the first
+object of the group, the per-object size and the count of objects in the
+group, along with some other information which is initialized later.
+
+ These entries are linked together in `pdump_entry_list' structures
+and can be enumerated thru either:
+
+ 1. the `pdump_object_table', an array of `pdump_entry_list', one per
+ lrecord type, indexed by type number.
+
+ 2. the `pdump_opaque_data_list', used for the opaque data which does
+ not include pointers, and hence does not need descriptions.
+
+ 3. the `pdump_struct_table', which is a vector of
+ `struct_description'/`pdump_entry_list' pairs, used for non-opaque
+ C structures.
+
+ This uses a marking strategy similar to the garbage collector. Some
+differences though:
+
+ 1. We do not use the mark bit (which does not exist for C structures
+ anyway); we use a big hash table instead.
+
+ 2. We do not use the mark function of lrecords but instead rely on the
+ external descriptions. This happens essentially because we need to
+ follow pointers to C structures and opaque data in addition to
+ Lisp_Object members.
+
+ This is done by `pdump_register_object()', which handles Lisp_Object
+variables, and `pdump_register_struct()' which handles C structures,
+which both delegate the description management to
+`pdump_register_sub()'.
+
+ The hash table doubles as a map object to pdump_entry_list_elmt (i.e.
+allows us to look up a pdump_entry_list_elmt with the object it points
+to). Entries are added with `pdump_add_entry()' and looked up with
+`pdump_get_entry()'. There is no need for entry removal. The hash
+value is computed quite simply from the object pointer by
+`pdump_make_hash()'.
+
+ The roots for the marking are:
+
+ 1. the `staticpro''ed variables (there is a special
+ `staticpro_nodump()' call for protected variables we do not want
+ to dump).
+
+ 2. the variables registered via `dump_add_root_object' (`staticpro()'
+ is equivalent to `staticpro_nodump()' + `dump_add_root_object()').
+
+ 3. the variables registered via `dump_add_root_struct_ptr', each of
+ which points to a C structure.
+
+ This does not include the GCPRO'ed variables, the specbinds, the
+catchtags, the backlist, the redisplay or the profiling info, since we
+do not want to rebuild the actual chain of lisp calls which end up to
+the dump-emacs call, only the global variables.
+
+ Weak lists and weak hash tables are dumped as if they were their
+non-weak equivalent (without changing their type, of course). This has
+not yet been a problem.
+
+\1f
+File: internals.info, Node: Address allocation, Next: The header, Prev: Object inventory, Up: Dumping phase
+
+Address allocation
+------------------
+
+ The next step is to allocate the offsets of each of the objects in
+the final dump file. This is done by `pdump_allocate_offset()' which
+is called indirectly by `pdump_scan_by_alignment()'.
+
+ The strategy to deal with alignment problems uses these facts:
+
+ 1. real world alignment requirements are powers of two.
+
+ 2. the C compiler is required to adjust the size of a struct so that
+ you can have an array of them next to each other. This means you
+ can have an upper bound of the alignment requirements of a given
+ structure by looking at which power of two its size is a multiple.
+
+ 3. the non-variant part of variable size lrecords has an alignment
+ requirement of 4.
+
+ Hence, for each lrecord type, C struct type or opaque data block the
+alignment requirement is computed as a power of two, with a minimum of
+2^2 for lrecords. `pdump_scan_by_alignment()' then scans all the
+`pdump_entry_list_elmt''s, the ones with the highest requirements
+first. This ensures the best packing.
+
+ The maximum alignment requirement we take into account is 2^8.
+
+ `pdump_allocate_offset()' only has to do a linear allocation,
+starting at offset 256 (this leaves room for the header and keeps the
+alignments happy).
+
+\1f
+File: internals.info, Node: The header, Next: Data dumping, Prev: Address allocation, Up: Dumping phase
+
+The header
+----------
+
+ The next step creates the file and writes a header with a signature
+and some random information in it. The `reloc_address' field, which
+indicates at which address the file should be loaded if we want to avoid
+post-reload relocation, is set to 0. It then seeks to offset 256 (base
+offset for the objects).
+
+\1f
+File: internals.info, Node: Data dumping, Next: Pointers dumping, Prev: The header, Up: Dumping phase
+
+Data dumping
+------------
+
+ The data is dumped in the same order as the addresses were allocated
+by `pdump_dump_data()', called from `pdump_scan_by_alignment()'. This
+function copies the data to a temporary buffer, relocates all pointers
+in the object to the addresses allocated in step Address Allocation,
+and writes it to the file. Using the same order means that, if we are
+careful with lrecords whose size is not a multiple of 4, we are ensured
+that the object is always written at the offset in the file allocated
+in step Address Allocation.
+
+\1f
+File: internals.info, Node: Pointers dumping, Prev: Data dumping, Up: Dumping phase
+
+Pointers dumping
+----------------
+
+ A bunch of tables needed to reassign properly the global pointers are
+then written. They are:
+
+ 1. the pdump_root_struct_ptrs dynarr
+
+ 2. the pdump_opaques dynarr
+
+ 3. a vector of all the offsets to the objects in the file that
+ include a description (for faster relocation at reload time)
+
+ 4. the pdump_root_objects and pdump_weak_object_chains dynarrs.
+
+ For each of the dynarrs we write both the pointer to the variables
+and the relocated offset of the object they point to. Since these
+variables are global, the pointers are still valid when restarting the
+program and are used to regenerate the global pointers.
+
+ The `pdump_weak_object_chains' dynarr is a special case. The
+variables it points to are the head of weak linked lists of lisp objects
+of the same type. Not all objects of this list are dumped so the
+relocated pointer we associate with them points to the first dumped
+object of the list, or Qnil if none is available. This is also the
+reason why they are not used as roots for the purpose of object
+enumeration.
+
+ Some very important information like the `staticpros' and
+`lrecord_implementations_table' are handled indirectly using
+`dump_add_opaque' or `dump_add_root_struct_ptr'.
+
+ This is the end of the dumping part.
+
+\1f
+File: internals.info, Node: Reloading phase, Next: Remaining issues, Prev: Dumping phase, Up: Dumping
+
+Reloading phase
+===============
+
+File loading
+------------
+
+ The file is mmap'ed in memory (which ensures a PAGESIZE alignment, at
+least 4096), or if mmap is unavailable or fails, a 256-bytes aligned
+malloc is done and the file is loaded.
+
+ Some variables are reinitialized from the values found in the header.
+
+ The difference between the actual loading address and the
+reloc_address is computed and will be used for all the relocations.
+
+Putting back the pdump_opaques
+------------------------------
+
+ The memory contents are restored in the obvious and trivial way.
+
+Putting back the pdump_root_struct_ptrs
+---------------------------------------
+
+ The variables pointed to by pdump_root_struct_ptrs in the dump phase
+are reset to the right relocated object addresses.
+
+Object relocation
+-----------------
+
+ All the objects are relocated using their description and their
+offset by `pdump_reloc_one'. This step is unnecessary if the
+reloc_address is equal to the file loading address.
+
+Putting back the pdump_root_objects and pdump_weak_object_chains
+----------------------------------------------------------------
+
+ Same as Putting back the pdump_root_struct_ptrs.
+
+Reorganize the hash tables
+--------------------------
+
+ Since some of the hash values in the lisp hash tables are
+address-dependent, their layout is now wrong. So we go through each of
+them and have them resorted by calling `pdump_reorganize_hash_table'.
+
+\1f
+File: internals.info, Node: Remaining issues, Prev: Reloading phase, Up: Dumping
+
+Remaining issues
+================
+
+ The build process will have to start a post-dump xemacs, ask it the
+loading address (which will, hopefully, be always the same between
+different xemacs invocations) and relocate the file to the new address.
+This way the object relocation phase will not have to be done, which
+means no writes in the objects and that, because of the use of mmap, the
+dumped data will be shared between all the xemacs running on the
+computer.
+
+ Some executable signature will be necessary to ensure that a given
+dump file is really associated with a given executable, or random
+crashes will occur. Maybe a random number set at compile or configure
+time thru a define. This will also allow for having
+differently-compiled xemacsen on the same system (mule and no-mule
+comes to mind).
+
+ The DOC file contents should probably end up in the dump file.
+
+\1f
File: internals.info, Node: Events and the Event Loop, Next: Evaluation; Stack Frames; Bindings, Prev: Dumping, Up: Top
Events and the Event Loop
* Dispatching Events; The Command Builder::
\1f
-File: internals.info, Node: Introduction to Events, Next: Main Loop, Prev: Events and the Event Loop, Up: Events and the Event Loop
+File: internals.info, Node: Introduction to Events, Next: Main Loop, Up: Events and the Event Loop
Introduction to Events
======================
* Catch and Throw::
\1f
-File: internals.info, Node: Evaluation, Next: Dynamic Binding; The specbinding Stack; Unwind-Protects, Prev: Evaluation; Stack Frames; Bindings, Up: Evaluation; Stack Frames; Bindings
+File: internals.info, Node: Evaluation, Next: Dynamic Binding; The specbinding Stack; Unwind-Protects, Up: Evaluation; Stack Frames; Bindings
Evaluation
==========
* Symbol Values::
\1f
-File: internals.info, Node: Introduction to Symbols, Next: Obarrays, Prev: Symbols and Variables, Up: Symbols and Variables
+File: internals.info, Node: Introduction to Symbols, Next: Obarrays, Up: Symbols and Variables
Introduction to Symbols
=======================
additional values with particular names, and once again the namespace is
independent of the function and variable namespaces.
-\1f
-File: internals.info, Node: Obarrays, Next: Symbol Values, Prev: Introduction to Symbols, Up: Symbols and Variables
-
-Obarrays
-========
-
- The identity of symbols with their names is accomplished through a
-structure called an obarray, which is just a poorly-implemented hash
-table mapping from strings to symbols whose name is that string. (I say
-"poorly implemented" because an obarray appears in Lisp as a vector
-with some hidden fields rather than as its own opaque type. This is an
-Emacs Lisp artifact that should be fixed.)
-
- Obarrays are implemented as a vector of some fixed size (which should
-be a prime for best results), where each "bucket" of the vector
-contains one or more symbols, threaded through a hidden `next' field in
-the symbol. Lookup of a symbol in an obarray, and adding a symbol to
-an obarray, is accomplished through standard hash-table techniques.
-
- The standard Lisp function for working with symbols and obarrays is
-`intern'. This looks up a symbol in an obarray given its name; if it's
-not found, a new symbol is automatically created with the specified
-name, added to the obarray, and returned. This is what happens when the
-Lisp reader encounters a symbol (or more precisely, encounters the name
-of a symbol) in some text that it is reading. There is a standard
-obarray called `obarray' that is used for this purpose, although the
-Lisp programmer is free to create his own obarrays and `intern' symbols
-in them.
-
- Note that, once a symbol is in an obarray, it stays there until
-something is done about it, and the standard obarray `obarray' always
-stays around, so once you use any particular variable name, a
-corresponding symbol will stay around in `obarray' until you exit
-XEmacs.
-
- Note that `obarray' itself is a variable, and as such there is a
-symbol in `obarray' whose name is `"obarray"' and which contains
-`obarray' as its value.
-
- Note also that this call to `intern' occurs only when in the Lisp
-reader, not when the code is executed (at which point the symbol is
-already around, stored as such in the definition of the function).
-
- You can create your own obarray using `make-vector' (this is
-horrible but is an artifact) and intern symbols into that obarray.
-Doing that will result in two or more symbols with the same name.
-However, at most one of these symbols is in the standard `obarray': You
-cannot have two symbols of the same name in any particular obarray.
-Note that you cannot add a symbol to an obarray in any fashion other
-than using `intern': i.e. you can't take an existing symbol and put it
-in an existing obarray. Nor can you change the name of an existing
-symbol. (Since obarrays are vectors, you can violate the consistency of
-things by storing directly into the vector, but let's ignore that
-possibility.)
-
- Usually symbols are created by `intern', but if you really want, you
-can explicitly create a symbol using `make-symbol', giving it some
-name. The resulting symbol is not in any obarray (i.e. it is
-"uninterned"), and you can't add it to any obarray. Therefore its
-primary purpose is as a symbol to use in macros to avoid namespace
-pollution. It can also be used as a carrier of information, but cons
-cells could probably be used just as well.
-
- You can also use `intern-soft' to look up a symbol but not create a
-new one, and `unintern' to remove a symbol from an obarray. This
-returns the removed symbol. (Remember: You can't put the symbol back
-into any obarray.) Finally, `mapatoms' maps over all of the symbols in
-an obarray.
-
-\1f
-File: internals.info, Node: Symbol Values, Prev: Obarrays, Up: Symbols and Variables
-
-Symbol Values
-=============
-
- The value field of a symbol normally contains a Lisp object.
-However, a symbol can be "unbound", meaning that it logically has no
-value. This is internally indicated by storing a special Lisp object,
-called "the unbound marker" and stored in the global variable
-`Qunbound'. The unbound marker is of a special Lisp object type called
-"symbol-value-magic". It is impossible for the Lisp programmer to
-directly create or access any object of this type.
-
- *You must not let any "symbol-value-magic" object escape to the Lisp
-level.* Printing any of these objects will cause the message `INTERNAL
-EMACS BUG' to appear as part of the print representation. (You may see
-this normally when you call `debug_print()' from the debugger on a Lisp
-object.) If you let one of these objects escape to the Lisp level, you
-will violate a number of assumptions contained in the C code and make
-the unbound marker not function right.
-
- When a symbol is created, its value field (and function field) are
-set to `Qunbound'. The Lisp programmer can restore these conditions
-later using `makunbound' or `fmakunbound', and can query to see whether
-the value of function fields are "bound" (i.e. have a value other than
-`Qunbound') using `boundp' and `fboundp'. The fields are set to a
-normal Lisp object using `set' (or `setq') and `fset'.
-
- Other symbol-value-magic objects are used as special markers to
-indicate variables that have non-normal properties. This includes any
-variables that are tied into C variables (setting the variable magically
-sets some global variable in the C code, and likewise for retrieving the
-variable's value), variables that magically tie into slots in the
-current buffer, variables that are buffer-local, etc. The
-symbol-value-magic object is stored in the value cell in place of a
-normal object, and the code to retrieve a symbol's value (i.e.
-`symbol-value') knows how to do special things with them. This means
-that you should not just fetch the value cell directly if you want a
-symbol's value.
-
- The exact workings of this are rather complex and involved and are
-well-documented in comments in `buffer.c', `symbols.c', and `lisp.h'.
-
-\1f
-File: internals.info, Node: Buffers and Textual Representation, Next: MULE Character Sets and Encodings, Prev: Symbols and Variables, Up: Top
-
-Buffers and Textual Representation
-**********************************
-
-* Menu:
-
-* Introduction to Buffers:: A buffer holds a block of text such as a file.
-* The Text in a Buffer:: Representation of the text in a buffer.
-* Buffer Lists:: Keeping track of all buffers.
-* Markers and Extents:: Tagging locations within a buffer.
-* Bufbytes and Emchars:: Representation of individual characters.
-* The Buffer Object:: The Lisp object corresponding to a buffer.
-
-\1f
-File: internals.info, Node: Introduction to Buffers, Next: The Text in a Buffer, Prev: Buffers and Textual Representation, Up: Buffers and Textual Representation
-
-Introduction to Buffers
-=======================
-
- A buffer is logically just a Lisp object that holds some text. In
-this, it is like a string, but a buffer is optimized for frequent
-insertion and deletion, while a string is not. Furthermore:
-
- 1. Buffers are "permanent" objects, i.e. once you create them, they
- remain around, and need to be explicitly deleted before they go
- away.
-
- 2. Each buffer has a unique name, which is a string. Buffers are
- normally referred to by name. In this respect, they are like
- symbols.
-
- 3. Buffers have a default insertion position, called "point".
- Inserting text (unless you explicitly give a position) goes at
- point, and moves point forward past the text. This is what is
- going on when you type text into Emacs.
-
- 4. Buffers have lots of extra properties associated with them.
-
- 5. Buffers can be "displayed". What this means is that there exist a
- number of "windows", which are objects that correspond to some
- visible section of your display, and each window has an associated
- buffer, and the current contents of the buffer are shown in that
- section of the display. The redisplay mechanism (which takes care
- of doing this) knows how to look at the text of a buffer and come
- up with some reasonable way of displaying this. Many of the
- properties of a buffer control how the buffer's text is displayed.
-
- 6. One buffer is distinguished and called the "current buffer". It is
- stored in the variable `current_buffer'. Buffer operations operate
- on this buffer by default. When you are typing text into a
- buffer, the buffer you are typing into is always `current_buffer'.
- Switching to a different window changes the current buffer. Note
- that Lisp code can temporarily change the current buffer using
- `set-buffer' (often enclosed in a `save-excursion' so that the
- former current buffer gets restored when the code is finished).
- However, calling `set-buffer' will NOT cause a permanent change in
- the current buffer. The reason for this is that the top-level
- event loop sets `current_buffer' to the buffer of the selected
- window, each time it finishes executing a user command.
-
- Make sure you understand the distinction between "current buffer"
-and "buffer of the selected window", and the distinction between
-"point" of the current buffer and "window-point" of the selected
-window. (This latter distinction is explained in detail in the section
-on windows.)
-
Foundation instead of in the original English.
\1f
+File: internals.info, Node: Obarrays, Next: Symbol Values, Prev: Introduction to Symbols, Up: Symbols and Variables
+
+Obarrays
+========
+
+ The identity of symbols with their names is accomplished through a
+structure called an obarray, which is just a poorly-implemented hash
+table mapping from strings to symbols whose name is that string. (I say
+"poorly implemented" because an obarray appears in Lisp as a vector
+with some hidden fields rather than as its own opaque type. This is an
+Emacs Lisp artifact that should be fixed.)
+
+ Obarrays are implemented as a vector of some fixed size (which should
+be a prime for best results), where each "bucket" of the vector
+contains one or more symbols, threaded through a hidden `next' field in
+the symbol. Lookup of a symbol in an obarray, and adding a symbol to
+an obarray, is accomplished through standard hash-table techniques.
+
+ The standard Lisp function for working with symbols and obarrays is
+`intern'. This looks up a symbol in an obarray given its name; if it's
+not found, a new symbol is automatically created with the specified
+name, added to the obarray, and returned. This is what happens when the
+Lisp reader encounters a symbol (or more precisely, encounters the name
+of a symbol) in some text that it is reading. There is a standard
+obarray called `obarray' that is used for this purpose, although the
+Lisp programmer is free to create his own obarrays and `intern' symbols
+in them.
+
+ Note that, once a symbol is in an obarray, it stays there until
+something is done about it, and the standard obarray `obarray' always
+stays around, so once you use any particular variable name, a
+corresponding symbol will stay around in `obarray' until you exit
+XEmacs.
+
+ Note that `obarray' itself is a variable, and as such there is a
+symbol in `obarray' whose name is `"obarray"' and which contains
+`obarray' as its value.
+
+ Note also that this call to `intern' occurs only when in the Lisp
+reader, not when the code is executed (at which point the symbol is
+already around, stored as such in the definition of the function).
+
+ You can create your own obarray using `make-vector' (this is
+horrible but is an artifact) and intern symbols into that obarray.
+Doing that will result in two or more symbols with the same name.
+However, at most one of these symbols is in the standard `obarray': You
+cannot have two symbols of the same name in any particular obarray.
+Note that you cannot add a symbol to an obarray in any fashion other
+than using `intern': i.e. you can't take an existing symbol and put it
+in an existing obarray. Nor can you change the name of an existing
+symbol. (Since obarrays are vectors, you can violate the consistency of
+things by storing directly into the vector, but let's ignore that
+possibility.)
+
+ Usually symbols are created by `intern', but if you really want, you
+can explicitly create a symbol using `make-symbol', giving it some
+name. The resulting symbol is not in any obarray (i.e. it is
+"uninterned"), and you can't add it to any obarray. Therefore its
+primary purpose is as a symbol to use in macros to avoid namespace
+pollution. It can also be used as a carrier of information, but cons
+cells could probably be used just as well.
+
+ You can also use `intern-soft' to look up a symbol but not create a
+new one, and `unintern' to remove a symbol from an obarray. This
+returns the removed symbol. (Remember: You can't put the symbol back
+into any obarray.) Finally, `mapatoms' maps over all of the symbols in
+an obarray.
+
+\1f
+File: internals.info, Node: Symbol Values, Prev: Obarrays, Up: Symbols and Variables
+
+Symbol Values
+=============
+
+ The value field of a symbol normally contains a Lisp object.
+However, a symbol can be "unbound", meaning that it logically has no
+value. This is internally indicated by storing a special Lisp object,
+called "the unbound marker" and stored in the global variable
+`Qunbound'. The unbound marker is of a special Lisp object type called
+"symbol-value-magic". It is impossible for the Lisp programmer to
+directly create or access any object of this type.
+
+ *You must not let any "symbol-value-magic" object escape to the Lisp
+level.* Printing any of these objects will cause the message `INTERNAL
+EMACS BUG' to appear as part of the print representation. (You may see
+this normally when you call `debug_print()' from the debugger on a Lisp
+object.) If you let one of these objects escape to the Lisp level, you
+will violate a number of assumptions contained in the C code and make
+the unbound marker not function right.
+
+ When a symbol is created, its value field (and function field) are
+set to `Qunbound'. The Lisp programmer can restore these conditions
+later using `makunbound' or `fmakunbound', and can query to see whether
+the value of function fields are "bound" (i.e. have a value other than
+`Qunbound') using `boundp' and `fboundp'. The fields are set to a
+normal Lisp object using `set' (or `setq') and `fset'.
+
+ Other symbol-value-magic objects are used as special markers to
+indicate variables that have non-normal properties. This includes any
+variables that are tied into C variables (setting the variable magically
+sets some global variable in the C code, and likewise for retrieving the
+variable's value), variables that magically tie into slots in the
+current buffer, variables that are buffer-local, etc. The
+symbol-value-magic object is stored in the value cell in place of a
+normal object, and the code to retrieve a symbol's value (i.e.
+`symbol-value') knows how to do special things with them. This means
+that you should not just fetch the value cell directly if you want a
+symbol's value.
+
+ The exact workings of this are rather complex and involved and are
+well-documented in comments in `buffer.c', `symbols.c', and `lisp.h'.
+
+\1f
+File: internals.info, Node: Buffers and Textual Representation, Next: MULE Character Sets and Encodings, Prev: Symbols and Variables, Up: Top
+
+Buffers and Textual Representation
+**********************************
+
+* Menu:
+
+* Introduction to Buffers:: A buffer holds a block of text such as a file.
+* The Text in a Buffer:: Representation of the text in a buffer.
+* Buffer Lists:: Keeping track of all buffers.
+* Markers and Extents:: Tagging locations within a buffer.
+* Bufbytes and Emchars:: Representation of individual characters.
+* The Buffer Object:: The Lisp object corresponding to a buffer.
+
+\1f
+File: internals.info, Node: Introduction to Buffers, Next: The Text in a Buffer, Up: Buffers and Textual Representation
+
+Introduction to Buffers
+=======================
+
+ A buffer is logically just a Lisp object that holds some text. In
+this, it is like a string, but a buffer is optimized for frequent
+insertion and deletion, while a string is not. Furthermore:
+
+ 1. Buffers are "permanent" objects, i.e. once you create them, they
+ remain around, and need to be explicitly deleted before they go
+ away.
+
+ 2. Each buffer has a unique name, which is a string. Buffers are
+ normally referred to by name. In this respect, they are like
+ symbols.
+
+ 3. Buffers have a default insertion position, called "point".
+ Inserting text (unless you explicitly give a position) goes at
+ point, and moves point forward past the text. This is what is
+ going on when you type text into Emacs.
+
+ 4. Buffers have lots of extra properties associated with them.
+
+ 5. Buffers can be "displayed". What this means is that there exist a
+ number of "windows", which are objects that correspond to some
+ visible section of your display, and each window has an associated
+ buffer, and the current contents of the buffer are shown in that
+ section of the display. The redisplay mechanism (which takes care
+ of doing this) knows how to look at the text of a buffer and come
+ up with some reasonable way of displaying this. Many of the
+ properties of a buffer control how the buffer's text is displayed.
+
+ 6. One buffer is distinguished and called the "current buffer". It is
+ stored in the variable `current_buffer'. Buffer operations operate
+ on this buffer by default. When you are typing text into a
+ buffer, the buffer you are typing into is always `current_buffer'.
+ Switching to a different window changes the current buffer. Note
+ that Lisp code can temporarily change the current buffer using
+ `set-buffer' (often enclosed in a `save-excursion' so that the
+ former current buffer gets restored when the code is finished).
+ However, calling `set-buffer' will NOT cause a permanent change in
+ the current buffer. The reason for this is that the top-level
+ event loop sets `current_buffer' to the buffer of the selected
+ window, each time it finishes executing a user command.
+
+ Make sure you understand the distinction between "current buffer"
+and "buffer of the selected window", and the distinction between
+"point" of the current buffer and "window-point" of the selected
+window. (This latter distinction is explained in detail in the section
+on windows.)
+
+\1f
File: internals.info, Node: The Text in a Buffer, Next: Buffer Lists, Prev: Introduction to Buffers, Up: Buffers and Textual Representation
The Text in a Buffer
* CCL::
\1f
-File: internals.info, Node: Character Sets, Next: Encodings, Prev: MULE Character Sets and Encodings, Up: MULE Character Sets and Encodings
+File: internals.info, Node: Character Sets, Next: Encodings, Up: MULE Character Sets and Encodings
Character Sets
==============
* JIS7::
\1f
-File: internals.info, Node: Japanese EUC (Extended Unix Code), Next: JIS7, Prev: Encodings, Up: Encodings
+File: internals.info, Node: Japanese EUC (Extended Unix Code), Next: JIS7, Up: Encodings
Japanese EUC (Extended Unix Code)
---------------------------------
* Internal Character Encoding::
\1f
-File: internals.info, Node: Internal String Encoding, Next: Internal Character Encoding, Prev: Internal Mule Encodings, Up: Internal Mule Encodings
+File: internals.info, Node: Internal String Encoding, Next: Internal Character Encoding, Up: Internal Mule Encodings
Internal String Encoding
------------------------
* Lstream Methods:: Creating new lstream types.
\1f
-File: internals.info, Node: Creating an Lstream, Next: Lstream Types, Prev: Lstreams, Up: Lstreams
+File: internals.info, Node: Creating an Lstream, Next: Lstream Types, Up: Lstreams
Creating an Lstream
===================
decoding
encoding
-\1f
-File: internals.info, Node: Lstream Functions, Next: Lstream Methods, Prev: Lstream Types, Up: Lstreams
-
-Lstream Functions
-=================
-
- - Function: Lstream * Lstream_new (Lstream_implementation *IMP, const
- char *MODE)
- Allocate and return a new Lstream. This function is not really
- meant to be called directly; rather, each stream type should
- provide its own stream creation function, which creates the stream
- and does any other necessary creation stuff (e.g. opening a file).
-
- - Function: void Lstream_set_buffering (Lstream *LSTR,
- Lstream_buffering BUFFERING, int BUFFERING_SIZE)
- Change the buffering of a stream. See `lstream.h'. By default the
- buffering is `STREAM_BLOCK_BUFFERED'.
-
- - Function: int Lstream_flush (Lstream *LSTR)
- Flush out any pending unwritten data in the stream. Clear any
- buffered input data. Returns 0 on success, -1 on error.
-
- - Macro: int Lstream_putc (Lstream *STREAM, int C)
- Write out one byte to the stream. This is a macro and so it is
- very efficient. The C argument is only evaluated once but the
- STREAM argument is evaluated more than once. Returns 0 on
- success, -1 on error.
-
- - Macro: int Lstream_getc (Lstream *STREAM)
- Read one byte from the stream. This is a macro and so it is very
- efficient. The STREAM argument is evaluated more than once.
- Return value is -1 for EOF or error.
-
- - Macro: void Lstream_ungetc (Lstream *STREAM, int C)
- Push one byte back onto the input queue. This will be the next
- byte read from the stream. Any number of bytes can be pushed back
- and will be read in the reverse order they were pushed back--most
- recent first. (This is necessary for consistency--if there are a
- number of bytes that have been unread and I read and unread a
- byte, it needs to be the first to be read again.) This is a macro
- and so it is very efficient. The C argument is only evaluated
- once but the STREAM argument is evaluated more than once.
-
- - Function: int Lstream_fputc (Lstream *STREAM, int C)
- - Function: int Lstream_fgetc (Lstream *STREAM)
- - Function: void Lstream_fungetc (Lstream *STREAM, int C)
- Function equivalents of the above macros.
-
- - Function: ssize_t Lstream_read (Lstream *STREAM, void *DATA, size_t
- SIZE)
- Read SIZE bytes of DATA from the stream. Return the number of
- bytes read. 0 means EOF. -1 means an error occurred and no bytes
- were read.
-
- - Function: ssize_t Lstream_write (Lstream *STREAM, void *DATA, size_t
- SIZE)
- Write SIZE bytes of DATA to the stream. Return the number of
- bytes written. -1 means an error occurred and no bytes were
- written.
-
- - Function: void Lstream_unread (Lstream *STREAM, void *DATA, size_t
- SIZE)
- Push back SIZE bytes of DATA onto the input queue. The next call
- to `Lstream_read()' with the same size will read the same bytes
- back. Note that this will be the case even if there is other
- pending unread data.
-
- - Function: int Lstream_close (Lstream *STREAM)
- Close the stream. All data will be flushed out.
-
- - Function: void Lstream_reopen (Lstream *STREAM)
- Reopen a closed stream. This enables I/O on it again. This is not
- meant to be called except from a wrapper routine that reinitializes
- variables and such--the close routine may well have freed some
- necessary storage structures, for example.
-
- - Function: void Lstream_rewind (Lstream *STREAM)
- Rewind the stream to the beginning.
-
-\1f
-File: internals.info, Node: Lstream Methods, Prev: Lstream Functions, Up: Lstreams
-
-Lstream Methods
-===============
-
- - Lstream Method: ssize_t reader (Lstream *STREAM, unsigned char
- *DATA, size_t SIZE)
- Read some data from the stream's end and store it into DATA, which
- can hold SIZE bytes. Return the number of bytes read. A return
- value of 0 means no bytes can be read at this time. This may be
- because of an EOF, or because there is a granularity greater than
- one byte that the stream imposes on the returned data, and SIZE is
- less than this granularity. (This will happen frequently for
- streams that need to return whole characters, because
- `Lstream_read()' calls the reader function repeatedly until it has
- the number of bytes it wants or until 0 is returned.) The lstream
- functions do not treat a 0 return as EOF or do anything special;
- however, the calling function will interpret any 0 it gets back as
- EOF. This will normally not happen unless the caller calls
- `Lstream_read()' with a very small size.
-
- This function can be `NULL' if the stream is output-only.
-
- - Lstream Method: ssize_t writer (Lstream *STREAM, const unsigned char
- *DATA, size_t SIZE)
- Send some data to the stream's end. Data to be sent is in DATA
- and is SIZE bytes. Return the number of bytes sent. This
- function can send and return fewer bytes than is passed in; in that
- case, the function will just be called again until there is no
- data left or 0 is returned. A return value of 0 means that no
- more data can be currently stored, but there is no error; the data
- will be squirreled away until the writer can accept data. (This is
- useful, e.g., if you're dealing with a non-blocking file
- descriptor and are getting `EWOULDBLOCK' errors.) This function
- can be `NULL' if the stream is input-only.
-
- - Lstream Method: int rewinder (Lstream *STREAM)
- Rewind the stream. If this is `NULL', the stream is not seekable.
-
- - Lstream Method: int seekable_p (Lstream *STREAM)
- Indicate whether this stream is seekable--i.e. it can be rewound.
- This method is ignored if the stream does not have a rewind
- method. If this method is not present, the result is determined
- by whether a rewind method is present.
-
- - Lstream Method: int flusher (Lstream *STREAM)
- Perform any additional operations necessary to flush the data in
- this stream.
-
- - Lstream Method: int pseudo_closer (Lstream *STREAM)
-
- - Lstream Method: int closer (Lstream *STREAM)
- Perform any additional operations necessary to close this stream
- down. May be `NULL'. This function is called when
- `Lstream_close()' is called or when the stream is
- garbage-collected. When this function is called, all pending data
- in the stream will already have been written out.
-
- - Lstream Method: Lisp_Object marker (Lisp_Object LSTREAM, void
- (*MARKFUN) (Lisp_Object))
- Mark this object for garbage collection. Same semantics as a
- standard `Lisp_Object' marker. This function can be `NULL'.
-
-\1f
-File: internals.info, Node: Consoles; Devices; Frames; Windows, Next: The Redisplay Mechanism, Prev: Lstreams, Up: Top
-
-Consoles; Devices; Frames; Windows
-**********************************
-
-* Menu:
-
-* Introduction to Consoles; Devices; Frames; Windows::
-* Point::
-* Window Hierarchy::
-* The Window Object::
-
-\1f
-File: internals.info, Node: Introduction to Consoles; Devices; Frames; Windows, Next: Point, Prev: Consoles; Devices; Frames; Windows, Up: Consoles; Devices; Frames; Windows
-
-Introduction to Consoles; Devices; Frames; Windows
-==================================================
-
- A window-system window that you see on the screen is called a
-"frame" in Emacs terminology. Each frame is subdivided into one or
-more non-overlapping panes, called (confusingly) "windows". Each
-window displays the text of a buffer in it. (See above on Buffers.) Note
-that buffers and windows are independent entities: Two or more windows
-can be displaying the same buffer (potentially in different locations),
-and a buffer can be displayed in no windows.
-
- A single display screen that contains one or more frames is called a
-"display". Under most circumstances, there is only one display.
-However, more than one display can exist, for example if you have a
-"multi-headed" console, i.e. one with a single keyboard but multiple
-displays. (Typically in such a situation, the various displays act like
-one large display, in that the mouse is only in one of them at a time,
-and moving the mouse off of one moves it into another.) In some cases,
-the different displays will have different characteristics, e.g. one
-color and one mono.
-
- XEmacs can display frames on multiple displays. It can even deal
-simultaneously with frames on multiple keyboards (called "consoles" in
-XEmacs terminology). Here is one case where this might be useful: You
-are using XEmacs on your workstation at work, and leave it running.
-Then you go home and dial in on a TTY line, and you can use the
-already-running XEmacs process to display another frame on your local
-TTY.
-
- Thus, there is a hierarchy console -> display -> frame -> window.
-There is a separate Lisp object type for each of these four concepts.
-Furthermore, there is logically a "selected console", "selected
-display", "selected frame", and "selected window". Each of these
-objects is distinguished in various ways, such as being the default
-object for various functions that act on objects of that type. Note
-that every containing object remembers the "selected" object among the
-objects that it contains: e.g. not only is there a selected window, but
-every frame remembers the last window in it that was selected, and
-changing the selected frame causes the remembered window within it to
-become the selected window. Similar relationships apply for consoles
-to devices and devices to frames.
-
-\1f
-File: internals.info, Node: Point, Next: Window Hierarchy, Prev: Introduction to Consoles; Devices; Frames; Windows, Up: Consoles; Devices; Frames; Windows
-
-Point
-=====
-
- Recall that every buffer has a current insertion position, called
-"point". Now, two or more windows may be displaying the same buffer,
-and the text cursor in the two windows (i.e. `point') can be in two
-different places. You may ask, how can that be, since each buffer has
-only one value of `point'? The answer is that each window also has a
-value of `point' that is squirreled away in it. There is only one
-selected window, and the value of "point" in that buffer corresponds to
-that window. When the selected window is changed from one window to
-another displaying the same buffer, the old value of `point' is stored
-into the old window's "point" and the value of `point' from the new
-window is retrieved and made the value of `point' in the buffer. This
-means that `window-point' for the selected window is potentially
-inaccurate, and if you want to retrieve the correct value of `point'
-for a window, you must special-case on the selected window and retrieve
-the buffer's point instead. This is related to why
-`save-window-excursion' does not save the selected window's value of
-`point'.
-
Foundation instead of in the original English.
\1f
+File: internals.info, Node: Lstream Functions, Next: Lstream Methods, Prev: Lstream Types, Up: Lstreams
+
+Lstream Functions
+=================
+
+ - Function: Lstream * Lstream_new (Lstream_implementation *IMP, const
+ char *MODE)
+ Allocate and return a new Lstream. This function is not really
+ meant to be called directly; rather, each stream type should
+ provide its own stream creation function, which creates the stream
+ and does any other necessary creation stuff (e.g. opening a file).
+
+ - Function: void Lstream_set_buffering (Lstream *LSTR,
+ Lstream_buffering BUFFERING, int BUFFERING_SIZE)
+ Change the buffering of a stream. See `lstream.h'. By default the
+ buffering is `STREAM_BLOCK_BUFFERED'.
+
+ - Function: int Lstream_flush (Lstream *LSTR)
+ Flush out any pending unwritten data in the stream. Clear any
+ buffered input data. Returns 0 on success, -1 on error.
+
+ - Macro: int Lstream_putc (Lstream *STREAM, int C)
+ Write out one byte to the stream. This is a macro and so it is
+ very efficient. The C argument is only evaluated once but the
+ STREAM argument is evaluated more than once. Returns 0 on
+ success, -1 on error.
+
+ - Macro: int Lstream_getc (Lstream *STREAM)
+ Read one byte from the stream. This is a macro and so it is very
+ efficient. The STREAM argument is evaluated more than once.
+ Return value is -1 for EOF or error.
+
+ - Macro: void Lstream_ungetc (Lstream *STREAM, int C)
+ Push one byte back onto the input queue. This will be the next
+ byte read from the stream. Any number of bytes can be pushed back
+ and will be read in the reverse order they were pushed back--most
+ recent first. (This is necessary for consistency--if there are a
+ number of bytes that have been unread and I read and unread a
+ byte, it needs to be the first to be read again.) This is a macro
+ and so it is very efficient. The C argument is only evaluated
+ once but the STREAM argument is evaluated more than once.
+
+ - Function: int Lstream_fputc (Lstream *STREAM, int C)
+ - Function: int Lstream_fgetc (Lstream *STREAM)
+ - Function: void Lstream_fungetc (Lstream *STREAM, int C)
+ Function equivalents of the above macros.
+
+ - Function: ssize_t Lstream_read (Lstream *STREAM, void *DATA, size_t
+ SIZE)
+ Read SIZE bytes of DATA from the stream. Return the number of
+ bytes read. 0 means EOF. -1 means an error occurred and no bytes
+ were read.
+
+ - Function: ssize_t Lstream_write (Lstream *STREAM, void *DATA, size_t
+ SIZE)
+ Write SIZE bytes of DATA to the stream. Return the number of
+ bytes written. -1 means an error occurred and no bytes were
+ written.
+
+ - Function: void Lstream_unread (Lstream *STREAM, void *DATA, size_t
+ SIZE)
+ Push back SIZE bytes of DATA onto the input queue. The next call
+ to `Lstream_read()' with the same size will read the same bytes
+ back. Note that this will be the case even if there is other
+ pending unread data.
+
+ - Function: int Lstream_close (Lstream *STREAM)
+ Close the stream. All data will be flushed out.
+
+ - Function: void Lstream_reopen (Lstream *STREAM)
+ Reopen a closed stream. This enables I/O on it again. This is not
+ meant to be called except from a wrapper routine that reinitializes
+ variables and such--the close routine may well have freed some
+ necessary storage structures, for example.
+
+ - Function: void Lstream_rewind (Lstream *STREAM)
+ Rewind the stream to the beginning.
+
+\1f
+File: internals.info, Node: Lstream Methods, Prev: Lstream Functions, Up: Lstreams
+
+Lstream Methods
+===============
+
+ - Lstream Method: ssize_t reader (Lstream *STREAM, unsigned char
+ *DATA, size_t SIZE)
+ Read some data from the stream's end and store it into DATA, which
+ can hold SIZE bytes. Return the number of bytes read. A return
+ value of 0 means no bytes can be read at this time. This may be
+ because of an EOF, or because there is a granularity greater than
+ one byte that the stream imposes on the returned data, and SIZE is
+ less than this granularity. (This will happen frequently for
+ streams that need to return whole characters, because
+ `Lstream_read()' calls the reader function repeatedly until it has
+ the number of bytes it wants or until 0 is returned.) The lstream
+ functions do not treat a 0 return as EOF or do anything special;
+ however, the calling function will interpret any 0 it gets back as
+ EOF. This will normally not happen unless the caller calls
+ `Lstream_read()' with a very small size.
+
+ This function can be `NULL' if the stream is output-only.
+
+ - Lstream Method: ssize_t writer (Lstream *STREAM, const unsigned char
+ *DATA, size_t SIZE)
+ Send some data to the stream's end. Data to be sent is in DATA
+ and is SIZE bytes. Return the number of bytes sent. This
+ function can send and return fewer bytes than is passed in; in that
+ case, the function will just be called again until there is no
+ data left or 0 is returned. A return value of 0 means that no
+ more data can be currently stored, but there is no error; the data
+ will be squirreled away until the writer can accept data. (This is
+ useful, e.g., if you're dealing with a non-blocking file
+ descriptor and are getting `EWOULDBLOCK' errors.) This function
+ can be `NULL' if the stream is input-only.
+
+ - Lstream Method: int rewinder (Lstream *STREAM)
+ Rewind the stream. If this is `NULL', the stream is not seekable.
+
+ - Lstream Method: int seekable_p (Lstream *STREAM)
+ Indicate whether this stream is seekable--i.e. it can be rewound.
+ This method is ignored if the stream does not have a rewind
+ method. If this method is not present, the result is determined
+ by whether a rewind method is present.
+
+ - Lstream Method: int flusher (Lstream *STREAM)
+ Perform any additional operations necessary to flush the data in
+ this stream.
+
+ - Lstream Method: int pseudo_closer (Lstream *STREAM)
+
+ - Lstream Method: int closer (Lstream *STREAM)
+ Perform any additional operations necessary to close this stream
+ down. May be `NULL'. This function is called when
+ `Lstream_close()' is called or when the stream is
+ garbage-collected. When this function is called, all pending data
+ in the stream will already have been written out.
+
+ - Lstream Method: Lisp_Object marker (Lisp_Object LSTREAM, void
+ (*MARKFUN) (Lisp_Object))
+ Mark this object for garbage collection. Same semantics as a
+ standard `Lisp_Object' marker. This function can be `NULL'.
+
+\1f
+File: internals.info, Node: Consoles; Devices; Frames; Windows, Next: The Redisplay Mechanism, Prev: Lstreams, Up: Top
+
+Consoles; Devices; Frames; Windows
+**********************************
+
+* Menu:
+
+* Introduction to Consoles; Devices; Frames; Windows::
+* Point::
+* Window Hierarchy::
+* The Window Object::
+
+\1f
+File: internals.info, Node: Introduction to Consoles; Devices; Frames; Windows, Next: Point, Up: Consoles; Devices; Frames; Windows
+
+Introduction to Consoles; Devices; Frames; Windows
+==================================================
+
+ A window-system window that you see on the screen is called a
+"frame" in Emacs terminology. Each frame is subdivided into one or
+more non-overlapping panes, called (confusingly) "windows". Each
+window displays the text of a buffer in it. (See above on Buffers.) Note
+that buffers and windows are independent entities: Two or more windows
+can be displaying the same buffer (potentially in different locations),
+and a buffer can be displayed in no windows.
+
+ A single display screen that contains one or more frames is called a
+"display". Under most circumstances, there is only one display.
+However, more than one display can exist, for example if you have a
+"multi-headed" console, i.e. one with a single keyboard but multiple
+displays. (Typically in such a situation, the various displays act like
+one large display, in that the mouse is only in one of them at a time,
+and moving the mouse off of one moves it into another.) In some cases,
+the different displays will have different characteristics, e.g. one
+color and one mono.
+
+ XEmacs can display frames on multiple displays. It can even deal
+simultaneously with frames on multiple keyboards (called "consoles" in
+XEmacs terminology). Here is one case where this might be useful: You
+are using XEmacs on your workstation at work, and leave it running.
+Then you go home and dial in on a TTY line, and you can use the
+already-running XEmacs process to display another frame on your local
+TTY.
+
+ Thus, there is a hierarchy console -> display -> frame -> window.
+There is a separate Lisp object type for each of these four concepts.
+Furthermore, there is logically a "selected console", "selected
+display", "selected frame", and "selected window". Each of these
+objects is distinguished in various ways, such as being the default
+object for various functions that act on objects of that type. Note
+that every containing object remembers the "selected" object among the
+objects that it contains: e.g. not only is there a selected window, but
+every frame remembers the last window in it that was selected, and
+changing the selected frame causes the remembered window within it to
+become the selected window. Similar relationships apply for consoles
+to devices and devices to frames.
+
+\1f
+File: internals.info, Node: Point, Next: Window Hierarchy, Prev: Introduction to Consoles; Devices; Frames; Windows, Up: Consoles; Devices; Frames; Windows
+
+Point
+=====
+
+ Recall that every buffer has a current insertion position, called
+"point". Now, two or more windows may be displaying the same buffer,
+and the text cursor in the two windows (i.e. `point') can be in two
+different places. You may ask, how can that be, since each buffer has
+only one value of `point'? The answer is that each window also has a
+value of `point' that is squirreled away in it. There is only one
+selected window, and the value of "point" in that buffer corresponds to
+that window. When the selected window is changed from one window to
+another displaying the same buffer, the old value of `point' is stored
+into the old window's "point" and the value of `point' from the new
+window is retrieved and made the value of `point' in the buffer. This
+means that `window-point' for the selected window is potentially
+inaccurate, and if you want to retrieve the correct value of `point'
+for a window, you must special-case on the selected window and retrieve
+the buffer's point instead. This is related to why
+`save-window-excursion' does not save the selected window's value of
+`point'.
+
+\1f
File: internals.info, Node: Window Hierarchy, Next: The Window Object, Prev: Point, Up: Consoles; Devices; Frames; Windows
Window Hierarchy
* Redisplay Piece by Piece::
\1f
-File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Prev: The Redisplay Mechanism, Up: The Redisplay Mechanism
+File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Up: The Redisplay Mechanism
Critical Redisplay Sections
===========================
* Extent Fragments:: Cached information useful for redisplay.
\1f
-File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Prev: Extents, Up: Extents
+File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Up: Extents
Introduction to Extents
=======================
* Lucid Widget Library:: An interface to various widget sets.
-\1f
-File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System
-
-Lucid Widget Library
-====================
-
- Lwlib is extremely poorly documented and quite hairy. The author(s)
-blame that on X, Xt, and Motif, with some justice, but also sufficient
-hypocrisy to avoid drawing the obvious conclusion about their own work.
-
- The Lucid Widget Library is composed of two more or less independent
-pieces. The first, as the name suggests, is a set of widgets. These
-widgets are intended to resemble and improve on widgets provided in the
-Motif toolkit but not in the Athena widgets, including menubars and
-scrollbars. Recent additions by Andy Piper integrate some "modern"
-widgets by Edward Falk, including checkboxes, radio buttons, progress
-gauges, and index tab controls (aka notebooks).
-
- The second piece of the Lucid widget library is a generic interface
-to several toolkits for X (including Xt, the Athena widget set, and
-Motif, as well as the Lucid widgets themselves) so that core XEmacs
-code need not know which widget set has been used to build the
-graphical user interface.
-
-* Menu:
-
-* Generic Widget Interface:: The lwlib generic widget interface.
-* Scrollbars::
-* Menubars::
-* Checkboxes and Radio Buttons::
-* Progress Bars::
-* Tab Controls::
-
-\1f
-File: internals.info, Node: Generic Widget Interface, Next: Scrollbars, Up: Lucid Widget Library
-
-Generic Widget Interface
-------------------------
-
- In general in any toolkit a widget may be a composite object. In Xt,
-all widgets have an X window that they manage, but typically a complex
-widget will have widget children, each of which manages a subwindow of
-the parent widget's X window. These children may themselves be
-composite widgets. Thus a widget is actually a tree or hierarchy of
-widgets.
-
- For each toolkit widget, lwlib maintains a tree of `widget_values'
-which mirror the hierarchical state of Xt widgets (including Motif,
-Athena, 3D Athena, and Falk's widget sets). Each `widget_value' has
-`contents' member, which points to the head of a linked list of its
-children. The linked list of siblings is chained through the `next'
-member of `widget_value'.
-
- +-----------+
- | composite |
- +-----------+
- |
- | contents
- V
- +-------+ next +-------+ next +-------+
- | child |----->| child |----->| child |
- +-------+ +-------+ +-------+
- |
- | contents
- V
- +-------------+ next +-------------+
- | grand child |----->| grand child |
- +-------------+ +-------------+
-
- The `widget_value' hierarchy of a composite widget with two simple
- children and one composite child.
-
- The `widget_instance' structure maintains the inverse view of the
-tree. As for the `widget_value', siblings are chained through the
-`next' member. However, rather than naming children, the
-`widget_instance' tree links to parents.
-
- +-----------+
- | composite |
- +-----------+
- A
- | parent
- |
- +-------+ next +-------+ next +-------+
- | child |----->| child |----->| child |
- +-------+ +-------+ +-------+
- A
- | parent
- |
- +-------------+ next +-------------+
- | grand child |----->| grand child |
- +-------------+ +-------------+
-
- The `widget_value' hierarchy of a composite widget with two simple
- children and one composite child.
-
- This permits widgets derived from different toolkits to be updated
-and manipulated generically by the lwlib library. For instance
-`update_one_widget_instance' can cope with multiple types of widget and
-multiple types of toolkit. Each element in the widget hierarchy is
-updated from its corresponding `widget_value' by walking the
-`widget_value' tree. This has desirable properties. For example,
-`lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the
-properties of a widget without having to know what the widget is or
-what toolkit it is from. Unfortunately this also has its hairy
-properties; the lwlib code quite complex. And of course lwlib has to
-know at some level what the widget is and how to set its properties.
-
- The `widget_instance' structure also contains a pointer to the root
-of its tree. Widget instances are further confi
-
-\1f
-File: internals.info, Node: Scrollbars, Next: Menubars, Prev: Generic Widget Interface, Up: Lucid Widget Library
-
-Scrollbars
-----------
-
-\1f
-File: internals.info, Node: Menubars, Next: Checkboxes and Radio Buttons, Prev: Scrollbars, Up: Lucid Widget Library
-
-Menubars
---------
-
-\1f
-File: internals.info, Node: Checkboxes and Radio Buttons, Next: Progress Bars, Prev: Menubars, Up: Lucid Widget Library
-
-Checkboxes and Radio Buttons
-----------------------------
-
-\1f
-File: internals.info, Node: Progress Bars, Next: Tab Controls, Prev: Checkboxes and Radio Buttons, Up: Lucid Widget Library
-
-Progress Bars
--------------
-
-\1f
-File: internals.info, Node: Tab Controls, Prev: Progress Bars, Up: Lucid Widget Library
-
-Tab Controls
-------------
-
Foundation instead of in the original English.
\1f
+File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System
+
+Lucid Widget Library
+====================
+
+ Lwlib is extremely poorly documented and quite hairy. The author(s)
+blame that on X, Xt, and Motif, with some justice, but also sufficient
+hypocrisy to avoid drawing the obvious conclusion about their own work.
+
+ The Lucid Widget Library is composed of two more or less independent
+pieces. The first, as the name suggests, is a set of widgets. These
+widgets are intended to resemble and improve on widgets provided in the
+Motif toolkit but not in the Athena widgets, including menubars and
+scrollbars. Recent additions by Andy Piper integrate some "modern"
+widgets by Edward Falk, including checkboxes, radio buttons, progress
+gauges, and index tab controls (aka notebooks).
+
+ The second piece of the Lucid widget library is a generic interface
+to several toolkits for X (including Xt, the Athena widget set, and
+Motif, as well as the Lucid widgets themselves) so that core XEmacs
+code need not know which widget set has been used to build the
+graphical user interface.
+
+* Menu:
+
+* Generic Widget Interface:: The lwlib generic widget interface.
+* Scrollbars::
+* Menubars::
+* Checkboxes and Radio Buttons::
+* Progress Bars::
+* Tab Controls::
+
+\1f
+File: internals.info, Node: Generic Widget Interface, Next: Scrollbars, Up: Lucid Widget Library
+
+Generic Widget Interface
+------------------------
+
+ In general in any toolkit a widget may be a composite object. In Xt,
+all widgets have an X window that they manage, but typically a complex
+widget will have widget children, each of which manages a subwindow of
+the parent widget's X window. These children may themselves be
+composite widgets. Thus a widget is actually a tree or hierarchy of
+widgets.
+
+ For each toolkit widget, lwlib maintains a tree of `widget_values'
+which mirror the hierarchical state of Xt widgets (including Motif,
+Athena, 3D Athena, and Falk's widget sets). Each `widget_value' has
+`contents' member, which points to the head of a linked list of its
+children. The linked list of siblings is chained through the `next'
+member of `widget_value'.
+
+ +-----------+
+ | composite |
+ +-----------+
+ |
+ | contents
+ V
+ +-------+ next +-------+ next +-------+
+ | child |----->| child |----->| child |
+ +-------+ +-------+ +-------+
+ |
+ | contents
+ V
+ +-------------+ next +-------------+
+ | grand child |----->| grand child |
+ +-------------+ +-------------+
+
+ The `widget_value' hierarchy of a composite widget with two simple
+ children and one composite child.
+
+ The `widget_instance' structure maintains the inverse view of the
+tree. As for the `widget_value', siblings are chained through the
+`next' member. However, rather than naming children, the
+`widget_instance' tree links to parents.
+
+ +-----------+
+ | composite |
+ +-----------+
+ A
+ | parent
+ |
+ +-------+ next +-------+ next +-------+
+ | child |----->| child |----->| child |
+ +-------+ +-------+ +-------+
+ A
+ | parent
+ |
+ +-------------+ next +-------------+
+ | grand child |----->| grand child |
+ +-------------+ +-------------+
+
+ The `widget_value' hierarchy of a composite widget with two simple
+ children and one composite child.
+
+ This permits widgets derived from different toolkits to be updated
+and manipulated generically by the lwlib library. For instance
+`update_one_widget_instance' can cope with multiple types of widget and
+multiple types of toolkit. Each element in the widget hierarchy is
+updated from its corresponding `widget_value' by walking the
+`widget_value' tree. This has desirable properties. For example,
+`lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the
+properties of a widget without having to know what the widget is or
+what toolkit it is from. Unfortunately this also has its hairy
+properties; the lwlib code quite complex. And of course lwlib has to
+know at some level what the widget is and how to set its properties.
+
+ The `widget_instance' structure also contains a pointer to the root
+of its tree. Widget instances are further confi
+
+\1f
+File: internals.info, Node: Scrollbars, Next: Menubars, Prev: Generic Widget Interface, Up: Lucid Widget Library
+
+Scrollbars
+----------
+
+\1f
+File: internals.info, Node: Menubars, Next: Checkboxes and Radio Buttons, Prev: Scrollbars, Up: Lucid Widget Library
+
+Menubars
+--------
+
+\1f
+File: internals.info, Node: Checkboxes and Radio Buttons, Next: Progress Bars, Prev: Menubars, Up: Lucid Widget Library
+
+Checkboxes and Radio Buttons
+----------------------------
+
+\1f
+File: internals.info, Node: Progress Bars, Next: Tab Controls, Prev: Checkboxes and Radio Buttons, Up: Lucid Widget Library
+
+Progress Bars
+-------------
+
+\1f
+File: internals.info, Node: Tab Controls, Prev: Progress Bars, Up: Lucid Widget Library
+
+Tab Controls
+------------
+
+\1f
File: internals.info, Node: Index, Prev: Interface to the X Window System, Up: Top
Index
* Menu:
+* allocation from frob blocks: Allocation from Frob Blocks.
+* allocation of objects in XEmacs Lisp: Allocation of Objects in XEmacs Lisp.
+* allocation, introduction to: Introduction to Allocation.
+* allocation, low-level: Low-level allocation.
* Amdahl Corporation: XEmacs.
* Andreessen, Marc: XEmacs.
* asynchronous subprocesses: Modules for Interfacing with the Operating System.
+* bars, progress: Progress Bars.
* Baur, Steve: XEmacs.
* Benson, Eric: Lucid Emacs.
+* binding; the specbinding stack; unwind-protects, dynamic: Dynamic Binding; The specbinding Stack; Unwind-Protects.
+* bindings, evaluation; stack frames;: Evaluation; Stack Frames; Bindings.
+* bit vector: Bit Vector.
* bridge, playing: XEmacs From the Outside.
* Buchholz, Martin: XEmacs.
* Bufbyte: Character-Related Data Types.
+* Bufbytes and Emchars: Bufbytes and Emchars.
+* buffer lists: Buffer Lists.
+* buffer object, the: The Buffer Object.
+* buffer, the text in a: The Text in a Buffer.
+* buffers and textual representation: Buffers and Textual Representation.
+* buffers, introduction to: Introduction to Buffers.
* Bufpos: Character-Related Data Types.
+* building, XEmacs from the perspective of: XEmacs From the Perspective of Building.
+* buttons, checkboxes and radio: Checkboxes and Radio Buttons.
+* byte positions, working with character and: Working With Character and Byte Positions.
* Bytecount: Character-Related Data Types.
* bytecount_to_charcount: Working With Character and Byte Positions.
* Bytind: Character-Related Data Types.
+* C code, rules when writing new: Rules When Writing New C Code.
* C vs. Lisp: The Lisp Language.
+* callback routines, the event stream: The Event Stream Callback Routines.
* caller-protects (GCPRO rule): Writing Lisp Primitives.
* case table: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* catch and throw: Catch and Throw.
+* CCL: CCL.
+* character and byte positions, working with: Working With Character and Byte Positions.
+* character encoding, internal: Internal Character Encoding.
+* character sets: Character Sets.
+* character sets and encodings, Mule: MULE Character Sets and Encodings.
+* character-related data types: Character-Related Data Types.
+* characters, integers and: Integers and Characters.
* Charcount: Character-Related Data Types.
* charcount_to_bytecount: Working With Character and Byte Positions.
* charptr_emchar: Working With Character and Byte Positions.
* charptr_n_addr: Working With Character and Byte Positions.
+* checkboxes and radio buttons: Checkboxes and Radio Buttons.
* closer: Lstream Methods.
* closure: The XEmacs Object System (Abstractly Speaking).
-* Coding for Mule: Coding for Mule.
+* code, an example of Mule-aware: An Example of Mule-Aware Code.
+* code, general guidelines for writing Mule-aware: General Guidelines for Writing Mule-Aware Code.
+* code, rules when writing new C: Rules When Writing New C Code.
+* coding for Mule: Coding for Mule.
+* coding rules, general: General Coding Rules.
+* command builder, dispatching events; the: Dispatching Events; The Command Builder.
+* comments, writing good: Writing Good Comments.
* Common Lisp: The Lisp Language.
* compact_string_chars: compact_string_chars.
+* compiled function: Compiled Function.
+* compiler, the Lisp reader and: The Lisp Reader and Compiler.
+* cons: Cons.
* conservative garbage collection: GCPROing.
+* consoles; devices; frames; windows: Consoles; Devices; Frames; Windows.
+* consoles; devices; frames; windows, introduction to: Introduction to Consoles; Devices; Frames; Windows.
+* control flow modules, editor-level: Editor-Level Control Flow Modules.
+* conversion to and from external data: Conversion to and from External Data.
+* converting events: Converting Events.
* copy-on-write: General Coding Rules.
+* creating Lisp object types: Techniques for XEmacs Developers.
* critical redisplay sections: Critical Redisplay Sections.
+* data dumping: Data dumping.
+* data types, character-related: Character-Related Data Types.
* DEC_CHARPTR: Working With Character and Byte Positions.
+* developers, techniques for XEmacs: Techniques for XEmacs Developers.
+* devices; frames; windows, consoles;: Consoles; Devices; Frames; Windows.
+* devices; frames; windows, introduction to consoles;: Introduction to Consoles; Devices; Frames; Windows.
* Devin, Matthieu: Lucid Emacs.
+* dispatching events; the command builder: Dispatching Events; The Command Builder.
* display order of extents: Mathematics of Extent Ordering.
+* display-related Lisp objects, modules for other: Modules for other Display-Related Lisp Objects.
+* displayable Lisp objects, modules for the basic: Modules for the Basic Displayable Lisp Objects.
+* dumping: Dumping.
+* dumping address allocation: Address allocation.
+* dumping and its justification, what is: Dumping.
+* dumping data descriptions: Data descriptions.
+* dumping object inventory: Object inventory.
+* dumping overview: Overview.
+* dumping phase: Dumping phase.
+* dumping, data: Data dumping.
+* dumping, file loading: Reloading phase.
+* dumping, object relocation: Reloading phase.
+* dumping, pointers: Pointers dumping.
+* dumping, putting back the pdump_opaques: Reloading phase.
+* dumping, putting back the pdump_root_objects and pdump_weak_object_chains: Reloading phase.
+* dumping, putting back the pdump_root_struct_ptrs: Reloading phase.
+* dumping, reloading phase: Reloading phase.
+* dumping, remaining issues: Remaining issues.
+* dumping, reorganize the hash tables: Reloading phase.
+* dumping, the header: The header.
* dynamic array: Low-Level Modules.
+* dynamic binding; the specbinding stack; unwind-protects: Dynamic Binding; The specbinding Stack; Unwind-Protects.
* dynamic scoping: The Lisp Language.
* dynamic types: The Lisp Language.
+* editing operations, modules for standard: Modules for Standard Editing Operations.
+* Emacs 19, GNU: GNU Emacs 19.
+* Emacs 20, GNU: GNU Emacs 20.
+* Emacs, a history of: A History of Emacs.
* Emchar: Character-Related Data Types.
+* Emchars, Bufbytes and: Bufbytes and Emchars.
+* encoding, internal character: Internal Character Encoding.
+* encoding, internal string: Internal String Encoding.
+* encodings, internal Mule: Internal Mule Encodings.
+* encodings, Mule: Encodings.
+* encodings, Mule character sets and: MULE Character Sets and Encodings.
* Energize: Lucid Emacs.
* Epoch <1>: XEmacs.
* Epoch: Lucid Emacs.
+* error checking: Techniques for XEmacs Developers.
+* EUC (Extended Unix Code), Japanese: Japanese EUC (Extended Unix Code).
+* evaluation: Evaluation.
+* evaluation; stack frames; bindings: Evaluation; Stack Frames; Bindings.
+* event gathering mechanism, specifics of the: Specifics of the Event Gathering Mechanism.
+* event loop functions, other: Other Event Loop Functions.
+* event loop, events and the: Events and the Event Loop.
+* event stream callback routines, the: The Event Stream Callback Routines.
+* event, specifics about the Lisp object: Specifics About the Emacs Event.
+* events and the event loop: Events and the Event Loop.
+* events, converting: Converting Events.
+* events, introduction to: Introduction to Events.
+* events, main loop: Main Loop.
+* events; the command builder, dispatching: Dispatching Events; The Command Builder.
* Extbyte: Character-Related Data Types.
* Extcount: Character-Related Data Types.
-* extent fragment: Extent Fragments.
+* Extended Unix Code, Japanese EUC: Japanese EUC (Extended Unix Code).
+* extent fragments: Extent Fragments.
+* extent info, format of the: Format of the Extent Info.
* extent mathematics: Mathematics of Extent Ordering.
-* extent ordering: Mathematics of Extent Ordering.
+* extent ordering <1>: Mathematics of Extent Ordering.
+* extent ordering: Extent Ordering.
+* extents: Extents.
* extents, display order: Mathematics of Extent Ordering.
+* extents, introduction to: Introduction to Extents.
+* extents, markers and: Markers and Extents.
+* extents, zero-length: Zero-Length Extents.
+* external data, conversion to and from: Conversion to and from External Data.
* external widget: Modules for Interfacing with X Windows.
+* faces: Faces.
+* file system, modules for interfacing with the: Modules for Interfacing with the File System.
* flusher: Lstream Methods.
+* fragments, extent: Extent Fragments.
+* frames; windows, consoles; devices;: Consoles; Devices; Frames; Windows.
+* frames; windows, introduction to consoles; devices;: Introduction to Consoles; Devices; Frames; Windows.
* Free Software Foundation: A History of Emacs.
+* frob blocks, allocation from: Allocation from Frob Blocks.
* FSF: A History of Emacs.
* FSF Emacs <1>: GNU Emacs 20.
* FSF Emacs: GNU Emacs 19.
+* function, compiled: Compiled Function.
* garbage collection: Garbage Collection.
+* garbage collection - step by step: Garbage Collection - Step by Step.
+* garbage collection protection <1>: GCPROing.
* garbage collection protection: Writing Lisp Primitives.
-* garbage collection step by step: Garbage Collection - Step by Step.
* garbage collection, conservative: GCPROing.
* garbage collection, invocation: Invocation.
* garbage_collect_1: garbage_collect_1.
* gc_sweep: gc_sweep.
+* GCPROing: GCPROing.
+* global Lisp variables, adding: Adding Global Lisp Variables.
+* glyph instantiation: Glyphs.
+* glyphs: Glyphs.
* GNU Emacs 19: GNU Emacs 19.
* GNU Emacs 20: GNU Emacs 20.
* Gosling, James <1>: The Lisp Language.
* Gosling, James: Through Version 18.
* Great Usenet Renaming: Through Version 18.
* Hackers (Steven Levy): A History of Emacs.
+* header files, inline functions: Techniques for XEmacs Developers.
* hierarchy of windows: Window Hierarchy.
-* history of Emacs: A History of Emacs.
+* history of Emacs, a: A History of Emacs.
* Illinois, University of: XEmacs.
* INC_CHARPTR: Working With Character and Byte Positions.
+* inline functions: Techniques for XEmacs Developers.
+* inline functions, headers: Techniques for XEmacs Developers.
+* inside, XEmacs from the: XEmacs From the Inside.
+* instantiation, glyph: Glyphs.
+* integers and characters: Integers and Characters.
* interactive: Modules for Standard Editing Operations.
+* interfacing with the file system, modules for: Modules for Interfacing with the File System.
+* interfacing with the operating system, modules for: Modules for Interfacing with the Operating System.
+* interfacing with X Windows, modules for: Modules for Interfacing with X Windows.
+* internal character encoding: Internal Character Encoding.
+* internal Mule encodings: Internal Mule Encodings.
+* internal string encoding: Internal String Encoding.
+* internationalization, modules for: Modules for Internationalization.
* interning: The XEmacs Object System (Abstractly Speaking).
+* interpreter and object system, modules for other aspects of the Lisp: Modules for Other Aspects of the Lisp Interpreter and Object System.
* ITS (Incompatible Timesharing System): A History of Emacs.
+* Japanese EUC (Extended Unix Code): Japanese EUC (Extended Unix Code).
* Java: The Lisp Language.
* Java vs. Lisp: The Lisp Language.
+* JIS7: JIS7.
* Jones, Kyle: XEmacs.
* Kaplan, Simon: XEmacs.
* Levy, Steven: A History of Emacs.
+* library, Lucid Widget: Lucid Widget Library.
* line start cache: Line Start Cache.
+* Lisp interpreter and object system, modules for other aspects of the: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* Lisp language, the: The Lisp Language.
+* Lisp modules, basic: Basic Lisp Modules.
+* Lisp object types, creating: Techniques for XEmacs Developers.
+* Lisp objects are represented in C, how: How Lisp Objects Are Represented in C.
+* Lisp objects, allocation of in XEmacs: Allocation of Objects in XEmacs Lisp.
+* Lisp objects, modules for other display-related: Modules for other Display-Related Lisp Objects.
+* Lisp objects, modules for the basic displayable: Modules for the Basic Displayable Lisp Objects.
+* Lisp primitives, writing: Writing Lisp Primitives.
+* Lisp reader and compiler, the: The Lisp Reader and Compiler.
* Lisp vs. C: The Lisp Language.
* Lisp vs. Java: The Lisp Language.
+* low-level allocation: Low-level allocation.
+* low-level modules: Low-Level Modules.
+* lrecords: lrecords.
* lstream: Modules for Interfacing with the File System.
+* lstream functions: Lstream Functions.
+* lstream methods: Lstream Methods.
+* lstream types: Lstream Types.
+* lstream, creating an: Creating an Lstream.
* Lstream_close: Lstream Functions.
* Lstream_fgetc: Lstream Functions.
* Lstream_flush: Lstream Functions.
* Lstream_ungetc: Lstream Functions.
* Lstream_unread: Lstream Functions.
* Lstream_write: Lstream Functions.
+* lstreams: Lstreams.
* Lucid Emacs: Lucid Emacs.
* Lucid Inc.: Lucid Emacs.
+* Lucid Widget Library: Lucid Widget Library.
+* macro hygiene: Techniques for XEmacs Developers.
+* main loop: Main Loop.
* mark and sweep: Garbage Collection.
* mark method <1>: lrecords.
* mark method: Modules for Other Aspects of the Lisp Interpreter and Object System.
* mark_object: mark_object.
-* marker: Lstream Methods.
-* mathematics of extents: Mathematics of Extent Ordering.
+* marker <1>: Lstream Methods.
+* marker: Marker.
+* markers and extents: Markers and Extents.
+* mathematics of extent ordering: Mathematics of Extent Ordering.
* MAX_EMCHAR_LEN: Working With Character and Byte Positions.
+* menubars: Menubars.
+* menus: Menus.
* merging attempts: XEmacs.
* MIT: A History of Emacs.
* Mlynarik, Richard: GNU Emacs 19.
+* modules for interfacing with the file system: Modules for Interfacing with the File System.
+* modules for interfacing with the operating system: Modules for Interfacing with the Operating System.
+* modules for interfacing with X Windows: Modules for Interfacing with X Windows.
+* modules for internationalization: Modules for Internationalization.
+* modules for other aspects of the Lisp interpreter and object system: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* modules for other display-related Lisp objects: Modules for other Display-Related Lisp Objects.
+* modules for standard editing operations: Modules for Standard Editing Operations.
+* modules for the basic displayable Lisp objects: Modules for the Basic Displayable Lisp Objects.
+* modules for the redisplay mechanism: Modules for the Redisplay Mechanism.
+* modules, a summary of the various XEmacs: A Summary of the Various XEmacs Modules.
+* modules, basic Lisp: Basic Lisp Modules.
+* modules, editor-level control flow: Editor-Level Control Flow Modules.
+* modules, low-level: Low-Level Modules.
+* MS-Windows environment, widget-glyphs in the: Glyphs.
+* Mule character sets and encodings: MULE Character Sets and Encodings.
+* Mule encodings: Encodings.
+* Mule encodings, internal: Internal Mule Encodings.
* MULE merged XEmacs appears: XEmacs.
+* Mule, coding for: Coding for Mule.
+* Mule-aware code, an example of: An Example of Mule-Aware Code.
+* Mule-aware code, general guidelines for writing: General Guidelines for Writing Mule-Aware Code.
* NAS: Modules for Interfacing with the Operating System.
* native sound: Modules for Interfacing with the Operating System.
* network connections: Modules for Interfacing with the Operating System.
* network sound: Modules for Interfacing with the Operating System.
* Niksic, Hrvoje: XEmacs.
+* obarrays: Obarrays.
+* object system (abstractly speaking), the XEmacs: The XEmacs Object System (Abstractly Speaking).
+* object system, modules for other aspects of the Lisp interpreter and: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* object types, creating Lisp: Techniques for XEmacs Developers.
+* object, the buffer: The Buffer Object.
+* object, the window: The Window Object.
+* objects are represented in C, how Lisp: How Lisp Objects Are Represented in C.
+* objects in XEmacs Lisp, allocation of: Allocation of Objects in XEmacs Lisp.
+* objects, modules for the basic displayable Lisp: Modules for the Basic Displayable Lisp Objects.
+* operating system, modules for interfacing with the: Modules for Interfacing with the Operating System.
+* outside, XEmacs from the: XEmacs From the Outside.
* pane: Modules for the Basic Displayable Lisp Objects.
* permanent objects: The XEmacs Object System (Abstractly Speaking).
* pi, calculating: XEmacs From the Outside.
+* point: Point.
+* pointers dumping: Pointers dumping.
+* positions, working with character and byte: Working With Character and Byte Positions.
+* primitives, writing Lisp: Writing Lisp Primitives.
+* progress bars: Progress Bars.
+* protection, garbage collection: GCPROing.
* pseudo_closer: Lstream Methods.
+* Purify: Techniques for XEmacs Developers.
+* Quantify: Techniques for XEmacs Developers.
+* radio buttons, checkboxes and: Checkboxes and Radio Buttons.
* read syntax: The XEmacs Object System (Abstractly Speaking).
* read-eval-print: XEmacs From the Outside.
* reader: Lstream Methods.
-* Redisplay Piece by Piece: Redisplay Piece by Piece.
+* reader and compiler, the Lisp: The Lisp Reader and Compiler.
+* redisplay mechanism, modules for the: Modules for the Redisplay Mechanism.
+* redisplay mechanism, the: The Redisplay Mechanism.
+* redisplay piece by piece: Redisplay Piece by Piece.
+* redisplay sections, critical: Critical Redisplay Sections.
+* reloading phase: Reloading phase.
* relocating allocator: Low-Level Modules.
* rename to XEmacs: XEmacs.
+* represented in C, how Lisp objects are: How Lisp Objects Are Represented in C.
* rewinder: Lstream Methods.
* RMS: A History of Emacs.
* scanner: Modules for Other Aspects of the Lisp Interpreter and Object System.
* scoping, dynamic: The Lisp Language.
+* scrollbars: Scrollbars.
* seekable_p: Lstream Methods.
* selections: Modules for Interfacing with X Windows.
* set_charptr_emchar: Working With Character and Byte Positions.
* sound, native: Modules for Interfacing with the Operating System.
* sound, network: Modules for Interfacing with the Operating System.
* SPARCWorks: XEmacs.
+* specbinding stack; unwind-protects, dynamic binding; the: Dynamic Binding; The specbinding Stack; Unwind-Protects.
+* special forms, simple: Simple Special Forms.
+* specifiers: Specifiers.
+* stack frames; bindings, evaluation;: Evaluation; Stack Frames; Bindings.
* Stallman, Richard: A History of Emacs.
+* string: String.
+* string encoding, internal: Internal String Encoding.
+* subprocesses: Subprocesses.
* subprocesses, asynchronous: Modules for Interfacing with the Operating System.
* subprocesses, synchronous: Modules for Interfacing with the Operating System.
* Sun Microsystems: XEmacs.
* sweep_bit_vectors_1: sweep_bit_vectors_1.
* sweep_lcrecords_1: sweep_lcrecords_1.
* sweep_strings: sweep_strings.
+* symbol: Symbol.
+* symbol values: Symbol Values.
+* symbols and variables: Symbols and Variables.
+* symbols, introduction to: Introduction to Symbols.
* synchronous subprocesses: Modules for Interfacing with the Operating System.
+* tab controls: Tab Controls.
* taxes, doing: XEmacs From the Outside.
+* techniques for XEmacs developers: Techniques for XEmacs Developers.
* TECO: A History of Emacs.
* temporary objects: The XEmacs Object System (Abstractly Speaking).
+* text in a buffer, the: The Text in a Buffer.
+* textual representation, buffers and: Buffers and Textual Representation.
* Thompson, Chuck: XEmacs.
+* throw, catch and: Catch and Throw.
* types, dynamic: The Lisp Language.
+* types, lstream: Lstream Types.
+* types, proper use of unsigned: Proper Use of Unsigned Types.
* University of Illinois: XEmacs.
+* unsigned types, proper use of: Proper Use of Unsigned Types.
+* unwind-protects, dynamic binding; the specbinding stack;: Dynamic Binding; The specbinding Stack; Unwind-Protects.
+* values, symbol: Symbol Values.
+* variables, adding global Lisp: Adding Global Lisp Variables.
+* variables, symbols and: Symbols and Variables.
+* vector: Vector.
+* vector, bit: Bit Vector.
+* version 18, through: Through Version 18.
+* version 19, GNU Emacs: GNU Emacs 19.
+* version 20, GNU Emacs: GNU Emacs 20.
+* widget interface, generic: Generic Widget Interface.
+* widget library, Lucid: Lucid Widget Library.
+* widget-glyphs: Glyphs.
+* widget-glyphs in the MS-Windows environment: Glyphs.
+* widget-glyphs in the X environment: Glyphs.
* Win-Emacs: XEmacs.
* window (in Emacs): Modules for the Basic Displayable Lisp Objects.
* window hierarchy: Window Hierarchy.
+* window object, the: The Window Object.
* window point internals: The Window Object.
+* windows, consoles; devices; frames;: Consoles; Devices; Frames; Windows.
+* windows, introduction to consoles; devices; frames;: Introduction to Consoles; Devices; Frames; Windows.
* Wing, Ben: XEmacs.
* writer: Lstream Methods.
+* writing good comments: Writing Good Comments.
+* writing Lisp primitives: Writing Lisp Primitives.
+* writing Mule-aware code, general guidelines for: General Guidelines for Writing Mule-Aware Code.
+* writing new C code, rules when: Rules When Writing New C Code.
+* X environment, widget-glyphs in the: Glyphs.
+* X Window System, interface to the: Interface to the X Window System.
+* X Windows, modules for interfacing with: Modules for Interfacing with X Windows.
* XEmacs: XEmacs.
+* XEmacs from the inside: XEmacs From the Inside.
+* XEmacs from the outside: XEmacs From the Outside.
+* XEmacs from the perspective of building: XEmacs From the Perspective of Building.
* XEmacs goes it alone: XEmacs.
+* XEmacs object system (abstractly speaking), the: The XEmacs Object System (Abstractly Speaking).
* Zawinski, Jamie: Lucid Emacs.
+* zero-length extents: Zero-Length Extents.
=> "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
=> "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
- (single-key-description 'kp_next)
- => "kp_next"
+ (single-key-description 'kp-next)
+ => "kp-next"
(single-key-description '(shift button1))
=> "Sh-button1"
* Setting Variables:: Customizing Emacs variables
* Init File:: Some examples of Lisp expressions in
- .emacs file
+ init.el file
Selecting and Moving Text
M-x find-file-other-window (bound to keys: C-x 4 f, C-x 4 C-f)
Syntax Highlighting
- You can customize your `.emacs' file to include the font-lock mode
+ You can customize your `init.el' file to include the font-lock mode
so that when you select this item, the comments will be displayed
in one face, strings in another, reserved words in another, and so
on. *Note Customization: (xemacs)Customization, for more
- information on customizing `.emacs' file. After selecting this
+ information on customizing `init.el' file. After selecting this
item, you will find your code a lot easier to read. When Fonts is
selected, different parts of the program will appear in different
Fonts. When Colors is selected, then the program will be displayed
Save Options
Selecting this item will save the current settings of your Options
- menu to your `.emacs' file so that the next time you start XEmacs,
+ menu to your `init.el' file so that the next time you start XEmacs,
you won't need to select the options again.
\1f
Customize key bindings and menus
********************************
- When you start Emacs, it reads the file `~/.emacs' in your home
-directory. You can use this file to initialize and customize Emacs to
-your liking. This file should contain lisp-code. You can customize your
-`.emacs' file to create new menus, disable menus, change key bindings,
-enable a minor mode, etc. Any kind of customization affects only a
-particular Emacs job that you do them in. If you want to save your
-customizations `permanently' i.e. for future use also, you have to put
-it in your `.emacs' file. After you make changes to your `.emacs' file
-and save it, the changes will be effective only after you start Emacs
-again i.e. for a new Emacs process. To try out some of the examples in
-this section, highlight that region and evaluate the region by giving
-the command `M-x eval-region'. You will be able to see the results of
-your customizations in that Emacs session only (*note Lisp Eval:
+ When you start Emacs, it reads the file `~/.xemacs/init.el' in the
+`.xemacs/' subdirectory of your home directory. You can use this file
+to initialize and customize Emacs to your liking. This file should
+contain lisp-code. You can customize your `init.el' file to create new
+menus, disable menus, change key bindings, enable a minor mode, etc.
+Any kind of customization affects only a particular Emacs job that you
+do them in. If you want to save your customizations `permanently' i.e.
+for future use also, you have to put it in your `init.el' file. After
+you make changes to your `init.el' file and save it, the changes will
+be effective only after you start Emacs again i.e. for a new Emacs
+process. To try out some of the examples in this section, highlight
+that region and evaluate the region by giving the command `M-x
+eval-region'. You will be able to see the results of your
+customizations in that Emacs session only (*note Lisp Eval:
(xemacs)Lisp Eval.).
* Menu:
the key `C-n' to move to the previous line by binding it to
previous-line and `C-p' to move to the next line by binding it to
next-line. To bind keys to globally run commands you need to use the
-following syntax in your .emacs file:
+following syntax in your init.el file:
`(global-set-key KEYS CMD)'
Here, `global-set-key' is a function which will bind the "keys" to the
-specified "cmd". For example, if you type the following in your .emacs
+specified "cmd". For example, if you type the following in your init.el
file:
(global-set-key "\C-p" 'next-line)
a command or turn off a feature. If you want to enable a command or
turn on a particular feature use `t' which stands for `true'. For
example, if you do not wish `C-x C-c' to `Exit Emacs' you can type the
-following expression in your `.emacs' file:
+following expression in your `init.el' file:
(global-set-key "\C-x\C-c" nil)
-You might want to have this statement in your `.emacs' file because its
-easy to hit this command by mistake and it could be annoying to exit
+You might want to have this statement in your `init.el' file because
+its easy to hit this command by mistake and it could be annoying to exit
Emacs unintentionally. There is a Exit Emacs option in the File menu
which you might want to use instead. To make a particular key undefined
you can also use:
This function will add a menu item to a menu, creating the menu
first if necessary. If the named item already exists, the menu
will remain unchanged. For example, if you add the following
- example to your `.emacs' file or evaluate it (*note Customization
+ example to your `init.el' file or evaluate it (*note Customization
Basics::),
(add-menu-item '("Edit") "Replace String" replace-string t "Clear")
asm-mode
Use asm-mode for editing files of assembler code. Look at the file
- ` /usr/local/lib/xemacs-19.11/lisp/modes/asm.el' for more
+ ` /usr/local/lib/xemacs-VERSION/lisp/modes/asm.el' for more
information.
There are some other modes and commands for working with other kinds
menu item from the Options menu on the menu-bar at the top. If you
wish to have this mode enabled permanently, choose Save Options
from the Options menu. *Note Options Menu::, for more information
- on the Options menu. You can also add statements in your `.emacs'
- file. For each major mode in which you wish to enable this minor
- mode, you need a statement in your `.emacs' file. The following
- example shows how to enable the font-lock mode when the major mode
- is c-mode.
+ on the Options menu. You can also add statements in your
+ `init.el' file. For each major mode in which you wish to enable
+ this minor mode, you need a statement in your `init.el' file. The
+ following example shows how to enable the font-lock mode when the
+ major mode is c-mode.
(add-hook 'c-mode-hook 'turn-on-font-lock)
********************
You can modify the behavior of Emacs in minor ways permanently by
-putting your changes in your `.emacs' file. This file contains Lisp
+putting your changes in your `init.el' file. This file contains Lisp
function call expressions. Each of these expressions will consist of a
function name followed by arguments, all surrounded by parentheses. For
example, to turn on the auto-fill-mode (i.e. break lines automatically
-when they become too long) , put the following line in your `.emacs'
+when they become too long) , put the following line in your `init.el'
file:
(add-hook 'text-mode-hook
Similarly, to enable the "font-lock mode" which displays your
program in different fonts and colors(*note Modes::), put the following
-in your `.emacs' file. The comments above the statement explain what the
-statements do.
+in your `init.el' file. The comments above the statement explain what
+the statements do.
;;; enables the font-lock-mode in Lisp Mode
(add-hook 'lisp-mode-hook 'turn-on-font-lock)
(set-face-foreground 'font-lock-comment-face "forest green")
For other customizations regarding the font-lock face, look at the file
-`/usr/local/lib/xemacs-19.11/etc/sample.emacs'.
+`/usr/local/lib/xemacs-VERSION/etc/sample.init.el'.
* Menu:
* Setting Variables:: Customizing Emacs variables
* Init File:: Some examples of Lisp expressions in
- .emacs file
+ init.el file
\1f
File: new-users-guide.info, Node: Setting Variables, Next: Init File, Prev: Other Customizations, Up: Other Customizations
, you will see that the new value of case-fold-search will be "nil" and
your searches will be case-sensitive. This will be effective only for
that Emacs session. If you want to change the value of a variable
-permanently put the following statement in your `.emacs' file :
+permanently put the following statement in your `init.el' file :
(setq case-fold-search nil)
This statement will make searches case-sensitive only in the current
-buffer which is the `.emacs' file. This will not be very useful. To
+buffer which is the `init.el' file. This will not be very useful. To
make searches case-sensitive globally in all buffers, use:
(setq-default case-fold-search nil)
==================
For customizing Emacs, you need to put Lisp expressions in your
-`.emacs' file. The following are some useful Lisp expressions. If you
-find any of them useful, just type them in your `.emacs' file:
+`init.el' file. The following are some useful Lisp expressions. If you
+find any of them useful, just type them in your `init.el' file:
* The following expression will make <TAB> in C mode insert a real
tab character if the cursor or point is in the middle of the line.
If we use "setq" instead of "setq-default" then searches will be
case-sensitive only in the current buffer's local value. In this
- case the buffer would be the `.emacs' file. Since this would not
+ case the buffer would be the `init.el' file. Since this would not
be too helpful and we want to have case-sensitive searches in all
buffers, we have to use "setq-default".
* If you don't want the text to be highlighted when you use commands
for marking regions so as to use the "kill" and "yank" commands
- later, you can use the following expression in your `.emacs' file:
+ later, you can use the following expression in your `init.el' file:
(setq zmacs-regions nil)
(set-menubar nil)
* If you want an extensive menu-bar use the following expression in
- your `.emacs' file.
+ your `init.el' file.
(load "big-menubar")
If you want to write your own menus, you can look at some of the
examples in
- `/usr/local/lib/xemacs-20.0/lisp/packages/big-menubar.el' file.
+ `/usr/local/lib/xemacs-VERSION/lisp/packages/big-menubar.el' file.
- For more information on initializing your `.emacs' file, *Note Init
+ For more information on initializing your `init.el' file, *Note Init
File: (xemacs)Init File. You should also look at
-`/usr/local/lib/xemacs-20.0/etc/sample.emacs', which is a sample
-`.emacs' file. It contains some of the commonly desired customizations
+`/usr/local/lib/xemacs-VERSION/etc/sample.init.el', which is a sample
+`init.el' file. It contains some of the commonly desired customizations
in Emacs.
\1f
* Menu:
-* .emacs: Customization Basics.
* abbrev-mode: Minor Modes.
* accumulating text: Accumulating text.
* add menus: Customizing Menus.
* Help menu: Help menu.
* hook: Other Customizations.
* init file examples: Init File.
+* init.el: Customization Basics.
* Insert File... menu item: File menu.
* insertion: Insert.
* key bindings: Customizing key Bindings.
END-INFO-DIR-ENTRY
GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999 Free Software Foundation, Inc.
+1997, 1998, 1999, 2000 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
Version
*******
- Last updated June 24, 1999.
+ Last updated February 21, 2001.
* Menu:
* Documentation:: Documenting Programs
* Managing Releases:: The Release Process
* References:: References to Non-Free Software or Documentation
+* Index::
\1f
File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
state reasons for writing in a certain way.
Corrections or suggestions for this document should be sent to
-<gnu@gnu.org>. If you make a suggestion, please include a suggested
-new wording for it; our time is limited. We prefer a context diff to
-the `standards.texi' or `make-stds.texi' files, but if you don't have
-those files, please mail your suggestion anyway.
-
- This release of the GNU Coding Standards was last updated June 24,
-1999.
+<bug-standards@gnu.org>. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the `standards.texi' or `make-stds.texi' files, but if you
+don't have those files, please mail your suggestion anyway.
+
+ This release of the GNU Coding Standards was last updated February
+21, 2001.
+
+ If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version. You can ftp the GNU Coding
+Standards from any GNU FTP host in the directory `/pub/gnu/standards/'.
+The GNU Coding Standards are available there in several different
+formats: `standards.text', `standards.texi', `standards.info', and
+`standards.dvi'. The GNU Coding Standards are also available on the
+GNU World Wide Web server: `http://www.gnu.org/prep/standards_toc.html'.
\1f
File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
Keeping Free Software Free
**************************
- This node discusses how you can make sure that GNU software remains
-unencumbered.
+ This node discusses how you can make sure that GNU software avoids
+legal difficulties, and other related issues.
* Menu:
* Reading Non-Free Code:: Referring to Proprietary Programs
* Contributions:: Accepting Contributions
+* Trademarks:: How We Deal with Trademark Issues
\1f
File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
obstacks.
\1f
-File: standards.info, Node: Contributions, Prev: Reading Non-Free Code, Up: Legal Issues
+File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
Accepting Contributions
=======================
released or not), please ask us for a copy.
\1f
+File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
+
+Trademarks
+==========
+
+ Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+ Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so. The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them. There is no legal requirement for them.
+
+ What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities. For example, since "Objective C" is
+(or at least was) a trademark, we made sure to say that we provide a
+"compiler for the Objective C language" rather than an "Objective C
+compiler". The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using "Objective C" as a label for the compiler rather than for the
+language.
+
+\1f
File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
General Program Design
* Menu:
+* Source Language:: Which languges to use.
* Compatibility:: Compatibility with other implementations
* Using Extensions:: Using non-standard features
-* ANSI C:: Using ANSI C features
-* Source Language:: Using languages other than C
+* Standard C:: Using Standard C features
\1f
-File: standards.info, Node: Compatibility, Next: Using Extensions, Up: Design Advice
+File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
+
+Which Languages to Use
+======================
+
+ When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C. Using another language is like
+using a non-standard feature: it will cause trouble for users. Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program. For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+ C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+ So in general it is much better to use C, rather than the comparable
+alternatives.
+
+ But there are two exceptions to that conclusion:
+
+ * It is no problem to use another language to write a tool
+ specifically intended for use with that language. That is because
+ the only people who want to build the tool will be those who have
+ installed the other language anyway.
+
+ * If an application is of interest only to a narrow part of the
+ community, then the question of which language it is written in
+ has less effect on other people, so you may as well please
+ yourself.
+
+ Many programs are designed to be extensible: they include an
+interpreter for a language that is higher level than C. Often much of
+the program is written in that language, too. The Emacs editor
+pioneered this technique.
+
+ The standard extensibility interpreter for GNU software is GUILE,
+which implements the language Scheme (an especially clean and simple
+dialect of Lisp). `http://www.gnu.org/software/guile/'. We don't
+reject programs written in other "scripting languages" such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
+\1f
+File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
Compatibility with Other Implementations
========================================
With occasional exceptions, utility programs and libraries for GNU
should be upward compatible with those in Berkeley Unix, and upward
-compatible with ANSI C if ANSI C specifies their behavior, and upward
-compatible with POSIX if POSIX specifies their behavior.
+compatible with Standard C if Standard C specifies their behavior, and
+upward compatible with POSIX if POSIX specifies their behavior.
When these standards conflict, it is useful to offer compatibility
modes for each of them.
- ANSI C and POSIX prohibit many kinds of extensions. Feel free to
-make the extensions anyway, and include a `--ansi', `--posix', or
+ Standard C and POSIX prohibit many kinds of extensions. Feel free
+to make the extensions anyway, and include a `--ansi', `--posix', or
`--compatible' option to turn them off. However, if the extension has
a significant chance of breaking any real programs or scripts, then it
-is not really upward compatible. Try to redesign its interface.
+is not really upward compatible. So you should try to redesign its
+interface to make it upward compatible.
Many GNU programs suppress extensions that conflict with POSIX if the
environment variable `POSIXLY_CORRECT' is defined (even if it is
`vi' is replaced with Emacs.) But it is nice to offer a compatible
feature as well. (There is a free `vi' clone, so we offer it.)
- Additional useful features not in Berkeley Unix are welcome.
+ Additional useful features are welcome regardless of whether there
+is any precedent for them.
\1f
-File: standards.info, Node: Using Extensions, Next: ANSI C, Prev: Compatibility, Up: Design Advice
+File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
Using Non-standard Features
===========================
are a big improvement.
An exception to this rule are the large, established programs (such
-as Emacs) which run on a great variety of systems. Such programs would
-be broken by use of GNU extensions.
+as Emacs) which run on a great variety of systems. Using GNU
+extensions in such programs would make many users unhappy, so we don't
+do that.
Another exception is for programs that are used as part of
compilation: anything that must be compiled with other compilers in
order to bootstrap the GNU compilation facilities. If these require
the GNU compiler, then no one can compile them without having them
-installed already. That would be no good.
+installed already. That would be extremely troublesome in certain
+cases.
\1f
-File: standards.info, Node: ANSI C, Next: Source Language, Prev: Using Extensions, Up: Design Advice
-
-ANSI C and pre-ANSI C
-=====================
+File: standards.info, Node: Standard C, Prev: Using Extensions, Up: Design Advice
- Do not ever use the "trigraph" feature of ANSI C.
+Standard C and Pre-Standard C
+=============================
- ANSI C is widespread enough now that it is ok to write new programs
-that use ANSI C features (and therefore will not work in non-ANSI
-compilers). And if a program is already written in ANSI C, there's no
-need to convert it to support non-ANSI compilers.
+ 1989 Standard C is widespread enough now that it is ok to use its
+features in new programs. There is one exception: do not ever use the
+"trigraph" feature of Standard C.
- If you don't know non-ANSI C, there's no need to learn it; just
-write in ANSI C.
+ 1999 Standard C is not widespread yet, so please do not require its
+features in programs. It is ok to use its features if they are present.
- However, it is easy to support non-ANSI compilers in most programs,
-so you might still consider doing so when you write a program. And if a
-program you are maintaining has such support, you should try to keep it
-working.
+ However, it is easy to support pre-standard compilers in most
+programs, so if you know how to do that, feel free. If a program you
+are maintaining has such support, you should try to keep it working.
- To support pre-ANSI C, instead of writing function definitions in
-ANSI prototype form,
+ To support pre-standard C, instead of writing function definitions in
+standard prototype form,
int
foo (int x, int y)
...
-write the definition in pre-ANSI style like this,
+write the definition in pre-standard style like this,
int
foo (x, y)
int foo (int, int);
You need such a declaration anyway, in a header file, to get the
-benefit of ANSI C prototypes in all the files where the function is
-called. And once you have the declaration, you normally lose nothing
-by writing the function definition in the pre-ANSI style.
+benefit of prototypes in all the files where the function is called.
+And once you have the declaration, you normally lose nothing by writing
+the function definition in the pre-standard style.
This technique does not work for integer types narrower than `int'.
If you think of an argument as being of a type narrower than `int',
`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
some machines; but you cannot use `int' instead, because `dev_t' is
wider than `int' on some machines. There is no type you can safely use
-on all machines in a non-ANSI definition. The only way to support
-non-ANSI C and pass such an argument is to check the width of `dev_t'
-using Autoconf and choose the argument type accordingly. This may not
-be worth the trouble.
+on all machines in a non-standard definition. The only way to support
+non-standard C and pass such an argument is to check the width of
+`dev_t' using Autoconf and choose the argument type accordingly. This
+may not be worth the trouble.
-\1f
-File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice
-
-Using Languages Other Than C
-============================
-
- Using a language other than C is like using a non-standard feature:
-it will cause trouble for users. Even if GCC supports the other
-language, users may find it inconvenient to have to install the
-compiler for that other language in order to build your program. For
-example, if you write your program in C++, people will have to install
-the C++ compiler in order to compile your program. Thus, it is better
-if you write in C.
-
- But there are three situations when there is no disadvantage in using
-some other language:
-
- * It is okay to use another language if your program contains an
- interpreter for that language.
-
- For example, if your program links with GUILE, it is ok to write
- part of the program in Scheme or another language supported by
- GUILE.
+ In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
- * It is okay to use another language in a tool specifically intended
- for use with that language.
-
- This is okay because the only people who want to build the tool
- will be those who have installed the other language anyway.
-
- * If an application is of interest to a narrow community, then
- perhaps it's not important if the application is inconvenient to
- install.
-
- C has one other advantage over C++ and other compiled languages: more
-people know C, so more people will find it easy to read and modify the
-program if it is written in C.
+ /* Declare the prototype for a general external function. */
+ #if defined (__STDC__) || defined (WINDOWSNT)
+ #define P_(proto) proto
+ #else
+ #define P_(proto) ()
+ #endif
\1f
File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
Program Behavior for All Programs
*********************************
- This node describes how to write robust software. It also describes
-general standards for error messages, the command line interface, and
-how libraries should behave.
+ This node describes conventions for writing robust software. It
+also describes general standards for error messages, the command line
+interface, and how libraries should behave.
* Menu:
* Semantics:: Writing robust programs
* Libraries:: Library behavior
* Errors:: Formatting error messages
-* User Interfaces:: Standards for command line interfaces
-* Option Table:: Table of long options.
+* User Interfaces:: Standards about interfaces generally
+* Graphical Interfaces:: Standards for graphical interfaces
+* Command-Line Interfaces:: Standards for command line interfaces
+* Option Table:: Table of long options
* Memory Usage:: When and how to care about memory needs
+* File Usage:: Which files to use, and where
\1f
File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior
variable; if that variable is defined, use the specified directory
instead of `/tmp'.
+ In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories. In C, you can
+avoid this problem by creating temporary files in this manner:
+
+ fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+
+or by using the `mkstemps' function from libiberty.
+
+ In bash, use `set -C' to avoid this problem.
+
\1f
File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
other; then they can both go in the same file.
External symbols that are not documented entry points for the user
-should have names beginning with `_'. They should also contain the
-chosen name prefix for the library, to prevent collisions with other
-libraries. These can go in the same files with user entry points if
-you like.
+should have names beginning with `_'. The `_' should be followed by
+the chosen name prefix for the library, to prevent collisions with
+other libraries. These can go in the same files with user entry points
+if you like.
Static functions and variables can be used as you like and need not
fit any naming convention.
end with a period.
\1f
-File: standards.info, Node: User Interfaces, Next: Option Table, Prev: Errors, Up: Program Behavior
+File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
-Standards for Command Line Interfaces
-=====================================
+Standards for Interfaces Generally
+==================================
Please don't make the behavior of a utility depend on the name used
to invoke it. It is useful sometimes to make a link to a utility with
`ls' except that its default output format is always multi-column
format.
+\1f
+File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
+
+Standards for Graphical Interfaces
+==================================
+
+ When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK toolkit unless the
+functionality specifically requires some alternative (for example,
+"displaying jpeg images while in console mode").
+
+ In addition, please provide a command-line interface to control the
+functionality. (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.) This is so
+that the same jobs can be done from scripts.
+
+ Please also consider providing a CORBA interface (for use from
+GNOME), a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console mode).
+Once you are doing the work to provide the functionality and the
+graphical interface, these won't be much extra work.
+
+\1f
+File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
+
+Standards for Command Line Interfaces
+=====================================
+
It is a good idea to follow the POSIX guidelines for the
command-line options of a program. The easiest way to do this is to use
`getopt' to parse them. Note that the GNU version of `getopt' will
Report bugs to MAILING-ADDRESS.
\1f
-File: standards.info, Node: Option Table, Next: Memory Usage, Prev: User Interfaces, Up: Program Behavior
+File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
Table of Long Options
=====================
Here is a table of long options used by GNU programs. It is surely
incomplete, but we aim to list all the options that a new program might
want to be compatible with. If you use names not already in the table,
-please send <gnu@gnu.org> a list of them, with their meanings, so we
-can update the table.
+please send <bug-standards@gnu.org> a list of them, with their
+meanings, so we can update the table.
`after-date'
`-N' in `tar'.
`hide-control-chars'
`-q' in `ls'.
+`html'
+ In `makeinfo', output HTML.
+
`idle'
`-u' in `who'.
`info'
`-i', `-l', and `-m' in Finger.
+`init-file'
+ In some programs, specify the name of the file to read as the
+ user's init file.
+
`initial'
`-i' in `expand'.
`intermix-type'
`-p' in `shar'.
+`iso-8601'
+ Used in `date'
+
`jobs'
`-j' in Make.
`-z' in `gprof'.
\1f
-File: standards.info, Node: Memory Usage, Prev: Option Table, Up: Program Behavior
+File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
Memory Usage
============
- If it typically uses just a few meg of memory, don't bother making
-any effort to reduce memory usage. For example, if it is impractical
-for other reasons to operate on files more than a few meg long, it is
-reasonable to read entire input files into core to operate on them.
+ If a program typically uses just a few meg of memory, don't bother
+making any effort to reduce memory usage. For example, if it is
+impractical for other reasons to operate on files more than a few meg
+long, it is reasonable to read entire input files into core to operate
+on them.
However, for programs such as `cat' or `tail', that can usefully
operate on very large files, it is important to avoid using a technique
in core and give a fatal error if `malloc' returns zero.
\1f
+File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
+
+File Usage
+==========
+
+ Programs should be prepared to operate when `/usr' and `/etc' are
+read-only file systems. Thus, if the program manages log files, lock
+files, backup files, score files, or any other files which are modified
+for internal purposes, these files should not be stored in `/usr' or
+`/etc'.
+
+ There are two exceptions. `/etc' is used to store system
+configuration information; it is reasonable for a program to modify
+files in `/etc' when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+\1f
File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
Making The Best Use of C
* Internationalization:: Techniques for internationalization
* Mmap:: How you can safely use `mmap'.
-\1f
-File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
-
-Formatting Your Source Code
-===========================
-
- It is important to put the open-brace that starts the body of a C
-function in column zero, and avoid putting any other open-brace or
-open-parenthesis or open-bracket in column zero. Several tools look
-for open-braces in column zero to find the beginnings of C functions.
-These tools will not work on code not formatted that way.
-
- It is also important for function definitions to start the name of
-the function in column zero. This helps people to search for function
-definitions, and may also help certain tools recognize them. Thus, the
-proper format is this:
-
- static char *
- concat (s1, s2) /* Name starts in column zero here */
- char *s1, *s2;
- { /* Open brace in column zero here */
- ...
- }
-
-or, if you want to use ANSI C, format the definition like this:
-
- static char *
- concat (char *s1, char *s2)
- {
- ...
- }
-
- In ANSI C, if the arguments don't fit nicely on one line, split it
-like this:
-
- int
- lots_of_args (int an_integer, long a_long, short a_short,
- double a_double, float a_float)
- ...
-
- For the body of the function, we prefer code formatted like this:
-
- if (x < foo (y, z))
- haha = bar[4] + 5;
- else
- {
- while (z)
- {
- haha += foo (z, z);
- z--;
- }
- return ++x + bar ();
- }
-
- We find it easier to read a program when it has spaces before the
-open-parentheses and after the commas. Especially after the commas.
-
- When you split an expression into multiple lines, split it before an
-operator, not after one. Here is the right way:
-
- if (foo_this_is_long && bar > win (x, y, z)
- && remaining_condition)
-
- Try to avoid having two operators of different precedence at the same
-level of indentation. For example, don't write this:
-
- mode = (inmode[j] == VOIDmode
- || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
- ? outmode[j] : inmode[j]);
-
- Instead, use extra parentheses so that the indentation shows the
-nesting:
-
- mode = ((inmode[j] == VOIDmode
- || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
- ? outmode[j] : inmode[j]);
-
- Insert extra parentheses so that Emacs will indent the code properly.
-For example, the following indentation looks nice if you do it by hand,
-but Emacs would mess it up:
-
- v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
-
- But adding a set of parentheses solves the problem:
-
- v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
- + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
-
- Format do-while statements like this:
-
- do
- {
- a = foo (a);
- }
- while (a > 0);
-
- Please use formfeed characters (control-L) to divide the program into
-pages at logical places (but not within a function). It does not matter
-just how long the pages are, since they do not have to fit on a printed
-page. The formfeeds should appear alone on lines by themselves.
-
END-INFO-DIR-ENTRY
GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999 Free Software Foundation, Inc.
+1997, 1998, 1999, 2000 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
+
+Formatting Your Source Code
+===========================
+
+ It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero. Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+ It is also important for function definitions to start the name of
+the function in column zero. This helps people to search for function
+definitions, and may also help certain tools recognize them. Thus, the
+proper format is this:
+
+ static char *
+ concat (s1, s2) /* Name starts in column zero here */
+ char *s1, *s2;
+ { /* Open brace in column zero here */
+ ...
+ }
+
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+ static char *
+ concat (char *s1, char *s2)
+ {
+ ...
+ }
+
+ In Standard C, if the arguments don't fit nicely on one line, split
+it like this:
+
+ int
+ lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+ ...
+
+ The rest of this section gives our recommendations for other aspects
+of C formatting style, which is also the default style of the `indent'
+program in version 1.2 and newer. It corresponds to the options
+
+ -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+ -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+
+ We don't think of these recommendations as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+ But whatever style you use, please use it consistently, since a
+mixture of styles within one program tends to look ugly. If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+ For the body of the function, our recommended style looks like this:
+
+ if (x < foo (y, z))
+ haha = bar[4] + 5;
+ else
+ {
+ while (z)
+ {
+ haha += foo (z, z);
+ z--;
+ }
+ return ++x + bar ();
+ }
+
+ We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas. Especially after the commas.
+
+ When you split an expression into multiple lines, split it before an
+operator, not after one. Here is the right way:
+
+ if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+
+ Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+ mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+
+ Instead, use extra parentheses so that the indentation shows the
+nesting:
+
+ mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+
+ Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+ v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+
+but Emacs would alter it. Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+ v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+
+ Format do-while statements like this:
+
+ do
+ {
+ a = foo (a);
+ }
+ while (a > 0);
+
+ Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function). It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page. The formfeeds should appear alone on lines by themselves.
+
+\1f
File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
Commenting Your Work
Clean Use of C Constructs
=========================
- Please explicitly declare all arguments to functions. Don't omit
-them just because they are `int's.
+ Please explicitly declare the types of all objects. For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return `int' rather than omitting the `int'.
+
+ Some programmers like to use the GCC `-Wall' option, and change the
+code whenever it issues a warning. If you want to do this, then do.
+Other programmers prefer not to use `-Wall', because it gives warnings
+for valid and legitimate code which they do not want to change. If you
+want to do this, then do. The compiler should be your servant, not
+your master.
Declarations of external functions and functions to appear later in
the source file should all go in one place near the beginning of the
When you want to define names with constant integer values, use
`enum' rather than `#define'. GDB knows about enumeration constants.
- Use file names of 14 characters or less, to avoid creating gratuitous
-problems on older System V systems. You can use the program `doschk'
-to test for this. `doschk' also tests for potential name conflicts if
-the files were loaded onto an MS-DOS file system--something you may or
-may not care about.
+ You might want to make sure that none of the file names would
+conflict the files were loaded onto an MS-DOS file system which
+shortens the names. You can use the program `doschk' to test for this.
+
+ Some GNU programs were designed to limit themselves to file names of
+14 characters or less, to avoid file name conflicts if they are read
+into older System V systems. Please preserve this feature in the
+existing GNU programs that have it, but there is no need to do this in
+new GNU programs. `doschk' also reports file names longer than 14
+characters.
\1f
File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
not paramount.
The primary purpose of GNU software is to run on top of the GNU
-kernel, compiled with the GNU C compiler, on various types of CPU. The
-amount and kinds of variation among GNU systems on different CPUs will
-be comparable to the variation among Linux-based GNU systems or among
-BSD systems today. So the kinds of portability that are absolutely
-necessary are quite limited.
-
- But many users do run GNU software on non-GNU Unix or Unix-like
-systems. So supporting a variety of Unix-like systems is desirable,
-although not paramount.
+kernel, compiled with the GNU C compiler, on various types of CPU. So
+the kinds of portability that are absolutely necessary are quite
+limited. But it is important to support Linux-based GNU systems, since
+they are the form of GNU that is popular.
+
+ Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to. Supporting a variety of Unix-like systems is desirable, although
+not paramount. It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
The easiest way to achieve portability to most Unix-like systems is
to use Autoconf. It's unlikely that your program needs to know more
will be useful on GNU and GNU/Linux, rather than on supporting other
incompatible systems.
+ It is a good idea to define the "feature test macro" `_GNU_SOURCE'
+when compiling your C files. When you compile on GNU or GNU/Linux,
+this will enable the declarations of GNU library extension functions,
+and that will usually give you a compiler error message if you define
+the same function names in some other way in your program. (You don't
+have to actually _use_ these functions, if you prefer to make the
+program more portable to other systems.)
+
+ But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings. Doing so would make it hard
+to move your code into other GNU programs.
+
\1f
File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
`int' will be less than 32 bits. We don't support 16-bit machines in
GNU.
+ Similarly, don't make any effort to cater to the possibility that
+`long' will be smaller than predefined types like `size_t'. For
+example, the following code is ok:
+
+ printf ("size = %lu\n", (unsigned long) sizeof array);
+ printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+
+ 1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows IA-64. We will
+leave it to those who want to port GNU programs to that environment to
+figure out how to do it.
+
+ Predefined file-size types like `off_t' are an exception: they are
+longer than `long' on many platforms, so code like the above won't work
+with them. One way to print an `off_t' value portably is to print its
+digits yourself, one by one.
+
Don't assume that the address of an `int' object is also the address
of its least-significant byte. This is false on big-endian machines.
Thus, don't make the following mistake:
When calling functions, you need not worry about the difference
between pointers of various types, or between pointers and integers.
On most machines, there's no difference anyway. As for the few
-machines where there is a difference, all of them support ANSI C, so
-you can use prototypes (conditionalized to be active only in ANSI C) to
-make the code work on those systems.
+machines where there is a difference, all of them support Standard C
+prototypes, so you can use prototypes (perhaps conditionalized to be
+active only in Standard C) to make the code work on those systems.
In certain cases, it is ok to pass integer and pointer arguments
indiscriminately to the same function, and use no prototype on any
}
In practice, this works on all machines, since a pointer is generally
-the widest possible kind of argument, and it is much simpler than any
+the widest possible kind of argument; it is much simpler than any
"correct" alternative. Be sure _not_ to use a prototype for such
functions.
- However, avoid casting pointers to integers unless you really need
-to. Outside of special situations, such casts greatly reduce
-portability, and in most programs they are easy to avoid. In the cases
-where casting pointers to integers is essential--such as, a Lisp
+ If you have decided to use Standard C, then you can instead define
+`error' using `stdarg.h', and pass the arguments along to `vfprintf'.
+
+ Avoid casting pointers to integers if you can. Such casts greatly
+reduce portability, and in most programs they are easy to avoid. In the
+cases where casting pointers to integers is essential--such as, a Lisp
interpreter which stores type information as well as an address in one
-word--it is ok to do it, but you'll have to make explicit provisions to
-handle different word sizes.
+word--you'll have to make explicit provisions to handle different word
+sizes. You will also need to make provision for systems in which the
+normal range of addresses you can get from `malloc' starts far away
+from zero.
\1f
File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
Calling System Functions
========================
- C implementations differ substantially. ANSI C reduces but does not
-eliminate the incompatibilities; meanwhile, many users wish to compile
-GNU software with pre-ANSI compilers. This chapter gives
-recommendations for how to use the more or less standard C library
-functions to avoid unnecessary loss of portability.
+ C implementations differ substantially. Standard C reduces but does
+not eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do. This
+chapter gives recommendations for how to use the more-or-less standard C
+library functions to avoid unnecessary loss of portability.
- * Don't use the value of `sprintf'. It returns the number of
+ * Don't use the return value of `sprintf'. It returns the number of
characters written on some systems, but not on all systems.
+ * Be aware that `vfprintf' is not always available.
+
* `main' should be declared to return type `int'. It should
terminate either by calling `exit' or by returning the integer
status code; make sure it cannot ever return an undefined value.
frequently caused actual conflicts.
* If you must declare a system function, don't specify the argument
- types. Use an old-style declaration, not an ANSI prototype. The
- more you specify about the function, the more likely a conflict.
+ types. Use an old-style declaration, not a Standard C prototype.
+ The more you specify about the function, the more likely a
+ conflict.
* In particular, don't unconditionally declare `malloc' or `realloc'.
declarations for the string functions from the header file in the
usual way.
- That causes less of a problem than you might think. The newer ANSI
- string functions should be avoided anyway because many systems
- still don't support them. The string functions you can use are
- these:
+ That causes less of a problem than you might think. The newer
+ standard string functions should be avoided anyway because many
+ systems still don't support them. The string functions you can
+ use are these:
strcpy strncpy strcat strncat
strlen strcmp strncmp
You should pick a single pair of names and use it throughout your
program. (Nowadays, it is better to choose `strchr' and `strrchr'
- for new programs, since those are the standard ANSI names.)
- Declare both of those names as functions returning `char *'. On
- systems which don't support those names, define them as macros in
- terms of the other pair. For example, here is what to put at the
- beginning of your file (or in a header) if you want to use the
- names `strchr' and `strrchr' throughout:
+ for new programs, since those are the standard names.) Declare
+ both of those names as functions returning `char *'. On systems
+ which don't support those names, define them as macros in terms of
+ the other pair. For example, here is what to put at the beginning
+ of your file (or in a header) if you want to use the names
+ `strchr' and `strrchr' throughout:
#ifndef HAVE_STRCHR
#define strchr index
Documenting Programs
********************
+ A GNU program should ideally come with full free documentation,
+adequate for both reference and tutorial purposes. If the package can
+be programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
* Menu:
* GNU Manuals:: Writing proper manuals.
+* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
* Manual Structure Details:: Specific structure conventions.
* License for Manuals:: Writing the distribution terms for a manual.
+* Manual Credits:: Giving credit to documentation contributors.
+* Printed Manuals:: Mentioning the printed manual.
* NEWS File:: NEWS files supplement manuals.
* Change Logs:: Recording Changes
* Man Pages:: Man pages are secondary.
from other manuals.
\1f
-File: standards.info, Node: GNU Manuals, Next: Manual Structure Details, Up: Documentation
+File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
GNU Manuals
===========
- The preferred way to document part of the GNU system is to write a
-manual in the Texinfo formatting language. This makes it possible to
-produce a good quality formatted book, using TeX, and to generate an
-Info file. It is also possible to generate HTML output from Texinfo
-source. See the Texinfo manual, either the hardcopy, or the on-line
-version available through `info' or the Emacs Info subsystem (`C-h i').
+ The preferred document format for the GNU system is the Texinfo
+formatting language. Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners. Texinfo
+makes it possible to produce a good quality formatted book, using TeX,
+and to generate an Info file. It is also possible to generate HTML
+output from Texinfo source. See the Texinfo manual, either the
+hardcopy, or the on-line version available through `info' or the Emacs
+Info subsystem (`C-h i').
+
+ Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo. It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
Programmers often find it most natural to structure the documentation
following the structure of the implementation, which they know. But
as well as `cmp'. By documenting these programs together, we can make
the whole subject clearer.
- The manual which discusses a program should document all of the
-program's command-line options and all of its commands. It should give
-examples of their use. But don't organize the manual as a list of
+ The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands. It should
+give examples of their use. But don't organize the manual as a list of
features. Instead, organize it logically, by subtopics. Address the
questions that a user will ask when thinking about the job that the
program does.
the framework for a beginner to understand the rest of the manual. The
Bison manual provides a good example of how to do this.
+ To serve as a reference, a manual should have an Index that list all
+the functions, variables, options, and important concepts that are part
+of the program. One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+*Note Making Index Entries: (texinfo)Index Entries, and see *Note
+Defining the Entries of an Index: (texinfo)Indexing Commands.
+
Don't use Unix man pages as a model for how to write GNU
documentation; most of them are terse, badly structured, and give
inadequate explanation of the underlying concepts. (There are, of
-course exceptions.) Also Unix man pages use a particular format which
-is different from what we use in GNU manuals.
+course, some exceptions.) Also, Unix man pages use a particular format
+which is different from what we use in GNU manuals.
Please include an email address in the manual for where to report
bugs _in the manual_.
Please do not use the term "illegal" to refer to erroneous input to a
computer program. Please use "invalid" for this, and reserve the term
-"illegal" for violations of law.
+"illegal" for activities punishable by law.
+
+\1f
+File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
+
+Doc Strings and Manuals
+=======================
+
+ Some programming systems, such as Emacs, provide a documentation
+string for each function, command or variable. You may be tempted to
+write a reference manual by compiling the documentation strings and
+writing a little additional text to go around them--but you must not do
+it. That approach is a fundamental mistake. The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+ A documentation string needs to stand alone--when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+ The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection. Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables. The previous descriptions of functions and variables in the
+section will also have given information about the topic. A description
+written to stand alone would repeat some of that information; this
+redundance looks bad. Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+ The only good way to use documentation strings in writing a good
+manual is to use them as a source of information for writing good text.
\1f
-File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: GNU Manuals, Up: Documentation
+File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
Manual Structure Details
========================
of the above patterns. This identifies the node which that item points
to as the node for this purpose, regardless of the node's actual name.
- There will be automatic features for specifying a program name and
-quickly reading just this part of its manual.
+ The `--usage' feature of the Info reader looks for such a node or
+menu item in order to find the relevant text, so it is essential for
+every Texinfo file to have one.
If one manual describes several programs, it should have such a node
-for each program described.
+for each program described in the manual.
\1f
-File: standards.info, Node: License for Manuals, Next: NEWS File, Prev: Manual Structure Details, Up: Documentation
+File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
License for Manuals
===================
- If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
-contains chapters that make political or personal statements, please
-copy the distribution terms of the GNU Emacs Manual, and adapt it by
-modifying appropriately the list of special chapters that may not be
-modified or deleted.
+ Please use the GNU Free Documentation License for all GNU manuals
+that are more than a few pages long. Likewise for a collection of short
+documents--you only need one copy of the GNU FDL for the whole
+collection. For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
- If the manual does not contain any such chapters, then imitate the
-simpler distribution terms of the Texinfo manual.
+ See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
+of how to employ the GFDL.
+
+ Note that it is not obligatory to include a copy of the GNU GPL or
+GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
+can be a good idea to include the program's license in a large manual;
+in a short manual, whose size would be increased considerably by
+including the program's license, it is probably better not to include
+it.
\1f
-File: standards.info, Node: NEWS File, Next: Change Logs, Prev: License for Manuals, Up: Documentation
+File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
+
+Manual Credits
+==============
+
+ Please credit the principal human writers of the manual as the
+authors, on the title page of the manual. If a company sponsored the
+work, thank the company in a suitable place in the manual, but do not
+cite the company as an author.
+
+\1f
+File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
+
+Printed Manuals
+===============
+
+ The FSF publishes some GNU manuals in printed form. To encourage
+sales of these manuals, the on-line versions of the manual should
+mention at the very start that the printed manual is available and
+should point at information for getting it--for instance, with a link
+to the page <http://www.gnu.org/order/order.html>. This should not be
+included in the printed manual, though, because there it is redundant.
+
+ It is also useful to explain in the on-line forms of the manual how
+the user can print out the manual from the sources.
+
+\1f
+File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
The NEWS File
=============
* Style of Change Logs::
* Simple Changes::
* Conditional Changes::
+* Indicating the Part Changed::
\1f
File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
Style of Change Logs
--------------------
- Here are some examples of change log entries:
+ Here are some simple examples of change log entries, starting with
+the header line that says who made the change and when, followed by
+descriptions of specific changes. (These examples are drawn from Emacs
+and GCC.)
+ 1998-08-17 Richard Stallman <rms@gnu.org>
+
* register.el (insert-register): Return nil.
(jump-to-register): Likewise.
then don't put blank lines between them. Then you can omit the file
name and the asterisk when successive entries are in the same file.
+ Break long lists of function names by closing continued lines with
+`)', rather than `,', and opening the continuation with `(' as in this
+example:
+
+ * keyboard.c (menu_bar_items, tool_bar_items)
+ (Fexecute_extended_command): Deal with `keymap' property.
+
\1f
File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
log.
When you change the calling sequence of a function in a simple
-fashion, and you change all the callers of the function, there is no
-need to make individual entries for all the callers that you changed.
-Just write in the entry for the function being called, "All callers
-changed."
+fashion, and you change all the callers of the function to use the new
+calling sequence, there is no need to make individual entries for all
+the callers that you changed. Just write in the entry for the function
+being called, "All callers changed"--like this:
* keyboard.c (Fcommand_execute): New arg SPECIAL.
All callers changed.
documentation says with the way the program actually works.
\1f
-File: standards.info, Node: Conditional Changes, Prev: Simple Changes, Up: Change Logs
+File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
Conditional Changes
-------------------
(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
\1f
+File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
+
+Indicating the Part Changed
+---------------------------
+
+ Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does. Here is an entry
+for a change in the part of the function `sh-while-getopts' that deals
+with `sh' commands:
+
+ * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+ user-specified option string is empty.
+
+\1f
File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
Man Pages
documentation. Copying from free documentation may be ok; please check
with the FSF about the individual case.
-\1f
-File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
-
-The Release Process
-*******************
-
- Making a release is more than just bundling up your source files in a
-tar file and putting it up for FTP. You should set up your software so
-that it can be configured to run on a variety of systems. Your Makefile
-should conform to the GNU standards described below, and your directory
-layout should also conform to the standards discussed below. Doing so
-makes it easy to include your package into the larger framework of all
-GNU software.
-
-* Menu:
-
-* Configuration:: How Configuration Should Work
-* Makefile Conventions:: Makefile Conventions
-* Releases:: Making Releases
-
-\1f
-File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
-
-How Configuration Should Work
-=============================
-
- Each GNU distribution should come with a shell script named
-`configure'. This script is given arguments which describe the kind of
-machine and system you want to compile the program for.
-
- The `configure' script must record the configuration options so that
-they affect compilation.
-
- One way to do this is to make a link from a standard name such as
-`config.h' to the proper configuration file for the chosen system. If
-you use this technique, the distribution should _not_ contain a file
-named `config.h'. This is so that people won't be able to build the
-program without configuring it first.
-
- Another thing that `configure' can do is to edit the Makefile. If
-you do this, the distribution should _not_ contain a file named
-`Makefile'. Instead, it should include a file `Makefile.in' which
-contains the input used for editing. Once again, this is so that people
-won't be able to build the program without configuring it first.
-
- If `configure' does write the `Makefile', then `Makefile' should
-have a target named `Makefile' which causes `configure' to be rerun,
-setting up the same configuration that was set up last time. The files
-that `configure' reads should be listed as dependencies of `Makefile'.
-
- All the files which are output from the `configure' script should
-have comments at the beginning explaining that they were generated
-automatically using `configure'. This is so that users won't think of
-trying to edit them by hand.
-
- The `configure' script should write a file named `config.status'
-which describes which configuration options were specified when the
-program was last configured. This file should be a shell script which,
-if run, will recreate the same configuration.
-
- The `configure' script should accept an option of the form
-`--srcdir=DIRNAME' to specify the directory where sources are found (if
-it is not the current directory). This makes it possible to build the
-program in a separate directory, so that the actual source directory is
-not modified.
-
- If the user does not specify `--srcdir', then `configure' should
-check both `.' and `..' to see if it can find the sources. If it finds
-the sources in one of these places, it should use them from there.
-Otherwise, it should report that it cannot find the sources, and should
-exit with nonzero status.
-
- Usually the easy way to support `--srcdir' is by editing a
-definition of `VPATH' into the Makefile. Some rules may need to refer
-explicitly to the specified source directory. To make this possible,
-`configure' can add to the Makefile a variable named `srcdir' whose
-value is precisely the specified directory.
-
- The `configure' script should also take an argument which specifies
-the type of system to build the program for. This argument should look
-like this:
-
- CPU-COMPANY-SYSTEM
-
- For example, a Sun 3 might be `m68k-sun-sunos4.1'.
-
- The `configure' script needs to be able to decode all plausible
-alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
-would be a valid alias. For many programs, `vax-dec-ultrix' would be
-an alias for `vax-dec-bsd', simply because the differences between
-Ultrix and BSD are rarely noticeable, but a few programs might need to
-distinguish them.
-
- There is a shell script called `config.sub' that you can use as a
-subroutine to validate system types and canonicalize aliases.
-
- Other options are permitted to specify in more detail the software
-or hardware present on the machine, and include or exclude optional
-parts of the package:
-
-`--enable-FEATURE[=PARAMETER]'
- Configure the package to build and install an optional user-level
- facility called FEATURE. This allows users to choose which
- optional features to include. Giving an optional PARAMETER of
- `no' should omit FEATURE, if it is built by default.
-
- No `--enable' option should *ever* cause one feature to replace
- another. No `--enable' option should ever substitute one useful
- behavior for another useful behavior. The only proper use for
- `--enable' is for questions of whether to build part of the program
- or exclude it.
-
-`--with-PACKAGE'
- The package PACKAGE will be installed, so configure this package
- to work with PACKAGE.
-
- Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
- `gnu-libc', `gdb', `x', and `x-toolkit'.
-
- Do not use a `--with' option to specify the file name to use to
- find certain files. That is outside the scope of what `--with'
- options are for.
-
-`--nfp'
- The target machine has no floating point processor.
-
-`--gas'
- The target machine assembler is GAS, the GNU assembler. This is
- obsolete; users should use `--with-gnu-as' instead.
-
-`--x'
- The target machine has the X Window System installed. This is
- obsolete; users should use `--with-x' instead.
-
- All `configure' scripts should accept all of these "detail" options,
-whether or not they make any difference to the particular package at
-hand. In particular, they should accept any option that starts with
-`--with-' or `--enable-'. This is so users will be able to configure
-an entire GNU source tree at once with a single set of options.
-
- You will note that the categories `--with-' and `--enable-' are
-narrow: they *do not* provide a place for any sort of option you might
-think of. That is deliberate. We want to limit the possible
-configuration options in GNU software. We do not want GNU programs to
-have idiosyncratic configuration options.
-
- Packages that perform part of the compilation process may support
-cross-compilation. In such a case, the host and target machines for
-the program may be different. The `configure' script should normally
-treat the specified type of system as both the host and the target,
-thus producing a program which works for the same type of machine that
-it runs on.
-
- The way to build a cross-compiler, cross-assembler, or what have
-you, is to specify the option `--host=HOSTTYPE' when running
-`configure'. This specifies the host system without changing the type
-of target system. The syntax for HOSTTYPE is the same as described
-above.
-
- Bootstrapping a cross-compiler requires compiling it on a machine
-other than the host it will run on. Compilation packages accept a
-configuration option `--build=HOSTTYPE' for specifying the
-configuration on which you will compile them, in case that is different
-from the host.
-
- Programs for which cross-operation is not meaningful need not accept
-the `--host' option, because configuring an entire operating system for
-cross-operation is not a meaningful thing.
-
- Some programs have ways of configuring themselves automatically. If
-your program is set up to do this, your `configure' script can simply
-ignore most of its arguments.
-
-\1f
-File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
-
-Makefile Conventions
-====================
-
- This node describes conventions for writing the Makefiles for GNU
-programs. Using Automake will help you write a Makefile that follows
-these conventions.
-
-* Menu:
-
-* Makefile Basics:: General Conventions for Makefiles
-* Utilities in Makefiles:: Utilities in Makefiles
-* Command Variables:: Variables for Specifying Commands
-* Directory Variables:: Variables for Installation Directories
-* Standard Targets:: Standard Targets for Users
-* Install Command Categories:: Three categories of commands in the `install'
- rule: normal, pre-install and post-install.
-
-\1f
-File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
-
-General Conventions for Makefiles
----------------------------------
-
- Every Makefile should contain this line:
-
- SHELL = /bin/sh
-
-to avoid trouble on systems where the `SHELL' variable might be
-inherited from the environment. (This is never a problem with GNU
-`make'.)
-
- Different `make' programs have incompatible suffix lists and
-implicit rules, and this sometimes creates confusion or misbehavior. So
-it is a good idea to set the suffix list explicitly using only the
-suffixes you need in the particular Makefile, like this:
-
- .SUFFIXES:
- .SUFFIXES: .c .o
-
-The first line clears out the suffix list, the second introduces all
-suffixes which may be subject to implicit rules in this Makefile.
-
- Don't assume that `.' is in the path for command execution. When
-you need to run programs that are a part of your package during the
-make, please make sure that it uses `./' if the program is built as
-part of the make or `$(srcdir)/' if the file is an unchanging part of
-the source code. Without one of these prefixes, the current search
-path is used.
-
- The distinction between `./' (the "build directory") and
-`$(srcdir)/' (the "source directory") is important because users can
-build in a separate directory using the `--srcdir' option to
-`configure'. A rule of the form:
-
- foo.1 : foo.man sedscript
- sed -e sedscript foo.man > foo.1
-
-will fail when the build directory is not the source directory, because
-`foo.man' and `sedscript' are in the the source directory.
-
- When using GNU `make', relying on `VPATH' to find the source file
-will work in the case where there is a single dependency file, since
-the `make' automatic variable `$<' will represent the source file
-wherever it is. (Many versions of `make' set `$<' only in implicit
-rules.) A Makefile target like
-
- foo.o : bar.c
- $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
-
-should instead be written as
-
- foo.o : bar.c
- $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
-
-in order to allow `VPATH' to work correctly. When the target has
-multiple dependencies, using an explicit `$(srcdir)' is the easiest way
-to make the rule work well. For example, the target above for `foo.1'
-is best written as:
-
- foo.1 : foo.man sedscript
- sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
-
- GNU distributions usually contain some files which are not source
-files--for example, Info files, and the output from Autoconf, Automake,
-Bison or Flex. Since these files normally appear in the source
-directory, they should always appear in the source directory, not in the
-build directory. So Makefile rules to update them should put the
-updated files in the source directory.
-
- However, if a file does not appear in the distribution, then the
-Makefile should not put it in the source directory, because building a
-program in ordinary circumstances should not modify the source directory
-in any way.
-
- Try to make the build and installation targets, at least (and all
-their subtargets) work correctly with a parallel `make'.
-
END-INFO-DIR-ENTRY
GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999 Free Software Foundation, Inc.
+1997, 1998, 1999, 2000 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
translation approved by the Free Software Foundation.
\1f
+File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
+
+The Release Process
+*******************
+
+ Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems. Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below. Doing so
+makes it easy to include your package into the larger framework of all
+GNU software.
+
+* Menu:
+
+* Configuration:: How Configuration Should Work
+* Makefile Conventions:: Makefile Conventions
+* Releases:: Making Releases
+
+\1f
+File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
+
+How Configuration Should Work
+=============================
+
+ Each GNU distribution should come with a shell script named
+`configure'. This script is given arguments which describe the kind of
+machine and system you want to compile the program for.
+
+ The `configure' script must record the configuration options so that
+they affect compilation.
+
+ One way to do this is to make a link from a standard name such as
+`config.h' to the proper configuration file for the chosen system. If
+you use this technique, the distribution should _not_ contain a file
+named `config.h'. This is so that people won't be able to build the
+program without configuring it first.
+
+ Another thing that `configure' can do is to edit the Makefile. If
+you do this, the distribution should _not_ contain a file named
+`Makefile'. Instead, it should include a file `Makefile.in' which
+contains the input used for editing. Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+ If `configure' does write the `Makefile', then `Makefile' should
+have a target named `Makefile' which causes `configure' to be rerun,
+setting up the same configuration that was set up last time. The files
+that `configure' reads should be listed as dependencies of `Makefile'.
+
+ All the files which are output from the `configure' script should
+have comments at the beginning explaining that they were generated
+automatically using `configure'. This is so that users won't think of
+trying to edit them by hand.
+
+ The `configure' script should write a file named `config.status'
+which describes which configuration options were specified when the
+program was last configured. This file should be a shell script which,
+if run, will recreate the same configuration.
+
+ The `configure' script should accept an option of the form
+`--srcdir=DIRNAME' to specify the directory where sources are found (if
+it is not the current directory). This makes it possible to build the
+program in a separate directory, so that the actual source directory is
+not modified.
+
+ If the user does not specify `--srcdir', then `configure' should
+check both `.' and `..' to see if it can find the sources. If it finds
+the sources in one of these places, it should use them from there.
+Otherwise, it should report that it cannot find the sources, and should
+exit with nonzero status.
+
+ Usually the easy way to support `--srcdir' is by editing a
+definition of `VPATH' into the Makefile. Some rules may need to refer
+explicitly to the specified source directory. To make this possible,
+`configure' can add to the Makefile a variable named `srcdir' whose
+value is precisely the specified directory.
+
+ The `configure' script should also take an argument which specifies
+the type of system to build the program for. This argument should look
+like this:
+
+ CPU-COMPANY-SYSTEM
+
+ For example, a Sun 3 might be `m68k-sun-sunos4.1'.
+
+ The `configure' script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
+would be a valid alias. For many programs, `vax-dec-ultrix' would be
+an alias for `vax-dec-bsd', simply because the differences between
+Ultrix and BSD are rarely noticeable, but a few programs might need to
+distinguish them.
+
+ There is a shell script called `config.sub' that you can use as a
+subroutine to validate system types and canonicalize aliases.
+
+ Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+`--enable-FEATURE[=PARAMETER]'
+ Configure the package to build and install an optional user-level
+ facility called FEATURE. This allows users to choose which
+ optional features to include. Giving an optional PARAMETER of
+ `no' should omit FEATURE, if it is built by default.
+
+ No `--enable' option should *ever* cause one feature to replace
+ another. No `--enable' option should ever substitute one useful
+ behavior for another useful behavior. The only proper use for
+ `--enable' is for questions of whether to build part of the program
+ or exclude it.
+
+`--with-PACKAGE'
+ The package PACKAGE will be installed, so configure this package
+ to work with PACKAGE.
+
+ Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
+ `gnu-libc', `gdb', `x', and `x-toolkit'.
+
+ Do not use a `--with' option to specify the file name to use to
+ find certain files. That is outside the scope of what `--with'
+ options are for.
+
+ All `configure' scripts should accept all of these "detail" options,
+whether or not they make any difference to the particular package at
+hand. In particular, they should accept any option that starts with
+`--with-' or `--enable-'. This is so users will be able to configure
+an entire GNU source tree at once with a single set of options.
+
+ You will note that the categories `--with-' and `--enable-' are
+narrow: they *do not* provide a place for any sort of option you might
+think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
+
+ Packages that perform part of the compilation process may support
+cross-compilation. In such a case, the host and target machines for the
+program may be different.
+
+ The `configure' script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+ To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
+for the host type. So the command would look like this:
+
+ ./configure HOSTTYPE --target=TARGETTYPE
+
+ Programs for which cross-operation is not meaningful need not accept
+the `--target' option, because configuring an entire operating system
+for cross-operation is not a meaningful operation.
+
+ Bootstrapping a cross-compiler requires compiling it on a machine
+other than the host it will run on. Compilation packages accept a
+configuration option `--build=BUILDTYPE' for specifying the
+configuration on which you will compile them, but the configure script
+should normally guess the build machine type (using `config.guess'), so
+this option is probably not necessary. The host and target types
+normally default from the build type, so in bootstrapping a
+cross-compiler you must specify them both explicitly.
+
+ Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your `configure' script can simply
+ignore most of its arguments.
+
+\1f
+File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
+
+Makefile Conventions
+====================
+
+ This node describes conventions for writing the Makefiles for GNU
+programs. Using Automake will help you write a Makefile that follows
+these conventions.
+
+* Menu:
+
+* Makefile Basics:: General Conventions for Makefiles
+* Utilities in Makefiles:: Utilities in Makefiles
+* Command Variables:: Variables for Specifying Commands
+* Directory Variables:: Variables for Installation Directories
+* Standard Targets:: Standard Targets for Users
+* Install Command Categories:: Three categories of commands in the `install'
+ rule: normal, pre-install and post-install.
+
+\1f
+File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
+
+General Conventions for Makefiles
+---------------------------------
+
+ Every Makefile should contain this line:
+
+ SHELL = /bin/sh
+
+to avoid trouble on systems where the `SHELL' variable might be
+inherited from the environment. (This is never a problem with GNU
+`make'.)
+
+ Different `make' programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior. So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+ .SUFFIXES:
+ .SUFFIXES: .c .o
+
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+ Don't assume that `.' is in the path for command execution. When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses `./' if the program is built as
+part of the make or `$(srcdir)/' if the file is an unchanging part of
+the source code. Without one of these prefixes, the current search
+path is used.
+
+ The distinction between `./' (the "build directory") and
+`$(srcdir)/' (the "source directory") is important because users can
+build in a separate directory using the `--srcdir' option to
+`configure'. A rule of the form:
+
+ foo.1 : foo.man sedscript
+ sed -e sedscript foo.man > foo.1
+
+will fail when the build directory is not the source directory, because
+`foo.man' and `sedscript' are in the source directory.
+
+ When using GNU `make', relying on `VPATH' to find the source file
+will work in the case where there is a single dependency file, since
+the `make' automatic variable `$<' will represent the source file
+wherever it is. (Many versions of `make' set `$<' only in implicit
+rules.) A Makefile target like
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+
+should instead be written as
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
+
+in order to allow `VPATH' to work correctly. When the target has
+multiple dependencies, using an explicit `$(srcdir)' is the easiest way
+to make the rule work well. For example, the target above for `foo.1'
+is best written as:
+
+ foo.1 : foo.man sedscript
+ sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
+
+ GNU distributions usually contain some files which are not source
+files--for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex. Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory. So Makefile rules to update them should put the
+updated files in the source directory.
+
+ However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+ Try to make the build and installation targets, at least (and all
+their subtargets) work correctly with a parallel `make'.
+
+\1f
File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
Utilities in Makefiles
basic command for installing a file into the system.
Every Makefile should also define the variables `INSTALL_PROGRAM'
-and `INSTALL_DATA'. (The default for each of these should be
-`$(INSTALL)'.) Then it should use those variables as the commands for
-actual installation, for executables and nonexecutables respectively.
-Use these variables as follows:
+and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
+`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
+644'.) Then it should use those variables as the commands for actual
+installation, for executables and nonexecutables respectively. Use
+these variables as follows:
$(INSTALL_PROGRAM) foo $(bindir)/foo
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
Installation directories should always be named by variables, so it
is easy to install in a nonstandard place. The standard names for these
variables are described below. They are based on a standard filesystem
-layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
-other modern operating systems.
+layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
+and other modern operating systems.
These two variables set the root for the installation. All the other
installation directories should be subdirectories of one of these two,
are using Autoconf, write it as `@prefix@'.)
Running `make install' with a different value of `prefix' from the
- one used to build the program should NOT recompile the program.
+ one used to build the program should _not_ recompile the program.
`exec_prefix'
A prefix used in constructing the default values of some of the
directories.
Running `make install' with a different value of `exec_prefix'
- from the one used to build the program should NOT recompile the
+ from the one used to build the program should _not_ recompile the
program.
Executable programs are installed in one of the following
`srcdir'
The directory for the sources being compiled. The value of this
variable is normally inserted by the `configure' shell script.
- (If you are using Autoconf, use `srcdir = @srcdir@'.)
+ (If you are using Autconf, use `srcdir = @srcdir@'.)
For example:
`install-strip'
Like `install', but strip the executable files while installing
- them. In many cases, the definition of this target can be very
- simple:
+ them. In simple cases, this target can use the `install' target in
+ a simple way:
install-strip:
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
install
+ But if the package installs scripts as well as real executables,
+ the `install-strip' target can't just refer to the `install'
+ target; it has to strip the executables but not the scripts.
+
+ `install-strip' should not strip the executables in the build
+ directory which are being copied for installation. It should only
+ strip the copies that are installed.
+
Normally we do not recommend stripping an executable unless you
are sure the program has no bugs. However, it can be reasonable
to install a stripped executable for actual execution while saving
appropriately named, use `ln' or `cp' to install the proper files
in it, and then `tar' that subdirectory.
- Compress the tar file file with `gzip'. For example, the actual
+ Compress the tar file with `gzip'. For example, the actual
distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
The `dist' target should explicitly depend on all non-source files
$(libdir) $(infodir) \
$(mandir)
+ or, if you wish to support `DESTDIR',
+
+ # Make sure all installation directories (e.g. $(bindir))
+ # actually exist by making them if necessary.
+ installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs \
+ $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+ $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+ $(DESTDIR)$(mandir)
+
This rule should not modify the directories where compilation is
done. It should do nothing but create installation directories.
know what other files to get.
\1f
-File: standards.info, Node: References, Prev: Managing Releases, Up: Top
+File: standards.info, Node: References, Next: Index, Prev: Managing Releases, Up: Top
References to Non-Free Software and Documentation
*************************************************
undermine our position by recommending use of documentation that isn't
free.
-
END-INFO-DIR-ENTRY
\1f
+File: xemacs-faq.info, Node: Q3.1.5, Next: Q3.1.6, Prev: Q3.1.4, Up: Customization
+
+Q3.1.5: How can I get the icon to just say `XEmacs'?
+----------------------------------------------------
+
+ I'd like the icon to just say `XEmacs', and not include the name of
+the current file in it.
+
+ Add the following line to your `init.el'/`.emacs':
+
+ (setq frame-icon-title-format "XEmacs")
+
+\1f
+File: xemacs-faq.info, Node: Q3.1.6, Next: Q3.1.7, Prev: Q3.1.5, Up: Customization
+
+Q3.1.6: How can I have the window title area display the full path?
+-------------------------------------------------------------------
+
+ I'd like to have the window title area display the full
+directory/name of the current buffer file and not just the name.
+
+ Add the following line to your `init.el'/`.emacs':
+
+ (setq frame-title-format "%S: %f")
+
+ A more sophisticated title might be:
+
+ (setq frame-title-format
+ '("%S: " (buffer-file-name "%f"
+ (dired-directory dired-directory "%b"))))
+
+ That is, use the file name, or the dired-directory, or the buffer
+name.
+
+\1f
File: xemacs-faq.info, Node: Q3.1.7, Next: Q3.1.8, Prev: Q3.1.6, Up: Customization
Q3.1.7: `xemacs -name junk' doesn't work?
3.2: Textual Fonts & Colors
===========================
-Q3.2.1: How can I set color options from `.emacs'?
---------------------------------------------------
+Q3.2.1: How can I set color options from `init.el'/`.emacs'?
+------------------------------------------------------------
- How can I set the most commonly used color options from my `.emacs'
-instead of from my `.Xdefaults'?
+ How can I set the most commonly used color options from my
+`init.el'/`.emacs' instead of from my `.Xdefaults'?
Like this:
Emacs.zmacs-region.attributeForeground: firebrick
Emacs.zmacs-region.attributeBackground: lightseagreen
- or in your `.emacs':
+ or in your `init.el'/`.emacs':
(set-face-background 'zmacs-region "red")
(set-face-foreground 'zmacs-region "yellow")
----------------------------------------
I'm using Netscape (or another color grabber like XEmacs); is there
-anyway to limit the number of available colors in the color map?
+any way to limit the number of available colors in the color map?
- XEmacs 19.13 didn't have such a mechanism (unlike netscape, or other
-color-hogs). One solution is to start XEmacs prior to netscape, since
-this will prevent Netscape from grabbing all colors (but Netscape will
-complain). You can use the flags for Netscape, like -mono, -ncols <#>
-or -install (for mono, limiting to <#> colors, or for using a private
-color map). Since Netscape will take the entire colormap and never
-release it, the only reasonable way to run it is with `-install'.
+ Answer: No, but you can start Netscape before XEmacs, and it will use
+the closest available color if the colormap is full. You can also limit
+the number of colors Netscape uses, using the flags -mono, -ncols <#> or
+-install (for mono, limiting to <#> colors, or for using a private color
+map).
If you have the money, another solution would be to use a truecolor
or direct color video.
- Starting with XEmacs 19.14, XEmacs uses the closest available color
-if the colormap is full, so it's O.K. now to start Netscape first.
-
\1f
File: xemacs-faq.info, Node: Q3.2.5, Next: Q3.2.6, Prev: Q3.2.4, Up: Customization
(set-specifier has-modeline-p nil)
- Starting with XEmacs 19.14 the modeline responds to mouse clicks, so
-if you haven't liked or used the modeline in the past, you might want to
-try the new version out.
-
\1f
File: xemacs-faq.info, Node: Q3.3.2, Next: Q3.3.3, Prev: Q3.3.1, Up: Customization
Q3.3.2: How do you have XEmacs display the line number in the modeline?
-----------------------------------------------------------------------
- Add the following line to your `.emacs' file to display the line
-number:
+ Add the following line to your `init.el'/`.emacs' file to display
+the line number:
(line-number-mode 1)
(column-number-mode 1)
- Or select from the `Options' menu
-`Customize->Emacs->Editing->Basics->Line Number Mode' and/or
-`Customize->Emacs->Editing->Basics->Column Number Mode'
+ Or select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Basics->Line Number Mode' and/or `Advanced
+(Customize)->Emacs->Editing->Basics->Column Number Mode'
Or type `M-x customize <RET> editing-basics <RET>'.
Q3.3.3: How do I get XEmacs to put the time of day on the modeline?
-------------------------------------------------------------------
- Add the following line to your `.emacs' file to display the time:
+ Add the following line to your `init.el'/`.emacs' file to display
+the time:
(display-time)
With AUC TeX, fast typing is hard because the current chapter,
section etc. are given in the modeline. How can I turn this off?
- It's not AUC TeX, it comes from `func-menu' in `func-menu.el'. Add
-this code to your `.emacs' to turn it off:
-
- (setq fume-display-in-modeline-p nil)
-
- Or just add a hook to `TeX-mode-hook' to turn it off only for TeX
-mode:
-
- (add-hook 'TeX-mode-hook
- '(lambda () (setq fume-display-in-modeline-p nil)))
+ It's not AUC TeX, it comes from `func-menu' in `func-menu.el'.
David Hughes <dhughes@origin-at.co.uk> writes:
- If you have 19.14 or later, try this instead; you'll still get the
- function name displayed in the modeline, but it won't attempt to
- keep track when you modify the file. To refresh when it gets out
- of synch, you simply need click on the `Rescan Buffer' option in
- the function-menu.
+ Try this; you'll still get the function name displayed in the
+ modeline, but it won't attempt to keep track when you modify the
+ file. To refresh when it gets out of synch, you simply need click
+ on the `Rescan Buffer' option in the function-menu.
(setq-default fume-auto-rescan-buffer-p nil)
(set-face-background 'modeline "red" (current-buffer))))
Then, when editing a Lisp file (i.e. when in Lisp mode), the modeline
-colors change from the default set in your `.emacs'. The change will
-only be made in the buffer you just entered (which contains the Lisp
-file you are editing) and will not affect the modeline colors anywhere
-else.
+colors change from the default set in your `init.el'/`.emacs'. The
+change will only be made in the buffer you just entered (which contains
+the Lisp file you are editing) and will not affect the modeline colors
+anywhere else.
Notes:
* The hook is the mode name plus `-hook'. eg. c-mode-hook,
- c++-mode-hook, emacs-lisp-mode-hook (used for your `.emacs' or a
- `xx.el' file), lisp-interaction-mode-hook (the `*scratch*'
- buffer), text-mode-hook, etc.
+ c++-mode-hook, emacs-lisp-mode-hook (used for your
+ `init.el'/`.emacs' or a `xx.el' file), lisp-interaction-mode-hook
+ (the `*scratch*' buffer), text-mode-hook, etc.
* Be sure to use `add-hook', not `(setq c-mode-hook xxxx)',
otherwise you will erase anything that anybody has already put on
(current-buffer))' if you wish the modeline font to vary based on
the current mode.
- This works in 19.15 as well, but there are additional modeline faces,
-`modeline-buffer-id', `modeline-mousable', and
-`modeline-mousable-minor-mode', which you may want to customize.
+ There are additional modeline faces, `modeline-buffer-id',
+`modeline-mousable', and `modeline-mousable-minor-mode', which you may
+want to customize.
\1f
File: xemacs-faq.info, Node: Q3.4.1, Next: Q3.4.2, Prev: Q3.3.5, Up: Customization
Q3.4.1: How do I open a frame on another screen of my multi-headed display?
---------------------------------------------------------------------------
- The support for this was revamped for 19.14. Use the command `M-x
-make-frame-on-display'. This command is also on the File menu in the
-menubar.
+ Use the command `M-x make-frame-on-display'. This command is also
+on the File menu in the menubar.
- XEmacs 19.14 and later also have the command `make-frame-on-tty'
-which will establish a connection to any tty-like device. Opening the
-TTY devices should be left to `gnuclient', though.
+ The command `make-frame-on-tty' also exists, which will establish a
+connection to any tty-like device. Opening the TTY devices should be
+left to `gnuclient', though.
\1f
File: xemacs-faq.info, Node: Q3.4.2, Next: Q3.5.1, Prev: Q3.4.1, Up: Customization
Q3.4.2: Can I really connect to a running XEmacs after calling up over a modem? How?
-------------------------------------------------------------------------------------
- If you're not running at least XEmacs 19.14, you can't. Otherwise
-check out the `gnuattach' program supplied with XEmacs. Starting with
-XEmacs 20.3, `gnuattach' and `gnudoit' functionality is provided by
-`gnuclient'.
+ Yes. Use `gnuclient -nw'. (Prior to 20.3, use the `gnuattach'
+program supplied with XEmacs instead.)
Also *Note Q5.0.12::.
Q3.5.2: How can I stop down-arrow from adding empty lines to the bottom of my buffers?
--------------------------------------------------------------------------------------
- Add the following line to your `.emacs' file:
+ Add the following line to your `init.el'/`.emacs' file:
(setq next-line-add-newlines nil)
I cannot manage to globally bind my `Delete' key to something other
than the default. How does one do this?
+ Answer: The problem is that many modes explicitly bind `Delete'. To
+get around this, try the following:
+
(defun foo ()
(interactive)
(message "You hit DELETE"))
- (global-set-key 'delete 'foo)
-
- However, some modes explicitly bind `Delete', so you would need to
-add a hook that does `local-set-key' for them. If what you want to do
-is make the Backspace and Delete keys work more PC/Motif-like, then
-take a look at the `delbs.el' package.
-
- New in XEmacs 19.14 is a variable called `key-translation-map' which
-makes it easier to bind `Delete'. `delbs.el' is a good example of how
-to do this correctly.
+ (define-key key-translation-map 'delete 'redirected-delete)
+ (global-set-key 'redirected-delete 'foo)
Also *Note Q3.5.10::.
(setq scroll-step 1)
Starting with XEmacs-20.3 you can also change this with Customize.
-Select from the `Options' menu
-`Customize->Emacs->Environment->Windows->Scroll Step...' or type `M-x
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Windows->Scroll Step...' or type `M-x
customize <RET> windows <RET>'.
\1f
(global-set-key [help] 'help-command);; Help
- The following works in XEmacs 19.15 with the addition of shift:
+ The following works in XEmacs with the addition of shift:
(global-set-key [(shift help)] 'help-command);; Help
One way is to use the package `x-compose'. Then you can use
sequences like `Compose " a' to get ä, etc.
- Another way is to use the `iso-insert' package, provided in XEmacs
-19.15 and later. Then you can use sequences like `C-x 8 " a' to get ä,
-etc.
+ Another way is to use the `iso-insert' package. Then you can use
+sequences like `C-x 8 " a' to get ä, etc.
Glynn Clements <glynn@sensei.co.uk> writes:
\1f
File: xemacs-faq.info, Node: Q3.5.8, Next: Q3.5.9, Prev: Q3.5.7, Up: Customization
-Q3.5.8: Why does `(global-set-key [delete-forward] 'delete-char)' complain?
----------------------------------------------------------------------------
-
- Why does `(define-key global-map [ delete-forward ] 'delete-char)'
-complain of not being able to bind an unknown key?
-
- Try this instead:
-
- (define-key global-map [delete_forward] 'delete-char)
-
- and it will work.
-
- What you are seeing above is a bug due to code that is trying to
-check for GNU Emacs syntax like:
-
- (define-key global-map [C-M-a] 'delete-char)
-
- which otherwise would cause no errors but would not result in the
-expected behavior.
+Q3.5.8: [This question intentionally left blank]
+------------------------------------------------
- This bug has been fixed in 19.14.
+ Obsolete question, left blank to avoid renumbering.
\1f
File: xemacs-faq.info, Node: Q3.5.9, Next: Q3.5.10, Prev: Q3.5.8, Up: Customization
Starting with XEmacs-20.3 better solution is to set variable
`delete-key-deletes-forward' to t. You can also change this with
-Customize. Select from the `Options' menu
-`Customize->Emacs->Editing->Basics->Delete Key Deletes Forward' or type
-`M-x customize <RET> editing-basics <RET>'.
+Customize. Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Basics->Delete Key Deletes Forward' or
+type `M-x customize <RET> editing-basics <RET>'.
Also *Note Q3.5.4::.
(setq bar-cursor 'anything-else)
Starting with XEmacs-20.3 you can also change these with Customize.
-Select from the `Options' menu
-`Customize->Emacs->Environment->Display->Bar Cursor...' or type `M-x
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Display->Bar Cursor...' or type `M-x
customize <RET> display <RET>'.
You can use a color to make it stand out better:
(setq bar-cursor nil)
- Starting with XEmacs-20.3 you can also change this with Customize.
-Select from the `Options' menu
-`Customize->Emacs->Environment->Display->Bar Cursor...' or type `M-x
+ Starting with XEmacs 20.3 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Display->Bar Cursor...' or type `M-x
customize <RET> display <RET>'.
\1f
Q3.6.3: Can I make the cursor blink?
------------------------------------
- If you are running a version of XEmacs older than 19.14, no.
-Otherwise you can do the following:
+ Yes, like this:
(blink-cursor-mode)
Examine the function `mouse-yank', by typing `C-h f mouse-yank
<RET>'.
- To get XEmacs to paste at the text cursor, add this your `.emacs':
+ To get XEmacs to paste at the text cursor, add this your
+`init.el'/`.emacs':
(setq mouse-yank-at-point t)
Starting with XEmacs-20.2 you can also change this with Customize.
-Select from the `Options' menu `Customize->Emacs->Editing->Mouse->Yank
-At Point...' or type `M-x customize <RET> mouse <RET>'.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Mouse->Yank At Point...' or type `M-x
+customize <RET> mouse <RET>'.
\1f
File: xemacs-faq.info, Node: Q3.7.7, Next: Q3.7.8, Prev: Q3.7.6, Up: Customization
(setq mouse-track-rectangle-p t)
Starting with XEmacs-20.2 you can also change this with Customize.
-Select from the `Options' menu `Customize->Emacs->Editing->Mouse->Track
-Rectangle...' or type `M-x customize <RET> mouse <RET>'.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Mouse->Track Rectangle...' or type `M-x
+customize <RET> mouse <RET>'.
mouse-track-do-rectangle: (event)
-- an interactive compiled Lisp function.
Q3.8.1: How do I get rid of the menu (or menubar)?
--------------------------------------------------
- If you are running XEmacs 19.13 and earlier, add this command to your
-`.emacs'.
-
- (set-menubar nil)
-
- Starting with XEmacs 19.14 the preferred method is:
-
(set-specifier menubar-visible-p nil)
\1f
Q3.8.2: Can I customize the basic menubar?
------------------------------------------
- For an extensive menubar, add this line to your `.emacs':
+ For an extensive menubar, add this line to your `init.el'/`.emacs':
(load "big-menubar")
Q3.8.3: How do I control how many buffers are listed in the menu `Buffers List'?
--------------------------------------------------------------------------------
- Add the following to your `.emacs' (suit to fit):
+ Add the following to your `init.el'/`.emacs' (suit to fit):
(setq buffers-menu-max-size 20)
For no limit, use an argument of `nil'.
Starting with XEmacs-20.3 you can also change this with Customize.
-Select from the `Options' menu
-`Customize->Emacs->Environment->Menu->Buffers Menu->Max Size...' or
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Menu->Buffers Menu->Max Size...' or
type `M-x customize <RET> buffers-menu <RET>'.
\1f
(set-specifier scrollbar-width 0 (current-buffer))
- In XEmacs versions prior to 19.14, you had to use the hairier
-construct:
-
- (set-specifier scrollbar-width (cons (selected-frame) 0))
-
\1f
File: xemacs-faq.info, Node: Q3.9.2, Next: Q3.9.3, Prev: Q3.9.1, Up: Customization
\1f
File: xemacs-faq.info, Node: Q3.9.4, Next: Q3.10.1, Prev: Q3.9.3, Up: Customization
-Q3.9.4: How can I get automatic horizontal scrolling?
------------------------------------------------------
-
- By the same token, how can I turn it off in specific modes?
-
- To do this, add to your `.emacs' file:
-
- (require 'auto-show)
+Q3.9.4: How can I turn off automatic horizontal scrolling in specific modes?
+----------------------------------------------------------------------------
- Then do `(setq truncate-lines t)' in the mode-hooks for any modes in
+ Do `(setq truncate-lines t)' in the mode-hooks for any modes in
which you want lines truncated.
More precisely: If `truncate-lines' is nil, horizontal scrollbars
then horizontal scrollbars will not appear in truncated buffers
unless the package specifically asked for them.
- Automatic horizontal scrolling is now standard, starting with 19.14.
-
\1f
File: xemacs-faq.info, Node: Q3.10.1, Next: Q3.10.2, Prev: Q3.9.4, Up: Customization
The `zmacs' mode allows for what some might call gratuitous
highlighting for selected regions (either by setting mark or by using
the mouse). This is the default behavior. To turn off, add the
-following line to your `.emacs' file:
+following line to your `init.el'/`.emacs' file:
(setq zmacs-regions nil)
Starting with XEmacs-20.2 you can also change this with Customize.
-Select from the `Options' menu `Customize->Emacs->Editing->Basics->Zmacs
-Regions' or type `M-x customize <RET> editing-basics <RET>'.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Basics->Zmacs Regions' or type `M-x
+customize <RET> editing-basics <RET>'.
To change the face for selection, look at `Options->Customize' on
the menubar.
and you press a key to replace the selected region by the key you typed.
Usually backspace kills the selected region.
- To get this behavior, add the following lines to your `.emacs':
+ To get this behavior, add the following lines to your
+`init.el'/`.emacs':
(cond
((fboundp 'turn-on-pending-delete)
I do not like my text highlighted while I am doing isearch as I am
not able to see what's underneath. How do I turn it off?
- Put the following in your `.emacs':
+ Put the following in your `init.el'/`.emacs':
(setq isearch-highlight nil)
(autoload 'smiley-buffer "smiley" nil t)
(add-hook 'mime-viewer/plain-text-preview-hook 'smiley-buffer)
+\1f
+File: xemacs-faq.info, Node: Q4.0.12, Next: Q4.1.1, Prev: Q4.0.11, Up: Subsystems
+
+Q4.0.12: Customization of VM not covered in the manual, or here.
+----------------------------------------------------------------
+
+ giacomo boffi <boffi@hp735.stru.polimi.it> writes:
+
+ The meta-answer is to look into the file `vm-vars.el', in the vm
+ directory of the lisp library.
+
+ `vm-vars.el' contains, initializes and carefully describes, with
+ examples of usage, the plethora of user options that _fully_
+ control VM's behavior.
+
+ Enter vm-vars, `forward-search' for toolbar, find the variables
+ that control the toolbar placement, appearance, existence, copy to
+ your `init.el'/`.emacs' or `.vm' and modify according to the
+ detailed instructions.
+
+ The above also applies to all the various features of VM: search
+ for some keywords, maybe the first you conjure isn't appropriate,
+ find the appropriate variables, copy and experiment.
+
END-INFO-DIR-ENTRY
\1f
-File: xemacs-faq.info, Node: Q4.0.12, Next: Q4.1.1, Prev: Q4.0.11, Up: Subsystems
-
-Q4.0.12: Customization of VM not covered in the manual, or here.
-----------------------------------------------------------------
-
- giacomo boffi <boffi@hp735.stru.polimi.it> writes:
-
- The meta-answer is to look into the file `vm-vars.el', in the vm
- directory of the lisp library.
-
- `vm-vars.el' contains, initializes and carefully describes, with
- examples of usage, the plethora of user options that _fully_
- control VM's behavior.
-
- Enter vm-vars, `forward-search' for toolbar, find the variables
- that control the toolbar placement, appearance, existence, copy to
- your `.emacs' or `.vm' and modify according to the detailed
- instructions.
-
- The above also applies to all the various features of VM: search
- for some keywords, maybe the first you conjure isn't appropriate,
- find the appropriate variables, copy and experiment.
-
-\1f
File: xemacs-faq.info, Node: Q4.1.1, Next: Q4.1.2, Prev: Q4.0.12, Up: Subsystems
4.1: Web browsing with W3
* Q5.0.1:: How can I do source code highlighting using font-lock?
* Q5.0.2:: I do not like cc-mode. How do I use the old c-mode?
* Q5.0.3:: How do I get `More' Syntax Highlighting on by default?
-* Q5.0.4:: How can I enable auto-indent?
+* Q5.0.4:: How can I enable auto-indent and/or Filladapt?
* Q5.0.5:: How can I get XEmacs to come up in text/auto-fill mode by default?
* Q5.0.6:: How do I start up a second shell buffer?
* Q5.0.7:: Telnet from shell filters too much.
* Q5.0.8:: Why does edt emulation not work?
* Q5.0.9:: How can I emulate VI and use it as my default mode?
* Q5.0.10:: [This question intentionally left blank]
-* Q5.0.11:: How do I turn on filladapt for all buffers?
+* Q5.0.11:: [This question intentionally left blank]
* Q5.0.12:: How do I disable gnuserv from opening a new frame?
* Q5.0.13:: How do I start gnuserv so that each subsequent XEmacs is a client?
* Q5.0.14:: Strange things are happening in Shell Mode.
Miscellaneous:
* Q5.3.1:: How do you make XEmacs indent CL if-clauses correctly?
-* Q5.3.2:: Fontifying hangs when editing a postscript file.
+* Q5.3.2:: [This question intentionally left blank]
* Q5.3.3:: How can I print WYSIWYG a font-locked buffer?
* Q5.3.4:: Getting M-x lpr to work with postscript printer.
* Q5.3.5:: How do I specify the paths that XEmacs uses for finding files?
--------------------------------------------------------------
For most modes, font-lock is already set up and just needs to be
-turned on. This can be done by `M-x font-lock-mode', or by having
-XEmacs automatically start it by adding lines like:
+turned on. This can be done by adding the line:
- (add-hook 'emacs-lisp-mode-hook 'turn-on-font-lock)
- (add-hook 'dired-mode-hook 'turn-on-font-lock)
+ (require 'font-lock)
- to your `.emacs'. See the file `etc/sample.emacs' for more examples.
+ to your `init.el'/`.emacs'. (You can turn it on for the current
+buffer and session only by `M-x font-lock-mode'.) See the file
+`etc/sample.init.el' (`etc/sample.emacs' in XEmacs versions prior to
+21.4) for more information.
See also `Syntax Highlighting' from the `Options' menu. Remember to
save options.
getting your old offsets to work, try using `c-set-offset' instead.
You might also consider using the package `cc-compat'.
- But, if you still insist, add the following lines to your `.emacs':
+ But, if you still insist, add the following lines to your
+`init.el'/`.emacs':
(fmakunbound 'c-mode)
(makunbound 'c-mode-map)
Q5.0.3: How do I get `More' Syntax Highlighting on by default?
--------------------------------------------------------------
- Use the following code in your `.emacs':
+ Use the following code in your `init.el'/`.emacs':
(setq-default font-lock-maximum-decoration t)
- In versions of XEmacs prior to 19.14, you had to use a kludgy
-solution like this:
-
- (setq c-font-lock-keywords c-font-lock-keywords-2
- c++-font-lock-keywords c++-font-lock-keywords-2
- lisp-font-lock-keywords lisp-font-lock-keywords-2)
-
- It will work for C, C++ and Lisp.
-
See also `Syntax Highlighting' from the `Options' menu. Remember to
save options.
\1f
File: xemacs-faq.info, Node: Q5.0.4, Next: Q5.0.5, Prev: Q5.0.3, Up: Miscellaneous
-Q5.0.4: How can I enable auto-indent?
--------------------------------------
+Q5.0.4: How can I enable auto-indent and/or Filladapt?
+------------------------------------------------------
- Put the following line in your `.emacs':
+ Put the following line in your `init.el'/`.emacs':
(setq indent-line-function 'indent-relative-maybe)
If you want to get fancy, try the `filladapt' package available
-standard with XEmacs. Put this into your `.emacs':
+standard with XEmacs. Put this into your `init.el'/`.emacs':
(require 'filladapt)
- (add-hook 'text-mode-hook 'turn-on-filladapt-mode)
- ;;; and others ...
+ (setq-default filladapt-mode t)
+ (add-hook 'c-mode-hook 'turn-off-filladapt-mode)
+
+ This will enable Filladapt for all modes except C mode, where it
+doesn't work well. To turn Filladapt on only in particular major
+modes, remove the `(setq-default ...)' line and use
+`turn-on-filladapt-mode', like this:
+
+ (add-hook 'text-mode-hook 'turn-on-filladapt-mode)
You can customize filling and adaptive filling with Customize.
-Select from the `Options' menu
-`Customize->Emacs->->Editing->Fill->Fill...' or type `M-x customize
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Fill->Fill...' or type `M-x customize
<RET> fill <RET>'.
Note that well-behaving text-lookalike modes will run
Q5.0.5: How can I get XEmacs to come up in text/auto-fill mode by default?
--------------------------------------------------------------------------
- Try the following lisp in your `.emacs':
+ Try the following lisp in your `init.el'/`.emacs':
(setq default-major-mode 'text-mode)
(setq text-mode-hook 'turn-on-auto-fill)
We don't know, but you can use tpu-edt emulation instead, which works
fine and is a little fancier than the standard edt emulation. To do
-this, add the following line to your `.emacs':
+this, add the following line to your `init.el'/`.emacs':
(tpu-edt)
-----------------------------------------------------------
Our recommended VI emulator is viper. To make viper-mode the default,
-add this to your `.emacs':
+add this to your `init.el'/`.emacs':
(viper-mode)
Michael Kifer <kifer@CS.SunySB.EDU> writes:
- This should be added as close to the top of `.emacs' as you can get
- it, otherwise some minor modes may not get viper-ized.
+ This should be added as close to the top of `init.el'/`.emacs' as
+ you can get it, otherwise some minor modes may not get viper-ized.
\1f
File: xemacs-faq.info, Node: Q5.0.10, Next: Q5.0.11, Prev: Q5.0.9, Up: Miscellaneous
\1f
File: xemacs-faq.info, Node: Q5.0.11, Next: Q5.0.12, Prev: Q5.0.10, Up: Miscellaneous
-Q5.0.11: How do I turn on filladapt for all buffers?
-----------------------------------------------------
-
- Filladapt is a minor mode and minor modes are traditionally off by
-default. The following added to your `.emacs' will turn it on for all
-buffers:
-
- (setq-default filladapt-mode t)
-
- Use `turn-on-filladapt-mode' to turn Filladapt on in particular
-major modes, like this:
+Q5.0.11: [This question intentionally left blank]
+-------------------------------------------------
- (add-hook 'text-mode-hook 'turn-on-filladapt-mode)
+ Obsolete question, left blank to avoid renumbering
\1f
File: xemacs-faq.info, Node: Q5.0.12, Next: Q5.0.13, Prev: Q5.0.11, Up: Miscellaneous
(setq gnuserv-frame (selected-frame))
- early on in your `.emacs', to ensure that the first frame created is
-the one used for your gnuserv buffers.
+ early on in your `init.el'/`.emacs', to ensure that the first frame
+created is the one used for your gnuserv buffers.
- Starting in 19.15, there is an option to set the gnuserv target to
-the current frame. See `Options->"Other Window" Location->Make current
-frame gnuserv target'
+ There is an option to set the gnuserv target to the current frame.
+See `Options->Display->"Other Window" Location->Make Current Frame
+Gnuserv Target'
Starting with XEmacs-20.3 you can also change this with Customize.
-Select from the `Options' menu
-`Customize->Emacs->Environment->Gnuserv->Gnuserv Frame...' or type `M-x
-customize <RET> gnuserv <RET>'.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Gnuserv->Gnuserv Frame...' or type
+`M-x customize <RET> gnuserv <RET>'.
\1f
File: xemacs-faq.info, Node: Q5.0.13, Next: Q5.0.14, Prev: Q5.0.12, Up: Miscellaneous
Q5.0.13: How do I start gnuserv so that each subsequent XEmacs is a client?
---------------------------------------------------------------------------
- Put the following in your `.emacs' file to start the server:
+ Put the following in your `init.el'/`.emacs' file to start the
+server:
(gnuserv-start)
`auto-show-mode' controls whether or not a horizontal scrollbar
magically appears when a line is too long to be displayed. This is
-enabled by default. To turn it off, put the following in your `.emacs':
+enabled by default. To turn it off, put the following in your
+`init.el'/`.emacs':
(setq auto-show-mode nil)
(setq-default auto-show-mode nil)
Q5.0.17: How can I get two instances of info?
---------------------------------------------
- You can't. The `info' package does not provide for multiple info
-buffers.
+ Before 21.4, you can't. The `info' package does not provide for
+multiple info buffers. In 21.4, this should be fixed. #### how?
\1f
File: xemacs-faq.info, Node: Q5.0.18, Next: Q5.0.19, Prev: Q5.0.17, Up: Miscellaneous
Please try not to make your code much uglier to gain a very small
speed gain. It's not usually worth it.
+\1f
+File: xemacs-faq.info, Node: Q5.1.9, Next: Q5.1.10, Prev: Q5.1.8, Up: Miscellaneous
+
+Q5.1.9: How do I put a glyph as annotation in a buffer?
+-------------------------------------------------------
+
+ Here is a solution that will insert the glyph annotation at the
+beginning of buffer:
+
+ (make-annotation (make-glyph '([FORMAT :file FILE]
+ [string :data "fallback-text"]))
+ (point-min)
+ 'text
+ (current-buffer))
+
+ Replace `FORMAT' with an unquoted symbol representing the format of
+the image (e.g. `xpm', `xbm', `gif', `jpeg', etc.) Instead of `FILE',
+use the image file name (e.g.
+`/usr/local/lib/xemacs-21.4/etc/recycle.xpm').
+
+ You can turn this to a function (that optionally prompts you for a
+file name), and inserts the glyph at `(point)' instead of `(point-min)'.
+
END-INFO-DIR-ENTRY
\1f
-File: xemacs-faq.info, Node: Q5.1.9, Next: Q5.1.10, Prev: Q5.1.8, Up: Miscellaneous
-
-Q5.1.9: How do I put a glyph as annotation in a buffer?
--------------------------------------------------------
-
- Here is a solution that will insert the glyph annotation at the
-beginning of buffer:
-
- (make-annotation (make-glyph '([FORMAT :file FILE]
- [string :data "fallback-text"]))
- (point-min)
- 'text
- (current-buffer))
-
- Replace `FORMAT' with an unquoted symbol representing the format of
-the image (e.g. `xpm', `xbm', `gif', `jpeg', etc.) Instead of `FILE',
-use the image file name (e.g.
-`/usr/local/lib/xemacs-20.2/etc/recycle.xpm').
-
- You can turn this to a function (that optionally prompts you for a
-file name), and inserts the glyph at `(point)' instead of `(point-min)'.
-
-\1f
File: xemacs-faq.info, Node: Q5.1.10, Next: Q5.1.11, Prev: Q5.1.9, Up: Miscellaneous
Q5.1.10: `map-extents' won't traverse all of my extents!
an easy way to find out where it spends time?
- zHrvoje Niksic <hniksic@xemacs.org> writes:
- Under XEmacs 20.4 and later you can use `M-x
- profile-key-sequence', press a key (say <RET> in the Gnus Group
- buffer), and get the results using `M-x profile-results'. It
- should give you an idea of where the time is being spent.
+ Hrvoje Niksic <hniksic@xemacs.org> writes:
+ Under XEmacs 20.4 and later you can use `M-x profile-key-sequence',
+ press a key (say <RET> in the Gnus Group buffer), and get the
+ results using `M-x profile-results'. It should give you an idea of
+ where the time is being spent.
\1f
File: xemacs-faq.info, Node: Q5.2.1, Next: Q5.2.2, Prev: Q5.1.11, Up: Miscellaneous
Q5.2.1: How do I turn off the sound?
------------------------------------
- Add the following line to your `.emacs':
+ Add the following line to your `init.el'/`.emacs':
(setq bell-volume 0)
(setq sound-alist nil)
That will make your XEmacs totally silent--even the default ding
sound (TTY beep on TTY-s) will be gone.
- Starting with XEmacs-20.2 you can also change these with Customize.
-Select from the `Options' menu
-`Customize->Emacs->Environment->Sound->Sound...' or type `M-x customize
-<RET> sound <RET>'.
+ Starting with XEmacs 20.2 you can also change these with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Sound->Sound...' or type `M-x
+customize <RET> sound <RET>'.
\1f
File: xemacs-faq.info, Node: Q5.2.2, Next: Q5.2.3, Prev: Q5.2.1, Up: Miscellaneous
-----------------------------------------------------------
Make sure your XEmacs was compiled with sound support, and then put
-this in your `.emacs':
+this in your `init.el'/`.emacs':
(load-default-sounds)
- The sound support in XEmacs 19.14 was greatly improved over previous
-versions.
-
\1f
File: xemacs-faq.info, Node: Q5.2.3, Next: Q5.2.4, Prev: Q5.2.2, Up: Miscellaneous
same amount instead of indenting the 3rd clause differently from the
first two.
- One way is to add, to `.emacs':
+ One way is to add, to `init.el'/`.emacs':
(put 'if 'lisp-indent-function nil)
\1f
File: xemacs-faq.info, Node: Q5.3.2, Next: Q5.3.3, Prev: Q5.3.1, Up: Miscellaneous
-Q5.3.2: Fontifying hang when editing a postscript file.
--------------------------------------------------------
-
- When I try to edit a postscript file it gets stuck saying:
-`fontifying 'filename' (regexps....)' and it just sits there. If I
-press `C-c' in the window where XEmacs was started, it suddenly becomes
-alive again.
-
- This was caused by a bug in the Postscript font-lock regular
-expressions. It was fixed in 19.13. For earlier versions of XEmacs,
-have a look at your `.emacs' file. You will probably have a line like:
-
- (add-hook 'postscript-mode-hook 'turn-on-font-lock)
+Q5.3.2: [This question intentionally left blank]
+------------------------------------------------
- Take it out, restart XEmacs, and it won't try to fontify your
-postscript files anymore.
+ Obsolete question, left blank to avoid renumbering.
\1f
File: xemacs-faq.info, Node: Q5.3.3, Next: Q5.3.4, Prev: Q5.3.2, Up: Miscellaneous
Postscript files, so how do I get `M-x lpr-region' and `M-x lpr-buffer'
to work?
- Put something like this in your `.emacs':
+ Put something like this in your `init.el'/`.emacs':
(setq lpr-command "a2ps")
(setq lpr-switches '("-p" "-1"))
* Q6.0.1:: What is the status of the XEmacs port to Windows?
* Q6.0.2:: What flavors of MS Windows are supported?
* Q6.0.3:: Where are the XEmacs on MS Windows binaries?
-* Q6.0.4:: Does XEmacs on MS Windows require an X server to run?
+* Q6.0.4:: Can I build XEmacs on MS Windows with support for X or Cygwin?
Building XEmacs on MS Windows
* Q6.1.1:: I decided to run with X. Where do I get an X server?
Customization and User Interface
* Q6.2.1:: How will the port cope with differences in the Windows user interface?
* Q6.2.2:: How do I change fonts in XEmacs on MS Windows?
-* Q6.2.3:: Where do I put my `.emacs' file?
+* Q6.2.3:: Where do I put my `init.el'/`.emacs' file?
Miscellaneous
* Q6.3.1:: Will XEmacs rename all the win32-* symbols to w32-*?
list at <xemacs-nt@xemacs.org> is dedicated to that effort (please use
the -request address to subscribe).
- At this time, XEmacs on MS Windows is usable, but lacks some of the
-features of XEmacs on UNIX and UNIX-like systems. Notably,
-internationalization does not work.
+ At this time, XEmacs on MS Windows is stable and full-featured.
+However, the internationalization (Mule) support does not work -
+although this is being actively worked on.
\1f
File: xemacs-faq.info, Node: Q6.0.2, Next: Q6.0.3, Prev: Q6.0.1, Up: MS Windows
Q6.0.2: What flavors of MS Windows are supported? The list name implies NT only.
---------------------------------------------------------------------------------
- The list name is misleading, as XEmacs will support both Windows 95,
-Windows 98 and Windows NT. The MS Windows-specific code is based on
+ The list name is misleading, as XEmacs will support Windows 95,
+Windows 98, Windows NT, Windows 2000, Windows ME, Windows XP, and all
+newer versions of Windows. The MS Windows-specific code is based on
Microsoft Win32 API, and will not work on MS Windows 3.x or on MS-DOS.
\1f
File: xemacs-faq.info, Node: Q6.0.3, Next: Q6.0.4, Prev: Q6.0.2, Up: MS Windows
-Q6.0.3: Are binary kits available?
-----------------------------------
+Q6.0.3: Are binaries available?
+-------------------------------
- Binary kits are available at
-`ftp://ftp.xemacs.org/pub/xemacs/binary-kits/win32/' for the "plain" MS
+ Binaries are available at
+`ftp://ftp.xemacs.org/pub/xemacs/binaries/win32/' for the native MS
Windows version.
\1f
File: xemacs-faq.info, Node: Q6.0.4, Next: Q6.1.1, Prev: Q6.0.3, Up: MS Windows
-Q6.0.4: Does XEmacs on MS Windows require an X server to run?
--------------------------------------------------------------
+Q6.0.4: Can I build XEmacs on MS Windows with support for X or Cygwin?
+----------------------------------------------------------------------
- Short answer: No.
+ Yes. XEmacs can be built in several ways in the MS Windows
+environment.
- Long answer: XEmacs can be built in several ways in the MS Windows
-environment, some of them requiring an X server and some not.
+ The standard way is what we call the "native" port. It uses the
+Win32 API and has no connection with X whatsoever - it does not require
+X libraries to build, nor does it require an X server to run. The
+native port is the most reliable version and provides the best graphical
+support. Almost all development is geared towards this version, and
+there is little reason not to use it.
- One is what we call the "X" port--it requires X libraries to build
+ You can also build XEmacs "X" port--it requires X libraries to build
and an X server to run. Internally it uses the Xt event loop and makes
-use of X toolkits. Its look is quite un-Windowsy, but it works
-reliably and supports all of the graphical features of Unix XEmacs.
-
- The other is what we call the "native" port. It uses the Win32 API
-and does not require X libraries to build, nor does it require an X to
-run. In fact, it has no connection with X whatsoever. At this time,
-the native port obsoletes the X port, providing almost all of its
-features, including support for menus, scrollbars, toolbars, embedded
-images and background pixmaps, frame pointers, etc. Most of the future
-work will be based on the native port.
+use of X toolkits. Its look is quite un-Windowsy, and it is not well
+maintained, but it is being kept around for the time being because it
+has a long history.
There is also a third special case, the Cygwin port. It takes
advantage of Cygnus emulation library under Win32, which enables it to
reuse much of the Unix XEmacs code base, such as processes and network
support, or internal select() mechanisms.
- Cygwin port supports all display types--TTY, X & MS gui, and can be
-built with support for all three. If you build with ms gui support
+ Cygwin port supports all display types--TTY, X & MS GUI, and can be
+built with support for all three. If you build with MS GUI support
then the Cygwin version uses the majority of the msw code, which is
mostly related to display. If you want to build with X support you
-need X libraries. If you want to build with tty support you need
-ncurses. MS gui requires no additional libraries.
-
- Some of the advantages of the Cygwin version are that it:
-
- * integrates well with Cygwin environment for existing Cygwin users;
-
- * uses configure so building with different features is very easy;
-
- * has process support in X & tty.
+need X libraries. If you want to build with TTY support you need
+ncurses. MS GUI requires no additional libraries.
+ The advantages of the Cygwin version are that it integrates well with
+Cygwin environment for existing Cygwin users; uses configure so building
+with different features is very easy; and has process support in X &
+tty.
The disadvantage is that it requires several Unix utilities and the
whole Cygwin environment, whereas the native port requires only a
Similar as on Unix; use the usual `configure' and `make' process.
Some problems to watch out for:
- * make sure HOME is set. This controls where you `.emacs' file comes
- from;
+ * make sure HOME is set. This controls where you `init.el'/`.emacs'
+ file comes from;
* CYGWIN needs to be set to tty for process support work. e.g.
CYGWIN=tty; (use CYGWIN32=tty under b19 and older.)
- * picking up some other grep or other unix like tools can kill
+ * picking up some other grep or other UNIX-like tools can kill
configure;
- * static heap too small, adjust src/sheap-adjust.h to a more positive
- number;
+ * static heap too small, adjust `src/sheap-adjust.h' to a more
+ positive number;
* The Cygwin version doesn't understand `//machine/path' type paths
so you will need to manually mount a directory of this form under
\1f
File: xemacs-faq.info, Node: Q6.2.3, Next: Q6.3.1, Prev: Q6.2.2, Up: MS Windows
-Q6.2.3: Where do I put my `.emacs' file?
-----------------------------------------
+Q6.2.3: Where do I put my `init.el'/`.emacs' file?
+--------------------------------------------------
- If the HOME environment variable is set, `.emacs' will be looked for
-there. Else the directory defaults to `c:\'.
+ `init.el' is the name of the init file starting with 21.4, and is
+located in the subdirectory `.xemacs/' of your home directory. In
+prior versions, the init file is called `.emacs' and is located in your
+home directory. Your home directory under Windows is determined by the
+HOME environment variable. If this is not set, it defaults to `C:\'.
\1f
File: xemacs-faq.info, Node: Q6.3.1, Next: Q6.3.2, Prev: Q6.2.3, Up: MS Windows
will be provided as compatibility aliases.
Architectural note: We believe that there should be a very small
-number of window-systems-specific variables, and will try to provide
-generic interfaces whenever possible.
+number of window-systems-specific variables, and we provide generic
+interfaces whenever possible. Thus, most of the equivalents of GNU
+Emacs `w32-*' functions and variables (as well as the corresponding
+`x-*' versions) are non-window-system-specific in XEmacs, and the issue
+of `mswindows-*' vs. `w32-*' does not come up much.
\1f
File: xemacs-faq.info, Node: Q6.3.2, Next: Q6.3.3, Prev: Q6.3.1, Up: MS Windows
Q6.3.3: What is the porting team doing at the moment?
-----------------------------------------------------
+ (as of March 2001)
+
The porting team is continuing work on the MS Windows-specific code.
+Major projects are the development of Mule (internationalization)
+support for Windows and the improvement of the widget support (better
+support for dialog boxes, buttons, edit fields, and similar UI
+elements).
\1f
File: xemacs-faq.info, Node: Q6.4.1, Prev: Q6.3.3, Up: MS Windows
* Package Terminology:: Understanding different kinds of packages.
* Installing Packages:: How to install packages.
* Building Packages:: Building packages from CVS sources.
-* Local.rules File:: This is an important file don't forget to create/edit it.
+* Local.rules File:: This is an important file that you must create.
* Creating Packages:: The basics.
* Available Packages:: A brief directory of packaged LISP.
the *Note Available Packages:: at the time of the XEmacs release.
Packages are also listed on the `Options' menu under:
- Options -> Customize -> Emacs -> Packages
+ Options->Customize->Emacs->Packages
However, don't select any of these menu picks unless you actually
want to install the given package (and have properly configured your
they are installed, using the visual package browser and installer.
You can access it via the menus:
- Options -> Manage Packages -> List & Install
+ Options->Manage Packages->List & Install
Or, you can get to it via the keyboard:
`GNU cp'
-`GNU ginstall'
+`GNU install'
(or a BSD compatible install program).
`GNU make'
The first few `make' variables defined are `VERSION',
`AUTHOR_VERSION', `MAINTAINER', `PACKAGE', `PKG_TYPE', `REQUIRES', and
`CATEGORY'. All but one were described in the description of
-`package-info.in'. The last is an admistrative grouping. Current
+`package-info.in'. The last is an administrative grouping. Current
categories include `comm', `games', `libs', `mule', `oa', `os', `prog',
and `wp'. *Note Available Packages::, for a list of categories.
-%Start ErrorText ErrorMessage OtherText
-
-EC [0-9][0-9][0-9][0-9]-[0-9][0-9][0-9]
-D [0-9]
-D3 [0-9 ][0-9 ][0-9]
-D4 [0-9 ][0-9 ][0-9 ][0-9]
-D5 [0-9 ][0-9 ][0-9 ][0-9 ][0-9]
-DS [0-9 ]
-
-%{
-/* moore@wilma.cs.utk.edu
-
- * Hack to work around the AIX C compiler's brain-damaged error messages
- * so that emacs can parse them. It runs /bin/cc as a subprocess, and
- * tries to rearrange the error messages so that (a) each message contains
- * both the filename and line number where the error occurred, and (b)
- * the error message(s) for a particular line get displayed *before* the
- * line itself.
- *
- * to compile:
- * lex aixcc.lex
- * cc -o aixcc lex.yy.c
- *
- *
- * Copyright December 1991 by Keith Moore
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- *
- * TODO: figure out how the compiler counts file numbers for included
- * files, keep track of which file corresponds to which number, and
- * always output the right file name.
- */
-
-#include <stdio.h>
-#include <string.h>
-
-char *current_file;
-int line;
-int debug = 0;
-char bigbuf[10240];
-char *bufptr = bigbuf;
-int last_line_was_error = 0;
-
-spaces (s)
-char *s;
-{
- while (*s++)
- *bufptr++ = ' ';
-}
-
-char *
-strsave (s)
-char *s;
-{
- char *ptr = malloc (strlen (s) + 1);
- strcpy (ptr, s);
- return ptr;
-}
-
-yywrap ()
-{
- *bufptr = '\0';
- bufptr = bigbuf;
- while (*bufptr)
- putc (*bufptr++, yyout);
- return 1;
-}
-
-%}
-%%
-^File\ Line\ Column\ Message\ text[^\n]* {
- /*
- * ignore this. don't treat it as error text
- */
-}
-
-^{DS}{DS}{DS}\ {D5}\ \| {
- /*
- * (optional) nesting level, followed by line number, followed
- * by the source code fragment that caused the error
- */
-
- /*
- * save the line number for later
- */
- line = atoi (yytext+4);
-
- if (debug) {
- fprintf (yyout, "line <= %d\n", line);
- fprintf (yyout, "%s\n", yytext);
- }
-
- /*
- * if the last line was an error message, to flush out all of
- * the old source text before starting to save the new source text.
- */
- if (last_line_was_error) {
- *bufptr = '\0';
- bufptr = bigbuf;
- while (*bufptr)
- putc (*bufptr++, yyout);
- bufptr = bigbuf;
- last_line_was_error = 0;
- }
- /*
- * stuff enough spaces in the text buffer so that the
- * saved text will line up properly when displayed.
- */
- spaces (yytext);
-
- BEGIN ErrorText; /* continue below */
-}
-
-<ErrorText>[^\n]*$ {
- char *ptr;
-
- /*
- * Save the text until we see the error message(s), then print it.
- * This because emacs puts the error message at the top of the
- * window, and it's nice to be able to see the text below it.
- */
-
- ptr = yytext;
- while (*ptr)
- *bufptr++ = *ptr++;
- *bufptr++ = '\n';
-
- BEGIN 0;
-}
-
-^Processing\ include\ file\ .*$ {
- /*
- * name of a new include file being processed. Increment file number
- * and remember the file name corresponding to this file number.
- */
-
- current_file = strsave (yytext+24);
-
- if (debug) {
- fprintf (yyout, "current_file <= %s\n", current_file);
- fprintf (yyout, "%s\n", yytext);
- }
-}
-
-^([a-z]\ -)?\ *{EC}: {
- /*
- * error message (which we print immediately) preceded by an
- * error code (which we ignore)
- */
-
- fprintf (yyout, "\"%s\", line %d: %c -", current_file, line, *yytext);
- last_line_was_error = 1;
- BEGIN ErrorMessage;
-}
-
-^{D3}\ {D5}\ {D4}\ {EC}: {
- /*
- * (optional) nesting level, followed by line number, followed
- * by column number, followed by error message text.
- */
-
- /*
- * save the line number for later
- */
- line = atoi (yytext+4);
-
- if (debug) {
- fprintf (yyout, "line <= %d\n", line);
- fprintf (yyout, "%s\n", yytext);
- }
-
- /*
- * if the last line was an error message, flush out all of
- * the old source text before printing this error message.
- */
- if (last_line_was_error) {
- *bufptr = '\0';
- bufptr = bigbuf;
- while (*bufptr)
- putc (*bufptr++, yyout);
- bufptr = bigbuf;
- last_line_was_error = 0;
- }
- fprintf (yyout, "\"%s\", line %d:", current_file, line);
- last_line_was_error = 1;
- BEGIN ErrorMessage;
-}
-
-<ErrorMessage>[^\n]*$ {
- fprintf (yyout, "%s\n", yytext);
- BEGIN 0;
-}
-
-
-^[^ :]+".c:"\ *$ {
- /* name of new source file being processed */
-
- char *ptr;
-
- if (current_file)
- free (current_file);
- ptr = strchr (yytext, ':');
- *ptr = '\0';
- current_file = strsave (yytext);
-}
-
-^[^\n] {
- /*
- * other text starting with a newline. We have to break it up this
- * way to keep this rule from matching any of the above patterns
- */
-
- if (last_line_was_error) {
- *bufptr = '\0';
- bufptr = bigbuf;
- while (*bufptr)
- putc (*bufptr++, yyout);
- bufptr = bigbuf;
- last_line_was_error = 0;
- }
-
- *bufptr++ = *yytext;
- BEGIN OtherText;
-}
-
-<OtherText>[^\n]*$ {
- char *ptr;
-
- ptr = yytext;
- while (*ptr)
- *bufptr++ = *ptr++;
- *bufptr++ = '\n';
-
- BEGIN 0;
-}
-
-\n ;
-
-%%
-
-main (argc, argv)
-char **argv;
-{
- int pfd[2];
- int child_pid;
- int i;
-
- current_file = strsave ("/dev/null");
-
- line = 0;
-
- for (i = 1; i < argc; ++i) {
- char *ptr = strrchr (argv[i], '.');
- if (ptr && ptr[1] == 'c' && ptr[2] == '\0') {
- current_file = strsave (argv[i]);
- break;
- }
- }
-
- if (pipe (pfd) < 0) {
- perror ("pipe");
- exit (1);
- }
- if ((child_pid = fork()) > 0) {
- int status;
-
- close (pfd[1]);
- yyin = fdopen (pfd[0], "r");
- yyout = stderr;
- yylex();
-
- wait (&status);
- exit ((status >> 8) & 0xff);
- }
- else if (child_pid == 0) {
- dup2 (pfd[1], 2);
- close (pfd[0]);
- close (pfd[1]);
- argv[0] = "cc";
- execv ("/bin/cc", argv);
- perror ("/bin/cc");
- exit (1);
- }
- else {
- perror ("fork");
- exit (1);
- }
-}
-#ifndef INCLUDED_dump_id_h_
-#define INCLUDED_dump_id_h_
-
-extern unsigned int dump_id;
-
-#endif
projects / chise / xemacs-chise.git- / commitdiff