X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-12;h=45c5285b613c614e8dd43ba182bc5ab50b815fa2;hb=f25aa1d46f1ded748f0ea4bcf875441a538ec14a;hp=4630e5177b2cb9c69047544807de3df84c8256ad;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git- diff --git a/info/xemacs.info-12 b/info/xemacs.info-12 index 4630e51..45c5285 100644 --- a/info/xemacs.info-12 +++ b/info/xemacs.info-12 @@ -1,4 +1,4 @@ -This is ../info/xemacs.info, produced by makeinfo version 3.12s from +This is ../info/xemacs.info, produced by makeinfo version 4.0b from xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor @@ -30,1143 +30,1192 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries - -Loading Libraries ------------------ - -`M-x load-file FILE' - Load the file FILE of Lisp code. - -`M-x load-library LIBRARY' - Load the library named LIBRARY. - -`M-x locate-library LIBRARY &optional NOSUFFIX' - Show the full path name of Emacs library LIBRARY. - - To execute a file of Emacs Lisp, use `M-x load-file'. This command -reads the file name you provide in the minibuffer, then executes the -contents of that file as Lisp code. It is not necessary to visit the -file first; in fact, this command reads the file as found on disk, not -the text in an Emacs buffer. - - Once a file of Lisp code is installed in the Emacs Lisp library -directories, users can load it using `M-x load-library'. Programs can -load it by calling `load-library', or with `load', a more primitive -function that is similar but accepts some additional arguments. - - `M-x load-library' differs from `M-x load-file' in that it searches -a sequence of directories and tries three file names in each directory. -The three names are: first, the specified name with `.elc' appended; -second, the name with `.el' appended; third, the specified name alone. -A `.elc' file would be the result of compiling the Lisp file into byte -code; if possible, it is loaded in preference to the Lisp file itself -because the compiled file loads and runs faster. - - Because the argument to `load-library' is usually not in itself a -valid file name, file name completion is not available. In fact, when -using this command, you usually do not know exactly what file name will -be used. - - The sequence of directories searched by `M-x load-library' is -specified by the variable `load-path', a list of strings that are -directory names. The elements of this list may not begin with "`~'", -so you must call `expand-file-name' on them before adding them to the -list. The default value of the list contains the directory where the -Lisp code for Emacs itself is stored. If you have libraries of your -own, put them in a single directory and add that directory to -`load-path'. `nil' in this list stands for the current default -directory, but it is probably not a good idea to put `nil' in the list. -If you start wishing that `nil' were in the list, you should probably -use `M-x load-file' for this case. - - The variable is initialized by the EMACSLOADPATH environment -variable. If no value is specified, the variable takes the default value -specified in the file `paths.h' when Emacs was built. If a path isn't -specified in `paths.h', a default value is obtained from the file -system, near the directory in which the Emacs executable resides. - - Like `M-x load-library', `M-x locate-library' searches the -directories in `load-path' to find the file that `M-x load-library' -would load. If the optional second argument NOSUFFIX is non-`nil', the -suffixes `.elc' or `.el' are not added to the specified name LIBRARY -(like calling `load' instead of `load-library'). - - You often do not have to give any command to load a library, because -the commands defined in the library are set up to "autoload" that -library. Running any of those commands causes `load' to be called to -load the library; this replaces the autoload definitions with the real -ones from the library. - - If autoloading a file does not finish, either because of an error or -because of a `C-g' quit, all function definitions made by the file are -undone automatically. So are any calls to `provide'. As a -consequence, the entire file is loaded a second time if you use one of -the autoloadable commands again. This prevents problems when the -command is no longer autoloading but is working incorrectly because the -file was only partially loaded. Function definitions are undone only -for autoloading; explicit calls to `load' do not undo anything if -loading is not completed. - - The variable `after-load-alist' takes an alist of expressions to be -evaluated when particular files are loaded. Each element has the form -`(FILENAME forms...)'. When `load' is run and the filename argument is -FILENAME, the forms in the corresponding element are executed at the -end of loading. - - FILENAME must match exactly. Normally FILENAME is the name of a -library, with no directory specified, since that is how load is -normally called. An error in `forms' does not undo the load, but it -does prevent execution of the rest of the `forms'. +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: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries +File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs -Compiling Libraries -------------------- +Tags Tables +=========== - Emacs Lisp code can be compiled into byte-code which loads faster, -takes up less space when loaded, and executes faster. - -`M-x batch-byte-compile' - Run byte-compile-file on the files remaining on the command line. - -`M-x byte-compile-buffer &optional BUFFER' - Byte-compile and evaluate contents of BUFFER (default is current - buffer). - -`M-x byte-compile-file' - Compile a file of Lisp code named FILENAME into a file of byte - code. - -`M-x byte-compile-and-load-file FILENAME' - Compile a file of Lisp code named FILENAME into a file of byte - code and load it. - -`M-x byte-recompile-directory DIRECTORY' - Recompile every `.el' file in DIRECTORY that needs recompilation. - -`M-x disassemble' - Print disassembled code for OBJECT on (optional) STREAM. - -`M-x make-obsolete FUNCTION NEW' - Make the byte-compiler warn that FUNCTION is obsolete and NEW - should be used instead. - - `byte-compile-file' creates a byte-code compiled file from an -Emacs-Lisp source file. The default argument for this function is the -file visited in the current buffer. The function reads the specified -file, compiles it into byte code, and writes an output file whose name -is made by appending `c' to the input file name. Thus, the file -`rmail.el' would be compiled into `rmail.elc'. To compile a file of -Lisp code named FILENAME into a file of byte code and then load it, use -`byte-compile-and-load-file'. To compile and evaluate Lisp code in a -given buffer, use `byte-compile-buffer'. - - To recompile all changed Lisp files in a directory, use `M-x -byte-recompile-directory'. Specify just the directory name as an -argument. Each `.el' file that has been byte-compiled before is -byte-compiled again if it has changed since the previous compilation. -A numeric argument to this command tells it to offer to compile each -`.el' file that has not been compiled yet. You must answer `y' or `n' -to each offer. - - You can use the function `batch-byte-compile' to invoke Emacs -non-interactively from the shell to do byte compilation. When you use -this function, the files to be compiled are specified with command-line -arguments. Use a shell command of the form: - - emacs -batch -f batch-byte-compile FILES... - - Directory names may also be given as arguments; in that case, -`byte-recompile-directory' is invoked on each such directory. -`batch-byte-compile' uses all remaining command-line arguments as file -or directory names, then kills the Emacs process. - - `M-x disassemble' explains the result of byte compilation. Its -argument is a function name. It displays the byte-compiled code in a -help window in symbolic form, one instruction per line. If the -instruction refers to a variable or constant, that is shown, too. + 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. - -File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries + Tags tables are stored in files called "tags table files". The +conventional name for a tags table file is `TAGS'. -Converting Mocklisp to Lisp ---------------------------- + 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. - XEmacs can run Mocklisp files by converting them to Emacs Lisp first. -To convert a Mocklisp file, visit it and then type `M-x -convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file -in a file whose name ends in `.el' and use the new file as a Lisp -library. + 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". - You cannot currently byte-compile converted Mocklisp code. The -reason is that converted Mocklisp code uses some special Lisp features -to deal with Mocklisp's incompatible ideas of how arguments are -evaluated and which values signify "true" or "false". + The Ebrowse is a separate facility tailored for C++, with tags and a +class browser. *Note : (ebrowse). - -File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running - -Evaluating Emacs-Lisp Expressions -================================= - - Lisp programs intended to be run in Emacs should be edited in -Emacs-Lisp mode; this will happen automatically for file names ending in -`.el'. By contrast, Lisp mode itself should be used for editing Lisp -programs intended for other Lisp systems. Emacs-Lisp mode can be -selected with the command `M-x emacs-lisp-mode'. - - For testing of Lisp programs to run in Emacs, it is useful to be able -to evaluate part of the program as it is found in the Emacs buffer. For -example, if you change the text of a Lisp function definition and then -evaluate the definition, Emacs installs the change for future calls to -the function. Evaluation of Lisp expressions is also useful in any -kind of editing task for invoking non-interactive functions (functions -that are not commands). - -`M-' - Read a Lisp expression in the minibuffer, evaluate it, and print - the value in the minibuffer (`eval-expression'). - -`C-x C-e' - Evaluate the Lisp expression before point, and print the value in - the minibuffer (`eval-last-sexp'). - -`C-M-x' - Evaluate the defun containing point or after point, and print the - value in the minibuffer (`eval-defun'). - -`M-x eval-region' - Evaluate all the Lisp expressions in the region. - -`M-x eval-current-buffer' - Evaluate all the Lisp expressions in the buffer. - - `M-' (`eval-expression') is the most basic command for -evaluating a Lisp expression interactively. It reads the expression -using the minibuffer, so you can execute any expression on a buffer -regardless of what the buffer contains. When evaluation is complete, -the current buffer is once again the buffer that was current when -`M-' was typed. - - `M-' can easily confuse users, especially on keyboards with -autorepeat, where it can result from holding down the key for too -long. Therefore, `eval-expression' is normally a disabled command. -Attempting to use this command asks for confirmation and gives you the -option of enabling it; once you enable the command, you are no longer -required to confirm. *Note Disabling::. - - In Emacs-Lisp mode, the key `C-M-x' is bound to the function -`eval-defun', which parses the defun containing point or following point -as a Lisp expression and evaluates it. The value is printed in the echo -area. This command is convenient for installing in the Lisp environment -changes that you have just made in the text of a function definition. - - The command `C-x C-e' (`eval-last-sexp') performs a similar job but -is available in all major modes, not just Emacs-Lisp mode. It finds -the sexp before point, reads it as a Lisp expression, evaluates it, and -prints the value in the echo area. It is sometimes useful to type in an -expression and then, with point still after it, type `C-x C-e'. - - If `C-M-x' or `C-x C-e' are given a numeric argument, they print the -value by inserting it into the current buffer at point, rather than in -the echo area. The argument value does not matter. - - The most general command for evaluating Lisp expressions from a -buffer is `eval-region'. `M-x eval-region' parses the text of the -region as one or more Lisp expressions, evaluating them one by one. -`M-x eval-current-buffer' is similar, but it evaluates the entire -buffer. This is a reasonable way to install the contents of a file of -Lisp code that you are just ready to test. After finding and fixing a -bug, use `C-M-x' on each function that you change, to keep the Lisp -world in step with the source file. +* Menu: - -File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running - -The Emacs-Lisp Debugger -======================= - - XEmacs contains a debugger for Lisp programs executing inside it. -This debugger is normally not used; many commands frequently get Lisp -errors when invoked in inappropriate contexts (such as `C-f' at the end -of the buffer) and it would be unpleasant to enter a special debugging -mode in this case. When you want to make Lisp errors invoke the -debugger, you must set the variable `debug-on-error' to non-`nil'. -Quitting with `C-g' is not considered an error, and `debug-on-error' -has no effect on the handling of `C-g'. However, if you set -`debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This -can be useful for debugging an infinite loop; type `C-g' once the loop -has had time to reach its steady state. `debug-on-quit' has no effect -on errors. - - You can make Emacs enter the debugger when a specified function is -called or at a particular place in Lisp code. Use `M-x debug-on-entry' -with argument FUN-NAME to have Emacs enter the debugger as soon as -FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the -function stop entering the debugger when called. (Redefining the -function also does this.) To enter the debugger from some other place -in Lisp code, you must insert the expression `(debug)' there and -install the changed code with `C-M-x'. *Note Lisp Eval::. - - When the debugger is entered, it displays the previously selected -buffer in one window and a buffer named `*Backtrace*' in another -window. The backtrace buffer contains one line for each level of Lisp -function execution currently going on. At the beginning of the buffer -is a message describing the reason that the debugger was invoked, for -example, an error message if it was invoked due to an error. - - The backtrace buffer is read-only and is in Backtrace mode, a special -major mode in which letters are defined as debugger commands. The -usual Emacs editing commands are available; you can switch windows to -examine the buffer that was being edited at the time of the error, and -you can switch buffers, visit files, and perform any other editing -operations. However, the debugger is a recursive editing level (*note -Recursive Edit::); it is a good idea to return to the backtrace buffer -and explictly exit the debugger when you don't want to use it any more. -Exiting the debugger kills the backtrace buffer. - - The contents of the backtrace buffer show you the functions that are -executing and the arguments that were given to them. It also allows you -to specify a stack frame by moving point to the line describing that -frame. The frame whose line point is on is considered the "current -frame". Some of the debugger commands operate on the current frame. -Debugger commands are mainly used for stepping through code one -expression at a time. Here is a list of them: - -`c' - Exit the debugger and continue execution. In most cases, - execution of the program continues as if the debugger had never - been entered (aside from the effect of any variables or data - structures you may have changed while inside the debugger). This - includes entry to the debugger due to function entry or exit, - explicit invocation, and quitting or certain errors. Most errors - cannot be continued; trying to continue an error usually causes - the same error to occur again. - -`d' - Continue execution, but enter the debugger the next time a Lisp - function is called. This allows you to step through the - subexpressions of an expression, and see what the subexpressions - do and what values they compute. - - When you enter the debugger this way, Emacs flags the stack frame - for the function call from which you entered. The same function - is then called when you exit the frame. To cancel this flag, use - `u'. - -`b' - Set up to enter the debugger when the current frame is exited. - Frames that invoke the debugger on exit are flagged with stars. - -`u' - Don't enter the debugger when the current frame is exited. This - cancels a `b' command on a frame. - -`e' - Read a Lisp expression in the minibuffer, evaluate it, and print - the value in the echo area. This is equivalent to the command - `M-', except that `e' is not normally disabled like `M-'. - -`q' - Terminate the program being debugged; return to top-level Emacs - command execution. - - If the debugger was entered due to a `C-g' but you really want to - quit, not to debug, use the `q' command. - -`r' - Return a value from the debugger. The value is computed by - reading an expression with the minibuffer and evaluating it. - - The value returned by the debugger makes a difference when the - debugger was invoked due to exit from a Lisp call frame (as - requested with `b'); then the value specified in the `r' command - is used as the value of that frame. - - The debugger's return value also matters with many errors. For - example, `wrong-type-argument' errors will use the debugger's - return value instead of the invalid argument; `no-catch' errors - will use the debugger value as a throw tag instead of the tag that - was not found. If an error was signaled by calling the Lisp - function `signal', the debugger's return value is returned as the - value of `signal'. +* Tag Syntax:: Tag syntax for various types of code and text files. +* Create Tags Table:: Creating a tags table with `etags'. +* Etags Regexps:: Create arbitrary tags using regular expressions. +* 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.  -File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running - -Lisp Interaction Buffers -======================== - - The buffer `*scratch*', which is selected when Emacs starts up, is -provided for evaluating Lisp expressions interactively inside Emacs. -Both the expressions you evaluate and their output goes in the buffer. - - The `*scratch*' buffer's major mode is Lisp Interaction mode, which -is the same as Emacs-Lisp mode except for one command, . In -Emacs-Lisp mode, is an indentation command. In Lisp Interaction -mode, is bound to `eval-print-last-sexp'. This function reads -the Lisp expression before point, evaluates it, and inserts the value -in printed representation before point. - - The way to use the `*scratch*' buffer is to insert Lisp expressions -at the end, ending each one with so that it will be evaluated. -The result is a complete typescript of the expressions you have -evaluated and their values. - - The rationale for this feature is that Emacs must have a buffer when -it starts up, but that buffer is not useful for editing files since a -new buffer is made for every file that you visit. The Lisp interpreter -typescript is the most useful thing I can think of for the initial -buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp -Interaction mode. +File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Up: Tags - -File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running - -Running an External Lisp -======================== - - Emacs has facilities for running programs in other Lisp systems. -You can run a Lisp process as an inferior of Emacs, and pass -expressions to it to be evaluated. You can also pass changed function -definitions directly from the Emacs buffers in which you edit the Lisp -programs to the inferior Lisp process. - - To run an inferior Lisp process, type `M-x run-lisp'. This runs the -program named `lisp', the same program you would run by typing `lisp' -as a shell command, with both input and output going through an Emacs -buffer named `*lisp*'. In other words, any "terminal output" from Lisp -will go into the buffer, advancing point, and any "terminal input" for -Lisp comes from text in the buffer. To give input to Lisp, go to the -end of the buffer and type the input, terminated by . The -`*lisp*' buffer is in Inferior Lisp mode, which has all the special -characteristics of Lisp mode and Shell mode (*note Shell Mode::). - - Use Lisp mode to run the source files of programs in external Lisps. -You can select this mode with `M-x lisp-mode'. It is used automatically -for files whose names end in `.l' or `.lisp', as most Lisp systems -usually expect. - - When you edit a function in a Lisp program you are running, the -easiest way to send the changed definition to the inferior Lisp process -is the key `C-M-x'. In Lisp mode, this key runs the function -`lisp-send-defun', which finds the defun around or following point and -sends it as input to the Lisp process. (Emacs can send input to any -inferior process regardless of what buffer is current.) - - Contrast the meanings of `C-M-x' in Lisp mode (for editing programs -to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp -programs to be run in Emacs): in both modes it has the effect of -installing the function definition that point is in, but the way of -doing so is different according to where the relevant Lisp environment -is found. *Note Lisp Modes::. +Source File Tag Syntax +---------------------- - -File: xemacs.info, Node: Packages, Next: Abbrevs, Prev: Running, Up: Top + Here is how tag syntax is defined for the most popular languages: -Packages -======== + * In C code, any C function or typedef is a tag, and so are + definitions of `struct', `union' and `enum'. You can tag function + declarations and external variables in addition to function + definitions by giving the `--declarations' option to `etags'. + `#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. - The XEmacs 21 distribution comes only with a very basic set of -built-in modes and packages. Most of the packages that were part of -the distribution of earlier versions of XEmacs are now available -separately. The installer as well as the user can choose which -packages to install; the actual installation process is easy. This -gives an installer the ability to tailor an XEmacs installation for -local needs with safe removal of unnecessary code. + * 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'. `operator' functions tags are named, for + example `operator+'. -* Menu: + * In Java code, tags include all the constructs recognized in C++, + plus the `interface', `extends' and `implements' constructs. Tags + for variables and functions in classes are named `CLASS.VARIABLE' + and `CLASS.FUNCTION'. -* Package Terminology:: Understanding different kinds of packages. -* Using Packages:: How to install and use packages. -* Building Packages:: Building packages from sources. + * 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. - -File: xemacs.info, Node: Package Terminology, Next: Using Packages, Up: Packages + 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 + command names. For example, -Package Flavors ---------------- + TEXTAGS="def:newcommand:newenvironment" + export TEXTAGS - There are two main flavors of packages. + specifies (using Bourne shell syntax) that the commands `\def', + `\newcommand' and `\newenvironment' also define tags. - * Regular Packages A regular package is one in which multiple files - are involved and one may not in general safely remove any of them. + * 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. - * Single-File Packages A single-file package is an aggregate - collection of thematically related but otherwise independent lisp - files. These files are bundled together for download convenience - and individual files may be deleted at will without any loss of - functionality. + * 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. -Package Distributions ---------------------- + Several other languages are also supported: - XEmacs Lisp packages are distributed in two ways, depending on the -intended use. Binary Packages are for installers and end-users and may -be installed directly into an XEmacs package directory. Source Packages -are for developers and include all files necessary for rebuilding -bytecompiled lisp and creating tarballs for distribution. + * In Ada code, functions, procedures, packages, tasks, and types are + tags. Use the `--packages-only' option to create tags for + packages only. -Binary Packages ---------------- + With Ada, it is possible to have the same name used for different + entity kinds (e.g. the same name for a procedure and a function). + Also, for things like packages, procedures and functions, there is + the spec (i.e. the interface) and the body (i.e. the + implementation). To facilitate the choice to the user, a tag + value is appended with a qualifier: - Binary packages may be installed directly into an XEmacs package -hierarchy. + function + `/f' -Source Packages ---------------- + procedure + `/p' - Source packages contain all of the Package author's (where -appropriate in regular packages) source code plus all of the files -necessary to build distribution tarballs (Unix Tar format files, -gzipped for space savings). + package spec + `/s' - -File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages + package body + `/b' -Getting Started ---------------- + type + `/t' + + task + `/k' + + So, as an example, `M-x find-tag bidule/b' will go directly to the + body of the package BIDULE while `M-x find-tag bidule' will just + search for any tag BIDULE. + + * In assembler code, labels appearing at the beginning of a line, + followed by a colon, are tags. + + * 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. - When you first download XEmacs 21, you will usually first grab the -"core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the -21.0 by the current version number.) The core distribution contains -the sources of XEmacs and a minimal set of Emacs Lisp files, which are -in the subdirectory named `lisp'. This subdirectory used to contain -all Emacs Lisp files distributed with XEmacs. Now, to conserve disk -space, most non-essential packages were made optional. + * In Cobol code, tags are paragraph names; that is, any word + starting in column 8 and followed by a period. -Choosing the Packages You Need ------------------------------- + * In Erlang code, the tags are the functions, records, and macros + defined in the file. - The available packages can currently be found in the same ftp -directory where you grabbed the core distribution from, and are located -in the subdirectory `packages/binary-packages'. Package file names -follow the naming convention `--pkg.tar.gz'. + * In Fortran code, functions, subroutines and blockdata are tags. - If you have EFS *Note (EFS)::, packages can be installed over the -network. Alternatively, if you have copies of the packages locally, -you can install packages from a local disk or CDROM. + * In makefiles, targets are tags. - The file `etc/PACKAGES' in the core distribution contains a list of -the packages available at the time of the XEmacs release. Packages are -also listed on the `Options' menu under: + * In Objective C code, tags include Objective C definitions for + classes, class categories, methods, and protocols. - Options->Customize->Emacs->Packages + * In Pascal code, the tags are the functions and procedures defined + in the file. - However, don't select any of these menu picks unless you actually -want to install the given package (and have properly configured your -system to do so). + * In Perl code, the tags are the procedures defined by the `sub', + `my' and `local' keywords. Use `--globals' if you want to tag + global variables. - You can also get a list of available packages, and whether or not -they are installed, using the visual package browser and installer. -You can access it via the menus: + * In PostScript code, the tags are the functions. - Options->Manage Packages->List & Install + * In Prolog code, a tag name appears at the left margin. - Or, you can get to it via the keyboard: + * In Python code, `def' or `class' at the beginning of a line + generate a tag. - M-x pui-list-packages + You can also generate tags based on regexp matching (*note Etags +Regexps::) to handle other formats and languages. - Hint to system administrators of multi-user systems: it might be a -good idea to install all packages and not interfere with the wishes of -your users. + +File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, 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. You can intermix +compressed and plain text source file names. `etags' knows about the +most common compression formats, and does the right thing. So you can +compress all your source files and have `etags' look for compressed +versions of its file name arguments, if it does not find uncompressed +versions. Under MS-DOS, `etags' also looks for file names like +`mycode.cgz' if it is given `mycode.c' on the command line and +`mycode.c' does not exist. + + `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 MS-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 (*note Etags Regexps::). + + `etags --help' prints the list of the languages `etags' knows, and +the file name rules for guessing the language. It also prints a list of +all the available `etags' options, together with a short explanation. + + +File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags + +Etags Regexps +------------- + + 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: - If you can't find which package provides the feature you require, try -using the `package-get-package-provider' function. Eg., if you know -that you need `thingatpt', type: + --regex=/TAGREGEXP[/NAMEREGEXP]/ - M-x package-get-package-provider RET thingatpt +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. - which will return something like (fsf-compat "1.06"). You can the use -one of the methods above for installing the package you want. + 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. -XEmacs and Installing Packages ------------------------------- + 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 (as will +usually be the case), you should add a NAMEREGEXP, to pick out just the +tag. This will enable Emacs to find tags more accurately and to do +completion on tag names more reliably. You can find some examples +below. - Normally, packages are installed over the network, using EFS *Note -(EFS)::. However, you may not have network access, or you may already -have some or all of the packages on a local disk, such as a CDROM. If -you want to install from a local disk, you must first tell XEmacs where -to find the package binaries. This is done by adding a line like the -following to your `.emacs' file: + The option `--ignore-case-regex' (or `-c') is like `--regex', except +that the regular expression provided will be matched without regard to +case, which is appropriate for various programming languages. - (setq package-get-remote (cons (list nil "/my/path/to/package/binaries") - package-get-remote)) + 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: - Here, you'd change `/my/path/to/package/binaries' to be the path to -your local package binaries. Next, restart XEmacs, and you're ready to -go (advanced users can just re-evaluate the sexp). + etags --regex=/REG1/ voo.doo --regex=/REG2/ \ + bar.ber -R --lang=lisp los.er - If you are installing from a temporary, one-time directory, you can -also add these directory names to `package-get-remote' using: +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'. - M-x pui-add-install-directory + A regular expression can be bound to a given language, by prepending +it with `{lang}'. When you do this, `etags' will use the regular +expression only for files of that language. `etags --help' prints the +list of languages recognised by `etags'. The following example tags +the `DEFVAR' macros in the Emacs source files. `etags' applies this +regular expression to C files only: - Note, however, that any directories added using this function are not -saved; this information will be lost when you quit XEmacs. + --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' - If you're going to install over the network, you only have to insure -that EFS *Note (EFS):: works, and that it can get outside a firewall, if -you happen to be behind one. You shouldn't have to do anything else; -XEmacs already knows where to go. However you can add your own mirrors -to this list. See `package-get-remote'. +This feature is particularly useful when storing a list of regular +expressions in a file. The following option syntax instructs `etags' +to read two files of regular expressions. The regular expressions +contained in the second file are matched without regard to case. - The easiest way to install a package is to use the visual package -browser and installer, using the menu pick: + --regex=@first-file --ignore-case-regex=@second-file - Options->Manage Packages->List & Install - or - Options->Manage Packages->Using Custom->Select-> ... +A regex file contains one regular expressions per line. Empty lines, +and lines beginning with space or tab are ignored. When the first +character in a line is `@', `etags' assumes that the rest of the line +is the name of a file of regular expressions. This means that such +files can be nested. All the other lines are taken to be regular +expressions. For example, one can create a file called `emacs.tags' +with the following contents (the first line in the file is a comment): - You can also access it using the keyboard: + -- This is for GNU Emacs source files + {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ - M-x pui-list-packages +and then use it like this: - The visual package browser will then display a list of all packages. -Help information will be displayed at the very bottom of the buffer; you -may have to scroll down to see it. You can also press `?' to get the -same help. From this buffer, you can tell the package status by the -character in the first column: + etags --regex=@emacs.tags *.[ch] */*.[ch] -`-' - The package has not been installed. + Here are some more examples. The regexps are quoted to protect them +from shell interpretation. -`*' - The package has been installed, but a newer version is available. - The current version is out-of-date. + * Tag Octave files: -`+' - The package has been marked for installation/update. + etags --language=none \ + --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ + --regex='/###key \(.*\)/\1/' \ + --regex='/[ \t]*global[ \t].*/' \ + *.m - If there is no character in the first column, the package has been -installed and is up-to-date. + Note that tags are not generated for scripts so that you have to + add a line by yourself of the form `###key ' if you + want to jump to it. - From here, you can select or unselect packages for installation using -the key, the `Mouse-2' button or selecting "Select" from the -(Popup) Menu. Once you've finished selecting the packages, you can -press the `x' key (or use the menu) to actually install the packages. -Note that you will have to restart XEmacs for XEmacs to recognize any -new packages. + * Tag Tcl files: - Key summary: + etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl -`?' - Display simple help. + * Tag VHDL files: -`' -`' - Toggle between selecting and unselecting a package for - installation. + --language=none \ + --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ + --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ + \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' -`x' - Install selected packages. + +File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags + +Selecting a Tags Table +---------------------- + + 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'. -`' - View, in the minibuffer, additional information about the package, - such as the package date (not the build date) and the package - author. Moving the mouse over a package name will also do the - same thing. + +File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags -`v' - Toggle between verbose and non-verbose package display. +Finding a Tag +------------- -`g' - Refresh the package display. + The most important thing that a tags table enables you to do is to +find the definition of a specific tag. -`q' - Kill the package buffer. +`M-. TAG &OPTIONAL OTHER-WINDOW' + Find first definition of TAG (`find-tag'). - Moving the mouse over a package will also cause additional -information about the package to be displayed in the minibuffer. +`C-u M-.' + Find next alternate definition of last tag specified. -Other package installation interfaces -------------------------------------- +`C-x 4 . TAG' + Find first definition of TAG, but display it in another window + (`find-tag-other-window'). - For an alternative package interface, you can select packages from -the customize menus, under: + `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. - Options->Customize->Emacs->Packages-> ... - or - Options->Manage Packages->Using Custom->Select-> ... + 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. - Set their state to on, and then do: + 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-.'. - Options->Manage Packages->Using Custom->Update Packages + 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. - This will automatically retrieve the packages you have selected from -the XEmacs ftp site or your local disk, and install them into XEmacs. -Additionally it will update any packages you already have installed to -the newest version. Note that if a package is newly installed you will -have to restart XEmacs for the change to take effect. + Variables of note include the following: - You can also install packages using a semi-manual interface: +`tag-table-alist' + Controls which tables apply to which buffers. - M-x package-get-all +`tags-file-name' + Stores a default tags table. - Enter the name of the package (e.g., `prog-modes'), and XEmacs will -search for the latest version (as listed in the lisp file -`lisp/package-get-base.el'), and install it and any packages that it -depends upon. +`tags-build-completion-table' + Controls completion behavior. -Manual Binary Package Installation ----------------------------------- +`buffer-tag-table' + Specifies a buffer-local table. - Pre-compiled, binary packages can be installed in either a system -package directory (this is determined when XEmacs is compiled), or in -one of the following subdirectories of your `$HOME' directory: +`make-tags-files-invisible' + Sets whether tags tables should be very hidden. - ~/.xemacs/mule-packages - ~/.xemacs/xemacs-packages +`tag-mark-stack-max' + Specifies how many tags-based hops to remember. - Packages in the former directory will only be found by a Mule-enabled -XEmacs. + 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.) - XEmacs does not have to be running to install binary packages, -although XEmacs will not know about any newly-installed packages until -you restart XEmacs. Note, however, that installing a newer version of a -package while XEmacs is running could cause strange errors in XEmacs; -it's best to exit XEmacs before upgrading an existing package. + 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. - To install binary packages manually: + +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. + + 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. + + 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::. + + 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'. + +`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. + +`M-x next-file' + Visit the next file in the selected tags table. - 1. Download the package(s) that you want to install. Each binary - package will typically be a gzip'd tarball. + +File: xemacs.info, Node: List Tags, Prev: Tags Search, Up: Tags - 2. Decide where to install the packages: in the system package - directory, or in `~/.xemacs/mule-packages' or - `~/.xemacs/xemacs-packages', respectively. If you want to install - the packages in the system package directory, make sure you can - write into that directory. If you want to install in your `$HOME' - directory, create the directory, `~/.xemacs/mule-packages' or - `~/.xemacs/xemacs-packages', respectively. +Tags Table Inquiries +-------------------- - 3. Next, `cd' to the directory under which you want to install the - package(s). +`M-x list-tags' + Display a list of the tags defined in a specific program file. - 4. From this directory, uncompress and extract each of the gzip'd - tarballs that you downloaded in step 1. Unix and Cygnus cygwin - users will typically do this using the commands: +`M-x tags-apropos' + Display a list of all tags matching a specified regexp. - gunzip < package.tar.gz | tar xvf - + `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. - Above, replace `package.tar.gz' with the filename of the package - that you downloaded in step 1. + `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. - Of course, if you use GNU `tar', you could also use: + +File: xemacs.info, Node: Fortran, Next: Asm Mode, Prev: Tags, Up: Programs - tar xvzf package.tar.gz +Fortran Mode +============ - 5. That's it. Quit and restart XEmacs to get it to recognize any new - or changed packages. + 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. + +* 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: Building Packages, Prev: Using Packages, Up: Packages - - Source packages are available from the `packages/source-packages' -subdirectory of your favorite XEmacs distribution site. Alternatively, -they are available via CVS from `cvs.xemacs.org'. Look at -`http://cvs.xemacs.org' for instructions. - -Prerequisites for Building Source Packages ------------------------------------------- - - You must have GNU `cp', GNU `install' (or a BSD compatible `install' -program) GNU `make' (3.75 or later preferred), `makeinfo' (1.68 from -`texinfo-3.11' or later required), GNU `tar' and XEmacs 21.0. The -source packages will untar into a correct directory structure. At the -top level you must have `XEmacs.rules' and `package-compile.el'. These -files are available from the XEmacs FTP site from the same place you -obtained your source package distributions. - -What You Can Do With Source Packages ------------------------------------- - - NB: A global build operation doesn't exist yet as of 13 January -1998. - - Source packages are most useful for creating XEmacs package tarballs -for installation into your own XEmacs installations or for distributing -to others. - - Supported operations from `make' are: - -`clean' - Remove all built files except `auto-autoloads.el' and - `custom-load.el'. - -`distclean' - Remove XEmacs backups as well as the files deleted by `make clean'. - -`all' - Bytecompile all files, build and bytecompile byproduct files like - `auto-autoloads.el' and `custom-load.el'. Create info version of - TeXinfo documentation if present. - -`srckit' - Usually aliased to `make srckit-std'. This does a `make - distclean' and creates a package source tarball in the staging - directory. This is generally only of use for package maintainers. - -`binkit' - May be aliased to `binkit-sourceonly', `binkit-sourceinfo', - `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly' - indicates there is nothing to install in a data directory or info - directory. `sourceinfo' indicates that source and info files are - to be installed. `sourcedata' indicates that source and etc - (data) files are to be installed. `sourcedatainfo' indicates - source, etc (data), and info files are to be installed. A few - packages have needs beyond the basic templates so this is not yet - complete. - -`dist' - Runs the rules `srckit' followed by `binkit'. This is primarily - of use by XEmacs maintainers producing files for distribution. +File: xemacs.info, Node: Fortran Motion, Next: Fortran Indent, Prev: Fortran, Up: Fortran + +Motion Commands +--------------- + + 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. + +`C-M-a' + Move to beginning of subprogram + (`beginning-of-fortran-subprogram'). + +`C-M-e' + Move to end of subprogram (`end-of-fortran-subprogram'). + +`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').  -File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top - -Abbrevs -******* - - An "abbrev" is a word which "expands" into some different text. -Abbrevs are defined by the user to expand in specific ways. For -example, you might define `foo' as an abbrev expanding to `find outer -otter'. With this abbrev defined, you would be able to get `find outer -otter ' into the buffer by typing `f o o '. - - Abbrevs expand only when Abbrev mode (a minor mode) is enabled. -Disabling Abbrev mode does not cause abbrev definitions to be discarded, -but they do not expand until Abbrev mode is enabled again. The command -`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it -turns Abbrev mode on if the argument is positive, off otherwise. *Note -Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on -when the variable is non-`nil'. The variable `abbrev-mode' -automatically becomes local to the current buffer when it is set. - - Abbrev definitions can be "mode-specific"--active only in one major -mode. Abbrevs can also have "global" definitions that are active in -all major modes. The same abbrev can have a global definition and -various mode-specific definitions for different major modes. A -mode-specific definition for the current major mode overrides a global -definition. - - You can define Abbrevs interactively during an editing session. You -can also save lists of abbrev definitions in files and reload them in -later sessions. Some users keep extensive lists of abbrevs that they -load in every session. - - A second kind of abbreviation facility is called the "dynamic -expansion". Dynamic abbrev expansion happens only when you give an -explicit command and the result of the expansion depends only on the -current contents of the buffer. *Note Dynamic Abbrevs::. +File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran + +Fortran Indentation +------------------- + + 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. * Menu: -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. +* 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.  -File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs - -Defining Abbrevs -================ - -`C-x a g' - Define an abbrev to expand into some text before point - (`add-global-abbrev'). - -`C-x a l' - Similar, but define an abbrev available only in the current major - mode (`add-mode-abbrev'). - -`C-x a i g' - Define a word in the buffer as an abbrev - (`inverse-add-global-abbrev'). - -`C-x a i l' - Define a word in the buffer as a mode-specific abbrev - (`inverse-add-mode-abbrev'). - -`M-x kill-all-abbrevs' - After this command, no abbrev definitions remain in effect. - - The usual way to define an abbrev is to enter the text you want the -abbrev to expand to, position point after it, and type `C-x a g' -(`add-global-abbrev'). This reads the abbrev itself using the -minibuffer, and then defines it as an abbrev for one or more words -before point. Use a numeric argument to say how many words before point -should be taken as the expansion. For example, to define the abbrev -`foo' as in the example above, insert the text `find outer otter', then -type -`C-u 3 C-x a g f o o '. - - An argument of zero to `C-x a g' means to use the contents of the -region as the expansion of the abbrev being defined. - - The command `C-x a l' (`add-mode-abbrev') is similar, but defines a -mode-specific abbrev. Mode-specific abbrevs are active only in a -particular major mode. `C-x a l' defines an abbrev for the major mode -in effect at the time `C-x a l' is typed. The arguments work the same -way they do for `C-x a g'. - - If the text of an abbrev you want is already in the buffer instead of -the expansion, use command `C-x a i g' (`inverse-add-global-abbrev') -instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev') -instead of `C-x a l'. These commands are called "inverse" because they -invert the meaning of the argument found in the buffer and the argument -read using the minibuffer. - - To change the definition of an abbrev, just add the new definition. -You will be asked to confirm if the abbrev has a prior definition. To -remove an abbrev definition, give a negative argument to `C-x a g' or -`C-x a l'. You must choose the command to specify whether to kill a -global definition or a mode-specific definition for the current mode, -since those two definitions are independent for one abbrev. - - `M-x kill-all-abbrevs' removes all existing abbrev definitions. +File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent + +Fortran Indentation Commands +............................ + +`' + Indent the current line (`fortran-indent-line'). + +`M-' + Break the current line and set up a continuation line. + +`C-M-q' + Indent all the lines of the subprogram point is in + (`fortran-indent-subprogram'). + + 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. + + 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. + + 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.  -File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs - -Controlling Abbrev Expansion -============================ - - An abbrev expands whenever it is in a buffer just before point and -you type a self-inserting punctuation character (, comma, etc.). -Most often an abbrev is used by inserting the abbrev followed by -punctuation. - - Abbrev expansion preserves case; thus, `foo' expands into `find -outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER -OTTER' or `Find Outer Otter' according to the variable -`abbrev-all-caps' (a non-`nil' value chooses the first of the two -expansions). - - Two commands are available to control abbrev expansion: - -`M-'' - Separate a prefix from a following abbrev to be expanded - (`abbrev-prefix-mark'). - -`C-x a e' - Expand the abbrev before point (`expand-abbrev'). This is - effective even when Abbrev mode is not enabled. - -`M-x unexpand-abbrev' - Undo last abbrev expansion. - -`M-x expand-region-abbrevs' - Expand some or all abbrevs found in the region. - - You may wish to expand an abbrev with a prefix attached. For -example, if `cnst' expands into `construction', you may want to use it -to enter `reconstruction'. It does not work to type `recnst', because -that is not necessarily a defined abbrev. Instead, you can use the -command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the -abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a -minus sign in the buffer to indicate that it has done its work. Then -insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now -insert a punctuation character to expand the abbrev `cnst' into -`construction'. The minus sign is deleted at this point by `M-''. The -resulting text is the desired `reconstruction'. - - If you actually want the text of the abbrev in the buffer, rather -than its expansion, insert the following punctuation with `C-q'. Thus, -`foo C-q -' leaves `foo-' in the buffer. - - If you expand an abbrev by mistake, you can undo the expansion -(replace the expansion by the original abbrev text) with `M-x -unexpand-abbrev'. You can also use `C-_' (`undo') to undo the -expansion; but that will first undo the insertion of the punctuation -character. - - `M-x expand-region-abbrevs' searches through the region for defined -abbrevs, and offers to replace each one it finds with its expansion. -This command is useful if you have typed text using abbrevs but forgot -to turn on Abbrev mode first. It may also be useful together with a -special set of abbrev definitions for making several global -replacements at once. The command is effective even if Abbrev mode is -not enabled. +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: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs +File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent + +Syntactic Conventions +..................... + + Fortran mode assumes that you follow certain conventions that +simplify the task of understanding a Fortran program well enough to +indent it properly: + + * Two nested `do' loops never share a `continue' statement. + + * 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 `$'. -Examining and Editing Abbrevs -============================= +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. -`M-x list-abbrevs' - Print a list of all abbrev definitions. + +File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent -`M-x edit-abbrevs' - Edit a list of abbrevs; you can add, alter, or remove definitions. +Variables for Fortran Indentation +................................. - The output from `M-x list-abbrevs' looks like this: + Several additional variables control how Fortran indentation works. - (lisp-mode-abbrev-table) - "dk" 0 "define-key" - (global-abbrev-table) - "dfn" 0 "definition" +`fortran-do-indent' + Extra indentation within each level of `do' statement (the default + is 3). -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) +`fortran-if-indent' + Extra indentation within each level of `if' statement (the default + is 3). - A line containing a name in parentheses is the header for abbrevs in -a particular abbrev table; `global-abbrev-table' contains all the global -abbrevs, and the other abbrev tables that are named after major modes -contain the mode-specific abbrevs. +`fortran-continuation-indent' + Extra indentation for bodies of continuation lines (the default is + 5). - Within each abbrev table, each non-blank line defines one abbrev. -The word at the beginning is the abbrev. The number that appears is -the number of times the abbrev has been expanded. Emacs keeps track of -this to help you see which abbrevs you actually use, in case you want -to eliminate those that you don't use often. The string at the end of -the line is the expansion. +`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'. - `M-x edit-abbrevs' allows you to add, change or kill abbrev -definitions by editing a list of them in an Emacs buffer. The list has -the format described above. The buffer of abbrevs is called -`*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key -`C-c C-c' to install the abbrev definitions as specified in the buffer. -The `edit-abbrevs-redefine' command does this. Any abbrevs not -described in the buffer are eliminated when this is done. +`fortran-minimum-statement-indent' + Minimum indentation for Fortran statements. For standard Fortran, + this is 6. Statement bodies are always indented at least this + much. - `edit-abbrevs' is actually the same as `list-abbrevs', except that -it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely -displays it in another window. + +File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran + +Comments +-------- + + 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. + + 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::). + +`M-;' + Align comment or insert new comment (`fortran-comment-indent'). + +`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. + +`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.  -File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs +File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran + +Columns +------- -Saving Abbrevs -============== +`C-c C-r' + Displays a "column ruler" momentarily above the current line + (`fortran-column-ruler'). - These commands allow you to keep abbrev definitions between editing -sessions. +`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'). -`M-x write-abbrev-file' - Write a file describing all defined abbrevs. + 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. -`M-x read-abbrev-file' - Read such an abbrev file and define abbrevs as specified there. + 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. -`M-x quietly-read-abbrev-file' - Similar, but do not display a message about what is going on. + 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. -`M-x define-abbrevs' - Define abbrevs from buffer. + 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. + + +File: xemacs.info, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran -`M-x insert-abbrevs' - Insert all abbrevs and their expansions into the buffer. +Fortran Keyword Abbrevs +----------------------- - Use `M-x write-abbrev-file' to save abbrev definitions for use in a -later session. The command reads a file name using the minibuffer and -writes a description of all current abbrev definitions into the -specified file. The text stored in the file looks like the output of -`M-x list-abbrevs'. + 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::. - `M-x read-abbrev-file' prompts for a file name using the minibuffer -and reads the specified file, defining abbrevs according to its -contents. `M-x quietly-read-abbrev-file' is the same but does not -display a message in the echo area; it is actually useful primarily in -the `.emacs' file. If you give an empty argument to either of these -functions, the file name Emacs uses is the value of the variable -`abbrev-file-name', which is by default `"~/.abbrev_defs"'. + 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". - Emacs offers to save abbrevs automatically if you have changed any of -them, whenever it offers to save all files (for `C-x s' or `C-x C-c'). -Set the variable `save-abbrevs' to `nil' to inhibit this feature. + 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. - The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are -similar to the previous commands but work on text in an Emacs buffer. -`M-x insert-abbrevs' inserts text into the current buffer before point, -describing all current abbrev definitions; `M-x define-abbrevs' parses -the entire current buffer and defines abbrevs accordingly. + Type `;?' or `;C-h' to display a list of all built-in Fortran +abbrevs and what they stand for.  -File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs - -Dynamic Abbrev Expansion -======================== - - The abbrev facility described above operates automatically as you -insert text, but all abbrevs must be defined explicitly. By contrast, -"dynamic abbrevs" allow the meanings of abbrevs to be determined -automatically from the contents of the buffer, but dynamic abbrev -expansion happens only when you request it explicitly. - -`M-/' - Expand the word in the buffer before point as a "dynamic abbrev", - by searching in the buffer for words starting with that - abbreviation (`dabbrev-expand'). - - For example, if the buffer contains `does this follow ' and you type -`f o M-/', the effect is to insert `follow' because that is the last -word in the buffer that starts with `fo'. A numeric argument to `M-/' -says to take the second, third, etc. distinct expansion found looking -backward from point. Repeating `M-/' searches for an alternative -expansion by looking farther back. After the entire buffer before -point has been considered, the buffer after point is searched. - - Dynamic abbrev expansion is completely independent of Abbrev mode; -the expansion of a word with `M-/' is completely independent of whether -it has a definition as an ordinary abbrev. +File: xemacs.info, Node: Asm Mode, Prev: Fortran, Up: Programs + +Asm Mode +======== + + Asm mode is a major mode for editing files of assembler code. It +defines these commands: + +`' + `tab-to-tab-stop'. + +`' + 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'. + +`;' + Insert or align a comment. + + The variable `asm-comment-char' specifies which character starts +comments in assembler syntax.  -File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top - -Editing Pictures -**************** - - If you want to create a picture made out of text characters (for -example, a picture of the division of a register into fields, as a -comment in a program), use the command `edit-picture' to enter Picture -mode. - - In Picture mode, editing is based on the "quarter-plane" model of -text. In this model, the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the -end of a line does not exist in this model; the most you can say is -where the last non-blank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But in Picture mode most -frequently-used keys are rebound to commands that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture -mode to do essentially the same thing but in a quarter-plane way. In -addition, Picture mode defines various keys starting with the `C-c' -prefix to run special picture editing commands. - - One of these keys, `C-c C-c', is pretty important. Often a picture -is part of a larger file that is usually edited in some other major -mode. `M-x edit-picture' records the name of the previous major mode. -You can then use the `C-c C-c' command (`picture-mode-exit') to restore -that mode. `C-c C-c' also deletes spaces from the ends of lines, -unless you give it a numeric argument. - - The commands used in Picture mode all work in other modes (provided -the `picture' library is loaded), but are only bound to keys in -Picture mode. Note that the descriptions below talk of moving "one -column" and so on, but all the picture mode commands handle numeric -arguments as their normal equivalents do. - - Turning on Picture mode calls the value of the variable -`picture-mode-hook' as a function, with no arguments, if that value -exists and is non-`nil'. +File: xemacs.info, Node: Running, Next: Abbrevs, Prev: Programs, Up: Top + +Compiling and Testing Programs +****************************** + + 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: -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. +* 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: Compilation, Next: Lisp Modes, Prev: Running, Up: Running + +Running "make", or Compilers Generally +====================================== + + 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 = ... + + +File: xemacs.info, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Running + +Major Modes for Lisp +==================== + + 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. + +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::. + +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::. + +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::. + +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::). + +Scheme mode + Like Lisp mode but for Scheme programs. + +Inferior Scheme mode + The mode for an interactive session with an inferior Scheme + process.