translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization
+
+Customizing the Diary
+.....................
+
+ Ordinarily, the mode line of the diary buffer window indicates any
+holidays that fall on the date of the diary entries. The process of
+checking for holidays can take several seconds, so including holiday
+information delays the display of the diary buffer noticeably. If you'd
+prefer to have a faster display of the diary buffer but without the
+holiday information, set the variable `holidays-in-diary-buffer' to
+`nil'.
+
+ The variable `number-of-diary-entries' controls the number of days
+of diary entries to be displayed at one time. It affects the initial
+display when `view-diary-entries-initially' is `t', as well as the
+command `M-x diary'. For example, the default value is 1, which says
+to display only the current day's diary entries. If the value is 2,
+both the current day's and the next day's entries are displayed. The
+value can also be a vector of seven elements: for example, if the value
+is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the
+current date's and the next day's diary entries appear Monday through
+Thursday, Friday through Monday's entries appear on Friday, while on
+Saturday only that day's entries appear.
+
+ The variable `print-diary-entries-hook' is a normal hook run after
+preparation of a temporary buffer containing just the diary entries
+currently visible in the diary buffer. (The other, irrelevant diary
+entries are really absent from the temporary buffer; in the diary
+buffer, they are merely hidden.) The default value of this hook does
+the printing with the command `lpr-buffer'. If you want to use a
+different command to do the printing, just change the value of this
+hook. Other uses might include, for example, rearranging the lines into
+order by day and time.
+
+ You can customize the form of dates in your diary file, if neither
+the standard American nor European styles suits your needs, by setting
+the variable `diary-date-forms'. This variable is a list of patterns
+for recognizing a date. Each date pattern is a list whose elements may
+be regular expressions (*note Regexps::) or the symbols `month', `day',
+`year', `monthname', and `dayname'. All these elements serve as
+patterns that match certain kinds of text in the diary file. In order
+for the date pattern, as a whole, to match, all of its elements must
+match consecutively.
+
+ A regular expression in a date pattern matches in its usual fashion,
+using the standard syntax table altered so that `*' is a word
+constituent.
+
+ The symbols `month', `day', `year', `monthname', and `dayname' match
+the month number, day number, year number, month name, and day name of
+the date being considered. The symbols that match numbers allow
+leading zeros; those that match names allow three-letter abbreviations
+and capitalization. All the symbols can match `*'; since `*' in a
+diary entry means "any day", "any month", and so on, it should match
+regardless of the date being considered.
+
+ The default value of `diary-date-forms' in the American style is
+this:
+
+ ((month "/" day "[^/0-9]")
+ (month "/" day "/" year "[^0-9]")
+ (monthname " *" day "[^,0-9]")
+ (monthname " *" day ", *" year "[^0-9]")
+ (dayname "\\W"))
+
+Emacs matches of the diary entries with the date forms is done with the
+standard syntax table from Fundamental mode (*note Syntax Tables:
+(lispref)Syntax Tables.), but with the `*' changed so that it is a word
+constituent.
+
+ The date patterns in the list must be _mutually exclusive_ and must
+not match any portion of the diary entry itself, just the date and one
+character of whitespace. If, to be mutually exclusive, the pattern
+must match a portion of the diary entry text--beyond the whitespace
+that ends the date--then the first element of the date pattern _must_
+be `backup'. This causes the date recognizer to back up to the
+beginning of the current word of the diary entry, after finishing the
+match. Even if you use `backup', the date pattern must absolutely not
+match more than a portion of the first word of the diary entry. The
+default value of `diary-date-forms' in the European style is this list:
+
+ ((day "/" month "[^/0-9]")
+ (day "/" month "/" year "[^0-9]")
+ (backup day " *" monthname "\\W+\\<[^*0-9]")
+ (day " *" monthname " *" year "[^0-9]")
+ (dayname "\\W"))
+
+Notice the use of `backup' in the third pattern, because it needs to
+match part of a word beyond the date itself to distinguish it from the
+fourth pattern.
+
+\1f
+File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization
+
+Hebrew- and Islamic-Date Diary Entries
+......................................
+
+ Your diary file can have entries based on Hebrew or Islamic dates, as
+well as entries based on the world-standard Gregorian calendar.
+However, because recognition of such entries is time-consuming and most
+people don't use them, you must explicitly enable their use. If you
+want the diary to recognize Hebrew-date diary entries, for example, you
+must do this:
+
+ (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+ (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+
+If you want Islamic-date entries, do this:
+
+ (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+ (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
+
+ Hebrew- and Islamic-date diary entries have the same formats as
+Gregorian-date diary entries, except that `H' precedes a Hebrew date
+and `I' precedes an Islamic date. Moreover, because the Hebrew and
+Islamic month names are not uniquely specified by the first three
+letters, you may not abbreviate them. For example, a diary entry for
+the Hebrew date Heshvan 25 could look like this:
+
+ HHeshvan 25 Happy Hebrew birthday!
+
+and would appear in the diary for any date that corresponds to Heshvan
+25 on the Hebrew calendar. And here is Islamic-date diary entry that
+matches Dhu al-Qada 25:
+
+ IDhu al-Qada 25 Happy Islamic birthday!
+
+and would appear in the diary for any date that corresponds to Dhu
+al-Qada 25 on the Islamic calendar.
+
+ As with Gregorian-date diary entries, Hebrew- and Islamic-date
+entries are nonmarking if they are preceded with an ampersand (`&').
+
+ Here is a table of commands used in the calendar to create diary
+entries that match the selected date and other dates that are similar
+in the Hebrew or Islamic calendar:
+
+`i h d'
+ Add a diary entry for the Hebrew date corresponding to the
+ selected date (`insert-hebrew-diary-entry').
+
+`i h m'
+ Add a diary entry for the day of the Hebrew month corresponding to
+ the selected date (`insert-monthly-hebrew-diary-entry'). This
+ diary entry matches any date that has the same Hebrew
+ day-within-month as the selected date.
+
+`i h y'
+ Add a diary entry for the day of the Hebrew year corresponding to
+ the selected date (`insert-yearly-hebrew-diary-entry'). This diary
+ entry matches any date which has the same Hebrew month and
+ day-within-month as the selected date.
+
+`i i d'
+ Add a diary entry for the Islamic date corresponding to the
+ selected date (`insert-islamic-diary-entry').
+
+`i i m'
+ Add a diary entry for the day of the Islamic month corresponding
+ to the selected date (`insert-monthly-islamic-diary-entry').
+
+`i i y'
+ Add a diary entry for the day of the Islamic year corresponding to
+ the selected date (`insert-yearly-islamic-diary-entry').
+
+ These commands work much like the corresponding commands for ordinary
+diary entries: they apply to the date that point is on in the calendar
+window, and what they do is insert just the date portion of a diary
+entry at the end of your diary file. You must then insert the rest of
+the diary entry.
+
+\1f
+File: xemacs.info, Node: Fancy Diary Display, Next: Included Diary Files, Prev: Hebrew/Islamic Entries, Up: Calendar Customization
+
+Fancy Diary Display
+...................
+
+ Diary display works by preparing the diary buffer and then running
+the hook `diary-display-hook'. The default value of this hook
+(`simple-diary-display') hides the irrelevant diary entries and then
+displays the buffer. However, if you specify the hook as follows,
+
+ (add-hook 'diary-display-hook 'fancy-diary-display)
+
+this enables fancy diary display. It displays diary entries and
+holidays by copying them into a special buffer that exists only for the
+sake of display. Copying to a separate buffer provides an opportunity
+to change the displayed text to make it prettier--for example, to sort
+the entries by the dates they apply to.
+
+ As with simple diary display, you can print a hard copy of the buffer
+with `print-diary-entries'. To print a hard copy of a day-by-day diary
+for a week by positioning point on Sunday of that week, type `7 d' and
+then do `M-x print-diary-entries'. As usual, the inclusion of the
+holidays slows down the display slightly; you can speed things up by
+setting the variable `holidays-in-diary-buffer' to `nil'.
+
+ Ordinarily, the fancy diary buffer does not show days for which
+there are no diary entries, even if that day is a holiday. If you want
+such days to be shown in the fancy diary buffer, set the variable
+`diary-list-include-blanks' to `t'.
+
+ If you use the fancy diary display, you can use the normal hook
+`list-diary-entries-hook' to sort each day's diary entries by their
+time of day. Add this line to your init file:
+
+ (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
+
+ *Note Init File::.
+
+For each day, this sorts diary entries that begin with a recognizable
+time of day according to their times. Diary entries without times come
+first within each day.
+
+\1f
+File: xemacs.info, Node: Included Diary Files, Next: Sexp Diary Entries, Prev: Fancy Diary Display, Up: Calendar Customization
+
+Included Diary Files
+....................
+
+ Fancy diary display also has the ability to process included diary
+files. This permits a group of people to share a diary file for events
+that apply to all of them. Lines in the diary file of this form:
+
+ #include "FILENAME"
+
+includes the diary entries from the file FILENAME in the fancy diary
+buffer. The include mechanism is recursive, so that included files can
+include other files, and so on; you must be careful not to have a cycle
+of inclusions, of course. Here is how to enable the include facility:
+
+ (add-hook 'list-diary-entries-hook 'include-other-diary-files)
+ (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
+
+ The include mechanism works only with the fancy diary display,
+because ordinary diary display shows the entries directly from your
+diary file.
+
+\1f
+File: xemacs.info, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Included Diary Files, Up: Calendar Customization
+
+Sexp Entries and the Fancy Diary Display
+........................................
+
+ Sexp diary entries allow you to do more than just have complicated
+conditions under which a diary entry applies. If you use the fancy
+diary display, sexp entries can generate the text of the entry depending
+on the date itself. For example, an anniversary diary entry can insert
+the number of years since the anniversary date into the text of the
+diary entry. Thus the `%d' in this dairy entry:
+
+ %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
+
+gets replaced by the age, so on October 31, 1990 the entry appears in
+the fancy diary buffer like this:
+
+ Arthur's birthday (42 years old)
+
+If the diary file instead contains this entry:
+
+ %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
+
+the entry in the fancy diary buffer for October 31, 1990 appears like
+this:
+
+ Arthur's 42nd birthday
+
+ Similarly, cyclic diary entries can interpolate the number of
+repetitions that have occurred:
+
+ %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
+
+looks like this:
+
+ Renew medication (5th time)
+
+in the fancy diary display on September 8, 1990.
+
+ The generality of sexp diary entries lets you specify any diary entry
+that you can describe algorithmically. A sexp diary entry contains an
+expression that computes whether the entry applies to any given date.
+If its value is non-`nil', the entry applies to that date; otherwise,
+it does not. The expression can use the variable `date' to find the
+date being considered; its value is a list (MONTH DAY YEAR) that refers
+to the Gregorian calendar.
+
+ Suppose you get paid on the 21st of the month if it is a weekday, and
+on the Friday before if the 21st is on a weekend. Here is how to write
+a sexp diary entry that matches those dates:
+
+ &%%(let ((dayname (calendar-day-of-week date))
+ (day (car (cdr date))))
+ (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
+ (and (memq day '(19 20)) (= dayname 5)))
+ ) Pay check deposited
+
+applies to just those dates. This example illustrates how the sexp can
+depend on the variable `date'; this variable is a list (MONTH DAY YEAR)
+that gives the Gregorian date for which the diary entries are being
+found. If the value of the expression is `t', the entry applies to
+that date. If the expression evaluates to `nil', the entry does _not_
+apply to that date.
+
+ The following sexp diary entries take advantage of the ability (in
+the fancy diary display) to concoct diary entries whose text varies
+based on the date:
+
+`%%(diary-sunrise-sunset)'
+ Make a diary entry for the local times of today's sunrise and
+ sunset.
+
+`%%(diary-phases-of-moon)'
+ Make a diary entry for the phases (quarters) of the moon.
+
+`%%(diary-day-of-year)'
+ Make a diary entry with today's day number in the current year and
+ the number of days remaining in the current year.
+
+`%%(diary-iso-date)'
+ Make a diary entry with today's equivalent ISO commercial date.
+
+`%%(diary-julian-date)'
+ Make a diary entry with today's equivalent date on the Julian
+ calendar.
+
+`%%(diary-astro-day-number)'
+ Make a diary entry with today's equivalent astronomical (Julian)
+ day number.
+
+`%%(diary-hebrew-date)'
+ Make a diary entry with today's equivalent date on the Hebrew
+ calendar.
+
+`%%(diary-islamic-date)'
+ Make a diary entry with today's equivalent date on the Islamic
+ calendar.
+
+`%%(diary-french-date)'
+ Make a diary entry with today's equivalent date on the French
+ Revolutionary calendar.
+
+`%%(diary-mayan-date)'
+ Make a diary entry with today's equivalent date on the Mayan
+ calendar.
+
+Thus including the diary entry
+
+ &%%(diary-hebrew-date)
+
+causes every day's diary display to contain the equivalent date on the
+Hebrew calendar, if you are using the fancy diary display. (With simple
+diary display, the line `&%%(diary-hebrew-date)' appears in the diary
+for any date, but does nothing particularly useful.)
+
+ These functions can be used to construct sexp diary entries based on
+the Hebrew calendar in certain standard ways:
+
+`%%(diary-rosh-hodesh)'
+ Make a diary entry that tells the occurrence and ritual
+ announcement of each new Hebrew month.
+
+`%%(diary-parasha)'
+ Make a Saturday diary entry that tells the weekly synagogue
+ scripture reading.
+
+`%%(diary-sabbath-candles)'
+ Make a Friday diary entry that tells the _local time_ of Sabbath
+ candle lighting.
+
+`%%(diary-omer)'
+ Make a diary entry that gives the omer count, when appropriate.
+
+`%%(diary-yahrzeit MONTH DAY YEAR) NAME'
+ Make a diary entry marking the anniversary of a date of death.
+ The date is the _Gregorian_ (civil) date of death. The diary
+ entry appears on the proper Hebrew calendar anniversary and on the
+ day before. (In the European style, the order of the parameters
+ is changed to DAY, MONTH, YEAR.)
+
+\1f
+File: xemacs.info, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customization
+
+Customizing Appointment Reminders
+.................................
+
+ You can specify exactly how Emacs reminds you of an appointment, and
+how far in advance it begins doing so, by setting these variables:
+
+`appt-message-warning-time'
+ The time in minutes before an appointment that the reminder
+ begins. The default is 10 minutes.
+
+`appt-audible'
+ If this is `t' (the default), Emacs rings the terminal bell for
+ appointment reminders.
+
+`appt-visible'
+ If this is `t' (the default), Emacs displays the appointment
+ message in echo area.
+
+`appt-display-mode-line'
+ If this is `t' (the default), Emacs displays the number of minutes
+ to the appointment on the mode line.
+
+`appt-msg-window'
+ If this is `t' (the default), Emacs displays the appointment
+ message in another window.
+
+`appt-display-duration'
+ The number of seconds an appointment message is displayed. The
+ default is 5 seconds.
+
+\1f
+File: xemacs.info, Node: Sorting, Next: Shell, Prev: Calendar/Diary, Up: Top
+
+Sorting Text
+============
+
+ XEmacs provides several commands for sorting text in a buffer. All
+operate on the contents of the region (the text between point and the
+mark). They divide the text of the region into many "sort records",
+identify a "sort key" for each record, and then reorder the records
+using the order determined by the sort keys. The records are ordered so
+that their keys are in alphabetical order, or, for numerical sorting, in
+numerical order. In alphabetical sorting, all upper-case letters `A'
+through `Z' come before lower-case `a', in accordance with the ASCII
+character sequence.
+
+ The sort commands differ in how they divide the text into sort
+records and in which part of each record they use as the sort key.
+Most of the commands make each line a separate sort record, but some
+commands use paragraphs or pages as sort records. Most of the sort
+commands use each entire sort record as its own sort key, but some use
+only a portion of the record as the sort key.
+
+`M-x sort-lines'
+ Divide the region into lines and sort by comparing the entire text
+ of a line. A prefix argument means sort in descending order.
+
+`M-x sort-paragraphs'
+ Divide the region into paragraphs and sort by comparing the entire
+ text of a paragraph (except for leading blank lines). A prefix
+ argument means sort in descending order.
+
+`M-x sort-pages'
+ Divide the region into pages and sort by comparing the entire text
+ of a page (except for leading blank lines). A prefix argument
+ means sort in descending order.
+
+`M-x sort-fields'
+ Divide the region into lines and sort by comparing the contents of
+ one field in each line. Fields are defined as separated by
+ whitespace, so the first run of consecutive non-whitespace
+ characters in a line constitutes field 1, the second such run
+ constitutes field 2, etc.
+
+ You specify which field to sort by with a numeric argument: 1 to
+ sort by field 1, etc. A negative argument means sort in descending
+ order. Thus, minus 2 means sort by field 2 in reverse-alphabetical
+ order.
+
+`M-x sort-numeric-fields'
+ Like `M-x sort-fields', except the specified field is converted to
+ a number for each line and the numbers are compared. `10' comes
+ before `2' when considered as text, but after it when considered
+ as a number.
+
+`M-x sort-columns'
+ Like `M-x sort-fields', except that the text within each line used
+ for comparison comes from a fixed range of columns. An explanation
+ is given below.
+
+ For example, if the buffer contains:
+
+ On systems where clash detection (locking of files being edited) is
+ implemented, XEmacs also checks the first time you modify a buffer
+ whether the file has changed on disk since it was last visited or
+ saved. If it has, you are asked to confirm that you want to change
+ the buffer.
+
+then if you apply `M-x sort-lines' to the entire buffer you get:
+
+ On systems where clash detection (locking of files being edited) is
+ implemented, XEmacs also checks the first time you modify a buffer
+ saved. If it has, you are asked to confirm that you want to change
+ the buffer.
+ whether the file has changed on disk since it was last visited or
+
+where the upper case `O' comes before all lower case letters. If you
+apply instead `C-u 2 M-x sort-fields' you get:
+
+ saved. If it has, you are asked to confirm that you want to change
+ implemented, XEmacs also checks the first time you modify a buffer
+ the buffer.
+ On systems where clash detection (locking of files being edited) is
+ whether the file has changed on disk since it was last visited or
+
+where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'.
+
+ `M-x sort-columns' requires more explanation. You specify the
+columns by putting point at one of the columns and the mark at the other
+column. Because this means you cannot put point or the mark at the
+beginning of the first line to sort, this command uses an unusual
+definition of `region': all of the line point is in is considered part
+of the region, and so is all of the line the mark is in.
+
+ For example, to sort a table by information found in columns 10 to
+15, you could put the mark on column 10 in the first line of the table,
+and point on column 15 in the last line of the table, and then use this
+command. Or you could put the mark on column 15 in the first line and
+point on column 10 in the last line.
+
+ This can be thought of as sorting the rectangle specified by point
+and the mark, except that the text on each line to the left or right of
+the rectangle moves along with the text inside the rectangle. *Note
+Rectangles::.
+
+\1f
+File: xemacs.info, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top
+
+Running Shell Commands from XEmacs
+==================================
+
+ XEmacs has commands for passing single command lines to inferior
+shell processes; it can also run a shell interactively with input and
+output to an XEmacs buffer `*shell*'.
+
+`M-!'
+ Run a specified shell command line and display the output
+ (`shell-command').
+
+`M-|'
+ Run a specified shell command line with region contents as input;
+ optionally replace the region with the output
+ (`shell-command-on-region').
+
+`M-x shell'
+ Run a subshell with input and output through an XEmacs buffer.
+ You can then give commands interactively.
+
+`M-x term'
+ Run a subshell with input and output through an XEmacs buffer.
+ You can then give commands interactively. Full terminal emulation
+ is available.
+
+* Menu:
+
+* Single Shell:: How to run one shell command and return.
+* Interactive Shell:: Permanent shell taking input via XEmacs.
+* Shell Mode:: Special XEmacs commands used with permanent shell.
+* Terminal emulator:: An XEmacs window as a terminal emulator.
+* Term Mode:: Special XEmacs commands used in Term mode.
+* Paging in Term:: Paging in the terminal emulator.
+
+\1f
+File: xemacs.info, Node: Single Shell, Next: Interactive Shell, Prev: Shell, Up: Shell
+
+Single Shell Commands
+---------------------
+
+ `M-!' (`shell-command') reads a line of text using the minibuffer
+and creates an inferior shell to execute the line as a command.
+Standard input from the command comes from the null device. If the
+shell command produces any output, the output goes to an XEmacs buffer
+named `*Shell Command Output*', which is displayed in another window
+but not selected. A numeric argument, as in `M-1 M-!', directs this
+command to insert any output into the current buffer. In that case,
+point is left before the output and the mark is set after the output.
+
+ `M-|' (`shell-command-on-region') is like `M-!' but passes the
+contents of the region as input to the shell command, instead of no
+input. If a numeric argument is used to direct output to the current
+buffer, then the old region is deleted first and the output replaces it
+as the contents of the region.
+
+ Both `M-!' and `M-|' use `shell-file-name' to specify the shell to
+use. This variable is initialized based on your `SHELL' environment
+variable when you start XEmacs. If the file name does not specify a
+directory, the directories in the list `exec-path' are searched; this
+list is initialized based on the `PATH' environment variable when you
+start XEmacs. You can override either or both of these default
+initializations in your init file. *Note Init File::.
+
+ When you use `M-!' and `M-|', XEmacs has to wait until the shell
+command completes. You can quit with `C-g'; that terminates the shell
+command.
+
+\1f
File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell
Interactive Inferior Shell
* X Resources:: X resources controlling various aspects of the
behavior of XEmacs.
-\1f
-File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization
-
-Minor Modes
-===========
-
- Minor modes are options which you can use or not. For example, Auto
-Fill mode is a minor mode in which <SPC> breaks lines between words as
-you type. All the minor modes are independent of each other and of the
-selected major mode. Most minor modes inform you in the mode line when
-they are on; for example, `Fill' in the mode line means that Auto Fill
-mode is on.
-
- Append `-mode' to the name of a minor mode to get the name of a
-command function that turns the mode on or off. Thus, the command to
-enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These
-commands are usually invoked with `M-x', but you can bind keys to them
-if you wish. With no argument, the function turns the mode on if it was
-off and off if it was on. This is known as "toggling". A positive
-argument always turns the mode on, and an explicit zero argument or a
-negative argument always turns it off.
-
- Auto Fill mode allows you to enter filled text without breaking lines
-explicitly. Emacs inserts newlines as necessary to prevent lines from
-becoming too long. *Note Filling::.
-
- Overwrite mode causes ordinary printing characters to replace
-existing text instead of moving it to the right. For example, if point
-is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite
-mode, it changes to `FOOGAR', instead of `FOOGBAR'.
-
- Abbrev mode allows you to define abbreviations that automatically
-expand as you type them. For example, `amd' might expand to `abbrev
-mode'. *Note Abbrevs::, for full information.
-
-\1f
-File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization
-
-Variables
-=========
-
- A "variable" is a Lisp symbol which has a value. Variable names can
-contain any characters, but by convention they are words separated by
-hyphens. A variable can also have a documentation string, which
-describes what kind of value it should have and how the value will be
-used.
-
- Lisp allows any variable to have any kind of value, but most
-variables that Emacs uses require a value of a certain type. Often the
-value has to be a string or a number. Sometimes we say that a certain
-feature is turned on if a variable is "non-`nil'," meaning that if the
-variable's value is `nil', the feature is off, but the feature is on
-for any other value. The conventional value to turn on the
-feature--since you have to pick one particular value when you set the
-variable--is `t'.
-
- Emacs uses many Lisp variables for internal recordkeeping, as any
-Lisp program must, but the most interesting variables for you are the
-ones that exist for the sake of customization. Emacs does not
-(usually) change the values of these variables; instead, you set the
-values, and thereby alter and control the behavior of certain Emacs
-commands. These variables are called "options". Most options are
-documented in this manual and appear in the Variable Index (*note
-Variable Index::).
-
- One example of a variable which is an option is `fill-column', which
-specifies the position of the right margin (as a number of characters
-from the left margin) to be used by the fill commands (*note Filling::).
-
-* Menu:
-
-* Examining:: Examining or setting one variable's value.
-* Easy Customization:: Convenient and easy customization of variables.
-* Edit Options:: Examining or editing list of all variables' values.
-* Locals:: Per-buffer values of variables.
-* File Variables:: How files can specify variable values.
-
-\1f
-File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables
-
-Examining and Setting Variables
--------------------------------
-
-`C-h v'
-`M-x describe-variable'
- Print the value and documentation of a variable.
-
-`M-x set-variable'
- Change the value of a variable.
-
- To examine the value of a single variable, use `C-h v'
-(`describe-variable'), which reads a variable name using the
-minibuffer, with completion. It prints both the value and the
-documentation of the variable.
-
- C-h v fill-column <RET>
-
-prints something like:
-
- fill-column's value is 75
-
- Documentation:
- *Column beyond which automatic line-wrapping should happen.
- Automatically becomes local when set in any fashion.
-
-The star at the beginning of the documentation indicates that this
-variable is an option. `C-h v' is not restricted to options; it allows
-any variable name.
-
- If you know which option you want to set, you can use `M-x
-set-variable' to set it. This prompts for the variable name in the
-minibuffer (with completion), and then prompts for a Lisp expression
-for the new value using the minibuffer a second time. For example,
-
- M-x set-variable <RET> fill-column <RET> 75 <RET>
-
-sets `fill-column' to 75, as if you had executed the Lisp expression
-`(setq fill-column 75)'.
-
- Setting variables in this way, like all means of customizing Emacs
-except where explicitly stated, affects only the current Emacs session.
-
-\1f
-File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables
-
-Easy Customization Interface
-----------------------------
-
- A convenient way to find the user option variables that you want to
-change, and then change them, is with `M-x customize'. This command
-creates a "customization buffer" with which you can browse through the
-Emacs user options in a logically organized structure, then edit and
-set their values. You can also use the customization buffer to save
-settings permanently. (Not all Emacs user options are included in this
-structure as of yet, but we are adding the rest.)
-
-* Menu:
-
-* Groups: Customization Groups.
- How options are classified in a structure.
-* Changing an Option:: How to edit a value and set an option.
-* Face Customization:: How to edit the attributes of a face.
-* Specific Customization:: Making a customization buffer for specific
- options, faces, or groups.
-
-\1f
-File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization
-
-Customization Groups
-....................
-
- For customization purposes, user options are organized into "groups"
-to help you find them. Groups are collected into bigger groups, all
-the way up to a master group called `Emacs'.
-
- `M-x customize' creates a customization buffer that shows the
-top-level `Emacs' group and the second-level groups immediately under
-it. It looks like this, in part:
-
- /- Emacs group: ---------------------------------------------------\
- [State]: visible group members are all at standard settings.
- Customization of the One True Editor.
- See also [Manual].
-
- [Open] Editing group
- Basic text editing facilities.
-
- [Open] External group
- Interfacing to external utilities.
-
- MORE SECOND-LEVEL GROUPS
-
- \- Emacs group end ------------------------------------------------/
-
-This says that the buffer displays the contents of the `Emacs' group.
-The other groups are listed because they are its contents. But they
-are listed differently, without indentation and dashes, because _their_
-contents are not included. Each group has a single-line documentation
-string; the `Emacs' group also has a `[State]' line.
-
- Most of the text in the customization buffer is read-only, but it
-typically includes some "editable fields" that you can edit. There are
-also "active fields"; this means a field that does something when you
-"invoke" it. To invoke an active field, either click on it with
-`Mouse-1', or move point to it and type <RET>.
-
- For example, the phrase `[Open]' that appears in a second-level
-group is an active field. Invoking the `[Open]' field for a group
-opens up a new customization buffer, which shows that group and its
-contents. This field is a kind of hypertext link to another group.
-
- The `Emacs' group does not include any user options itself, but
-other groups do. By examining various groups, you will eventually find
-the options and faces that belong to the feature you are interested in
-customizing. Then you can use the customization buffer to set them.
-
- You can view the structure of customization groups on a larger scale
-with `M-x customize-browse'. This command creates a special kind of
-customization buffer which shows only the names of the groups (and
-options and faces), and their structure.
-
- In this buffer, you can show the contents of a group by invoking
-`[+]'. When the group contents are visible, this button changes to
-`[-]'; invoking that hides the group contents.
-
- Each group, option or face name in this buffer has an active field
-which says `[Group]', `[Option]' or `[Face]'. Invoking that active
-field creates an ordinary customization buffer showing just that group
-and its contents, just that option, or just that face. This is the way
-to set values in it.
-
-\1f
-File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization
-
-Changing an Option
-..................
-
- Here is an example of what a user option looks like in the
-customization buffer:
-
- Kill Ring Max: [Hide] 30
- [State]: this option is unchanged from its standard setting.
- Maximum length of kill ring before oldest elements are thrown away.
-
- The text following `[Hide]', `30' in this case, indicates the
-current value of the option. If you see `[Show]' instead of `[Hide]',
-it means that the value is hidden; the customization buffer initially
-hides values that take up several lines. Invoke `[Show]' to show the
-value.
-
- The line after the option name indicates the "customization state"
-of the option: in the example above, it says you have not changed the
-option yet. The word `[State]' at the beginning of this line is
-active; you can get a menu of various operations by invoking it with
-`Mouse-1' or <RET>. These operations are essential for customizing the
-variable.
-
- The line after the `[State]' line displays the beginning of the
-option's documentation string. If there are more lines of
-documentation, this line ends with `[More]'; invoke this to show the
-full documentation string.
-
- To enter a new value for `Kill Ring Max', move point to the value
-and edit it textually. For example, you can type `M-d', then insert
-another number.
-
- When you begin to alter the text, you will see the `[State]' line
-change to say that you have edited the value:
-
- [State]: you have edited the value as text, but not set the option.
-
- Editing the value does not actually set the option variable. To do
-that, you must "set" the option. To do this, invoke the word `[State]'
-and choose `Set for Current Session'.
-
- The state of the option changes visibly when you set it:
-
- [State]: you have set this option, but not saved it for future sessions.
-
- You don't have to worry about specifying a value that is not valid;
-setting the option checks for validity and will not really install an
-unacceptable value.
-
- While editing a value or field that is a file name, directory name,
-command name, or anything else for which completion is defined, you can
-type `M-<TAB>' (`widget-complete') to do completion.
-
- Some options have a small fixed set of possible legitimate values.
-These options don't let you edit the value textually. Instead, an
-active field `[Value Menu]' appears before the value; invoke this field
-to edit the value. For a boolean "on or off" value, the active field
-says `[Toggle]', and it changes to the other value. `[Value Menu]' and
-`[Toggle]' edit the buffer; the changes take effect when you use the
-`Set for Current Session' operation.
-
- Some options have values with complex structure. For example, the
-value of `load-path' is a list of directories. Here is how it appears
-in the customization buffer:
-
- Load Path:
- [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
- [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
- [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
- [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
- [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
- [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
- [INS]
- [State]: this item has been changed outside the customization buffer.
- List of directories to search for files to load....
-
-Each directory in the list appears on a separate line, and each line has
-several editable or active fields.
-
- You can edit any of the directory names. To delete a directory from
-the list, invoke `[DEL]' on that line. To insert a new directory in
-the list, invoke `[INS]' at the point where you want to insert it.
-
- You can also invoke `[Current dir?]' to switch between including a
-specific named directory in the path, and including `nil' in the path.
-(`nil' in a search path means "try the current directory.")
-
- Two special commands, <TAB> and `S-<TAB>', are useful for moving
-through the customization buffer. <TAB> (`widget-forward') moves
-forward to the next active or editable field; `S-<TAB>'
-(`widget-backward') moves backward to the previous active or editable
-field.
-
- Typing <RET> on an editable field also moves forward, just like
-<TAB>. The reason for this is that people have a tendency to type
-<RET> when they are finished editing a field. If you have occasion to
-insert a newline in an editable field, use `C-o' or `C-q C-j',
-
- Setting the option changes its value in the current Emacs session;
-"saving" the value changes it for future sessions as well. This works
-by writing code into your init file so as to set the option variable
-again each time you start Emacs. *Note Init File::. To save the
-option, invoke `[State]' and select the `Save for Future Sessions'
-operation.
-
- You can also restore the option to its standard value by invoking
-`[State]' and selecting the `Reset' operation. There are actually
-three reset operations:
-
-`Reset to Current'
- If you have made some modifications and not yet set the option,
- this restores the text in the customization buffer to match the
- actual value.
-
-`Reset to Saved'
- This restores the value of the option to the last saved value, and
- updates the text accordingly.
-
-`Reset to Standard Settings'
- This sets the option to its standard value, and updates the text
- accordingly. This also eliminates any saved value for the option,
- so that you will get the standard value in future Emacs sessions.
-
- The state of a group indicates whether anything in that group has
-been edited, set or saved. You can select `Set for Current Session',
-`Save for Future Sessions' and the various kinds of `Reset' operation
-for the group; these operations on the group apply to all options in
-the group and its subgroups.
-
- Near the top of the customization buffer there are two lines
-containing several active fields:
-
- [Set] [Save] [Reset] [Done]
-
-Invoking `[Done]' buries this customization buffer. Each of the other
-fields performs an operation--set, save or reset--on each of the items
-in the buffer that could meaningfully be set, saved or reset.
-
-\1f
-File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
-
-Customizing Faces
-.................
-
- In addition to user options, some customization groups also include
-faces. When you show the contents of a group, both the user options and
-the faces in the group appear in the customization buffer. Here is an
-example of how a face looks:
-
- Custom Changed Face: (sample)
- [State]: this face is unchanged from its standard setting.
- Face used when the customize item has been changed.
- Parent groups: [Custom Magic Faces]
- Attributes: [ ] Bold: [Toggle] off (nil)
- [ ] Italic: [Toggle] off (nil)
- [ ] Underline: [Toggle] off (nil)
- [ ] Foreground: white (sample)
- [ ] Background: blue (sample)
- [ ] Inverse: [Toggle] off (nil)
- [ ] Stipple:
- [ ] Font Family:
- [ ] Size:
- [ ] Strikethru: off
-
- Each face attribute has its own line. The `[X]' field before the
-attribute name indicates whether the attribute is "enabled"; `X' means
-that it is. You can enable or disable the attribute by invoking that
-field. When the attribute is enabled, you can change the attribute
-value in the usual ways.
-
- Setting, saving and resetting a face work like the same operations
-for options (*note Changing an Option::).
-
- A face can specify different appearances for different types of
-display. For example, a face can make text red on a color display, but
-use a bold font on a monochrome display. To specify multiple
-appearances for a face, select `Show Display Types' in the menu you get
-from invoking `[State]'.
-
-\1f
-File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
-
-Customizing Specific Items
-..........................
-
- Instead of finding the options you want to change by moving down
-through the structure of groups, you can specify the particular option,
-face or group that you want to customize.
-
-`M-x customize-option <RET> OPTION <RET>'
- Set up a customization buffer with just one option, OPTION.
-
-`M-x customize-face <RET> FACE <RET>'
- Set up a customization buffer with just one face, FACE.
-
-`M-x customize-group <RET> GROUP <RET>'
- Set up a customization buffer with just one group, GROUP.
-
-`M-x customize-apropos <RET> REGEXP <RET>'
- Set up a customization buffer with all the options, faces and
- groups that match REGEXP.
-
-`M-x customize-saved'
- Set up a customization buffer containing all options and faces
- that you have saved with customization buffers.
-
-`M-x customize-customized'
- Set up a customization buffer containing all options and faces
- that you have customized but not saved.
-
- If you want to alter a particular user option variable with the
-customization buffer, and you know its name, you can use the command
-`M-x customize-option' and specify the option name. This sets up the
-customization buffer with just one option--the one that you asked for.
-Editing, setting and saving the value work as described above, but only
-for the specified option.
-
- Likewise, you can modify a specific face, chosen by name, using `M-x
-customize-face'.
-
- You can also set up the customization buffer with a specific group,
-using `M-x customize-group'. The immediate contents of the chosen
-group, including option variables, faces, and other groups, all appear
-as well. However, these subgroups' own contents start out hidden. You
-can show their contents in the usual way, by invoking `[Show]'.
-
- To control more precisely what to customize, you can use `M-x
-customize-apropos'. You specify a regular expression as argument; then
-all options, faces and groups whose names match this regular expression
-are set up in the customization buffer. If you specify an empty regular
-expression, this includes _all_ groups, options and faces in the
-customization buffer (but that takes a long time).
-
- If you change option values and then decide the change was a mistake,
-you can use two special commands to revisit your previous changes. Use
-`customize-saved' to look at the options and faces that you have saved.
-Use `M-x customize-customized' to look at the options and faces that
-you have set but not saved.
-
-\1f
-File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables
-
-Editing Variable Values
------------------------
-
-`M-x list-options'
- Display a buffer listing names, values, and documentation of all
- options.
-
-`M-x edit-options'
- Change option values by editing a list of options.
-
- `M-x list-options' displays a list of all Emacs option variables in
-an Emacs buffer named `*List Options*'. Each option is shown with its
-documentation and its current value. Here is what a portion of it might
-look like:
-
- ;; exec-path:
- ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
- *List of directories to search programs to run in subprocesses.
- Each element is a string (directory name)
- or nil (try the default directory).
- ;;
- ;; fill-column:
- 75
- *Column beyond which automatic line-wrapping should happen.
- Automatically becomes local when set in any fashion.
- ;;
-
- `M-x edit-options' goes one step further and immediately selects the
-`*List Options*' buffer; this buffer uses the major mode Options mode,
-which provides commands that allow you to point at an option and change
-its value:
-
-`s'
- Set the variable point is in or near to a new value read using the
- minibuffer.
-
-`x'
- Toggle the variable point is in or near: if the value was `nil',
- it becomes `t'; otherwise it becomes `nil'.
-
-`1'
- Set the variable point is in or near to `t'.
-
-`0'
- Set the variable point is in or near to `nil'.
-
-`n'
-`p'
- Move to the next or previous variable.
-
-\1f
-File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables
-
-Local Variables
----------------
-
-`M-x make-local-variable'
- Make a variable have a local value in the current buffer.
-
-`M-x kill-local-variable'
- Make a variable use its global value in the current buffer.
-
-`M-x make-variable-buffer-local'
- Mark a variable so that setting it will make it local to the
- buffer that is current at that time.
-
- You can make any variable "local" to a specific Emacs buffer. This
-means that the variable's value in that buffer is independent of its
-value in other buffers. A few variables are always local in every
-buffer. All other Emacs variables have a "global" value which is in
-effect in all buffers that have not made the variable local.
-
- Major modes always make the variables they set local to the buffer.
-This is why changing major modes in one buffer has no effect on other
-buffers.
-
- `M-x make-local-variable' reads the name of a variable and makes it
-local to the current buffer. Further changes in this buffer will not
-affect others, and changes in the global value will not affect this
-buffer.
-
- `M-x make-variable-buffer-local' reads the name of a variable and
-changes the future behavior of the variable so that it automatically
-becomes local when it is set. More precisely, once you have marked a
-variable in this way, the usual ways of setting the variable will
-automatically invoke `make-local-variable' first. We call such
-variables "per-buffer" variables.
-
- Some important variables have been marked per-buffer already. They
-include `abbrev-mode', `auto-fill-function', `case-fold-search',
-`comment-column', `ctl-arrow', `fill-column', `fill-prefix',
-`indent-tabs-mode', `left-margin',
-`mode-line-format', `overwrite-mode', `selective-display-ellipses',
-`selective-display', `tab-width', and `truncate-lines'. Some other
-variables are always local in every buffer, but they are used for
-internal purposes.
-
- Note: the variable `auto-fill-function' was formerly named
-`auto-fill-hook'.
-
- If you want a variable to cease to be local to the current buffer,
-call `M-x kill-local-variable' and provide the name of a variable to
-the prompt. The global value of the variable is again in effect in
-this buffer. Setting the major mode kills all the local variables of
-the buffer.
-
- To set the global value of a variable, regardless of whether the
-variable has a local value in the current buffer, you can use the Lisp
-function `setq-default'. It works like `setq'. If there is a local
-value in the current buffer, the local value is not affected by
-`setq-default'; thus, the new global value may not be visible until you
-switch to another buffer, as in the case of:
-
- (setq-default fill-column 75)
-
-`setq-default' is the only way to set the global value of a variable
-that has been marked with `make-variable-buffer-local'.
-
- Programs can look at a variable's default value with `default-value'.
-This function takes a symbol as an argument and returns its default
-value. The argument is evaluated; usually you must quote it
-explicitly, as in the case of:
-
- (default-value 'fill-column)
-
projects / chise / xemacs-chise.git- / blobdiff