@node Programs, Running, Text, Top
@chapter Editing Programs
+@cindex Programming Languages
@cindex Lisp
-@cindex C
- Emacs has many commands designed to understand the syntax of programming
-languages such as Lisp and C. These commands can:
+ XEmacs provides specialized support for editing source files for many
+different programming languages. For example it is possible to
@itemize @bullet
@item
+Follow the usual indentation conventions of the language
+(@pxref{Grinding}).
+@item
Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
@item
Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
@item
Insert, kill, or align comments (@pxref{Comments}).
@item
-Follow the usual indentation conventions of the language
-(@pxref{Grinding}).
+Find functions and symbols in program by name (@pxref{Tags}).
@end itemize
The commands available for words, sentences, and paragraphs are useful in
There are editing commands to operate on them.
* Grinding:: Adjusting indentation to show the nesting.
* Matching:: Insertion of a close-delimiter flashes matching open.
-* Comments:: Inserting, illing and aligning comments.
+* Comments:: Inserting, filling and aligning comments.
* Balanced Editing:: Inserting two matching parentheses at once, etc.
* Lisp Completion:: Completion on symbol names in Lisp code.
* Documentation:: Getting documentation of functions you plan to call.
* Change Log:: Maintaining a change history for your program.
* Tags:: Go direct to any function in your program in one
command. Tags remembers which file it is in.
+* CC Mode:: Modes for C, C++, Java and similar languages
* Fortran:: Fortran mode and its special features.
* Asm Mode:: Asm mode and its special features.
@end menu
@section Major Modes for Programming Languages
@cindex Lisp mode
-@cindex C mode
-@cindex Scheme mode
- Emacs has several major modes for the programming languages Lisp, Scheme (a
-variant of Lisp), C, Fortran, and Muddle. Ideally, a major mode should be
-implemented for each programming language you might want to edit with
-Emacs; but often the mode for one language can serve for other
-syntactically similar languages. The language modes that exist are those
-that someone decided to take the trouble to write.
-
- There are several variants of Lisp mode, which differ in the way they
-interface to Lisp execution. @xref{Lisp Modes}.
-
- Each of the programming language modes defines the @key{TAB} key to run
-an indentation function that knows the indentation conventions of that
-language and updates the current line's indentation accordingly. For
-example, in C mode @key{TAB} is bound to @code{c-indent-line}. @key{LFD}
-is normally defined to do @key{RET} followed by @key{TAB}; thus it, too,
-indents in a mode-specific fashion.
+ Emacs has several major modes (@pxref{Major Modes}) to support
+programming languages. These major modes will typically understand
+language syntax, provide automatic indentation features, syntax based
+highlighting of text, and will often provide interfaces to the
+programming environment to assist in compiling, executing and debugging
+programs.
+
+ A language mode exist when someone decides to take the trouble to
+write it. At this time many widely used programming languages are
+supported by XEmacs. Examples include Ada, Awk, C, C++, CORBA (IDL),
+Fortran, Java, Lisp, Modula 2, Objective-C, Perl, Pike, Prolog, Python,
+Ruby, Scheme, Simula, SQL, Tcl, Unix Shell scripts, and VHDL. Some of
+these language have seperate manuals, and some times more than one mode
+may be available for a language. For example, there are several
+variants of Lisp mode, which differ in the way they interface to Lisp
+execution. @xref{Lisp Modes}.
+
+ Major modes for programming language support are distributed in
+optional XEmacs packages (@pxref{Packages}) that must be installed
+before use. A notable exception to this rule is that a Lisp Mode is
+integral to XEmacs. The Programming Mode Package (@file{prog-modes})
+contains many such modes. Some languages are supported by packages of
+their own; prominent examples of such packages include @file{cc-mode}
+for C, C++, Java, Objective C etc.@:, @file{python-modes} for Python,
+and @file{scheme} for Scheme.
+
+ For a language named @var{lang} the major mode for the language will
+typically be named @code{@var{lang}-mode}. For example, the mode for C
+is called @code{c-mode}, that for Bourne shell scripts is called
+@code{sh-mode} and so on. These modes will invoke the functions listed
+in the corresponding hook variables as a last step. @xref{Mode Hooks}.
+
+ A mode can be invoked by typing @kbd{M-x @var{lang}-mode
+@key{RET}}. However this step is not normally required. If the package
+for a language mode is installed XEmacs usually knows when to
+automatically invoke the mode. This is normally done based on examining
+the file name to determine the language. @ref{Choosing Modes}.
+
+ Each of the programming language modes defines the @key{TAB} key to
+run an indentation function that knows the indentation conventions of
+that language and updates the current line's indentation accordingly.
+@key{LFD} is normally defined to do @key{RET} followed by @key{TAB};
+thus it, too, indents in a mode-specific fashion.
@kindex DEL
@findex backward-delete-char-untabify
if enabled in a programming language major mode, indents the new lines
which it creates.
-@cindex mode hook
-@vindex c-mode-hook
-@vindex lisp-mode-hook
-@vindex emacs-lisp-mode-hook
-@vindex lisp-interaction-mode-hook
-@vindex scheme-mode-hook
-@vindex muddle-mode-hook
- Turning on a major mode calls a user-supplied function called the
-@dfn{mode hook}, which is the value of a Lisp variable. For example,
-turning on C mode calls the value of the variable @code{c-mode-hook} if
-that value exists and is non-@code{nil}. Mode hook variables for other
-programming language modes include @code{lisp-mode-hook},
-@code{emacs-lisp-mode-hook}, @code{lisp-interaction-mode-hook},
-@code{scheme-mode-hook}, and @code{muddle-mode-hook}. The mode hook
-function receives no arguments.@refill
-
@node Lists, Defuns, Program Modes, Programs
@section Lists and Sexps
specified number of times; with a negative argument, it moves in the
opposite direction.
-In languages such as C where the comment-terminator can be recognized,
-the sexp commands move across comments as if they were whitespace. In
-Lisp and other languages where comments run until the end of a line, it
-is very difficult to ignore comments when parsing backwards; therefore,
-in such languages the sexp commands treat the text of comments as if it
-were code.
-
@kindex C-M-k
@findex kill-sexp
Killing an sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
* Basic Indent::
* Multi-line Indent:: Commands to reindent many lines at once.
* Lisp Indent:: Specifying how each Lisp function should be indented.
-* C Indent:: Choosing an indentation style for C code.
@end menu
@node Basic Indent, Multi-line Indent, Grinding, Grinding
mark. The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB}
to every line whose first character is between point and mark.
-@node Lisp Indent, C Indent, Multi-line Indent, Grinding
+@node Lisp Indent, , Multi-line Indent, Grinding
@subsection Customizing Lisp Indentation
@cindex customization
until the end of the list.
@end table
-@node C Indent,, Lisp Indent, Grinding
-@subsection Customizing C Indentation
-
- Two variables control which commands perform C indentation and when.
-
-@vindex c-auto-newline
- If @code{c-auto-newline} is non-@code{nil}, newlines are inserted both
-before and after braces that you insert and after colons and semicolons.
-Correct C indentation is done on all the lines that are made this way.
-
-@vindex c-tab-always-indent
- If @code{c-tab-always-indent} is non-@code{nil}, the @key{TAB} command
-in C mode does indentation only if point is at the left margin or within
-the line's indentation. If there is non-whitespace to the left of point,
-@key{TAB} just inserts a tab character in the buffer. Normally,
-this variable is @code{nil}, and @key{TAB} always reindents the current line.
-
- C does not have anything analogous to particular function names for which
-special forms of indentation are desirable. However, it has a different
-need for customization facilities: many different styles of C indentation
-are in common use.
-
- There are six variables you can set to control the style that Emacs C
-mode will use.
-
-@table @code
-@item c-indent-level
-Indentation of C statements within surrounding block. The surrounding
-block's indentation is the indentation of the line on which the
-open-brace appears.
-@item c-continued-statement-offset
-Extra indentation given to a substatement, such as the then-clause of
-an @code{if} or body of a @code{while}.
-@item c-brace-offset
-Extra indentation for lines that start with an open brace.
-@item c-brace-imaginary-offset
-An open brace following other text is treated as if it were this far
-to the right of the start of its line.
-@item c-argdecl-indent
-Indentation level of declarations of C function arguments.
-@item c-label-offset
-Extra indentation for a line that is a label, case, or default.
-@end table
-
-@vindex c-indent-level
- The variable @code{c-indent-level} controls the indentation for C
-statements with respect to the surrounding block. In the example:
-
-@example
- @{
- foo ();
-@end example
-
-@noindent
-the difference in indentation between the lines is @code{c-indent-level}.
-Its standard value is 2.
-
-If the open-brace beginning the compound statement is not at the beginning
-of its line, the @code{c-indent-level} is added to the indentation of the
-line, not the column of the open-brace. For example,
-
-@example
-if (losing) @{
- do_this ();
-@end example
-
-@noindent
-One popular indentation style is that which results from setting
-@code{c-indent-level} to 8 and putting open-braces at the end of a line
-in this way. Another popular style prefers to put the open-brace on a
-separate line.
-
-@vindex c-brace-imaginary-offset
- In fact, the value of the variable @code{c-brace-imaginary-offset} is
-also added to the indentation of such a statement. Normally this variable
-is zero. Think of this variable as the imaginary position of the open
-brace, relative to the first non-blank character on the line. By setting
-the variable to 4 and @code{c-indent-level} to 0, you can get this style:
-
-@example
-if (x == y) @{
- do_it ();
- @}
-@end example
-
- When @code{c-indent-level} is zero, the statements inside most braces
-line up exactly under the open brace. An exception are braces in column
-zero, like those surrounding a function's body. The statements inside
-those braces are not placed at column zero. Instead,
-@code{c-brace-offset} and @code{c-continued-statement-offset} (see
-below) are added to produce a typical offset between brace levels, and
-the statements are indented that far.
-
-@vindex c-continued-statement-offset
- @code{c-continued-statement-offset} controls the extra indentation for
-a line that starts within a statement (but not within parentheses or
-brackets). These lines are usually statements inside other statements,
-like the then-clauses of @code{if} statements and the bodies of
-@code{while} statements. The @code{c-continued-statement-offset}
-parameter determines the difference in indentation between the two lines in:
-
-@example
-if (x == y)
- do_it ();
-@end example
-
-@noindent
-The default value for @code{c-continued-statement-offset} is 2. Some
-popular indentation styles correspond to a value of zero for
-@code{c-continued-statement-offset}.
-
-@vindex c-brace-offset
- @code{c-brace-offset} is the extra indentation given to a line that
-starts with an open-brace. Its standard value is zero;
-compare:
-
-@example
-if (x == y)
- @{
-@end example
-
-@noindent
-with:
-
-@example
-if (x == y)
- do_it ();
-@end example
-
-@noindent
-If you set @code{c-brace-offset} to 4, the first example becomes:
-
-@example
-if (x == y)
- @{
-@end example
-
-@vindex c-argdecl-indent
- @code{c-argdecl-indent} controls the indentation of declarations of the
-arguments of a C function. It is absolute: argument declarations receive
-exactly @code{c-argdecl-indent} spaces. The standard value is 5 and
-results in code like this:
-
-@example
-char *
-index (string, char)
- char *string;
- int char;
-@end example
-
-@vindex c-label-offset
- @code{c-label-offset} is the extra indentation given to a line that
-contains a label, a case statement, or a @code{default:} statement. Its
-standard value is @minus{}2 and results in code like this:
-
-@example
-switch (c)
- @{
- case 'x':
-@end example
-
-@noindent
-If @code{c-label-offset} were zero, the same code would be indented as:
-
-@example
-switch (c)
- @{
- case 'x':
-@end example
-
-@noindent
-This example assumes that the other variables above also have their
-default values.
-
-Using the indentation style produced by the default settings of the
-variables just discussed and putting open braces on separate lines
-produces clear and readable files. For an example, look at any of the C
-source files of XEmacs.
@node Matching, Comments, Grinding, Programs
@section Automatic Display of Matching Parentheses
@findex insert-parentheses
@findex move-over-close-and-reindent
The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
-(@code{move-over-close-@*and-reindent}) are designed to facilitate a style of
+(@code{move-over-close-and-reindent}) are designed to facilitate a style of
editing which keeps parentheses balanced at all times. @kbd{M-(} inserts a
pair of parentheses, either together as in @samp{()}, or, if given an
argument, around the next several sexps, and leaves point after the open
not displayed), set it again in final compute_motion.
@end smallexample
-@node Tags, Fortran, Change Log, Programs
+@node Tags, CC Mode, Change Log, Programs
@section Tags Tables
@cindex tags table
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 @kbd{M-.} command which finds the
+and positions makes possible the @kbd{M-.} command which finds the
definition of a function by looking up which of the files it is in.
Tags tables are stored in files called @dfn{tags table files}. The
global variables, data types, and anything else convenient. Each name
recorded is called a @dfn{tag}.
+@cindex C++ class browser, tags
+@cindex tags, C++
+@cindex class browser, C++
+@cindex Ebrowse
+The Ebrowse is a separate facility tailored for C++, with tags and a
+class browser. @xref{Top,,, ebrowse, Ebrowse User's Manual}.
+
@menu
-* Tag Syntax:: Tag syntax for various types of code and text files.
+* Tag Syntax:: Tag syntax for various types of code and text files.
* Create Tags Table:: Creating a tags table with @code{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.
+* 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.
@end menu
@itemize @bullet
@item
In C code, any C function or typedef is a tag, and so are definitions of
-@code{struct}, @code{union} and @code{enum}. @code{#define} macro
-definitions and @code{enum} constants are also tags, unless you specify
-@samp{--no-defines} when making the tags table. Similarly, global
-variables are tags, unless you specify @samp{--no-globals}. Use of
-@samp{--no-globals} and @samp{--no-defines} can make the tags table file
-much smaller.
+@code{struct}, @code{union} and @code{enum}. You can tag function
+declarations and external variables in addition to function definitions
+by giving the @samp{--declarations} option to @code{etags}.
+@code{#define} macro definitions and @code{enum} constants are also
+tags, unless you specify @samp{--no-defines} when making the tags table.
+Similarly, global variables are tags, unless you specify
+@samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
+can make the tags table file much smaller.
@item
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 @samp{--members} option. Tags for variables and functions in
classes are named @samp{@var{class}::@var{variable}} and
-@samp{@var{class}::@var{function}}.
+@samp{@var{class}::@var{function}}. @code{operator} functions tags are
+named, for example @samp{operator+}.
@item
In Java code, tags include all the constructs recognized in C++, plus
-the @code{extends} and @code{implements} constructs. Tags for variables
-and functions in classes are named @samp{@var{class}.@var{variable}} and
-@samp{@var{class}.@var{function}}.
+the @code{interface}, @code{extends} and @code{implements} constructs.
+Tags for variables and functions in classes are named
+@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
@item
In La@TeX{} text, the argument of any of the commands @code{\chapter},
Other commands can make tags as well, if you specify them in the
environment variable @code{TEXTAGS} before invoking @code{etags}. The
value of this environment variable should be a colon-separated list of
-commands names. For example,
+command names. For example,
@example
TEXTAGS="def:newcommand:newenvironment"
Several other languages are also supported:
@itemize @bullet
+
+@item
+In Ada code, functions, procedures, packages, tasks, and types are
+tags. Use the @samp{--packages-only} option to create tags for
+packages only.
+
+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:
+
+@table @asis
+@item function
+ @kbd{/f}
+@item procedure
+ @kbd{/p}
+@item package spec
+ @kbd{/s}
+@item package body
+ @kbd{/b}
+@item type
+ @kbd{/t}
+@item task
+ @kbd{/k}
+@end table
+
+So, as an example, @kbd{M-x find-tag bidule/b} will go directly to the
+body of the package @var{bidule} while @kbd{M-x find-tag bidule} will
+just search for any tag @var{bidule}.
+
@item
In assembler code, labels appearing at the beginning of a line,
followed by a colon, are tags.
as C code.
@item
-In Cobol code, paragraphs names are the tags, i.e. any word starting in
-column 8 and followed by a full stop.
+In Cobol code, tags are paragraph names; that is, any word starting in
+column 8 and followed by a period.
@item
In Erlang code, the tags are the functions, records, and macros defined
in the file.
@item
-In Fortran code, functions and subroutines are tags.
+In Fortran code, functions, subroutines and blockdata are tags.
+
+@item
+In makefiles, targets are tags.
@item
In Objective C code, tags include Objective C definitions for classes,
-class categories, methods and protocols.
+class categories, methods, and protocols.
@item
In Pascal code, the tags are the functions and procedures defined in
the file.
@item
-In Perl code, the tags are the procedures defined by the @code{sub}
-keyword.
+In Perl code, the tags are the procedures defined by the @code{sub},
+@code{my} and @code{local} keywords. Use @samp{--globals} if you want
+to tag global variables.
@item
-In Postscript code, the tags are the functions.
+In PostScript code, the tags are the functions.
@item
In Prolog code, a tag name appears at the left margin.
+
+@item
+In Python code, @code{def} or @code{class} at the beginning of a line
+generate a tag.
@end itemize
- You can also generate tags based on regexp matching (@pxref{Create
-Tags Table}) to handle other formats and languages.
+ You can also generate tags based on regexp matching (@pxref{Etags
+Regexps}) to handle other formats and languages.
@node Create Tags Table
@subsection Creating Tags Tables
@end example
@noindent
-The @code{etags} program reads the specified files, and writes a tags table
-named @file{TAGS} in the current working directory. @code{etags}
-recognizes the language used in an input file based on its file name and
-contents. You can specify the language with the
+The @code{etags} program reads the specified files, and writes a tags
+table named @file{TAGS} in the current working directory. You can
+intermix compressed and plain text source file names. @code{etags}
+knows about the most common compression formats, and does the right
+thing. So you can compress all your source files and have @code{etags}
+look for compressed versions of its file name arguments, if it does not
+find uncompressed versions. Under MS-DOS, @code{etags} also looks for
+file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
+command line and @samp{mycode.c} does not exist.
+
+ @code{etags} recognizes the language used in an input file based on
+its file name and contents. You can specify the language with the
@samp{--language=@var{name}} option, described below.
If the tags table data become outdated due to changes in the files
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
-@samp{/}, or with @samp{@var{device}:/} on MS-DOS and Windows.
+@samp{/}, or with @samp{@var{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
is to tell @code{etags} to read the file names from its standard input,
by typing a dash in place of the file names, like this:
-@example
+@smallexample
find . -name "*.[chCH]" -print | etags -
-@end example
+@end smallexample
Use the option @samp{--language=@var{name}} to specify the language
explicitly. You can intermix these options with file names; each one
@samp{--language=auto} to tell @code{etags} to resume guessing the
language from the file names and file contents. Specify
@samp{--language=none} to turn off language-specific processing
-entirely; then @code{etags} recognizes tags by regexp matching alone.
-@samp{etags --help} prints the list of the languages @code{etags} knows,
-and the file name rules for guessing the language.
+entirely; then @code{etags} recognizes tags by regexp matching alone
+(@pxref{Etags Regexps}).
+
+ @samp{etags --help} prints the list of the languages @code{etags}
+knows, and the file name rules for guessing the language. It also prints
+a list of all the available @code{etags} options, together with a short
+explanation.
+
+@node Etags Regexps
+@subsection Etags Regexps
The @samp{--regex} option provides a general way of recognizing tags
based on regexp matching. You can freely intermix it with file names.
Each @samp{--regex} option adds to the preceding ones, and applies only
to the following files. The syntax is:
-@example
+@smallexample
--regex=/@var{tagregexp}[/@var{nameregexp}]/
-@end example
+@end smallexample
@noindent
where @var{tagregexp} is used to match the lines to tag. It is always
You should not match more characters with @var{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 @var{tagregexp},
-you may find useful to add a @var{nameregexp}, in order to narrow the tag
-scope. You can find some examples below.
+more characters than needed are unavoidably matched by @var{tagregexp}
+(as will usually be the case), you should add a @var{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.
+
+ The option @samp{--ignore-case-regex} (or @samp{-c}) is like
+@samp{--regex}, except that the regular expression provided will be
+matched without regard to case, which is appropriate for various
+programming languages.
The @samp{-R} option deletes all the regexps defined with
@samp{--regex} options. It applies to the file names following it, as
you can see from the following example:
-@example
+@smallexample
etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
bar.ber -R --lang=lisp los.er
-@end example
+@end smallexample
@noindent
Here @code{etags} chooses the parsing language for @file{voo.doo} and
@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
matching, to recognize tags in @file{los.er}.
- Here are some more examples. The regexps are quoted to protect them
-from shell interpretation.
+ A regular expression can be bound to a given language, by prepending
+it with @samp{@{lang@}}. When you do this, @code{etags} will use the
+regular expression only for files of that language. @samp{etags --help}
+prints the list of languages recognised by @code{etags}. The following
+example tags the @code{DEFVAR} macros in the Emacs source files.
+@code{etags} applies this regular expression to C files only:
+
+@smallexample
+--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+@end smallexample
@noindent
-Tag the @code{DEFVAR} macros in the emacs source files:
+This feature is particularly useful when storing a list of regular
+expressions in a file. The following option syntax instructs
+@code{etags} to read two files of regular expressions. The regular
+expressions contained in the second file are matched without regard to
+case.
-@example
---regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
-@end example
+@smallexample
+--regex=@@first-file --ignore-case-regex=@@second-file
+@end smallexample
@noindent
-Tag VHDL files (this example is a single long line, broken here for
-formatting reasons):
+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 @samp{@@}, @code{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
+@samp{emacs.tags} with the following contents (the first line in the
+file is a comment):
-@example
---language=none
---regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
---regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
-\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
-@end example
+@smallexample
+ -- This is for GNU Emacs source files
+@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
+@end smallexample
@noindent
-Tag TCL files (this last example shows the usage of a @var{nameregexp}):
+and then use it like this:
-@example
---lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
-@end example
+@smallexample
+etags --regex=@@emacs.tags *.[ch] */*.[ch]
+@end smallexample
+
+ Here are some more examples. The regexps are quoted to protect them
+from shell interpretation.
- For a list of the other available @code{etags} options, execute
-@code{etags --help}.
+@itemize @bullet
+
+@item
+Tag Octave files:
-@node Select Tags Table, Find Tag, Create Tags Table, Tags
+@smallexample
+etags --language=none \
+ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+ --regex='/###key \(.*\)/\1/' \
+ --regex='/[ \t]*global[ \t].*/' \
+ *.m
+@end smallexample
+
+@noindent
+Note that tags are not generated for scripts so that you have to add a
+line by yourself of the form `###key <script-name>' if you want to jump
+to it.
+
+@item
+Tag Tcl files:
+
+@smallexample
+etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
+@end smallexample
+
+@item
+Tag VHDL files:
+
+@smallexample
+--language=none \
+--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+@end smallexample
+@end itemize
+
+@node Select Tags Table, Find Tag, Etags Regexps, Tags
@subsection Selecting a Tags Table
@vindex tag-table-alist
@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/")
- ))
+ '(("/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/")
+ ))
@end example
The example defines the tags table alist in the following way:
@table @kbd
@item tag-table-alist
Controls which tables apply to which buffers.
-@item tags-file-name
+@item tags-file-name
Stores a default tags table.
-@item tags-build-completion-table
+@item tags-build-completion-table
Controls completion behavior.
-@item buffer-tag-table
+@item buffer-tag-table
Specifies a buffer-local table.
-@item make-tags-files-invisible
+@item make-tags-files-invisible
Sets whether tags tables should be very hidden.
-@item tag-mark-stack-max
+@item tag-mark-stack-max
Specifies how many tags-based hops to remember.
@end table
Visit the next file in the selected tags table.
@end table
-@node List Tags,, Tags Search, Tags
+@node List Tags, , Tags Search, Tags
@subsection Tags Table Inquiries
@table @kbd
then finds all the tags in the selected tags table whose entries match that
regexp, and displays the tag names found.
-@node Fortran, Asm Mode, Tags, Programs
+@node CC Mode, Fortran, Tags, Programs
+@section Modes for C, C++, Java and similar languages
+@cindex C Mode
+@cindex C++ Mode
+@cindex Java Mode
+@cindex AWK Mode
+@cindex Objective C Mode
+@cindex CORBA IDL Mode
+@findex c-mode
+@findex c++-mode
+@findex java-mode
+@findex idl-mode
+@findex awk-mode
+@findex pike-mode
+@findex objc-mode
+@vindex c-mode-hook
+@vindex c++-mode-hook
+@vindex java-mode-hook
+@vindex idl-mode-hook
+@vindex awk-mode-hook
+@vindex pike-mode-hook
+@vindex objc-mode-hook
+@vindex c-mode-common-hook
+@vindex c-initialization-hook
+
+ The recommended means for supporting the ``C--like'' programming
+languages in XEmacs is the @file{cc-mode} package. CC Mode is not
+included in the basic XEmacs distribution but is available as an
+optional package. If loading a file whose names ends in the @file{.cc}
+extension does not automatically invoke a C++ Mode then the
+@file{cc-mode} package is probably not yet installed. @xref{Packages}.
+
+ CC Mode provides modes for editing source files in Awk
+(@code{awk-mode}), C (@code{c-mode}), C++ (@code{c++-mode}), CORBA IDL
+(@code{idl-mode}), Java (@code{java-mode}), Objective C
+(@code{objc-mode}), and Pike (@code{pike-mode}). All these languages are
+supported with an sophisticated ``indentation engine'' that is feature
+rich, customizable and quite efficient.
+
+ Each language major mode runs hooks in the conventionally named hook
+variables (@pxref{Mode Hooks}). In addition to this conventional
+behavior all the CC Mode major modes will also run hooks in
+@code{c-mode-common-hook} @emph{before} invoking the major mode specific
+hook.
+
+ CC Mode runs any hooks in @code{c-initialization-hook} exactly once
+when it is first loaded.
+
+ CC Mode is a very comprehensive and flexible system and full
+description of its capabilities is beyond the scope of this manual. It
+is strongly recommended that the reader consult the CC Mode
+documentation for details once the package has been
+installed. @xref{Top,CC Mode,,cc-mode, The CC Mode Manual}.
+
+@menu
+* Older Modes:: Older Modes for C and AWK
+* Customizing CC Mode:: An Introduction to Customizing CC Mode.
+@end menu
+
+
+@node Older Modes, Customizing CC Mode, CC Mode, CC Mode
+@subsection Older Modes for C and AWK
+@cindex Old C Mode
+@cindex Old AWK Mode
+@cindex C Mode without CC Mode
+@cindex AWK Mode without CC Mode
+@cindex old-c-mode
+
+ XEmacs provides older versions of a C Mode and an AWK Mode in the
+@file{prog-modes} package. These older modes do not share the
+indentation engine in CC Mode have have their own specific means of
+customizing indentation. To use these modes the @file{prog-modes}
+package must be installed.
+
+ This older C mode is known simply as the ``Old C Mode''. It supports
+only the C language and it lacks many of the features of CC Mode.
+However the old C mode offers modest space requirements and very fast
+operation. Old C Mode might be useful in space constrained
+environments, on slow machines, or for editing very large files. This
+old C mode is available in the @file{old-c-mode}
+library. @xref{old-c-mode,Old C Mode,old-c-mode,prog-modes,The
+Programming Modes Package Manual}.
+
+ The old AWK mode exists for similar reasons. It is available in the
+@file{awk-mode} library. @xref{awk-mode,Old AWK
+Mode,awk-mode,prog-modes,The Programming Modes Package Manual}.
+
+ Note that the prog-modes package will never automatically invoke these
+older modes for a user. However installing the @file{cc-mode} package
+@emph{will} make CC Mode's versions available automatically. As a
+result a user who wants to use these older modes must explicitly load
+the old libraries to use them.
+
+@node Customizing CC Mode, , Older Modes, CC Mode
+@subsection Customizing Indentation in CC Mode
+
+ A very brief introduction is included here on customizing CC Mode. CC
+Mode has many features, including useful minor modes, that are
+completely documented in its own manual.
+
+ CC Mode implements several different ``styles'' for C code (and the
+other languages supported by CC Mode). If you need to change the
+indentation style for CC Mode it is recommended that you first see if an
+existing style meets your requirements. The style chosen will affect the
+placement of language elements like braces, function declarations and
+comments. You can choose a style interactively by typing @kbd{C-c .} and
+pressing the space bar at the prompt to get a list of supported
+styles. @kbd{C-c .} runs the function @code{c-set-style} which applies
+to all CC Mode language modes though its name might suggest otherwise. A
+few of the the supported styles are listed below.
+
+@itemize @bullet
+@item
+``gnu'' --- The recommeded style from the Free Software Foundation for
+GNU software.
+@item
+``k&r'' --- The classic style from Kernighan and Ritchie.
+@item
+``linux'' --- The style recommended for code in the Linux kernel.
+@item
+``bsd'' --- The style recommended for software developed in BSD.
+@item
+``java --- The ``traditional'' Java style.
+@end itemize
+
+ The default style in XEmacs is ``gnu'' except for Java mode where it
+is the ``java'' style (this is governed by the variable
+@code{c-default-style}).
+
+ The styles included in CC Mode all use a buffer local variable called
+@code{c-basic-offset} as the basic indentation level (this buffer local
+variable is used in all CC Mode language modes though its name might
+suggest otherwise). All indentation is, by default, expressed in
+multiples of @code{c-basic-offset}.
+
+ Each style defines a default value for @code{c-basic-offset}, for the
+``gnu'' style sets it to 2. A very common customization scenario is
+where a user wants to use an existing style but with a different basic
+offset value. An easy way to do this is to set @code{c-basic-offset} in
+the language mode hook after selecting the chosen style.
+
+ For example, a user might want to follow a local coding convention of
+using the ``k&r'' style for C code with indentation in two columns
+multiples (instead of the five column default provided by the CC Mode
+``k&r'' style). This can be achieved with the following code in the
+initialization file (@pxref{Init File})
+
+@example
+(defun my-c-mode-hook ()
+ (c-set-style "k&r")
+ (setq c-basic-offset 2))
+(add-hook 'c-mode-hook 'my-c-mode-hook)
+@end example
+
+ Most customizations for indentation in various CC modes can be
+accomplished by choosing a style and then choosing value for
+@code{c-basic-offset} that meets the local coding convention. CC Mode
+has a very customizable indentation engine and a furthur discussion is
+really beyond the scope of this manual. @xref{Indentation
+Engine,,,cc-mode,The CC Mode Manual}.
+
+
+@node Fortran, Asm Mode, CC Mode, Programs
@section Fortran Mode
@cindex Fortran mode
retain its meaning when reindented even if the conventions are not
followed.
-@node ForIndent Vars,, ForIndent Conv, Fortran Indent
+@node ForIndent Vars, , ForIndent Conv, Fortran Indent
@subsubsection Variables for Fortran Indentation
@vindex fortran-do-indent
columns wide. When you edit in this window, you can immediately see
when a line gets too wide to be correct Fortran.
-@node Fortran Abbrev,, Fortran Columns, Fortran
+@node Fortran Abbrev, , Fortran Columns, Fortran
@subsection Fortran Keyword Abbrevs
Fortran mode provides many built-in abbrevs for common keywords and
Type @samp{;?} or @samp{;C-h} to display a list of all built-in
Fortran abbrevs and what they stand for.
-@node Asm Mode,, Fortran, Programs
+@node Asm Mode, , Fortran, Programs
@section Asm Mode
@cindex Asm mode
projects / chise / xemacs-chise.git.1 / blobdiff