From: Chong Yidong Date: Tue, 6 Dec 2011 08:12:18 +0000 (+0800) Subject: More updates to Programs chapter of Emacs manual. X-Git-Tag: emacs-pretest-24.0.93~218 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=2a185919b41986949f592ea51e17a3ac6c9afa2b;p=emacs.git More updates to Programs chapter of Emacs manual. * doc/emacs/programs.texi (Man Page): Clarify how to use Man-switches. Don't bother documenting Man-fontify-manpage-flag. (Lisp Doc): Add xref to Name Help node. (Hideshow): Add cindex. Mention role of ellipses, and default value of hs-isearch-open. Don't bother documenting hs-special-modes-alist. (Symbol Completion): Add kindex for C-M-i. Don't recommend changing the window manager binding of M-TAB. --- diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 894a5901295..20a6e8e84d7 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,14 @@ +2011-12-06 Chong Yidong + + * programs.texi (Man Page): Clarify how to use Man-switches. + Don't bother documenting Man-fontify-manpage-flag. + (Lisp Doc): Add xref to Name Help node. + (Hideshow): Add cindex. Mention role of ellipses, and default + value of hs-isearch-open. Don't bother documenting + hs-special-modes-alist. + (Symbol Completion): Add kindex for C-M-i. Don't recommend + changing the window manager binding of M-TAB. + 2011-12-05 Chong Yidong * programs.texi (Comment Commands): Fix description of for M-; on diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index c88535a076b..8d441f342f0 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1109,7 +1109,7 @@ mode which @kbd{C-h S} does support. @node Man Page @subsection Man Page Lookup -@cindex manual page +@cindex man page On Unix, the main form of on-line documentation was the @dfn{manual page} or @dfn{man page}. In the GNU operating system, we aim to replace man pages with better-organized manuals that you can browse @@ -1118,71 +1118,51 @@ still useful to read manual pages. @findex manual-entry You can read the man page for an operating system command, library -function, or system call, with the @kbd{M-x man} command. It -runs the @code{man} program to format the man page; if the system -permits, it runs @code{man} asynchronously, so that you can keep on -editing while the page is being formatted. (On MS-DOS and MS-Windows -3, you cannot edit while Emacs waits for @code{man} to finish.) The -result goes in a buffer named @samp{*Man @var{topic}*}. These buffers -use a special major mode, Man mode, that facilitates scrolling and -jumping to other manual pages. For details, type @kbd{C-h m} while in -a man page buffer. +function, or system call, with the @kbd{M-x man} command. This +prompts for a topic, with completion (@pxref{Completion}), and runs +the @command{man} program to format the corresponding man page. If +the system permits, it runs @command{man} asynchronously, so that you +can keep on editing while the page is being formatted. The result +goes in a buffer named @samp{*Man @var{topic}*}. These buffers use a +special major mode, Man mode, that facilitates scrolling and jumping +to other manual pages. For details, type @kbd{C-h m} while in a Man +mode buffer. @cindex sections of manual pages Each man page belongs to one of ten or more @dfn{sections}, each -named by a digit or by a digit and a letter. Sometimes there are -multiple man pages with the same name in different sections. To read -a man page from a specific section, type -@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} -when @kbd{M-x manual-entry} prompts for the topic. For example, to -read the man page for the C library function @code{chmod} (as opposed -to a command of the same name), type @kbd{M-x manual-entry @key{RET} -chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in -section @samp{2}.) +named by a digit or by a digit and a letter. Sometimes there are man +pages with the same name in different sections. To read a man page +from a specific section, type @samp{@var{topic}(@var{section})} or +@samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts +for the topic. For example, the man page for the C library function +@code{chmod} is in section 2, but there is a shell command of the same +name, whose man page is in section 1; to view the former, type +@kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}. @vindex Man-switches - If you do not specify a section, the results depend on how the -@code{man} program works on your system. Some of them display only -the first man page they find. Others display all man pages that have -the specified name, so you can move between them with the @kbd{M-n} -and @kbd{M-p} keys@footnote{On some systems, the @code{man} program -accepts a @samp{-a} command-line option which tells it to display all -the man pages for the specified topic. If you want this behavior, you -can add this option to the value of the variable @code{Man-switches}.}. -The mode line shows how many manual pages are present in the Man buffer. - -@vindex Man-fontify-manpage-flag - By default, Emacs highlights the text in man pages. For a long man -page, highlighting can take substantial time. You can turn off -highlighting of man pages by setting the variable -@code{Man-fontify-manpage-flag} to @code{nil}. - -@findex Man-fontify-manpage - If you insert the text of a man page into an Emacs buffer in some -other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to -perform the same conversions that @kbd{M-x manual-entry} does. +@kindex M-n @r{(Man mode)} +@kindex M-p @r{(Man mode)} + If you do not specify a section, @kbd{M-x man} normally displays +only the first man page found. On some systems, the @code{man} +program accepts a @samp{-a} command-line option, which tells it to +display all the man pages for the specified topic. To make use of +this, change the value of the variable @code{Man-switches} to +@samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and +@kbd{M-p} to switch between man pages in different sections. The mode +line shows how many manual pages are available. @findex woman @cindex manual pages, on MS-DOS/MS-Windows An alternative way of reading manual pages is the @kbd{M-x woman} -command@footnote{The name of the command, @code{woman}, is an acronym -for ``w/o (without) man,'' since it doesn't use the @code{man} -program.}. Unlike @kbd{M-x man}, it does not run any external -programs to format and display the man pages; instead it does the job -in Emacs Lisp, so it works on systems such as MS-Windows, where the -@code{man} program (and other programs it uses) are not generally -available. - - @kbd{M-x woman} prompts for a name of a manual page, and provides -completion based on the list of manual pages that are installed on -your machine; the list of available manual pages is computed -automatically the first time you invoke @code{woman}. The word at -point in the current buffer is used to suggest the default for the -name of the manual page. - - With a numeric argument, @kbd{M-x woman} recomputes the list of the -manual pages used for completion. This is useful if you add or delete -manual pages. +command. Unlike @kbd{M-x man}, it does not run any external programs +to format and display the man pages; the formatting is done by Emacs, +so it works on systems such as MS-Windows where the @command{man} +program may be unavailable. It prompts for a man page, and displays +it in a buffer named @samp{*WoMan @var{section} @var{topic}}. + + @kbd{M-x woman} computes the completion list for manpages the first +time you invoke the command. With a numeric argument, it recomputes +this list; this is useful if you add or delete manual pages. If you type a name of a manual page and @kbd{M-x woman} finds that several manual pages by the same name exist in different sections, it @@ -1201,42 +1181,40 @@ the WoMan Info manual, which is distributed with Emacs. @node Lisp Doc @subsection Emacs Lisp Documentation Lookup - As you edit Lisp code to be run in Emacs, you can use the commands -@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} -(@code{describe-variable}) to view documentation of functions and -variables that you want to use. These commands use the minibuffer to -read the name of a function or variable to document, and display the -documentation in a window. Their default arguments are based on the -code in the neighborhood of point. For @kbd{C-h f}, the default is -the function called in the innermost list containing point. @kbd{C-h -v} uses the symbol name around or adjacent to point as its default. + When editing Emacs Lisp code, you can use the commands @kbd{C-h f} +(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) +to view the built-in documentation for the Lisp functions and +variables that you want to use. @xref{Name Help}. @cindex Eldoc mode @findex eldoc-mode - A more automatic but less powerful method is Eldoc mode. This minor -mode constantly displays in the echo area the argument list for the -function being called at point. (In other words, it finds the -function call that point is contained in, and displays the argument -list of that function.) If point is over a documented variable, it -shows the first line of the variable's docstring. Eldoc mode applies -in Emacs Lisp and Lisp Interaction modes, and perhaps a few others -that provide special support for looking up doc strings. Use the -command @kbd{M-x eldoc-mode} to enable or disable this feature. + Eldoc is a buffer-local minor mode that helps with looking up Lisp +documention. When it is enabled, the echo area displays some useful +information whenever there is a Lisp function or variable at point; +for a function, it shows the argument list, and for a variable it +shows the first line of the variable's documentation string. To +toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used +with the Emacs Lisp and Lisp Interaction major modes. @node Hideshow @section Hideshow minor mode +@cindex Hideshow mode +@cindex mode, Hideshow @findex hs-minor-mode - Hideshow minor mode provides selective display of portions of a -program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} -to enable or disable this mode, or add @code{hs-minor-mode} to the -mode hook for certain major modes in order to enable it automatically -for those modes. + Hideshow mode is a buffer-local minor mode that allows you to +selectively display portions of a program, which are referred to as +@dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode +(@pxref{Minor Modes}). + + When you use Hideshow mode to hide a block, the block disappears +from the screen, to be replaced by an ellipsis (three periods in a +row). Just what constitutes a block depends on the major mode. In C +mode and related modes, blocks are delimited by braces, while in Lisp +mode they are delimited by parentheses. Multi-line comments also +count as blocks. - Just what constitutes a block depends on the major mode. In C mode -or C++ mode, they are delimited by braces, while in Lisp mode and -similar modes they are delimited by parentheses. Multi-line comments -also count as blocks. + Hideshow mode provides the following commands: @findex hs-hide-all @findex hs-hide-block @@ -1260,11 +1238,11 @@ Show the current block (@code{hs-show-block}). @item C-c @@ C-c Either hide or show the current block (@code{hs-toggle-hiding}). @item S-Mouse-2 -Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). +Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}). @item C-c @@ C-M-h Hide all top-level blocks (@code{hs-hide-all}). @item C-c @@ C-M-s -Show everything in the buffer (@code{hs-show-all}). +Show all blocks in the buffer (@code{hs-show-all}). @item C-c @@ C-l Hide all blocks @var{n} levels below this block (@code{hs-hide-level}). @@ -1273,80 +1251,61 @@ Hide all blocks @var{n} levels below this block @vindex hs-hide-comments-when-hiding-all @vindex hs-isearch-open @vindex hs-special-modes-alist - These variables exist for customizing Hideshow mode. + These variables can be used to customize Hideshow mode: @table @code @item hs-hide-comments-when-hiding-all -Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. +If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides +comments too. @item hs-isearch-open -Specifies what kind of hidden blocks incremental search should make -visible. The value should be one of these four symbols: - -@table @code -@item code -Open only code blocks. -@item comment -Open only comments. -@item t -Open both code blocks and comments. -@item nil -Open neither code blocks nor comments. -@end table - -@item hs-special-modes-alist -A list of elements, each specifying how to initialize Hideshow -variables for one major mode. See the variable's documentation string -for more information. +This variable specifies the conditions under which incremental search +should unhide a hidden block when matching text occurs within the +block. Its value should be either @code{code} (unhide only code +blocks), @code{comment} (unhide only comments), @code{t} (unhide both +code blocks and comments), or @code{nil} (unhide neither code blocks +nor comments). The default value is @code{code}. @end table @node Symbol Completion @section Completion for Symbol Names @cindex completion (symbol names) - In Emacs, completion is something you normally do in the minibuffer -(@pxref{Completion}). But one kind of completion is available in all -buffers: completion for symbol names. + Completion is normally done in the minibuffer (@pxref{Completion}), +but you can also complete symbol names in ordinary Emacs buffers. @kindex M-TAB - The character @kbd{M-@key{TAB}} runs a command to complete the -partial symbol before point against the set of meaningful symbol -names. This command inserts at point any additional characters that -it can determine from the partial name. - - If your window manager defines @kbd{M-@key{TAB}} to switch windows, -you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. -However, most window managers let you customize these shortcuts, so -you can change any that interfere with the way you use Emacs. - - If the partial name in the buffer has multiple possible completions -that differ in the very next character, so that it is impossible to -complete even one more character, @kbd{M-@key{TAB}} displays a list of -all possible completions in another window. +@kindex C-M-i + In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}} +to complete the partial symbol before point. On graphical displays, +the @kbd{M-@key{TAB}} key is usually reserved by the window manager +for switching graphical windows, so you should type @kbd{C-M-i} or +@kbd{@key{ESC} @key{TAB}} instead. @cindex tags-based completion @cindex Info index completion @findex complete-symbol - In most programming language major modes, @kbd{M-@key{TAB}} runs the -command @code{complete-symbol}, which provides two kinds of completion. -Normally it does completion based on a tags table (@pxref{Tags}); with a -numeric argument (regardless of the value), it does completion based on -the names listed in the Info file indexes for your language. Thus, to -complete the name of a symbol defined in your own program, use -@kbd{M-@key{TAB}} with no argument; to complete the name of a standard -library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based -completion works only if there is an Info file for the standard library -functions of your language, and only if it is installed at your site. + In-buffer symbol completion generates its completion list in a +number of different ways. In most programming language modes, +completion is normally done using a tags table (@pxref{Tags}). +However, if you supply @kbd{C-M-i} or @kbd{M-@key{TAB}} with a numeric +argument, it completes using the Info file indexes for the current +language (e.g.@: the C Library Manual). Of course, Info-based +completion works only if there is an Info file for the standard +library functions of your language, and only if it is installed at +your site. @cindex Lisp symbol completion @cindex completion (Lisp symbols) -@findex lisp-complete-symbol - In Emacs-Lisp mode, the name space for completion normally consists of -nontrivial symbols present in Emacs---those that have function -definitions, values or properties. However, if there is an -open-parenthesis immediately before the beginning of the partial symbol, -only symbols with function definitions are considered as completions. -The command which implements this is @code{lisp-complete-symbol}. + In Emacs Lisp mode, completion is performed using the function, +variable, and property names defined in the current Emacs session. If +there is an open parenthesis immediately before the beginning of the +partial symbol, only symbols with function definitions are considered. + + In all other respects, in-buffer symbol completion behaves like +minibuffer completion. For instance, if Emacs cannot complete to a +unique symbol, it displays a list of completion alternatives in +another window. @xref{Completion}. In Text mode and related modes, @kbd{M-@key{TAB}} completes words based on the spell-checker's dictionary. @xref{Spelling}. @@ -1354,20 +1313,20 @@ based on the spell-checker's dictionary. @xref{Spelling}. @node Glasses @section Glasses minor mode @cindex Glasses mode -@cindex identifiers, making long ones readable -@cindex StudlyCaps, making them readable -@findex glasses-mode - - Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} -readable by altering the way they display. It knows two different -ways to do this: by displaying underscores between a lower-case letter -and the following capital letter, and by emboldening the capital -letters. It does not alter the buffer text, only the way they -display, so you can use it even on read-only buffers. You can use the -command @kbd{M-x glasses-mode} to enable or disable the mode in the -current buffer; you can also add @code{glasses-mode} to the mode hook -of the programming language major modes in which you normally want -to use Glasses mode. +@cindex camel case +@findex mode, Glasses + + Glasses mode is a buffer-local minor mode that makes it easier to +read mixed-case (or ``CamelCase'') symbols like +@samp{unReadableSymbol}, by altering how they are displayed. By +default, it displays extra underscores between each lower-case letter +and the following capital letter. This does not alter the buffer +text, only how it is displayed. + + To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor +Modes}). When Glasses mode is enabled, the minor mode indicator +@samp{o^o} appears in the mode line. For more information about +Glasses mode, type @kbd{C-h P glasses @key{RET}}. @node Semantic @section Semantic @@ -1383,8 +1342,8 @@ see @ref{Top, Semantic,, semantic, Semantic}. see the Semantic Info manual, which is distributed with Emacs. @end iftex - Most of the ``language aware'' features in Emacs, such as font lock -(@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular + Most of the ``language aware'' features in Emacs, such as Font Lock +mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular expressions and syntax tables.} that usually give good results but are never completely exact. In contrast, the parsers used by Semantic have an exact understanding of programming language syntax. This @@ -1438,27 +1397,25 @@ is idle. @node Misc for Programs @section Other Features Useful for Editing Programs - A number of Emacs commands that aren't designed specifically for -editing programs are useful for that nonetheless. + Some Emacs commands that aren't designed specifically for editing +programs are useful for that nonetheless. The Emacs commands that operate on words, sentences and paragraphs are useful for editing code. Most symbols names contain words -(@pxref{Words}); sentences can be found in strings and comments -(@pxref{Sentences}). Paragraphs in the strict sense can be found in -program code (in long comments), but the paragraph commands are useful -in other places too, because programming language major modes define -paragraphs to begin and end at blank lines (@pxref{Paragraphs}). -Judicious use of blank lines to make the program clearer will also -provide useful chunks of text for the paragraph commands to work on. -Auto Fill mode, if enabled in a programming language major mode, -indents the new lines which it creates. - - The selective display feature is useful for looking at the overall -structure of a function (@pxref{Selective Display}). This feature -hides the lines that are indented more than a specified amount. -Programming modes often support Outline minor mode (@pxref{Outline -Mode}). The Foldout package provides folding-editor features -(@pxref{Foldout}). +(@pxref{Words}), while sentences can be found in strings and comments +(@pxref{Sentences}). As for paragraphs, they are defined in most +programming language modes to begin and end at blank lines +(@pxref{Paragraphs}). Therefore, judicious use of blank lines to make +the program clearer will also provide useful chunks of text for the +paragraph commands to work on. Auto Fill mode, if enabled in a +programming language major mode, indents the new lines which it +creates. + + Apart from Hideshow mode (@pxref{Hideshow}), another way to +selectively display parts of a program is to use the selective display +feature (@pxref{Selective Display}). Programming modes often also +support Outline minor mode (@pxref{Outline Mode}), which can be used +with the Foldout package (@pxref{Foldout}). @ifinfo The ``automatic typing'' features may be useful for writing programs.