+File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
+
+Pages
+=====
+
+ Files are often thought of as divided into "pages" by the "formfeed"
+character (ASCII Control-L, octal code 014). For example, if a file is
+printed on a line printer, each "page" of the file starts on a new page
+of paper. Emacs treats a page-separator character just like any other
+character. It can be inserted with `C-q C-l' or deleted with <DEL>.
+You are free to paginate your file or not. However, since pages are
+often meaningful divisions of the file, commands are provided to move
+over them and operate on them.
+
+`C-x ['
+ Move point to previous page boundary (`backward-page').
+
+`C-x ]'
+ Move point to next page boundary (`forward-page').
+
+`C-x C-p'
+ Put point and mark around this page (or another page)
+ (`mark-page').
+
+`C-x l'
+ Count the lines in this page (`count-lines-page').
+
+ The `C-x [' (`backward-page') command moves point to immediately
+after the previous page delimiter. If point is already right after a
+page delimiter, the command skips that one and stops at the previous
+one. A numeric argument serves as a repeat count. The `C-x ]'
+(`forward-page') command moves forward past the next page delimiter.
+
+ The `C-x C-p' command (`mark-page') puts point at the beginning of
+the current page and the mark at the end. The page delimiter at the end
+is included (the mark follows it). The page delimiter at the front is
+excluded (point follows it). You can follow this command by `C-w' to
+kill a page you want to move elsewhere. If you insert the page after a
+page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
+page will be properly delimited before and after once again.
+
+ A numeric argument to `C-x C-p' is used to specify which page to go
+to, relative to the current one. Zero means the current page. One
+means the next page, and -1 means the previous one.
+
+ The `C-x l' command (`count-lines-page') can help you decide where
+to break a page in two. It prints the total number of lines in the
+current page in the echo area, then divides the lines into those
+preceding the current line and those following it, for example
+
+ Page has 96 (72+25) lines
+
+Notice that the sum is off by one; this is correct if point is not at
+the beginning of a line.
+
+ The variable `page-delimiter' should have as its value a regexp that
+matches the beginning of a line that separates pages. This defines
+where pages begin. The normal value of this variable is `"^\f"', which
+matches a formfeed character at the beginning of a line.
+
+\1f
+File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
+
+Filling Text
+============
+
+ If you use Auto Fill mode, Emacs "fills" text (breaks it up into
+lines that fit in a specified width) as you insert it. When you alter
+existing text it is often no longer be properly filled afterwards and
+you can use explicit commands for filling.
+
+* Menu:
+
+* Auto Fill:: Auto Fill mode breaks long lines automatically.
+* Fill Commands:: Commands to refill paragraphs and center lines.
+* Fill Prefix:: Filling when every line is indented or in a comment, etc.
+
+\1f
+File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
+
+Auto Fill Mode
+--------------
+
+ "Auto Fill" mode is a minor mode in which lines are broken
+automatically when they become too wide. Breaking happens only when
+you type a <SPC> or <RET>.
+
+`M-x auto-fill-mode'
+ Enable or disable Auto Fill mode.
+
+`<SPC>'
+`<RET>'
+ In Auto Fill mode, break lines when appropriate.
+
+ `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
+if it was on. With a positive numeric argument the command always turns
+Auto Fill mode on, and with a negative argument it always turns it off.
+The presence of the word `Fill' in the mode line, inside the
+parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
+is a minor mode; you can turn it on or off for each buffer individually.
+*Note Minor Modes::.
+
+ In Auto Fill mode, lines are broken automatically at spaces when
+they get longer than desired. Line breaking and rearrangement takes
+place only when you type <SPC> or <RET>. To insert a space or newline
+without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
+(recall that a newline is really a linefeed). `C-o' inserts a newline
+without line breaking.
+
+ Auto Fill mode works well with Lisp mode: when it makes a new line in
+Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
+comment gets too long, the text of the comment is split into two
+comment lines. Optionally, new comment delimiters are inserted at the
+end of the first line and the beginning of the second, so that each line
+is a separate comment. The variable `comment-multi-line' controls the
+choice (*note Comments::).
+
+ Auto Fill mode does not refill entire paragraphs. It can break
+lines but cannot merge lines. Editing in the middle of a paragraph can
+result in a paragraph that is not correctly filled. The easiest way to
+make the paragraph properly filled again is using an explicit fill
+commands.
+
+ Many users like Auto Fill mode and want to use it in all text files.
+The section on init files explains how you can arrange this permanently
+for yourself. *Note Init File::.
+
+\1f
+File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
+
+Explicit Fill Commands
+----------------------
+
+`M-q'
+ Fill current paragraph (`fill-paragraph').
+
+`M-g'
+ Fill each paragraph in the region (`fill-region').
+
+`C-x f'
+ Set the fill column (`set-fill-column').
+
+`M-x fill-region-as-paragraph'
+ Fill the region, considering it as one paragraph.
+
+`M-s'
+ Center a line.
+
+ To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
+It causes the paragraph containing point, or the one after point if
+point is between paragraphs, to be refilled. All line breaks are
+removed, and new ones are inserted where necessary. `M-q' can be
+undone with `C-_'. *Note Undo::.
+
+ To refill many paragraphs, use `M-g' (`fill-region'), which divides
+the region into paragraphs and fills each of them.
+
+ `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
+paragraph boundaries (*note Paragraphs::). For more control, you can
+use `M-x fill-region-as-paragraph', which refills everything between
+point and mark. This command recognizes only blank lines as paragraph
+separators.
+
+ A numeric argument to `M-g' or `M-q' causes it to "justify" the text
+as well as filling it. Extra spaces are inserted to make the right
+margin line up exactly at the fill column. To remove the extra spaces,
+use `M-q' or `M-g' with no argument.
+
+ The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
+match lines that should not be auto-filled.
+
+ The command `Meta-s' (`center-line') centers the current line within
+the current fill column. With an argument, it centers several lines
+individually and moves past them.
+
+ The maximum line width for filling is in the variable `fill-column'.
+Altering the value of `fill-column' makes it local to the current
+buffer; until then, the default value--initially 70--is in effect.
+*Note Locals::.
+
+ The easiest way to set `fill-column' is to use the command `C-x f'
+(`set-fill-column'). With no argument, it sets `fill-column' to the
+current horizontal position of point. With a numeric argument, it uses
+that number as the new fill column.
+
+\1f
+File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
+
+The Fill Prefix
+---------------
+
+ To fill a paragraph in which each line starts with a special marker
+(which might be a few spaces, giving an indented paragraph), use the
+"fill prefix" feature. The fill prefix is a string which is not
+included in filling. Emacs expects every line to start with a fill
+prefix.
+
+`C-x .'
+ Set the fill prefix (`set-fill-prefix').
+
+`M-q'
+ Fill a paragraph using current fill prefix (`fill-paragraph').
+
+`M-x fill-individual-paragraphs'
+ Fill the region, considering each change of indentation as
+ starting a new paragraph.
+
+ To specify a fill prefix, move to a line that starts with the desired
+prefix, put point at the end of the prefix, and give the command
+`C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
+off the fill prefix, specify an empty prefix: type `C-x .' with point
+at the beginning of a line.
+
+ When a fill prefix is in effect, the fill commands remove the fill
+prefix from each line before filling and insert it on each line after
+filling. Auto Fill mode also inserts the fill prefix inserted on new
+lines it creates. Lines that do not start with the fill prefix are
+considered to start paragraphs, both in `M-q' and the paragraph
+commands; this is just right if you are using paragraphs with hanging
+indentation (every line indented except the first one). Lines which are
+blank or indented once the prefix is removed also separate or start
+paragraphs; this is what you want if you are writing multi-paragraph
+comments with a comment delimiter on each line.
+
+ The fill prefix is stored in the variable `fill-prefix'. Its value
+is a string, or `nil' when there is no fill prefix. This is a
+per-buffer variable; altering the variable affects only the current
+buffer, but there is a default value which you can change as well.
+*Note Locals::.
+
+ Another way to use fill prefixes is through `M-x
+fill-individual-paragraphs'. This function divides the region into
+groups of consecutive lines with the same amount and kind of
+indentation and fills each group as a paragraph, using its indentation
+as a fill prefix.
+
+\1f
+File: xemacs.info, Node: Case, Prev: Filling, Up: Text
+
+Case Conversion Commands
+========================
+
+ Emacs has commands for converting either a single word or any
+arbitrary range of text to upper case or to lower case.
+
+`M-l'
+ Convert following word to lower case (`downcase-word').
+
+`M-u'
+ Convert following word to upper case (`upcase-word').
+
+`M-c'
+ Capitalize the following word (`capitalize-word').
+
+`C-x C-l'
+ Convert region to lower case (`downcase-region').
+
+`C-x C-u'
+ Convert region to upper case (`upcase-region').
+
+ The word conversion commands are used most frequently. `Meta-l'
+(`downcase-word') converts the word after point to lower case, moving
+past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
+(`upcase-word') converts to all capitals instead, while `Meta-c'
+(`capitalize-word') puts the first letter of the word into upper case
+and the rest into lower case. The word conversion commands convert
+several words at once if given an argument. They are especially
+convenient for converting a large amount of text from all upper case to
+mixed case: you can move through the text using `M-l', `M-u', or `M-c'
+on each word as appropriate, occasionally using `M-f' instead to skip a
+word.
+
+ When given a negative argument, the word case conversion commands
+apply to the appropriate number of words before point, but do not move
+point. This is convenient when you have just typed a word in the wrong
+case: you can give the case conversion command and continue typing.
+
+ If a word case conversion command is given in the middle of a word,
+it applies only to the part of the word which follows point. This is
+just like what `Meta-d' (`kill-word') does. With a negative argument,
+case conversion applies only to the part of the word before point.
+
+ The other case conversion commands are `C-x C-u' (`upcase-region')
+and `C-x C-l' (`downcase-region'), which convert everything between
+point and mark to the specified case. Point and mark do not move.
+
+\1f
+File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
+
+Editing Programs
+****************
+
+ Emacs has many commands designed to understand the syntax of
+programming languages such as Lisp and C. These commands can:
+
+ * Move over or kill balanced expressions or "sexps" (*note Lists::).
+
+ * Move over or mark top-level balanced expressions ("defuns", in
+ Lisp; functions, in C).
+
+ * Show how parentheses balance (*note Matching::).
+
+ * Insert, kill, or align comments (*note Comments::).
+
+ * Follow the usual indentation conventions of the language (*note
+ Grinding::).
+
+ The commands available for words, sentences, and paragraphs are
+useful in editing code even though their canonical application is for
+editing human language text. Most symbols contain words (*note
+Words::); sentences can be found in strings and comments (*note
+Sentences::). Paragraphs per se are not present in code, but the
+paragraph commands are useful anyway, because Lisp mode and C mode
+define paragraphs to begin and end at blank lines (*note Paragraphs::).
+Judicious use of blank lines to make the program clearer also provides
+interesting chunks of text for the paragraph commands to work on.
+
+ The selective display feature is useful for looking at the overall
+structure of a function (*note Selective Display::). This feature
+causes only the lines that are indented less than a specified amount to
+appear on the screen.
+
+* Menu:
+
+* Program Modes:: Major modes for editing programs.
+* Lists:: Expressions with balanced parentheses.
+ There are editing commands to operate on them.
+* Defuns:: Each program is made up of separate functions.
+ There are editing commands to operate on them.
+* Grinding:: Adjusting indentation to show the nesting.
+* Matching:: Insertion of a close-delimiter flashes matching open.
+* Comments:: Inserting, filling and aligning comments.
+* Balanced Editing:: Inserting two matching parentheses at once, etc.
+* Lisp Completion:: Completion on symbol names in Lisp code.
+* Documentation:: Getting documentation of functions you plan to call.
+* Change Log:: Maintaining a change history for your program.
+* Tags:: Go direct to any function in your program in one
+ command. Tags remembers which file it is in.
+* Fortran:: Fortran mode and its special features.
+* Asm Mode:: Asm mode and its special features.
+
+\1f
+File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
+
+Major Modes for Programming Languages
+=====================================
+
+ Emacs has several major modes for the programming languages Lisp,
+Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
+mode should be implemented for each programming language you might want
+to edit with Emacs; but often the mode for one language can serve for
+other syntactically similar languages. The language modes that exist
+are those that someone decided to take the trouble to write.
+
+ There are several variants of Lisp mode, which differ in the way they
+interface to Lisp execution. *Note Lisp Modes::.
+
+ Each of the programming language modes defines the <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 <TAB> is bound to `c-indent-line'. <LFD> is
+normally defined to do <RET> followed by <TAB>; thus it, too, indents
+in a mode-specific fashion.
+
+ In most programming languages, indentation is likely to vary from
+line to line. So the major modes for those languages rebind <DEL> to
+treat a tab as if it were the equivalent number of spaces (using the
+command `backward-delete-char-untabify'). This makes it possible to
+rub out indentation one column at a time without worrying whether it is
+made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
+tab character before point.
+
+ Programming language modes define paragraphs to be separated only by
+blank lines, so that the paragraph commands remain useful. Auto Fill
+mode, if enabled in a programming language major mode, indents the new
+lines which it creates.
+
+ Turning on a major mode calls a user-supplied function called the
+"mode hook", which is the value of a Lisp variable. For example,
+turning on C mode calls the value of the variable `c-mode-hook' if that
+value exists and is non-`nil'. Mode hook variables for other
+programming language modes include `lisp-mode-hook',
+`emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
+`scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
+receives no arguments.
+
+\1f
+File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
+
+Lists and Sexps
+===============
+
+ By convention, Emacs keys for dealing with balanced expressions are
+usually `Control-Meta-' characters. They tend to be analogous in
+function to their `Control-' and `Meta-' equivalents. These commands
+are usually thought of as pertaining to expressions in programming
+languages, but can be useful with any language in which some sort of
+parentheses exist (including English).
+
+ The commands fall into two classes. Some commands deal only with
+"lists" (parenthetical groupings). They see nothing except
+parentheses, brackets, braces (depending on what must balance in the
+language you are working with), and escape characters that might be used
+to quote those.
+
+ The other commands deal with expressions or "sexps". The word `sexp'
+is derived from "s-expression", the term for a symbolic expression in
+Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
+refers to an expression in the language your program is written in.
+Each programming language has its own major mode, which customizes the
+syntax tables so that expressions in that language count as sexps.
+
+ Sexps typically include symbols, numbers, and string constants, as
+well as anything contained in parentheses, brackets, or braces.
+
+ In languages that use prefix and infix operators, such as C, it is
+not possible for all expressions to be sexps. For example, C mode does
+not recognize `foo + bar' as an sexp, even though it is a C expression;
+it recognizes `foo' as one sexp and `bar' as another, with the `+' as
+punctuation between them. This is a fundamental ambiguity: both `foo +
+bar' and `foo' are legitimate choices for the sexp to move over if
+point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
+
+ Some languages have obscure forms of syntax for expressions that
+nobody has bothered to make Emacs understand properly.
+
+`C-M-f'
+ Move forward over an sexp (`forward-sexp').
+
+`C-M-b'
+ Move backward over an sexp (`backward-sexp').
+
+`C-M-k'
+ Kill sexp forward (`kill-sexp').
+
+`C-M-u'
+ Move up and backward in list structure (`backward-up-list').
+
+`C-M-d'
+ Move down and forward in list structure (`down-list').
+
+`C-M-n'
+ Move forward over a list (`forward-list').
+
+`C-M-p'
+ Move backward over a list (`backward-list').
+
+`C-M-t'
+ Transpose expressions (`transpose-sexps').
+
+`C-M-@'
+ Put mark after following expression (`mark-sexp').
+
+ To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
+first significant character after point is an opening delimiter (`(' in
+Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
+delimiter. If the character begins a symbol, string, or number,
+`C-M-f' moves over that. If the character after point is a closing
+delimiter, `C-M-f' just moves past it. (This last is not really moving
+across an sexp; it is an exception which is included in the definition
+of `C-M-f' because it is as useful a behavior as anyone can think of
+for that situation.)
+
+ The command `C-M-b' (`backward-sexp') moves backward over a sexp.
+The detailed rules are like those above for `C-M-f', but with
+directions reversed. If there are any prefix characters (single quote,
+back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
+over them as well.
+
+ `C-M-f' or `C-M-b' with an argument repeats that operation the
+specified number of times; with a negative argument, it moves in the
+opposite direction.
+
+ In languages such as C where the comment-terminator can be
+recognized, the sexp commands move across comments as if they were
+whitespace. In Lisp and other languages where comments run until the
+end of a line, it is very difficult to ignore comments when parsing
+backwards; therefore, in such languages the sexp commands treat the
+text of comments as if it were code.
+
+ Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
+`C-M-k' kills the characters that `C-M-f' would move over.
+
+ The "list commands", `C-M-n' (`forward-list') and `C-M-p'
+(`backward-list'), move over lists like the sexp commands but skip over
+any number of other kinds of sexps (symbols, strings, etc). In some
+situations, these commands are useful because they usually ignore
+comments, since the comments usually do not contain any lists.
+
+ `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
+is possible. To move up one (or N) levels, use `C-M-u'
+(`backward-up-list'). `C-M-u' moves backward up past one unmatched
+opening delimiter. A positive argument serves as a repeat count; a
+negative argument reverses direction of motion and also requests
+repetition, so it moves forward and up one or more levels.
+
+ To move down in list structure, use `C-M-d' (`down-list'). In Lisp
+mode, where `(' is the only opening delimiter, this is nearly the same
+as searching for a `('. An argument specifies the number of levels of
+parentheses to go down.
+
+ `C-M-t' (`transpose-sexps') drags the previous sexp across the next
+one. An argument serves as a repeat count, and a negative argument
+drags backwards (thus canceling out the effect of `C-M-t' with a
+positive argument). An argument of zero, rather than doing nothing,
+transposes the sexps ending after point and the mark.
+
+ To make the region be the next sexp in the buffer, use `C-M-@'
+(`mark-sexp') which sets the mark at the same place that `C-M-f' would
+move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
+negative argument is useful for putting the mark at the beginning of
+the previous sexp.
+
+ The list and sexp commands' understanding of syntax is completely
+controlled by the syntax table. Any character can, for example, be
+declared to be an opening delimiter and act like an open parenthesis.
+*Note Syntax::.
+
+\1f
+File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
+
+Defuns
+======
+
+ In Emacs, a parenthetical grouping at the top level in the buffer is
+called a "defun". The name derives from the fact that most top-level
+lists in Lisp are instances of the special form `defun', but Emacs
+calls any top-level parenthetical grouping counts a defun regardless of
+its contents or the programming language. For example, in C, the body
+of a function definition is a defun.
+
+`C-M-a'
+ Move to beginning of current or preceding defun
+ (`beginning-of-defun').
+
+`C-M-e'
+ Move to end of current or following defun (`end-of-defun').
+
+`C-M-h'
+ Put region around whole current or following defun (`mark-defun').
+
+ The commands to move to the beginning and end of the current defun
+are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
+
+ To operate on the current defun, use `C-M-h' (`mark-defun') which
+puts point at the beginning and the mark at the end of the current or
+next defun. This is the easiest way to prepare for moving the defun to
+a different place. In C mode, `C-M-h' runs the function
+`mark-c-function', which is almost the same as `mark-defun', but which
+backs up over the argument declarations, function name, and returned
+data type so that the entire C function is inside the region.
+
+ To compile and evaluate the current defun, use `M-x compile-defun'.
+This function prints the results in the minibuffer. If you include an
+argument, it inserts the value in the current buffer after the defun.
+
+ Emacs assumes that any open-parenthesis found in the leftmost column
+is the start of a defun. Therefore, never put an open-parenthesis at
+the left margin in a Lisp file unless it is the start of a top level
+list. Never put an open-brace or other opening delimiter at the
+beginning of a line of C code unless it starts the body of a function.
+The most likely problem case is when you want an opening delimiter at
+the start of a line inside a string. To avoid trouble, put an escape
+character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
+before the opening delimiter. It will not affect the contents of the
+string.
+
+ The original Emacs found defuns by moving upward a level of
+parentheses until there were no more levels to go up. This required
+scanning back to the beginning of the buffer for every function. To
+speed this up, Emacs was changed to assume that any `(' (or other
+character assigned the syntactic class of opening-delimiter) at the
+left margin is the start of a defun. This heuristic is nearly always
+right; however, it mandates the convention described above.
+
+\1f
+File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
+
+Indentation for Programs
+========================
+
+ The best way to keep a program properly indented ("ground") is to
+use Emacs to re-indent it as you change the program. Emacs has commands
+to indent properly either a single line, a specified number of lines, or
+all of the lines inside a single parenthetical grouping.
+
+* Menu:
+
+* 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.
+
+\1f