X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-11;h=bf640bd62f012c4e2f849dee54227503d35168bd;hb=98769b42a33fd8236341ac4175165b2dab7ceae4;hp=c9ba3be7fa2c381f2fa4f8b817ce9d43b3d9337e;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git diff --git a/info/xemacs.info-11 b/info/xemacs.info-11 index c9ba3be..bf640bd 100644 --- a/info/xemacs.info-11 +++ b/info/xemacs.info-11 @@ -1,5 +1,5 @@ -This is Info file ../../info/xemacs.info, produced by Makeinfo version -1.68 from the input file xemacs.texi. +This is ../info/xemacs.info, produced by makeinfo version 4.0b from +xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -30,1104 +30,1144 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs - -Change Logs -=========== - - The Emacs command `M-x add-change-log-entry' helps you keep a record -of when and why you have changed a program. It assumes that you have a -file in which you write a chronological sequence of entries describing -individual changes. The default is to store the change entries in a -file called `ChangeLog' in the same directory as the file you are -editing. The same `ChangeLog' file therefore records changes for all -the files in a directory. - - A change log entry starts with a header line that contains your name -and the current date. Except for these header lines, every line in the -change log starts with a tab. One entry can describe several changes; -each change starts with a line starting with a tab and a star. `M-x -add-change-log-entry' visits the change log file and creates a new entry -unless the most recent entry is for today's date and your name. In -either case, it adds a new line to start the description of another -change just after the header line of the entry. When `M-x -add-change-log-entry' is finished, all is prepared for you to edit in -the description of what you changed and how. You must then save the -change log file yourself. - - The change log file is always visited in Indented Text mode, which -means that and auto-filling indent each new line like the previous -line. This is convenient for entering the contents of an entry, which -must be indented. *Note Text Mode::. - - Here is an example of the formatting conventions used in the change -log for Emacs: - - Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep) - - * xdisp.c (try_window_id): - If C-k is done at end of next-to-last line, - this fn updates window_end_vpos and cannot leave - window_end_pos nonnegative (it is zero, in fact). - If display is preempted before lines are output, - this is inconsistent. Fix by setting - blank_end_of_window to nonzero. - - Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep) - - * cmds.c (Fnewline): - Call the auto fill hook if appropriate. - - * xdisp.c (try_window_id): - If point is found by compute_motion after xp, record that - permanently. If display_text_line sets point position wrong - (case where line is killed, point is at eob and that line is - not displayed), set it again in final compute_motion. +File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text + +Pages +===== + + Files are often thought of as divided into "pages" by the "formfeed" +character (ASCII Control-L, octal code 014). For example, if a file is +printed on a line printer, each "page" of the file starts on a new page +of paper. Emacs treats a page-separator character just like any other +character. It can be inserted with `C-q C-l' or deleted with . +You are free to paginate your file or not. However, since pages are +often meaningful divisions of the file, commands are provided to move +over them and operate on them. + +`C-x [' + Move point to previous page boundary (`backward-page'). + +`C-x ]' + Move point to next page boundary (`forward-page'). + +`C-x C-p' + Put point and mark around this page (or another page) + (`mark-page'). + +`C-x l' + Count the lines in this page (`count-lines-page'). + + The `C-x [' (`backward-page') command moves point to immediately +after the previous page delimiter. If point is already right after a +page delimiter, the command skips that one and stops at the previous +one. A numeric argument serves as a repeat count. The `C-x ]' +(`forward-page') command moves forward past the next page delimiter. + + The `C-x C-p' command (`mark-page') puts point at the beginning of +the current page and the mark at the end. The page delimiter at the end +is included (the mark follows it). The page delimiter at the front is +excluded (point follows it). You can follow this command by `C-w' to +kill a page you want to move elsewhere. If you insert the page after a +page delimiter, at a place where `C-x ]' or `C-x [' would take you, the +page will be properly delimited before and after once again. + + A numeric argument to `C-x C-p' is used to specify which page to go +to, relative to the current one. Zero means the current page. One +means the next page, and -1 means the previous one. + + The `C-x l' command (`count-lines-page') can help you decide where +to break a page in two. It prints the total number of lines in the +current page in the echo area, then divides the lines into those +preceding the current line and those following it, for example + + Page has 96 (72+25) lines + +Notice that the sum is off by one; this is correct if point is not at +the beginning of a line. + + The variable `page-delimiter' should have as its value a regexp that +matches the beginning of a line that separates pages. This defines +where pages begin. The normal value of this variable is `"^\f"', which +matches a formfeed character at the beginning of a line.  -File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs +File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text -Tags Tables -=========== - - A "tags table" is a description of how a multi-file program is -broken up into files. It lists the names of the component files and the -names and positions of the functions (or other named subunits) in each -file. Grouping the related files makes it possible to search or replace -through all the files with one command. Recording the function names -and positions makes possible the `M-.' command which finds the -definition of a function by looking up which of the files it is in. - - Tags tables are stored in files called "tags table files". The -conventional name for a tags table file is `TAGS'. - - Each entry in the tags table records the name of one tag, the name -of the file that the tag is defined in (implicitly), and the position -in that file of the tag's definition. +Filling Text +============ - Just what names from the described files are recorded in the tags -table depends on the programming language of the described file. They -normally include all functions and subroutines, and may also include -global variables, data types, and anything else convenient. Each name -recorded is called a "tag". + If you use Auto Fill mode, Emacs "fills" text (breaks it up into +lines that fit in a specified width) as you insert it. When you alter +existing text it is often no longer be properly filled afterwards and +you can use explicit commands for filling. * Menu: -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with `etags'. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Listing and finding tags defined in a file. +* Auto Fill:: Auto Fill mode breaks long lines automatically. +* Fill Commands:: Commands to refill paragraphs and center lines. +* Fill Prefix:: Filling when every line is indented or in a comment, etc.  -File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Up: Tags - -Source File Tag Syntax ----------------------- - - Here is how tag syntax is defined for the most popular languages: - - * In C code, any C function or typedef is a tag, and so are - definitions of `struct', `union' and `enum'. `#define' macro - definitions and `enum' constants are also tags, unless you specify - `--no-defines' when making the tags table. Similarly, global - variables are tags, unless you specify `--no-globals'. Use of - `--no-globals' and `--no-defines' can make the tags table file - much smaller. - - * In C++ code, in addition to all the tag constructs of C code, - member functions are also recognized, and optionally member - variables if you use the `--members' option. Tags for variables - and functions in classes are named `CLASS::VARIABLE' and - `CLASS::FUNCTION'. - - * In Java code, tags include all the constructs recognized in C++, - plus the `extends' and `implements' constructs. Tags for variables - and functions in classes are named `CLASS.VARIABLE' and - `CLASS.FUNCTION'. +File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling + +Auto Fill Mode +-------------- + + "Auto Fill" mode is a minor mode in which lines are broken +automatically when they become too wide. Breaking happens only when +you type a or . + +`M-x auto-fill-mode' + Enable or disable Auto Fill mode. + +`' +`' + In Auto Fill mode, break lines when appropriate. + + `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off +if it was on. With a positive numeric argument the command always turns +Auto Fill mode on, and with a negative argument it always turns it off. +The presence of the word `Fill' in the mode line, inside the +parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode +is a minor mode; you can turn it on or off for each buffer individually. +*Note Minor Modes::. + + In Auto Fill mode, lines are broken automatically at spaces when +they get longer than desired. Line breaking and rearrangement takes +place only when you type or . To insert a space or newline +without permitting line-breaking, type `C-q ' or `C-q ' +(recall that a newline is really a linefeed). `C-o' inserts a newline +without line breaking. + + Auto Fill mode works well with Lisp mode: when it makes a new line in +Lisp mode, it indents that line with . If a line ending in a Lisp +comment gets too long, the text of the comment is split into two +comment lines. Optionally, new comment delimiters are inserted at the +end of the first line and the beginning of the second, so that each line +is a separate comment. The variable `comment-multi-line' controls the +choice (*note Comments::). + + Auto Fill mode does not refill entire paragraphs. It can break +lines but cannot merge lines. Editing in the middle of a paragraph can +result in a paragraph that is not correctly filled. The easiest way to +make the paragraph properly filled again is using an explicit fill +commands. + + Many users like Auto Fill mode and want to use it in all text files. +The section on init files explains how you can arrange this permanently +for yourself. *Note Init File::. - * In LaTeX text, the argument of any of the commands `\chapter', - `\section', `\subsection', `\subsubsection', `\eqno', `\label', - `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or - `\index', is a tag. - - Other commands can make tags as well, if you specify them in the - environment variable `TEXTAGS' before invoking `etags'. The value - of this environment variable should be a colon-separated list of - commands names. For example, - - TEXTAGS="def:newcommand:newenvironment" - export TEXTAGS - - specifies (using Bourne shell syntax) that the commands `\def', - `\newcommand' and `\newenvironment' also define tags. - - * In Lisp code, any function defined with `defun', any variable - defined with `defvar' or `defconst', and in general the first - argument of any expression that starts with `(def' in column zero, - is a tag. + +File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling - * In Scheme code, tags include anything defined with `def' or with a - construct whose name starts with `def'. They also include - variables set with `set!' at top level in the file. +Explicit Fill Commands +---------------------- - Several other languages are also supported: +`M-q' + Fill current paragraph (`fill-paragraph'). - * In assembler code, labels appearing at the beginning of a line, - followed by a colon, are tags. +`M-g' + Fill each paragraph in the region (`fill-region'). - * In Bison or Yacc input files, each rule defines as a tag the - nonterminal it constructs. The portions of the file that contain - C code are parsed as C code. +`C-x f' + Set the fill column (`set-fill-column'). - * In Cobol code, paragraphs names are the tags, i.e. any word - starting in column 8 and followed by a full stop. +`M-x fill-region-as-paragraph' + Fill the region, considering it as one paragraph. - * In Erlang code, the tags are the functions, records, and macros - defined in the file. +`M-s' + Center a line. - * In Fortran code, functions and subroutines are tags. + To refill a paragraph, use the command `Meta-q' (`fill-paragraph'). +It causes the paragraph containing point, or the one after point if +point is between paragraphs, to be refilled. All line breaks are +removed, and new ones are inserted where necessary. `M-q' can be +undone with `C-_'. *Note Undo::. - * In Objective C code, tags include Objective C definitions for - classes, class categories, methods and protocols. + To refill many paragraphs, use `M-g' (`fill-region'), which divides +the region into paragraphs and fills each of them. - * In Pascal code, the tags are the functions and procedures defined - in the file. + `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding +paragraph boundaries (*note Paragraphs::). For more control, you can +use `M-x fill-region-as-paragraph', which refills everything between +point and mark. This command recognizes only blank lines as paragraph +separators. - * In Perl code, the tags are the procedures defined by the `sub' - keyword. + A numeric argument to `M-g' or `M-q' causes it to "justify" the text +as well as filling it. Extra spaces are inserted to make the right +margin line up exactly at the fill column. To remove the extra spaces, +use `M-q' or `M-g' with no argument. - * In Postscript code, the tags are the functions. + The variable `auto-fill-inhibit-regexp' takes as a value a regexp to +match lines that should not be auto-filled. - * In Prolog code, a tag name appears at the left margin. + The command `Meta-s' (`center-line') centers the current line within +the current fill column. With an argument, it centers several lines +individually and moves past them. - You can also generate tags based on regexp matching (*note Create -Tags Table::.) to handle other formats and languages. + The maximum line width for filling is in the variable `fill-column'. +Altering the value of `fill-column' makes it local to the current +buffer; until then, the default value--initially 70--is in effect. +*Note Locals::. - -File: xemacs.info, Node: Create Tags Table, Next: Select Tags Table, Prev: Tag Syntax, Up: Tags - -Creating Tags Tables --------------------- - - The `etags' program is used to create a tags table file. It knows -the syntax of several languages, as described in *Note Tag Syntax::. -Here is how to run `etags': - - etags INPUTFILES... - -The `etags' program reads the specified files, and writes a tags table -named `TAGS' in the current working directory. `etags' recognizes the -language used in an input file based on its file name and contents. -You can specify the language with the `--language=NAME' option, -described below. - - If the tags table data become outdated due to changes in the files -described in the table, the way to update the tags table is the same -way it was made in the first place. It is not necessary to do this -often. - - If the tags table fails to record a tag, or records it for the wrong -file, then Emacs cannot possibly find its definition. However, if the -position recorded in the tags table becomes a little bit wrong (due to -some editing in the file that the tag definition is in), the only -consequence is a slight delay in finding the tag. Even if the stored -position is very wrong, Emacs will still find the tag, but it must -search the entire file for it. - - So you should update a tags table when you define new tags that you -want to have listed, or when you move tag definitions from one file to -another, or when changes become substantial. Normally there is no need -to update the tags table after each edit, or even every day. - - One tags table can effectively include another. Specify the included -tags file name with the `--include=FILE' option when creating the file -that is to include it. The latter file then acts as if it contained -all the files specified in the included file, as well as the files it -directly contains. - - If you specify the source files with relative file names when you run -`etags', the tags file will contain file names relative to the -directory where the tags file was initially written. This way, you can -move an entire directory tree containing both the tags file and the -source files, and the tags file will still refer correctly to the source -files. - - If you specify absolute file names as arguments to `etags', then the -tags file will contain absolute file names. This way, the tags file -will still refer to the same files even if you move it, as long as the -source files remain in the same place. Absolute file names start with -`/', or with `DEVICE:/' on MS-DOS and Windows. - - When you want to make a tags table from a great number of files, you -may have problems listing them on the command line, because some systems -have a limit on its length. The simplest way to circumvent this limit -is to tell `etags' to read the file names from its standard input, by -typing a dash in place of the file names, like this: - - find . -name "*.[chCH]" -print | etags - - - Use the option `--language=NAME' to specify the language explicitly. -You can intermix these options with file names; each one applies to -the file names that follow it. Specify `--language=auto' to tell -`etags' to resume guessing the language from the file names and file -contents. Specify `--language=none' to turn off language-specific -processing entirely; then `etags' recognizes tags by regexp matching -alone. `etags --help' prints the list of the languages `etags' knows, -and the file name rules for guessing the language. - - The `--regex' option provides a general way of recognizing tags -based on regexp matching. You can freely intermix it with file names. -Each `--regex' option adds to the preceding ones, and applies only to -the following files. The syntax is: - - --regex=/TAGREGEXP[/NAMEREGEXP]/ - -where TAGREGEXP is used to match the lines to tag. It is always -anchored, that is, it behaves as if preceded by `^'. If you want to -account for indentation, just match any initial number of blanks by -beginning your regular expression with `[ \t]*'. In the regular -expressions, `\' quotes the next character, and `\t' stands for the tab -character. Note that `etags' does not handle the other C escape -sequences for special characters. - - The syntax of regular expressions in `etags' is the same as in -Emacs, augmented with the "interval operator", which works as in `grep' -and `ed'. The syntax of an interval operator is `\{M,N\}', and its -meaning is to match the preceding expression at least M times and up to -N times. - - You should not match more characters with TAGREGEXP than that needed -to recognize what you want to tag. If the match is such that more -characters than needed are unavoidably matched by TAGREGEXP, you may -find useful to add a NAMEREGEXP, in order to narrow the tag scope. You -can find some examples below. - - The `-R' option deletes all the regexps defined with `--regex' -options. It applies to the file names following it, as you can see -from the following example: - - etags --regex=/REG1/ voo.doo --regex=/REG2/ \ - bar.ber -R --lang=lisp los.er - -Here `etags' chooses the parsing language for `voo.doo' and `bar.ber' -according to their contents. `etags' also uses REG1 to recognize -additional tags in `voo.doo', and both REG1 and REG2 to recognize -additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no -regexp matching, to recognize tags in `los.er'. - - Here are some more examples. The regexps are quoted to protect them -from shell interpretation. - -Tag the `DEFVAR' macros in the emacs source files: - - --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' - -Tag VHDL files (this example is a single long line, broken here for -formatting reasons): - - --language=none - --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' - --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ - \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' - -Tag TCL files (this last example shows the usage of a NAMEREGEXP): - - --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' - - For a list of the other available `etags' options, execute `etags ---help'. + The easiest way to set `fill-column' is to use the command `C-x f' +(`set-fill-column'). With no argument, it sets `fill-column' to the +current horizontal position of point. With a numeric argument, it uses +that number as the new fill column.  -File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Create Tags Table, Up: Tags +File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling -Selecting a Tags Table ----------------------- +The Fill Prefix +--------------- - At any time Emacs has one "selected" tags table, and all the commands -for working with tags tables use the selected one. To select a tags -table, use the variable `tag-table-alist'. - - The value of `tag-table-alist' is a list that determines which -`TAGS' files should be active for a given buffer. This is not really -an association list, in that all elements are checked. The car of each -element of this list is a pattern against which the buffers file name -is compared; if it matches, then the cdr of the list should be the name -of the tags table to use. If more than one element of this list -matches the buffers file name, all of the associated tags tables are -used. Earlier ones are searched first. - - If the car of elements of this list are strings, they are treated as -regular-expressions against which the file is compared (like the -`auto-mode-alist'). If they are not strings, they are evaluated. If -they evaluate to non-`nil', the current buffer is considered to match. - - If the cdr of the elements of this list are strings, they are -assumed to name a tags file. If they name a directory, the string -`tags' is appended to them to get the file name. If they are not -strings, they are evaluated and must return an appropriate string. - - For example: - - (setq tag-table-alist - '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/") - ("\\.el$" . "/usr/local/emacs/src/") - ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/") - ("" . "/usr/local/emacs/src/") - )) - - The example defines the tags table alist in the following way: - - * Anything in the directory `/usr/src/public/perl/' should use the - `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'. - - * Files ending in `.el' should use the `TAGS' file - `/usr/local/emacs/src/TAGS'. - - * Anything in or below the directory `/jbw/gnu/' should use the - `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'. - - If you had a file called `/usr/jbw/foo.el', it would use both `TAGS' -files, -`/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in -that order), because it matches both patterns. - - If the buffer-local variable `buffer-tag-table' is set, it names a -tags table that is searched before all others when `find-tag' is -executed from this buffer. - - If there is a file called `TAGS' in the same directory as the file -in question, then that tags file will always be used as well (after the -`buffer-tag-table' but before the tables specified by this list). - - If the variable `tags-file-name' is set, the `TAGS' file it names -will apply to all buffers (for backwards compatibility.) It is searched -first. - - If the value of the variable `tags-always-build-completion-table' is -`t', the tags file will always be added to the completion table without -asking first, regardless of the size of the tags file. - - The function `M-x visit-tags-table', is largely made obsolete by the -variable `tag-table-alist', tells tags commands to use the tags table -file FILE first. The FILE should be the name of a file created with -the `etags' program. A directory name is also acceptable; it means the -file `TAGS' in that directory. The function only stores the file name -you provide in the variable `tags-file-name'. Emacs does not actually -read in the tags table contents until you try to use them. You can set -the variable explicitly instead of using `visit-tags-table'. The value -of the variable `tags-file-name' is the name of the tags table used by -all buffers. This is for backward compatibility, and is largely -supplanted by the variable `tag-table-alist'. + To fill a paragraph in which each line starts with a special marker +(which might be a few spaces, giving an indented paragraph), use the +"fill prefix" feature. The fill prefix is a string which is not +included in filling. Emacs expects every line to start with a fill +prefix. + +`C-x .' + Set the fill prefix (`set-fill-prefix'). + +`M-q' + Fill a paragraph using current fill prefix (`fill-paragraph'). + +`M-x fill-individual-paragraphs' + Fill the region, considering each change of indentation as + starting a new paragraph. + + To specify a fill prefix, move to a line that starts with the desired +prefix, put point at the end of the prefix, and give the command +`C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn +off the fill prefix, specify an empty prefix: type `C-x .' with point +at the beginning of a line. + + When a fill prefix is in effect, the fill commands remove the fill +prefix from each line before filling and insert it on each line after +filling. Auto Fill mode also inserts the fill prefix inserted on new +lines it creates. Lines that do not start with the fill prefix are +considered to start paragraphs, both in `M-q' and the paragraph +commands; this is just right if you are using paragraphs with hanging +indentation (every line indented except the first one). Lines which are +blank or indented once the prefix is removed also separate or start +paragraphs; this is what you want if you are writing multi-paragraph +comments with a comment delimiter on each line. + + The fill prefix is stored in the variable `fill-prefix'. Its value +is a string, or `nil' when there is no fill prefix. This is a +per-buffer variable; altering the variable affects only the current +buffer, but there is a default value which you can change as well. +*Note Locals::. + + Another way to use fill prefixes is through `M-x +fill-individual-paragraphs'. This function divides the region into +groups of consecutive lines with the same amount and kind of +indentation and fills each group as a paragraph, using its indentation +as a fill prefix.  -File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags - -Finding a Tag -------------- +File: xemacs.info, Node: Case, Prev: Filling, Up: Text - The most important thing that a tags table enables you to do is to -find the definition of a specific tag. +Case Conversion Commands +======================== -`M-. TAG &OPTIONAL OTHER-WINDOW' - Find first definition of TAG (`find-tag'). + Emacs has commands for converting either a single word or any +arbitrary range of text to upper case or to lower case. -`C-u M-.' - Find next alternate definition of last tag specified. +`M-l' + Convert following word to lower case (`downcase-word'). -`C-x 4 . TAG' - Find first definition of TAG, but display it in another window - (`find-tag-other-window'). +`M-u' + Convert following word to upper case (`upcase-word'). - `M-.' (`find-tag') is the command to find the definition of a -specified tag. It searches through the tags table for that tag, as a -string, then uses the tags table information to determine the file in -which the definition is used and the approximate character position of -the definition in the file. Then `find-tag' visits the file, moves -point to the approximate character position, and starts searching -ever-increasing distances away for the text that should appear at the -beginning of the definition. +`M-c' + Capitalize the following word (`capitalize-word'). - If an empty argument is given (by typing ), the sexp in the -buffer before or around point is used as the name of the tag to find. -*Note Lists::, for information on sexps. +`C-x C-l' + Convert region to lower case (`downcase-region'). - The argument to `find-tag' need not be the whole tag name; it can be -a substring of a tag name. However, there can be many tag names -containing the substring you specify. Since `find-tag' works by -searching the text of the tags table, it finds the first tag in the -table that the specified substring appears in. To find other tags that -match the substring, give `find-tag' a numeric argument, as in `C-u -M-.'. This does not read a tag name, but continues searching the tag -table's text for another tag containing the same substring last used. -If your keyboard has a real key, `M-0 M-.' is an easier -alternative to `C-u M-.'. +`C-x C-u' + Convert region to upper case (`upcase-region'). - If the optional second argument OTHER-WINDOW is non-`nil', it uses -another window to display the tag. Multiple active tags tables and -completion are supported. + The word conversion commands are used most frequently. `Meta-l' +(`downcase-word') converts the word after point to lower case, moving +past it. Thus, repeating `Meta-l' converts successive words. `Meta-u' +(`upcase-word') converts to all capitals instead, while `Meta-c' +(`capitalize-word') puts the first letter of the word into upper case +and the rest into lower case. The word conversion commands convert +several words at once if given an argument. They are especially +convenient for converting a large amount of text from all upper case to +mixed case: you can move through the text using `M-l', `M-u', or `M-c' +on each word as appropriate, occasionally using `M-f' instead to skip a +word. - Variables of note include the following: + When given a negative argument, the word case conversion commands +apply to the appropriate number of words before point, but do not move +point. This is convenient when you have just typed a word in the wrong +case: you can give the case conversion command and continue typing. -`tag-table-alist' - Controls which tables apply to which buffers. + If a word case conversion command is given in the middle of a word, +it applies only to the part of the word which follows point. This is +just like what `Meta-d' (`kill-word') does. With a negative argument, +case conversion applies only to the part of the word before point. -`tags-file-name' - Stores a default tags table. - -`tags-build-completion-table' - Controls completion behavior. - -`buffer-tag-table' - Specifies a buffer-local table. - -`make-tags-files-invisible' - Sets whether tags tables should be very hidden. - -`tag-mark-stack-max' - Specifies how many tags-based hops to remember. - - Like most commands that can switch buffers, `find-tag' has another -similar command that displays the new buffer in another window. `C-x 4 -.' invokes the function `find-tag-other-window'. (This key sequence -ends with a period.) - - Emacs comes with a tags table file `TAGS' (in the directory -containing Lisp libraries) that includes all the Lisp libraries and all -the C sources of Emacs. By specifying this file with `visit-tags-table' -and then using `M-.' you can quickly look at the source of any Emacs -function. + The other case conversion commands are `C-x C-u' (`upcase-region') +and `C-x C-l' (`downcase-region'), which convert everything between +point and mark to the specified case. Point and mark do not move.  -File: xemacs.info, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags - -Searching and Replacing with Tags Tables ----------------------------------------- - - The commands in this section visit and search all the files listed -in the selected tags table, one by one. For these commands, the tags -table serves only to specify a sequence of files to search. A related -command is `M-x grep' (*note Compilation::.). - -`M-x tags-search REGEXP ' - Search for REGEXP through the files in the selected tags table. - -`M-x tags-query-replace REGEXP REPLACEMENT ' - Perform a `query-replace-regexp' on each file in the selected tags - table. - -`M-,' - Restart one of the commands above, from the current location of - point (`tags-loop-continue'). - - `M-x tags-search' reads a regexp using the minibuffer, then searches -for matches in all the files in the selected tags table, one file at a -time. It displays the name of the file being searched so you can -follow its progress. As soon as it finds an occurrence, `tags-search' -returns. - - Having found one match, you probably want to find all the rest. To -find one more match, type `M-,' (`tags-loop-continue') to resume the -`tags-search'. This searches the rest of the current buffer, followed -by the remaining files of the tags table. - - `M-x tags-query-replace' performs a single `query-replace-regexp' -through all the files in the tags table. It reads a regexp to search -for and a string to replace with, just like ordinary `M-x -query-replace-regexp'. It searches much like `M-x tags-search', but -repeatedly, processing matches according to your input. *Note -Replace::, for more information on query replace. - - It is possible to get through all the files in the tags table with a -single invocation of `M-x tags-query-replace'. But often it is useful -to exit temporarily, which you can do with any input event that has no -special query replace meaning. You can resume the query replace -subsequently by typing `M-,'; this command resumes the last tags search -or replace command that you did. - - The commands in this section carry out much broader searches than the -`find-tag' family. The `find-tag' commands search only for definitions -of tags that match your substring or regexp. The commands -`tags-search' and `tags-query-replace' find every occurrence of the -regexp, as ordinary search commands and replace commands do in the -current buffer. +File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top - These commands create buffers only temporarily for the files that -they have to search (those which are not already visited in Emacs -buffers). Buffers in which no match is found are quickly killed; the -others continue to exist. +Editing Programs +**************** - It may have struck you that `tags-search' is a lot like `grep'. You -can also run `grep' itself as an inferior of Emacs and have Emacs show -you the matching lines one by one. This works much like running a -compilation; finding the source locations of the `grep' matches works -like finding the compilation errors. *Note Compilation::. + Emacs has many commands designed to understand the syntax of +programming languages such as Lisp and C. These commands can: - If you wish to process all the files in a selected tags table, but -`M-x tags-search' and `M-x tags-query-replace' are not giving you the -desired result, you can use `M-x next-file'. + * Move over or kill balanced expressions or "sexps" (*note Lists::). -`C-u M-x next-file' - With a numeric argument, regardless of its value, visit the first - file in the tags table and prepare to advance sequentially by - files. + * Move over or mark top-level balanced expressions ("defuns", in + Lisp; functions, in C). -`M-x next-file' - Visit the next file in the selected tags table. + * Show how parentheses balance (*note Matching::). - -File: xemacs.info, Node: List Tags, Prev: Tags Search, Up: Tags + * Insert, kill, or align comments (*note Comments::). -Tags Table Inquiries --------------------- + * Follow the usual indentation conventions of the language (*note + Grinding::). -`M-x list-tags' - Display a list of the tags defined in a specific program file. + The commands available for words, sentences, and paragraphs are +useful in editing code even though their canonical application is for +editing human language text. Most symbols contain words (*note +Words::); sentences can be found in strings and comments (*note +Sentences::). Paragraphs per se are not present in code, but the +paragraph commands are useful anyway, because Lisp mode and C mode +define paragraphs to begin and end at blank lines (*note Paragraphs::). +Judicious use of blank lines to make the program clearer also provides +interesting chunks of text for the paragraph commands to work on. -`M-x tags-apropos' - Display a list of all tags matching a specified regexp. + The selective display feature is useful for looking at the overall +structure of a function (*note Selective Display::). This feature +causes only the lines that are indented less than a specified amount to +appear on the screen. - `M-x list-tags' reads the name of one of the files described by the -selected tags table, and displays a list of all the tags defined in that -file. The "file name" argument is really just a string to compare -against the names recorded in the tags table; it is read as a string -rather than a file name. Therefore, completion and defaulting are not -available, and you must enter the string the same way it appears in the -tag table. Do not include a directory as part of the file name unless -the file name recorded in the tags table contains that directory. +* Menu: - `M-x tags-apropos' is like `apropos' for tags. It reads a regexp, -then finds all the tags in the selected tags table whose entries match -that regexp, and displays the tag names found. +* Program Modes:: Major modes for editing programs. +* Lists:: Expressions with balanced parentheses. + There are editing commands to operate on them. +* Defuns:: Each program is made up of separate functions. + There are editing commands to operate on them. +* Grinding:: Adjusting indentation to show the nesting. +* Matching:: Insertion of a close-delimiter flashes matching open. +* Comments:: Inserting, filling and aligning comments. +* Balanced Editing:: Inserting two matching parentheses at once, etc. +* Lisp Completion:: Completion on symbol names in Lisp code. +* Documentation:: Getting documentation of functions you plan to call. +* Change Log:: Maintaining a change history for your program. +* Tags:: Go direct to any function in your program in one + command. Tags remembers which file it is in. +* Fortran:: Fortran mode and its special features. +* Asm Mode:: Asm mode and its special features.  -File: xemacs.info, Node: Fortran, Next: Asm Mode, Prev: Tags, Up: Programs - -Fortran Mode -============ - - Fortran mode provides special motion commands for Fortran statements -and subprograms, and indentation commands that understand Fortran -conventions of nesting, line numbers, and continuation statements. - - Special commands for comments are provided because Fortran comments -are unlike those of other languages. - - Built-in abbrevs optionally save typing when you insert Fortran -keywords. - - Use `M-x fortran-mode' to switch to this major mode. Doing so calls -the value of `fortran-mode-hook' as a function of no arguments if that -variable has a non-`nil' value. +File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs + +Major Modes for Programming Languages +===================================== + + Emacs has several major modes for the programming languages Lisp, +Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major +mode should be implemented for each programming language you might want +to edit with Emacs; but often the mode for one language can serve for +other syntactically similar languages. The language modes that exist +are those that someone decided to take the trouble to write. + + There are several variants of Lisp mode, which differ in the way they +interface to Lisp execution. *Note Lisp Modes::. + + Each of the programming language modes defines the key to run +an indentation function that knows the indentation conventions of that +language and updates the current line's indentation accordingly. For +example, in C mode is bound to `c-indent-line'. is +normally defined to do followed by ; thus it, too, indents +in a mode-specific fashion. + + In most programming languages, indentation is likely to vary from +line to line. So the major modes for those languages rebind to +treat a tab as if it were the equivalent number of spaces (using the +command `backward-delete-char-untabify'). This makes it possible to +rub out indentation one column at a time without worrying whether it is +made up of spaces or tabs. In these modes, use `C-b C-d' to delete a +tab character before point. + + Programming language modes define paragraphs to be separated only by +blank lines, so that the paragraph commands remain useful. Auto Fill +mode, if enabled in a programming language major mode, indents the new +lines which it creates. + + Turning on a major mode calls a user-supplied function called the +"mode hook", which is the value of a Lisp variable. For example, +turning on C mode calls the value of the variable `c-mode-hook' if that +value exists and is non-`nil'. Mode hook variables for other +programming language modes include `lisp-mode-hook', +`emacs-lisp-mode-hook', `lisp-interaction-mode-hook', +`scheme-mode-hook', and `muddle-mode-hook'. The mode hook function +receives no arguments. -* Menu: - -* Motion: Fortran Motion. Moving point by statements or subprograms. -* Indent: Fortran Indent. Indentation commands for Fortran. -* Comments: Fortran Comments. Inserting and aligning comments. -* Columns: Fortran Columns. Measuring columns for valid Fortran. -* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. - - Fortran mode was contributed by Michael Prange. + +File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs + +Lists and Sexps +=============== + + By convention, Emacs keys for dealing with balanced expressions are +usually `Control-Meta-' characters. They tend to be analogous in +function to their `Control-' and `Meta-' equivalents. These commands +are usually thought of as pertaining to expressions in programming +languages, but can be useful with any language in which some sort of +parentheses exist (including English). + + The commands fall into two classes. Some commands deal only with +"lists" (parenthetical groupings). They see nothing except +parentheses, brackets, braces (depending on what must balance in the +language you are working with), and escape characters that might be used +to quote those. + + The other commands deal with expressions or "sexps". The word `sexp' +is derived from "s-expression", the term for a symbolic expression in +Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It +refers to an expression in the language your program is written in. +Each programming language has its own major mode, which customizes the +syntax tables so that expressions in that language count as sexps. + + Sexps typically include symbols, numbers, and string constants, as +well as anything contained in parentheses, brackets, or braces. + + In languages that use prefix and infix operators, such as C, it is +not possible for all expressions to be sexps. For example, C mode does +not recognize `foo + bar' as an sexp, even though it is a C expression; +it recognizes `foo' as one sexp and `bar' as another, with the `+' as +punctuation between them. This is a fundamental ambiguity: both `foo + +bar' and `foo' are legitimate choices for the sexp to move over if +point is at the `f'. Note that `(foo + bar)' is a sexp in C mode. + + Some languages have obscure forms of syntax for expressions that +nobody has bothered to make Emacs understand properly. + +`C-M-f' + Move forward over an sexp (`forward-sexp'). + +`C-M-b' + Move backward over an sexp (`backward-sexp'). + +`C-M-k' + Kill sexp forward (`kill-sexp'). + +`C-M-u' + Move up and backward in list structure (`backward-up-list'). + +`C-M-d' + Move down and forward in list structure (`down-list'). + +`C-M-n' + Move forward over a list (`forward-list'). + +`C-M-p' + Move backward over a list (`backward-list'). + +`C-M-t' + Transpose expressions (`transpose-sexps'). + +`C-M-@' + Put mark after following expression (`mark-sexp'). + + To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the +first significant character after point is an opening delimiter (`(' in +Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing +delimiter. If the character begins a symbol, string, or number, +`C-M-f' moves over that. If the character after point is a closing +delimiter, `C-M-f' just moves past it. (This last is not really moving +across an sexp; it is an exception which is included in the definition +of `C-M-f' because it is as useful a behavior as anyone can think of +for that situation.) + + The command `C-M-b' (`backward-sexp') moves backward over a sexp. +The detailed rules are like those above for `C-M-f', but with +directions reversed. If there are any prefix characters (single quote, +back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back +over them as well. + + `C-M-f' or `C-M-b' with an argument repeats that operation the +specified number of times; with a negative argument, it moves in the +opposite direction. + + In languages such as C where the comment-terminator can be +recognized, the sexp commands move across comments as if they were +whitespace. In Lisp and other languages where comments run until the +end of a line, it is very difficult to ignore comments when parsing +backwards; therefore, in such languages the sexp commands treat the +text of comments as if it were code. + + Killing an sexp at a time can be done with `C-M-k' (`kill-sexp'). +`C-M-k' kills the characters that `C-M-f' would move over. + + The "list commands", `C-M-n' (`forward-list') and `C-M-p' +(`backward-list'), move over lists like the sexp commands but skip over +any number of other kinds of sexps (symbols, strings, etc). In some +situations, these commands are useful because they usually ignore +comments, since the comments usually do not contain any lists. + + `C-M-n' and `C-M-p' stay at the same level in parentheses, when that +is possible. To move up one (or N) levels, use `C-M-u' +(`backward-up-list'). `C-M-u' moves backward up past one unmatched +opening delimiter. A positive argument serves as a repeat count; a +negative argument reverses direction of motion and also requests +repetition, so it moves forward and up one or more levels. + + To move down in list structure, use `C-M-d' (`down-list'). In Lisp +mode, where `(' is the only opening delimiter, this is nearly the same +as searching for a `('. An argument specifies the number of levels of +parentheses to go down. + + `C-M-t' (`transpose-sexps') drags the previous sexp across the next +one. An argument serves as a repeat count, and a negative argument +drags backwards (thus canceling out the effect of `C-M-t' with a +positive argument). An argument of zero, rather than doing nothing, +transposes the sexps ending after point and the mark. + + To make the region be the next sexp in the buffer, use `C-M-@' +(`mark-sexp') which sets the mark at the same place that `C-M-f' would +move to. `C-M-@' takes arguments like `C-M-f'. In particular, a +negative argument is useful for putting the mark at the beginning of +the previous sexp. + + The list and sexp commands' understanding of syntax is completely +controlled by the syntax table. Any character can, for example, be +declared to be an opening delimiter and act like an open parenthesis. +*Note Syntax::.  -File: xemacs.info, Node: Fortran Motion, Next: Fortran Indent, Prev: Fortran, Up: Fortran +File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs -Motion Commands ---------------- +Defuns +====== - Fortran mode provides special commands to move by subprograms -(functions and subroutines) and by statements. There is also a command -to put the region around one subprogram, which is convenient for -killing it or moving it. + In Emacs, a parenthetical grouping at the top level in the buffer is +called a "defun". The name derives from the fact that most top-level +lists in Lisp are instances of the special form `defun', but Emacs +calls any top-level parenthetical grouping counts a defun regardless of +its contents or the programming language. For example, in C, the body +of a function definition is a defun. `C-M-a' - Move to beginning of subprogram - (`beginning-of-fortran-subprogram'). + Move to beginning of current or preceding defun + (`beginning-of-defun'). `C-M-e' - Move to end of subprogram (`end-of-fortran-subprogram'). + Move to end of current or following defun (`end-of-defun'). `C-M-h' - Put point at beginning of subprogram and mark at end - (`mark-fortran-subprogram'). - -`C-c C-n' - Move to beginning of current or next statement (`fortran-next- - statement'). - -`C-c C-p' - Move to beginning of current or previous statement (`fortran- - previous-statement'). + Put region around whole current or following defun (`mark-defun'). + + The commands to move to the beginning and end of the current defun +are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun'). + + To operate on the current defun, use `C-M-h' (`mark-defun') which +puts point at the beginning and the mark at the end of the current or +next defun. This is the easiest way to prepare for moving the defun to +a different place. In C mode, `C-M-h' runs the function +`mark-c-function', which is almost the same as `mark-defun', but which +backs up over the argument declarations, function name, and returned +data type so that the entire C function is inside the region. + + To compile and evaluate the current defun, use `M-x compile-defun'. +This function prints the results in the minibuffer. If you include an +argument, it inserts the value in the current buffer after the defun. + + Emacs assumes that any open-parenthesis found in the leftmost column +is the start of a defun. Therefore, never put an open-parenthesis at +the left margin in a Lisp file unless it is the start of a top level +list. Never put an open-brace or other opening delimiter at the +beginning of a line of C code unless it starts the body of a function. +The most likely problem case is when you want an opening delimiter at +the start of a line inside a string. To avoid trouble, put an escape +character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects) +before the opening delimiter. It will not affect the contents of the +string. + + The original Emacs found defuns by moving upward a level of +parentheses until there were no more levels to go up. This required +scanning back to the beginning of the buffer for every function. To +speed this up, Emacs was changed to assume that any `(' (or other +character assigned the syntactic class of opening-delimiter) at the +left margin is the start of a defun. This heuristic is nearly always +right; however, it mandates the convention described above.  -File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran +File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs -Fortran Indentation -------------------- +Indentation for Programs +======================== - Special commands and features are available for indenting Fortran -code. They make sure various syntactic entities (line numbers, comment -line indicators, and continuation line flags) appear in the columns -that are required for standard Fortran. + The best way to keep a program properly indented ("ground") is to +use Emacs to re-indent it as you change the program. Emacs has commands +to indent properly either a single line, a specified number of lines, or +all of the lines inside a single parenthetical grouping. * Menu: -* Commands: ForIndent Commands. Commands for indenting Fortran. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. +* Basic Indent:: +* Multi-line Indent:: Commands to reindent many lines at once. +* Lisp Indent:: Specifying how each Lisp function should be indented. +* C Indent:: Choosing an indentation style for C code.  -File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent +File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding -Fortran Indentation Commands -............................ +Basic Program Indentation Commands +---------------------------------- `' - Indent the current line (`fortran-indent-line'). + Adjust indentation of current line. -`M-' - Break the current line and set up a continuation line. +`' + Equivalent to followed by (`newline-and-indent'). + + The basic indentation command is , which gives the current line +the correct indentation as determined from the previous lines. The +function that runs depends on the major mode; it is +`lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These +functions understand different syntaxes for different languages, but +they all do about the same thing. in any programming language +major mode inserts or deletes whitespace at the beginning of the +current line, independent of where point is in the line. If point is +inside the whitespace at the beginning of the line, leaves it at +the end of that whitespace; otherwise, leaves point fixed with +respect to the characters around it. + + Use `C-q ' to insert a tab at point. + + When entering a large amount of new code, use +(`newline-and-indent'), which is equivalent to a followed by a +. creates a blank line, then gives it the appropriate +indentation. + + indents the second and following lines of the body of a +parenthetical grouping each under the preceding one; therefore, if you +alter one line's indentation to be nonstandard, the lines below tend to +follow it. This is the right behavior in cases where the standard +result of does not look good. + + Remember that Emacs assumes that an open-parenthesis, open-brace, or +other opening delimiter at the left margin (including the indentation +routines) is the start of a function. You should therefore never have +an opening delimiter in column zero that is not the beginning of a +function, not even inside a string. This restriction is vital for +making the indentation commands fast. *Note Defuns::, for more +information on this behavior. -`C-M-q' - Indent all the lines of the subprogram point is in - (`fortran-indent-subprogram'). + +File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding - is redefined by Fortran mode to reindent the current line for -Fortran (`fortran-indent-line'). Line numbers and continuation markers -are indented to their required columns, and the body of the statement -is independently indented, based on its nesting in the program. +Indenting Several Lines +----------------------- - The key `C-M-q' is redefined as `fortran-indent-subprogram', a -command that reindents all the lines of the Fortran subprogram -(function or subroutine) containing point. + Several commands are available to re-indent several lines of code +which have been altered or moved to a different level in a list +structure. - The key `M-' is redefined as `fortran-split-line', a command to -split a line in the appropriate fashion for Fortran. In a non-comment -line, the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. +`C-M-q' + Re-indent all the lines within one list (`indent-sexp'). + +`C-u ' + Shift an entire list rigidly sideways so that its first line is + properly indented. + +`C-M-\' + Re-indent all lines in the region (`indent-region'). + + To re-indent the contents of a single list, position point before the +beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in +Lisp mode, `indent-c-exp' in C mode, and bound to other suitable +functions in other modes. The indentation of the line the sexp starts +on is not changed; therefore, only the relative indentation within the +list, and not its position, is changed. To correct the position as +well, type a before `C-M-q'. + + If the relative indentation within a list is correct but the +indentation of its beginning is not, go to the line on which the list +begins and type `C-u '. When you give a numeric argument, +it moves all the lines in the group, starting on the current line, +sideways the same amount that the current line moves. The command does +not move lines that start inside strings, or C preprocessor lines when +in C mode. + + Another way to specify a range to be re-indented is with point and +mark. The command `C-M-\' (`indent-region') applies to every +line whose first character is between point and mark.  -File: xemacs.info, Node: ForIndent Num, Next: ForIndent Conv, Prev: ForIndent Commands, Up: Fortran Indent - -Line Numbers and Continuation -............................. - - If a number is the first non-whitespace in the line, it is assumed -to be a line number and is moved to columns 0 through 4. (Columns are -always counted from 0 in XEmacs.) If the text on the line starts with -the conventional Fortran continuation marker `$', it is moved to column -5. If the text begins with any non whitespace character in column 5, -it is assumed to be an unconventional continuation marker and remains -in column 5. - - Line numbers of four digits or less are normally indented one space. -This amount is controlled by the variable `fortran-line-number-indent', -which is the maximum indentation a line number can have. Line numbers -are indented to right-justify them to end in column 4 unless that would -require more than the maximum indentation. The default value of the -variable is 1. - - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -`fortran-electric-line-number' to `nil'. Then inserting line numbers -is like inserting anything else. +File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding - -File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent +Customizing Lisp Indentation +---------------------------- + + The indentation pattern for a Lisp expression can depend on the +function called by the expression. For each Lisp function, you can +choose among several predefined patterns of indentation, or define an +arbitrary one with a Lisp program. -Syntactic Conventions -..................... + The standard pattern of indentation is as follows: the second line +of the expression is indented under the first argument, if that is on +the same line as the beginning of the expression; otherwise, the second +line is indented underneath the function name. Each following line is +indented under the previous line whose nesting depth is the same. - Fortran mode assumes that you follow certain conventions that -simplify the task of understanding a Fortran program well enough to -indent it properly: + If the variable `lisp-indent-offset' is non-`nil', it overrides the +usual indentation pattern for the second line of an expression, so that +such lines are always indented `lisp-indent-offset' more columns than +the containing list. - * Two nested `do' loops never share a `continue' statement. + Certain functions override the standard pattern. Functions whose +names start with `def' always indent the second line by +`lisp-body-indention' extra columns beyond the open-parenthesis +starting the expression. - * The same character appears in column 5 of all continuation lines. - It is the value of the variable `fortran-continuation-char'. By - default, this character is `$'. + Individual functions can override the standard pattern in various +ways, according to the `lisp-indent-function' property of the function +name. (Note: `lisp-indent-function' was formerly called +`lisp-indent-hook'). There are four possibilities for this property: -If you fail to follow these conventions, the indentation commands may -indent some lines unaesthetically. However, a correct Fortran program -will retain its meaning when reindented even if the conventions are not -followed. +`nil' + This is the same as no property; the standard indentation pattern + is used. + +`defun' + The pattern used for function names that start with `def' is used + for this function also. + +a number, NUMBER + The first NUMBER arguments of the function are "distinguished" + arguments; the rest are considered the "body" of the expression. + A line in the expression is indented according to whether the + first argument on it is distinguished or not. If the argument is + part of the body, the line is indented `lisp-body-indent' more + columns than the open-parenthesis starting the containing + expression. If the argument is distinguished and is either the + first or second argument, it is indented twice that many extra + columns. If the argument is distinguished and not the first or + second argument, the standard pattern is followed for that line. + +a symbol, SYMBOL + SYMBOL should be a function name; that function is called to + calculate the indentation of a line within this expression. The + function receives two arguments: + STATE + The value returned by `parse-partial-sexp' (a Lisp primitive + for indentation and nesting computation) when it parses up to + the beginning of this line. + + POS + The position at which the line being indented begins. + + It should return either a number, which is the number of columns of + indentation for that line, or a list whose first element is such a + number. The difference between returning a number and returning a + list is that a number says that all following lines at the same + nesting level should be indented just like this one; a list says + that following lines might call for different indentations. This + makes a difference when the indentation is computed by `C-M-q'; if + the value is a number, `C-M-q' need not recalculate indentation + for the following lines until the end of the list.  -File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent +File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding -Variables for Fortran Indentation -................................. +Customizing C Indentation +------------------------- - Several additional variables control how Fortran indentation works. + Two variables control which commands perform C indentation and when. -`fortran-do-indent' - Extra indentation within each level of `do' statement (the default - is 3). + If `c-auto-newline' is non-`nil', newlines are inserted both before +and after braces that you insert and after colons and semicolons. +Correct C indentation is done on all the lines that are made this way. -`fortran-if-indent' - Extra indentation within each level of `if' statement (the default - is 3). + If `c-tab-always-indent' is non-`nil', the command in C mode +does indentation only if point is at the left margin or within the +line's indentation. If there is non-whitespace to the left of point, + just inserts a tab character in the buffer. Normally, this +variable is `nil', and always reindents the current line. -`fortran-continuation-indent' - Extra indentation for bodies of continuation lines (the default is - 5). + C does not have anything analogous to particular function names for +which special forms of indentation are desirable. However, it has a +different need for customization facilities: many different styles of C +indentation are in common use. -`fortran-check-all-num-for-matching-do' - If this is `nil', indentation assumes that each `do' statement - ends on a `continue' statement. Therefore, when computing - indentation for a statement other than `continue', it can save - time by not checking for a `do' statement ending there. If this - is non-`nil', indenting any numbered statement must check for a - `do' that ends there. The default is `nil'. + There are six variables you can set to control the style that Emacs C +mode will use. -`fortran-minimum-statement-indent' - Minimum indentation for Fortran statements. For standard Fortran, - this is 6. Statement bodies are always indented at least this - much. +`c-indent-level' + Indentation of C statements within surrounding block. The + surrounding block's indentation is the indentation of the line on + which the open-brace appears. - -File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran +`c-continued-statement-offset' + Extra indentation given to a substatement, such as the then-clause + of an `if' or body of a `while'. -Comments --------- +`c-brace-offset' + Extra indentation for lines that start with an open brace. - The usual Emacs comment commands assume that a comment can follow a -line of code. In Fortran, the standard comment syntax requires an -entire line to be just a comment. Therefore, Fortran mode replaces the -standard Emacs comment commands and defines some new variables. +`c-brace-imaginary-offset' + An open brace following other text is treated as if it were this + far to the right of the start of its line. - Fortran mode can also handle a non-standard comment syntax where -comments start with `!' and can follow other text. Because only some -Fortran compilers accept this syntax, Fortran mode will not insert such -comments unless you have specified to do so in advance by setting the -variable `comment-start' to `"!"' (*note Variables::.). +`c-argdecl-indent' + Indentation level of declarations of C function arguments. -`M-;' - Align comment or insert new comment (`fortran-comment-indent'). +`c-label-offset' + Extra indentation for a line that is a label, case, or default. -`C-x ;' - Applies to nonstandard `!' comments only. - -`C-c ;' - Turn all lines of the region into comments, or (with arg) turn - them back into real code (`fortran-comment-region'). - - `M-;' in Fortran mode is redefined as the command -`fortran-comment-indent'. Like the usual `M-;' command, it recognizes -an existing comment and aligns its text appropriately. If there is no -existing comment, a comment is inserted and aligned. - - Inserting and aligning comments is not the same in Fortran mode as in -other modes. When a new comment must be inserted, a full-line comment -is inserted if the current line is blank. On a non-blank line, a -non-standard `!' comment is inserted if you previously specified you -wanted to use them. Otherwise a full-line comment is inserted on a new -line before the current line. - - Non-standard `!' comments are aligned like comments in other -languages, but full-line comments are aligned differently. In a -standard full-line comment, the comment delimiter itself must always -appear in column zero. What can be aligned is the text within the -comment. You can choose from three styles of alignment by setting the -variable `fortran-comment-indent-style' to one of these values: - -`fixed' - The text is aligned at a fixed column, which is the value of - `fortran-comment-line-column'. This is the default. - -`relative' - The text is aligned as if it were a line of code, but with an - additional `fortran-comment-line-column' columns of indentation. + The variable `c-indent-level' controls the indentation for C +statements with respect to the surrounding block. In the example: -`nil' - Text in full-line columns is not moved automatically. - - You can also specify the character to be used to indent within -full-line comments by setting the variable `fortran-comment-indent-char' -to the character you want to use. - - Fortran mode introduces two variables `comment-line-start' and -`comment-line-start-skip', which do for full-line comments what -`comment-start' and `comment-start-skip' do for ordinary text-following -comments. Normally these are set properly by Fortran mode, so you do -not need to change them. - - The normal Emacs comment command `C-x ;' has not been redefined. It -can therefore be used if you use `!' comments, but is useless in -Fortran mode otherwise. - - The command `C-c ;' (`fortran-comment-region') turns all the lines -of the region into comments by inserting the string `C$$$' at the front -of each one. With a numeric arg, the region is turned back into live -code by deleting `C$$$' from the front of each line. You can control -the string used for the comments by setting the variable -`fortran-comment-region'. Note that here we have an example of a -command and a variable with the same name; the two uses of the name -never conflict because in Lisp and in Emacs it is always clear from the -context which one is referred to. + { + foo (); - -File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran +the difference in indentation between the lines is `c-indent-level'. +Its standard value is 2. -Columns -------- + If the open-brace beginning the compound statement is not at the +beginning of its line, the `c-indent-level' is added to the indentation +of the line, not the column of the open-brace. For example, -`C-c C-r' - Displays a "column ruler" momentarily above the current line - (`fortran-column-ruler'). + if (losing) { + do_this (); -`C-c C-w' - Splits the current window horizontally so that it is 72 columns - wide. This may help you avoid going over that limit - (`fortran-window-create'). +One popular indentation style is that which results from setting +`c-indent-level' to 8 and putting open-braces at the end of a line in +this way. Another popular style prefers to put the open-brace on a +separate line. - The command `C-c C-r' (`fortran-column-ruler') shows a column ruler -above the current line. The comment ruler consists of two lines of -text that show you the locations of columns with special significance -in Fortran programs. Square brackets show the limits of the columns for -line numbers, and curly brackets show the limits of the columns for the -statement body. Column numbers appear above them. + In fact, the value of the variable `c-brace-imaginary-offset' is +also added to the indentation of such a statement. Normally this +variable is zero. Think of this variable as the imaginary position of +the open brace, relative to the first non-blank character on the line. +By setting the variable to 4 and `c-indent-level' to 0, you can get +this style: - Note that the column numbers count from zero, as always in XEmacs. -As a result, the numbers may not be those you are familiar with; but the -actual positions in the line are standard Fortran. + if (x == y) { + do_it (); + } - The text used to display the column ruler is the value of the -variable `fortran-comment-ruler'. By changing this variable, you can -change the display. + When `c-indent-level' is zero, the statements inside most braces +line up exactly under the open brace. An exception are braces in column +zero, like those surrounding a function's body. The statements inside +those braces are not placed at column zero. Instead, `c-brace-offset' +and `c-continued-statement-offset' (see below) are added to produce a +typical offset between brace levels, and the statements are indented +that far. - For even more help, use `C-c C-w' (`fortran-window-create'), a -command which splits the current window horizontally, resulting in a -window 72 columns wide. When you edit in this window, you can -immediately see when a line gets too wide to be correct Fortran. + `c-continued-statement-offset' controls the extra indentation for a +line that starts within a statement (but not within parentheses or +brackets). These lines are usually statements inside other statements, +like the then-clauses of `if' statements and the bodies of `while' +statements. The `c-continued-statement-offset' parameter determines +the difference in indentation between the two lines in: - -File: xemacs.info, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran + if (x == y) + do_it (); -Fortran Keyword Abbrevs ------------------------ +The default value for `c-continued-statement-offset' is 2. Some +popular indentation styles correspond to a value of zero for +`c-continued-statement-offset'. - Fortran mode provides many built-in abbrevs for common keywords and -declarations. These are the same sort of abbrevs that you can define -yourself. To use them, you must turn on Abbrev mode. *note Abbrevs::.. + `c-brace-offset' is the extra indentation given to a line that +starts with an open-brace. Its standard value is zero; compare: - The built-in abbrevs are unusual in one way: they all start with a -semicolon. You cannot normally use semicolon in an abbrev, but Fortran -mode makes this possible by changing the syntax of semicolon to "word -constituent". + if (x == y) + { - For example, one built-in Fortran abbrev is `;c' for `continue'. If -you insert `;c' and then insert a punctuation character such as a space -or a newline, the `;c' changes automatically to `continue', provided -Abbrev mode is enabled. +with: - Type `;?' or `;C-h' to display a list of all built-in Fortran -abbrevs and what they stand for. + if (x == y) + do_it (); - -File: xemacs.info, Node: Asm Mode, Prev: Fortran, Up: Programs +If you set `c-brace-offset' to 4, the first example becomes: -Asm Mode -======== + if (x == y) + { - Asm mode is a major mode for editing files of assembler code. It -defines these commands: + `c-argdecl-indent' controls the indentation of declarations of the +arguments of a C function. It is absolute: argument declarations +receive exactly `c-argdecl-indent' spaces. The standard value is 5 and +results in code like this: -`' - `tab-to-tab-stop'. + char * + index (string, char) + char *string; + int char; -`' - Insert a newline and then indent using `tab-to-tab-stop'. - -`:' - Insert a colon and then remove the indentation from before the - label preceding colon. Then do `tab-to-tab-stop'. + `c-label-offset' is the extra indentation given to a line that +contains a label, a case statement, or a `default:' statement. Its +standard value is -2 and results in code like this: -`;' - Insert or align a comment. + switch (c) + { + case 'x': - The variable `asm-comment-char' specifies which character starts -comments in assembler syntax. +If `c-label-offset' were zero, the same code would be indented as: - -File: xemacs.info, Node: Running, Next: Packages, Prev: Programs, Up: Top + switch (c) + { + case 'x': -Compiling and Testing Programs -****************************** +This example assumes that the other variables above also have their +default values. - The previous chapter discusses the Emacs commands that are useful for -making changes in programs. This chapter deals with commands that -assist in the larger process of developing and maintaining programs. - -* Menu: + Using the indentation style produced by the default settings of the +variables just discussed and putting open braces on separate lines +produces clear and readable files. For an example, look at any of the C +source files of XEmacs. -* Compilation:: Compiling programs in languages other than Lisp - (C, Pascal, etc.) -* Modes: Lisp Modes. Various modes for editing Lisp programs, with - different facilities for running the Lisp programs. -* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. -* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. -* Debug: Lisp Debug. Debugging Lisp programs running in Emacs. -* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. + +File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs + +Automatic Display of Matching Parentheses +========================================= + + The Emacs parenthesis-matching feature shows you automatically how +parentheses match in the text. Whenever a self-inserting character that +is a closing delimiter is typed, the cursor moves momentarily to the +location of the matching opening delimiter, provided that is visible on +the screen. If it is not on the screen, some text starting with that +opening delimiter is displayed in the echo area. Either way, you see +the grouping you are closing off. + + In Lisp, automatic matching applies only to parentheses. In C, it +also applies to braces and brackets. Emacs knows which characters to +regard as matching delimiters based on the syntax table set by the major +mode. *Note Syntax::. + + If the opening delimiter and closing delimiter are mismatched--as in +`[x)'--the echo area displays a warning message. The correct matches +are specified in the syntax table. + + Two variables control parenthesis matching displays. +`blink-matching-paren' turns the feature on or off. The default is `t' +(match display is on); `nil' turns it off. +`blink-matching-paren-distance' specifies how many characters back +Emacs searches to find a matching opening delimiter. If the match is +not found in the specified region, scanning stops, and nothing is +displayed. This prevents wasting lots of time scanning when there is no +match. The default is 4000.  -File: xemacs.info, Node: Compilation, Next: Lisp Modes, Prev: Running, Up: Running +File: xemacs.info, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs -Running "make", or Compilers Generally -====================================== +Manipulating Comments +===================== - Emacs can run compilers for non-interactive languages like C and -Fortran as inferior processes, feeding the error log into an Emacs -buffer. It can also parse the error messages and visit the files in -which errors are found, moving point to the line where the error -occurred. - -`M-x compile' - Run a compiler asynchronously under Emacs, with error messages to - `*compilation*' buffer. - -`M-x grep' - Run `grep' asynchronously under Emacs, with matching lines listed - in the buffer named `*compilation*'. - -`M-x kill-compilation' - Kill the process made by the `M-x compile' command. - -`M-x kill-grep' - Kill the running compilation or `grep' subprocess. - -`C-x `' - Visit the next compiler error message or `grep' match. - - To run `make' or another compiler, type `M-x compile'. This command -reads a shell command line using the minibuffer, then executes the -specified command line in an inferior shell with output going to the -buffer named `*compilation*'. By default, the current buffer's default -directory is used as the working directory for the execution of the -command; therefore, the makefile comes from this directory. - - When the shell command line is read, the minibuffer appears -containing a default command line (the command you used the last time -you typed `M-x compile'). If you type just , the same command -line is used again. The first `M-x compile' provides `make -k' as the -default. The default is taken from the variable `compile-command'; if -the appropriate compilation command for a file is something other than -`make -k', it can be useful to have the file specify a local value for -`compile-command' (*note File Variables::.). - - When you start a compilation, the buffer `*compilation*' is -displayed in another window but not selected. Its mode line displays -the word `run' or `exit' in the parentheses to tell you whether -compilation is finished. You do not have to keep this buffer visible; -compilation continues in any case. - - To kill the compilation process, type `M-x-kill-compilation'. The -mode line of the `*compilation*' buffer changes to say `signal' instead -of `run'. Starting a new compilation also kills any running -compilation, as only one can occur at any time. Starting a new -compilation prompts for confirmation before actually killing a -compilation that is running. - - To parse the compiler error messages, type `C-x `' (`next-error'). -The character following `C-x' is the grave accent, not the single -quote. The command displays the buffer `*compilation*' in one window -and the buffer in which the next error occurred in another window. -Point in that buffer is moved to the line where the error was found. -The corresponding error message is scrolled to the top of the window in -which `*compilation*' is displayed. - - The first time you use `C-x `' after the start of a compilation, it -parses all the error messages, visits all the files that have error -messages, and creates markers pointing at the lines the error messages -refer to. It then moves to the first error message location. -Subsequent uses of `C-x `' advance down the data set up by the first -use. When the preparsed error messages are exhausted, the next `C-x `' -checks for any more error messages that have come in; this is useful if -you start editing compiler errors while compilation is still going on. -If no additional error messages have come in, `C-x `' reports an error. - - `C-u C-x `' discards the preparsed error message data and parses the -`*compilation*' buffer again, then displays the first error. This way, -you can process the same set of errors again. - - Instead of running a compiler, you can run `grep' and see the lines -on which matches were found. To do this, type `M-x grep' with an -argument line that contains the same arguments you would give to -`grep': a `grep'-style regexp (usually in single quotes to quote the -shell's special characters) followed by filenames, which may use -wildcard characters. The output from `grep' goes in the -`*compilation*' buffer. You can use `C-x `' to find the lines that -match as if they were compilation errors. - - Note: a shell is used to run the compile command, but the shell is -not run in interactive mode. In particular, this means that the shell -starts up with no prompt. If you find your usual shell prompt making an -unsightly appearance in the `*compilation*' buffer, it means you have -made a mistake in your shell's initialization file (`.cshrc' or `.shrc' -or ...) by setting the prompt unconditionally. The shell -initialization file should set the prompt only if there already is a -prompt. Here's how to do it in `csh': - - if ($?prompt) set prompt = ... + The comment commands insert, kill and align comments. - -File: xemacs.info, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Running +`M-;' + Insert or align comment (`indent-for-comment'). -Major Modes for Lisp -==================== +`C-x ;' + Set comment column (`set-comment-column'). - Emacs has four different major modes for Lisp. They are the same in -terms of editing commands, but differ in the commands for executing Lisp -expressions. +`C-u - C-x ;' + Kill comment on current line (`kill-comment'). -Emacs-Lisp mode - The mode for editing source files of programs to run in Emacs Lisp. - This mode defines `C-M-x' to evaluate the current defun. *Note - Lisp Libraries::. +`M-' + Like followed by inserting and aligning a comment + (`indent-new-comment-line'). + + The command that creates a comment is `Meta-;' +(`indent-for-comment'). If there is no comment already on the line, a +new comment is created and aligned at a specific column called the +"comment column". Emacs creates the comment by inserting the string at +the value of `comment-start'; see below. Point is left after that +string. If the text of the line extends past the comment column, +indentation is done to a suitable boundary (usually, at least one space +is inserted). If the major mode has specified a string to terminate +comments, that string is inserted after point, to keep the syntax valid. + + You can also use `Meta-;' to align an existing comment. If a line +already contains the string that starts comments, `M-;' just moves +point after it and re-indents it to the conventional place. Exception: +comments starting in column 0 are not moved. + + Some major modes have special rules for indenting certain kinds of +comments in certain contexts. For example, in Lisp code, comments which +start with two semicolons are indented as if they were lines of code, +instead of at the comment column. Comments which start with three +semicolons are supposed to start at the left margin. Emacs understands +these conventions by indenting a double-semicolon comment using +and by not changing the indentation of a triple-semicolon comment at +all. + + ;; This function is just an example. + ;;; Here either two or three semicolons are appropriate. + (defun foo (x) + ;;; And now, the first part of the function: + ;; The following line adds one. + (1+ x)) ; This line adds one. + + In C code, a comment preceded on its line by nothing but whitespace +is indented like a line of code. + + Even when an existing comment is properly aligned, `M-;' is still +useful for moving directly to the start of the comment. + + `C-u - C-x ;' (`kill-comment') kills the comment on the current +line, if there is one. The indentation before the start of the comment +is killed as well. If there does not appear to be a comment in the +line, nothing happens. To reinsert the comment on another line, move +to the end of that line, type first `C-y', and then `M-;' to realign +the comment. Note that `C-u - C-x ;' is not a distinct key; it is `C-x +;' (`set-comment-column') with a negative argument. That command is +programmed to call `kill-comment' when called with a negative argument. +However, `kill-comment' is a valid command which you could bind +directly to a key if you wanted to. + +Multiple Lines of Comments +-------------------------- + + If you are typing a comment and want to continue it on another line, +use the command `Meta-' (`indent-new-comment-line'), which +terminates the comment you are typing, creates a new blank line +afterward, and begins a new comment indented under the old one. If +Auto Fill mode is on and you go past the fill column while typing, the +comment is continued in just this fashion. If point is not at the end +of the line when you type `M-', the text on the rest of the line +becomes part of the new comment line. + +Options Controlling Comments +---------------------------- + + The comment column is stored in the variable `comment-column'. You +can explicitly set it to a number. Alternatively, the command `C-x ;' +(`set-comment-column') sets the comment column to the column point is +at. `C-u C-x ;' sets the comment column to match the last comment +before point in the buffer, and then calls `Meta-;' to align the +current line's comment under the previous one. Note that `C-u - C-x ;' +runs the function `kill-comment' as described above. + + `comment-column' is a per-buffer variable; altering the variable +affects only the current buffer. You can also change the default value. +*Note Locals::. Many major modes initialize this variable for the +current buffer. -Lisp Interaction mode - The mode for an interactive session with Emacs Lisp. It defines - to evaluate the sexp before point and insert its value in the - buffer. *Note Lisp Interaction::. + The comment commands recognize comments based on the regular +expression that is the value of the variable `comment-start-skip'. +This regexp should not match the null string. It may match more than +the comment starting delimiter in the strictest sense of the word; for +example, in C mode the value of the variable is `"/\\*+ *"', which +matches extra stars and spaces after the `/*' itself. (Note that `\\' +is needed in Lisp syntax to include a `\' in the string, which is needed +to deny the first star its special meaning in regexp syntax. *Note +Regexps::.) + + When a comment command makes a new comment, it inserts the value of +`comment-start' to begin it. The value of `comment-end' is inserted +after point and will follow the text you will insert into the comment. +In C mode, `comment-start' has the value `"/* "' and `comment-end' has +the value `" */"'. + + `comment-multi-line' controls how `M-' +(`indent-new-comment-line') behaves when used inside a comment. If +`comment-multi-line' is `nil', as it normally is, then `M-' +terminates the comment on the starting line and starts a new comment on +the new following line. If `comment-multi-line' is not `nil', then +`M-' sets up the new following line as part of the same comment +that was found on the starting line. This is done by not inserting a +terminator on the old line and not inserting a starter on the new line. +In languages where multi-line comments are legal, the value you choose +for this variable is a matter of taste. + + The variable `comment-indent-hook' should contain a function that is +called to compute the indentation for a newly inserted comment or for +aligning an existing comment. Major modes set this variable +differently. The function is called with no arguments, but with point +at the beginning of the comment, or at the end of a line if a new +comment is to be inserted. The function should return the column in +which the comment ought to start. For example, in Lisp mode, the +indent hook function bases its decision on the number of semicolons +that begin an existing comment and on the code in the preceding lines. -Lisp mode - The mode for editing source files of programs that run in other - dialects of Lisp than Emacs Lisp. This mode defines `C-M-x' to - send the current defun to an inferior Lisp process. *Note - External Lisp::. + +File: xemacs.info, Node: Balanced Editing, Next: Lisp Completion, Prev: Comments, Up: Programs + +Editing Without Unbalanced Parentheses +====================================== -Inferior Lisp mode - The mode for an interactive session with an inferior Lisp process. - This mode combines the special features of Lisp mode and Shell mode - (*note Shell Mode::.). +`M-(' + Put parentheses around next sexp(s) (`insert-parentheses'). -Scheme mode - Like Lisp mode but for Scheme programs. +`M-)' + Move past next close parenthesis and re-indent + (`move-over-close-and-reindent'). -Inferior Scheme mode - The mode for an interactive session with an inferior Scheme - process. + The commands `M-(' (`insert-parentheses') and `M-)' +(`move-over-close-and-reindent') are designed to facilitate a style of +editing which keeps parentheses balanced at all times. `M-(' inserts a +pair of parentheses, either together as in `()', or, if given an +argument, around the next several sexps, and leaves point after the open +parenthesis. Instead of typing `( F O O )', you can type `M-( F O O', +which has the same effect except for leaving the cursor before the +close parenthesis. You can then type `M-)', which moves past the close +parenthesis, deletes any indentation preceding it (in this example +there is none), and indents with after it.  -File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running +File: xemacs.info, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs -Libraries of Lisp Code for Emacs -================================ +Completion for Lisp Symbols +=========================== - Lisp code for Emacs editing commands is stored in files whose names -conventionally end in `.el'. This ending tells Emacs to edit them in -Emacs-Lisp mode (*note Lisp Modes::.). + Completion usually happens in the minibuffer. An exception is +completion for Lisp symbol names, which is available in all buffers. -* Menu: + The command `M-' (`lisp-complete-symbol') takes the partial +Lisp symbol before point to be an abbreviation, and compares it against +all non-trivial Lisp symbols currently known to Emacs. Any additional +characters that they all have in common are inserted at point. +Non-trivial symbols are those that have function definitions, values, or +properties. + + If there is an open-parenthesis immediately before the beginning of +the partial symbol, only symbols with function definitions are +considered as completions. -* Loading:: Loading libraries of Lisp code into Emacs for use. -* Compiling Libraries:: Compiling a library makes it load and run faster. -* Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it. + If the partial name in the buffer has more than one possible +completion and they have no additional characters in common, a list of +all possible completions is displayed in another window. + + +File: xemacs.info, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs + +Documentation Commands +====================== + + As you edit Lisp code to be run in Emacs, you can use the commands +`C-h f' (`describe-function') and `C-h v' (`describe-variable') to +print documentation of functions and variables you want to call. These +commands use the minibuffer to read the name of a function or variable +to document, and display the documentation in a window. + + For extra convenience, these commands provide default arguments +based on the code in the neighborhood of point. `C-h f' sets the +default to the function called in the innermost list containing point. +`C-h v' uses the symbol name around or adjacent to point as its default. + + The `M-x manual-entry' command gives you access to documentation on +Unix commands, system calls, and libraries. The command reads a topic +as an argument, and displays the Unix manual page for that topic. +`manual-entry' always searches all 8 sections of the manual and +concatenates all the entries it finds. For example, the topic +`termcap' finds the description of the termcap library from section 3, +followed by the description of the termcap data base from section 5.