xemacs-beta: man/xemacs/programs.texi comparison

comparison man/xemacs/programs.texi @ 2522:52dc9b940348

[xemacs-hg @ 2005-01-28 00:12:32 by ben] cc-mode patch from Shyamal Prasad xemacs/programs.texi: Updated it to reflect current status of programming modes. xemacs/programs.texi: New section introduces CC Mode. Introduces customization with reference to CC Mode manual. Also introduce C/AWK modes in prog-modes package xemacs/programs.texi: Removed - it was obsolete. prog-modes package documentation now contains indentation description for old C mode xemacs/major.texi: Add description of major mode hooks. Cleaned up and updated programming mode descriptions. xemacs/xemacs.texi: Updated Detailed Node listing for new CC Mode section in programs.texi

author	ben
date	Fri, 28 Jan 2005 00:12:39 +0000
parents	1df7a5cfb04a
children	6b0000935adc

comparison

equal deleted inserted replaced

-:67a2797862bc
+:52dc9b940348
 @node Programs, Running, Text, Top
 @chapter Editing Programs
+@cindex Programming Languages
 @cindex Lisp
-@cindex C
+XEmacs provides specialized support for editing source files for many
-Emacs has many commands designed to understand the syntax of programming
+different programming languages. For example it is possible to
-languages such as Lisp and C.  These commands can:
 @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;
 functions, in C).
 @item
 Show how parentheses balance (@pxref{Matching}).
 @item
 Insert, kill, or align comments (@pxref{Comments}).
 @item
-Follow the usual indentation conventions of the language
+Find functions and symbols in program by name (@pxref{Tags}).
-(@pxref{Grinding}).
 @end itemize
 The commands available for words, sentences, and paragraphs are useful in
 editing code even though their canonical application is for editing human
 language text.  Most symbols contain words (@pxref{Words}); sentences can
 * 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
 @node Program Modes, Lists, Programs, Programs
 @section Major Modes for Programming Languages
 @cindex Lisp mode
-@cindex C mode
+Emacs has several major modes (@pxref{Major Modes}) to support
-@cindex Scheme mode
+programming languages. These major modes will typically understand
-Emacs has several major modes for the programming languages Lisp, Scheme (a
+language syntax, provide automatic indentation features, syntax based
-variant of Lisp), C, Fortran, and Muddle.  Ideally, a major mode should be
+highlighting of text, and will often provide interfaces to the
-implemented for each programming language you might want to edit with
+programming environment to assist in compiling, executing and debugging
-Emacs; but often the mode for one language can serve for other
+programs.
-syntactically similar languages.  The language modes that exist are those
-that someone decided to take the trouble to write.
+A language mode exist when someone decides to take the trouble to
+write it. At this time many widely used programming languages are
-There are several variants of Lisp mode, which differ in the way they
+supported by XEmacs. Examples include Ada, Awk, C, C++, CORBA (IDL),
-interface to Lisp execution.  @xref{Lisp Modes}.
+Fortran, Java, Lisp, Modula 2, Objective-C, Perl, Pike, Prolog, Python,
+Ruby, Scheme, Simula, SQL, Tcl, Unix Shell scripts, and VHDL. Some of
-Each of the programming language modes defines the @key{TAB} key to run
+these language have seperate manuals, and some times more than one mode
-an indentation function that knows the indentation conventions of that
+may be available for a language.  For example, there are several
-language and updates the current line's indentation accordingly.  For
+variants of Lisp mode, which differ in the way they interface to Lisp
-example, in C mode @key{TAB} is bound to @code{c-indent-line}.  @key{LFD}
+execution.  @xref{Lisp Modes}.
-is normally defined to do @key{RET} followed by @key{TAB}; thus it, too,
-indents in a mode-specific fashion.
+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
 In most programming languages, indentation is likely to vary from line to
 line.  So the major modes for those languages rebind @key{DEL} to treat a
 Programming language modes define paragraphs to be separated only by
 blank lines, so that the paragraph commands remain useful.  Auto Fill mode,
 if enabled in a programming language major mode, indents the new lines
 which it creates.
-@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
 @cindex Control-Meta
 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
 specified number of times; with a negative argument, it moves in the
 opposite direction.
-In languages such as C where the comment-terminator can be recognized,
-the sexp commands move across comments as if they were whitespace.  In
-Lisp and other languages where comments run until the end of a line, it
-is very difficult to ignore comments when parsing backwards; therefore,
-in such languages the sexp commands treat the text of comments as if it
-were code.
 @kindex C-M-k
 @findex kill-sexp
 Killing an sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
 @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.
 @menu
 * 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
 @subsection Basic Program Indentation Commands
 @findex indent-region
 Another way to specify a range to be re-indented is with point and
 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
 The indentation pattern for a Lisp expression can depend on the function
 called by the expression.  For each Lisp function, you can choose among
 indentation is computed by @kbd{C-M-q}; if the value is a number,
 @kbd{C-M-q} need not recalculate indentation for the following lines
 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
 @cindex matching parentheses
 @cindex parentheses
 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.
 @end smallexample
-@node Tags, Fortran, Change Log, Programs
+@node Tags, CC Mode, Change Log, Programs
 @section Tags Tables
 @cindex tags table
 A @dfn{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
 @findex tags-apropos
 @kbd{M-x tags-apropos} is like @code{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.
-@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
 Fortran mode provides special motion commands for Fortran statements and
 subprograms, and indentation commands that understand Fortran conventions

Mercurial > hg > xemacs-beta

comparison man/xemacs/programs.texi @ 2522:52dc9b940348