diff options
| author | Juri Linkov | 2005-10-11 05:47:11 +0000 |
|---|---|---|
| committer | Juri Linkov | 2005-10-11 05:47:11 +0000 |
| commit | 655e5fd57a5f8a7b31c06d06ce36decd8fef7535 (patch) | |
| tree | cdf2e43dff65eca2b835e1897d3f72fed3a1a70b | |
| parent | a120694fcaf58e938553439c7433505039b57ac5 (diff) | |
| download | emacs-655e5fd57a5f8a7b31c06d06ce36decd8fef7535.tar.gz emacs-655e5fd57a5f8a7b31c06d06ce36decd8fef7535.zip | |
Rearrange nodes.
(Top): Update menu. Change ref `Info for Experts' to
`Advanced Info Commands'.
(Getting Started): Fix description of manual's parts.
(Help-Int): Change xref `Info Search' to `Search Index', and
`Expert Info' to `Advanced'.
(Advanced): Move node one level up.
(Search Text, Search Index): New nodes split out from `Info Search'.
(Go to node, Choose menu subtopic, Create Info buffer): New nodes
split out from `Advanced'.
(Advanced, Emacs Info Variables): De-document editing an Info file
in Info.
(Emacs Info Variables): Move node from `Expert Info' to `Advanced'.
(Creating an Info File): Delete node and move its text to
`Expert Info'.
| -rw-r--r-- | man/info.texi | 480 |
1 files changed, 233 insertions, 247 deletions
diff --git a/man/info.texi b/man/info.texi index 95e736ab246..532478ca521 100644 --- a/man/info.texi +++ b/man/info.texi | |||
| @@ -72,28 +72,28 @@ If you are new to the Info reader and want to learn how to use it, | |||
| 72 | type the command @kbd{h} now. It brings you to a programmed | 72 | type the command @kbd{h} now. It brings you to a programmed |
| 73 | instruction sequence. | 73 | instruction sequence. |
| 74 | 74 | ||
| 75 | To read about expert-level Info commands, type @kbd{n} twice. This | 75 | To read about advanced Info commands, type @kbd{n} twice. This |
| 76 | brings you to @cite{Info for Experts}, skipping over the `Getting | 76 | brings you to @cite{Advanced Info Commands}, skipping over the `Getting |
| 77 | Started' chapter. | 77 | Started' chapter. |
| 78 | @end ifinfo | 78 | @end ifinfo |
| 79 | @end ifnottex | 79 | @end ifnottex |
| 80 | 80 | ||
| 81 | @menu | 81 | @menu |
| 82 | * Getting Started:: Getting started using an Info reader. | 82 | * Getting Started:: Getting started using an Info reader. |
| 83 | * Advanced:: Advanced Info commands. | ||
| 83 | * Expert Info:: Info commands for experts. | 84 | * Expert Info:: Info commands for experts. |
| 84 | * Creating an Info File:: How to make your own Info file. | ||
| 85 | * Index:: An index of topics, commands, and variables. | 85 | * Index:: An index of topics, commands, and variables. |
| 86 | @end menu | 86 | @end menu |
| 87 | 87 | ||
| 88 | @node Getting Started, Expert Info, Top, Top | 88 | @node Getting Started, Advanced, Top, Top |
| 89 | @comment node-name, next, previous, up | 89 | @comment node-name, next, previous, up |
| 90 | @chapter Getting Started | 90 | @chapter Getting Started |
| 91 | 91 | ||
| 92 | This first part of this Info manual describes how to get around inside | 92 | This first part of this Info manual describes how to get around inside |
| 93 | of Info. The second part of the manual describes various advanced | 93 | of Info. The second part of the manual describes various advanced |
| 94 | Info commands, and how to write an Info as distinct from a Texinfo | 94 | Info commands. The third part briefly explains how to generate Info |
| 95 | file. The third part briefly explains how to generate Info files from | 95 | files from Texinfo files, and describes how to write an Info as |
| 96 | Texinfo files. | 96 | distinct from a Texinfo file. |
| 97 | 97 | ||
| 98 | @ifnotinfo | 98 | @ifnotinfo |
| 99 | This manual is primarily designed for browsing with an Info reader | 99 | This manual is primarily designed for browsing with an Info reader |
| @@ -847,7 +847,7 @@ describes the topic you want. | |||
| 847 | There is also a short-cut Info command, @kbd{i}, which does all of | 847 | There is also a short-cut Info command, @kbd{i}, which does all of |
| 848 | that for you. It searches the index for a given topic (a string) and | 848 | that for you. It searches the index for a given topic (a string) and |
| 849 | goes to the node which is listed in the index for that topic. | 849 | goes to the node which is listed in the index for that topic. |
| 850 | @xref{Info Search}, for a full explanation. | 850 | @xref{Search Index}, for a full explanation. |
| 851 | 851 | ||
| 852 | @kindex l @r{(Info mode)} | 852 | @kindex l @r{(Info mode)} |
| 853 | @findex Info-history-back | 853 | @findex Info-history-back |
| @@ -905,45 +905,129 @@ is @code{Info-top-node}. | |||
| 905 | >> Now type @kbd{n} to see the last node of the course. | 905 | >> Now type @kbd{n} to see the last node of the course. |
| 906 | @end format | 906 | @end format |
| 907 | 907 | ||
| 908 | @xref{Expert Info}, for more advanced Info features. | 908 | @xref{Advanced}, for more advanced Info features. |
| 909 | 909 | ||
| 910 | @c If a menu appears at the end of this node, remove it. | 910 | @c If a menu appears at the end of this node, remove it. |
| 911 | @c It is an accident of the menu updating command. | 911 | @c It is an accident of the menu updating command. |
| 912 | 912 | ||
| 913 | @node Expert Info | 913 | @node Advanced |
| 914 | @chapter Info for Experts | 914 | @chapter Advanced Info Commands |
| 915 | 915 | ||
| 916 | This chapter describes various Info commands for experts. (If you | 916 | This chapter describes various advanced Info commands. (If you |
| 917 | are using a stand-alone Info reader, there are additional commands | 917 | are using a stand-alone Info reader, there are additional commands |
| 918 | specific to it, which are documented in several chapters of @ref{Top,, | 918 | specific to it, which are documented in several chapters of @ref{Top,, |
| 919 | GNU Info, info-stnd, GNU Info}.) | 919 | GNU Info, info-stnd, GNU Info}.) |
| 920 | 920 | ||
| 921 | This chapter also explains how to write an Info as distinct from a | ||
| 922 | Texinfo file. (However, in most cases, writing a Texinfo file is | ||
| 923 | better, since you can use it to make a printed manual or produce other | ||
| 924 | formats, such as HTML and DocBook, as well as for generating Info | ||
| 925 | files.) @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU | ||
| 926 | Documentation Format}. | ||
| 927 | |||
| 928 | @menu | 921 | @menu |
| 929 | * Advanced:: Advanced Info commands: g, e, and 1 - 9. | 922 | * Search Text:: How to search Info documents. |
| 930 | * Info Search:: How to search Info documents for specific subjects. | 923 | * Search Index:: How to search the indices for specific subjects. |
| 931 | * Add:: Describes how to add new nodes to the hierarchy. | 924 | * Go to node:: How to go to a node by name. |
| 932 | Also tells what nodes look like. | 925 | * Choose menu subtopic:: How to choose a menu subtopic by its number. |
| 933 | * Menus:: How to add to or create menus in Info nodes. | 926 | * Create Info buffer:: How to create a new Info buffer in Emacs. |
| 934 | * Cross-refs:: How to add cross-references to Info nodes. | ||
| 935 | * Tags:: How to make tags tables for Info files. | ||
| 936 | * Checking:: Checking an Info File. | ||
| 937 | * Emacs Info Variables:: Variables modifying the behavior of Emacs Info. | 927 | * Emacs Info Variables:: Variables modifying the behavior of Emacs Info. |
| 938 | @end menu | 928 | @end menu |
| 939 | 929 | ||
| 940 | @node Advanced, Info Search, , Expert Info | 930 | @node Search Text, Search Index, , Advanced |
| 931 | @comment node-name, next, previous, up | ||
| 932 | @section How to search Info documents | ||
| 933 | |||
| 934 | @cindex searching Info documents | ||
| 935 | @cindex Info document as a reference | ||
| 936 | The commands which move between and inside nodes allow you to read | ||
| 937 | the entire manual or its large portions. But what if you need to find | ||
| 938 | some information in the manual as fast as you can, and you don't know | ||
| 939 | or don't remember in what node to look for it? This need arises when | ||
| 940 | you use a manual as a @dfn{reference}, or when it is impractical to | ||
| 941 | read the entire manual before you start using the programs it | ||
| 942 | describes. | ||
| 943 | |||
| 944 | Info has powerful searching facilities that let you find things | ||
| 945 | quickly. You can search either the manual text or its indices. | ||
| 946 | |||
| 947 | @kindex s @r{(Info mode)} | ||
| 948 | @findex Info-search | ||
| 949 | The @kbd{s} command allows you to search a whole Info file for a string. | ||
| 950 | It switches to the next node if and when that is necessary. You | ||
| 951 | type @kbd{s} followed by the string to search for, terminated by | ||
| 952 | @key{RET}. To search for the same string again, just @kbd{s} followed | ||
| 953 | by @key{RET} will do. The file's nodes are scanned in the order | ||
| 954 | they are in the file, which has no necessary relationship to the | ||
| 955 | order that they may be in the tree structure of menus and @samp{next} | ||
| 956 | pointers. But normally the two orders are not very different. In any | ||
| 957 | case, you can always look at the echo area to find out what node you have | ||
| 958 | reached, if the header is not visible (this can happen, because @kbd{s} | ||
| 959 | puts your cursor at the occurrence of the string, not at the beginning | ||
| 960 | of the node). | ||
| 961 | |||
| 962 | @kindex M-s @r{(Info mode)} | ||
| 963 | In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}. That is for | ||
| 964 | compatibility with other GNU packages that use @kbd{M-s} for a similar | ||
| 965 | kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the | ||
| 966 | command @code{Info-search}. | ||
| 967 | |||
| 968 | @kindex C-s @r{(Info mode)} | ||
| 969 | @kindex C-r @r{(Info mode)} | ||
| 970 | @findex isearch | ||
| 971 | Instead of using @kbd{s} in Emacs Info and in the stand-alone Info, | ||
| 972 | you can use an incremental search started with @kbd{C-s} or @kbd{C-r}. | ||
| 973 | It can search through multiple Info nodes. @xref{Incremental Search,,, | ||
| 974 | emacs, The GNU Emacs Manual}. In Emacs, this behavior is enabled only | ||
| 975 | if the variable @code{Info-isearch-search} is non-@code{nil} | ||
| 976 | (@pxref{Emacs Info Variables}). | ||
| 977 | |||
| 978 | @node Search Index, Go to node, Search Text, Advanced | ||
| 941 | @comment node-name, next, previous, up | 979 | @comment node-name, next, previous, up |
| 942 | @section Advanced Info Commands | 980 | @section How to search the indices for specific subjects |
| 981 | |||
| 982 | @cindex searching Info indices | ||
| 983 | @kindex i @r{(Info mode)} | ||
| 984 | @findex Info-index | ||
| 985 | Since most subjects related to what the manual describes should be | ||
| 986 | indexed, you should try the index search first. The @kbd{i} command | ||
| 987 | prompts you for a subject and then looks up that subject in the | ||
| 988 | indices. If it finds an index entry with the subject you typed, it | ||
| 989 | goes to the node to which that index entry points. You should browse | ||
| 990 | through that node to see whether the issue you are looking for is | ||
| 991 | described there. If it isn't, type @kbd{,} one or more times to go | ||
| 992 | through additional index entries which match your subject. | ||
| 943 | 993 | ||
| 944 | Here are some more Info commands that make it easier to move around. | 994 | The @kbd{i} command finds all index entries which include the string |
| 995 | you typed @emph{as a substring}. For each match, Info shows in the | ||
| 996 | echo area the full index entry it found. Often, the text of the full | ||
| 997 | index entry already gives you enough information to decide whether it | ||
| 998 | is relevant to what you are looking for, so we recommend that you read | ||
| 999 | what Info shows in the echo area before looking at the node it | ||
| 1000 | displays. | ||
| 945 | 1001 | ||
| 946 | @subheading @kbd{g} goes to a node by name | 1002 | Since @kbd{i} looks for a substring, you can search for subjects even |
| 1003 | if you are not sure how they are spelled in the index. For example, | ||
| 1004 | suppose you want to find something that is pertinent to commands which | ||
| 1005 | complete partial input (e.g., when you type @key{TAB}). If you want | ||
| 1006 | to catch index entries that refer to ``complete'', ``completion'', and | ||
| 1007 | ``completing'', you could type @kbd{icomplet@key{RET}}. | ||
| 1008 | |||
| 1009 | Info documents which describe programs should index the commands, | ||
| 1010 | options, and key sequences that the program provides. If you are | ||
| 1011 | looking for a description of a command, an option, or a key, just type | ||
| 1012 | their names when @kbd{i} prompts you for a topic. For example, if you | ||
| 1013 | want to read the description of what the @kbd{C-f} key does, type | ||
| 1014 | @kbd{i C - f @key{RET}}. Here @kbd{C-f} are 3 literal characters | ||
| 1015 | @samp{C}, @samp{-}, and @samp{f}, not the ``Control-f'' command key | ||
| 1016 | you type inside Emacs to run the command bound to @kbd{C-f}. | ||
| 1017 | |||
| 1018 | In Emacs, @kbd{i} runs the command @code{Info-index}. | ||
| 1019 | |||
| 1020 | @findex info-apropos | ||
| 1021 | @findex index-apropos | ||
| 1022 | If you don't know what manual documents something, try the @kbd{M-x | ||
| 1023 | info-apropos} command in Emacs, or the @kbd{M-x index-apropos} command | ||
| 1024 | in the stand-alone reader. It prompts for a string and then looks up | ||
| 1025 | that string in all the indices of all the Info documents installed on | ||
| 1026 | your system. | ||
| 1027 | |||
| 1028 | @node Go to node, Choose menu subtopic, Search Index, Advanced | ||
| 1029 | @comment node-name, next, previous, up | ||
| 1030 | @section @kbd{g} goes to a node by name | ||
| 947 | 1031 | ||
| 948 | @kindex g @r{(Info mode)} | 1032 | @kindex g @r{(Info mode)} |
| 949 | @findex Info-goto-node | 1033 | @findex Info-goto-node |
| @@ -951,7 +1035,7 @@ Here are some more Info commands that make it easier to move around. | |||
| 951 | If you know a node's name, you can go there by typing @kbd{g}, the | 1035 | If you know a node's name, you can go there by typing @kbd{g}, the |
| 952 | name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node | 1036 | name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node |
| 953 | called @samp{Top} in this file. (This is equivalent to @kbd{t}, see | 1037 | called @samp{Top} in this file. (This is equivalent to @kbd{t}, see |
| 954 | @ref{Help-Int}.) @kbd{gAdvanced@key{RET}} would come back here. | 1038 | @ref{Help-Int}.) @kbd{gGo to node@key{RET}} would come back here. |
| 955 | @kbd{g} in Emacs runs the command @code{Info-goto-node}. | 1039 | @kbd{g} in Emacs runs the command @code{Info-goto-node}. |
| 956 | 1040 | ||
| 957 | Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. | 1041 | Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. |
| @@ -969,7 +1053,9 @@ the node @samp{Top} in the Info file @file{dir}. Likewise, | |||
| 969 | all of the current file by typing @kbd{g*@key{RET}} or all of any | 1053 | all of the current file by typing @kbd{g*@key{RET}} or all of any |
| 970 | other file with @kbd{g(@var{filename})*@key{RET}}. | 1054 | other file with @kbd{g(@var{filename})*@key{RET}}. |
| 971 | 1055 | ||
| 972 | @subheading @kbd{1}--@kbd{9} choose a menu subtopic by its number | 1056 | @node Choose menu subtopic, Create Info buffer, Go to node, Advanced |
| 1057 | @comment node-name, next, previous, up | ||
| 1058 | @section @kbd{1}--@kbd{9} choose a menu subtopic by its number | ||
| 973 | 1059 | ||
| 974 | @kindex 1 @r{through} 9 @r{(Info mode)} | 1060 | @kindex 1 @r{through} 9 @r{(Info mode)} |
| 975 | @findex Info-nth-menu-item | 1061 | @findex Info-nth-menu-item |
| @@ -994,22 +1080,9 @@ underlining. If you need to actually count items, it is better to use | |||
| 994 | @kbd{m} instead, and specify the name, or use @key{TAB} to quickly | 1080 | @kbd{m} instead, and specify the name, or use @key{TAB} to quickly |
| 995 | move between menu items. | 1081 | move between menu items. |
| 996 | 1082 | ||
| 997 | @subheading @kbd{e} makes Info document editable | 1083 | @node Create Info buffer, Emacs Info Variables, Choose menu subtopic, Advanced |
| 998 | 1084 | @comment node-name, next, previous, up | |
| 999 | @kindex e @r{(Info mode)} | 1085 | @section @kbd{M-n} creates a new independent Info buffer in Emacs |
| 1000 | @findex Info-edit | ||
| 1001 | @cindex edit Info document | ||
| 1002 | The Info command @kbd{e} changes from Info mode to an ordinary | ||
| 1003 | Emacs editing mode, so that you can edit the text of the current node. | ||
| 1004 | Type @kbd{C-c C-c} to switch back to Info. The @kbd{e} command is allowed | ||
| 1005 | only if the variable @code{Info-enable-edit} is non-@code{nil}. | ||
| 1006 | |||
| 1007 | The @kbd{e} command only works in Emacs, where it runs the command | ||
| 1008 | @code{Info-edit}. The stand-alone Info reader doesn't allow you to | ||
| 1009 | edit the Info file, so typing @kbd{e} there goes to the end of the | ||
| 1010 | current node. | ||
| 1011 | |||
| 1012 | @subheading @kbd{M-n} creates a new independent Info buffer in Emacs | ||
| 1013 | 1086 | ||
| 1014 | @kindex M-n @r{(Info mode)} | 1087 | @kindex M-n @r{(Info mode)} |
| 1015 | @findex clone-buffer | 1088 | @findex clone-buffer |
| @@ -1031,100 +1104,128 @@ prefix argument for the @kbd{C-h i} command (@code{info}) which | |||
| 1031 | switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} | 1104 | switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} |
| 1032 | switches to the buffer @samp{*info*<2>}, creating it if necessary. | 1105 | switches to the buffer @samp{*info*<2>}, creating it if necessary. |
| 1033 | 1106 | ||
| 1034 | @node Info Search, Add, Advanced, Expert Info | 1107 | @node Emacs Info Variables, , Create Info buffer, Advanced |
| 1035 | @comment node-name, next, previous, up | 1108 | @comment node-name, next, previous, up |
| 1036 | @section How to search Info documents for specific subjects | 1109 | @section Emacs Info-mode Variables |
| 1037 | 1110 | ||
| 1038 | @cindex searching Info documents | 1111 | The following variables may modify the behavior of Info-mode in Emacs; |
| 1039 | @cindex Info document as a reference | 1112 | you may wish to set one or several of these variables interactively, or |
| 1040 | The commands which move between and inside nodes allow you to read | 1113 | in your @file{~/.emacs} init file. @xref{Examining, Examining and Setting |
| 1041 | the entire manual or its large portions. But what if you need to find | 1114 | Variables, Examining and Setting Variables, emacs, The GNU Emacs |
| 1042 | some information in the manual as fast as you can, and you don't know | 1115 | Manual}. The stand-alone Info reader program has its own set of |
| 1043 | or don't remember in what node to look for it? This need arises when | 1116 | variables, described in @ref{Variables,, Manipulating Variables, |
| 1044 | you use a manual as a @dfn{reference}, or when it is impractical to | 1117 | info-stnd, GNU Info}. |
| 1045 | read the entire manual before you start using the programs it | ||
| 1046 | describes. | ||
| 1047 | 1118 | ||
| 1048 | Info has powerful searching facilities that let you find things | 1119 | @vtable @code |
| 1049 | quickly. You can search either the manual indices or its text. | 1120 | @item Info-directory-list |
| 1121 | The list of directories to search for Info files. Each element is a | ||
| 1122 | string (directory name) or @code{nil} (try default directory). If not | ||
| 1123 | initialized Info uses the environment variable @env{INFOPATH} to | ||
| 1124 | initialize it, or @code{Info-default-directory-list} if there is no | ||
| 1125 | @env{INFOPATH} variable in the environment. | ||
| 1050 | 1126 | ||
| 1051 | @kindex i @r{(Info mode)} | 1127 | If you wish to customize the Info directory search list for both Emacs |
| 1052 | @findex Info-index | 1128 | Info and stand-alone Info, it is best to set the @env{INFOPATH} |
| 1053 | Since most subjects related to what the manual describes should be | 1129 | environment variable, since that applies to both programs. |
| 1054 | indexed, you should try the index search first. The @kbd{i} command | ||
| 1055 | prompts you for a subject and then looks up that subject in the | ||
| 1056 | indices. If it finds an index entry with the subject you typed, it | ||
| 1057 | goes to the node to which that index entry points. You should browse | ||
| 1058 | through that node to see whether the issue you are looking for is | ||
| 1059 | described there. If it isn't, type @kbd{,} one or more times to go | ||
| 1060 | through additional index entries which match your subject. | ||
| 1061 | 1130 | ||
| 1062 | The @kbd{i} command finds all index entries which include the string | 1131 | @item Info-additional-directory-list |
| 1063 | you typed @emph{as a substring}. For each match, Info shows in the | 1132 | A list of additional directories to search for Info documentation files. |
| 1064 | echo area the full index entry it found. Often, the text of the full | 1133 | These directories are not searched for merging the @file{dir} file. |
| 1065 | index entry already gives you enough information to decide whether it | ||
| 1066 | is relevant to what you are looking for, so we recommend that you read | ||
| 1067 | what Info shows in the echo area before looking at the node it | ||
| 1068 | displays. | ||
| 1069 | 1134 | ||
| 1070 | Since @kbd{i} looks for a substring, you can search for subjects even | 1135 | @item Info-mode-hook |
| 1071 | if you are not sure how they are spelled in the index. For example, | 1136 | Hooks run when @code{Info-mode} is called. By default, it contains |
| 1072 | suppose you want to find something that is pertinent to commands which | 1137 | the hook @code{turn-on-font-lock} which enables highlighting of Info |
| 1073 | complete partial input (e.g., when you type @key{TAB}). If you want | 1138 | files. You can change how the highlighting looks by customizing the |
| 1074 | to catch index entries that refer to ``complete'', ``completion'', and | 1139 | faces @code{info-node}, @code{info-xref}, @code{info-xref-visited}, |
| 1075 | ``completing'', you could type @kbd{icomplet@key{RET}}. | 1140 | @code{info-header-xref}, @code{info-header-node}, @code{info-menu-header}, |
| 1141 | @code{info-menu-star}, and @code{info-title-@var{n}} (where @var{n} | ||
| 1142 | is the level of the section, a number between 1 and 4). To customize | ||
| 1143 | a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}}, | ||
| 1144 | where @var{face} is one of the face names listed here. | ||
| 1076 | 1145 | ||
| 1077 | Info documents which describe programs should index the commands, | 1146 | @item Info-fontify-maximum-menu-size |
| 1078 | options, and key sequences that the program provides. If you are | 1147 | Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}. |
| 1079 | looking for a description of a command, an option, or a key, just type | ||
| 1080 | their names when @kbd{i} prompts you for a topic. For example, if you | ||
| 1081 | want to read the description of what the @kbd{C-f} key does, type | ||
| 1082 | @kbd{i C - f @key{RET}}. Here @kbd{C-f} are 3 literal characters | ||
| 1083 | @samp{C}, @samp{-}, and @samp{f}, not the ``Control-f'' command key | ||
| 1084 | you type inside Emacs to run the command bound to @kbd{C-f}. | ||
| 1085 | 1148 | ||
| 1086 | In Emacs, @kbd{i} runs the command @code{Info-index}. | 1149 | @item Info-fontify-visited-nodes |
| 1150 | If non-@code{nil}, menu items and cross-references pointing to visited | ||
| 1151 | nodes are displayed in the @code{info-xref-visited} face. | ||
| 1087 | 1152 | ||
| 1088 | @findex info-apropos | 1153 | @item Info-use-header-line |
| 1089 | @findex index-apropos | 1154 | If non-@code{nil}, Emacs puts in the Info buffer a header line showing |
| 1090 | If you don't know what manual documents something, try the @kbd{M-x | 1155 | the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does |
| 1091 | info-apropos} command in Emacs, or the @kbd{M-x index-apropos} command | 1156 | not scroll with the rest of the buffer, making these links always |
| 1092 | in the stand-alone reader. It prompts for a string and then looks up | 1157 | visible. |
| 1093 | that string in all the indices of all the Info documents installed on | ||
| 1094 | your system. | ||
| 1095 | 1158 | ||
| 1096 | @kindex s @r{(Info mode)} | 1159 | @item Info-hide-note-references |
| 1097 | @findex Info-search | 1160 | As explained in earlier nodes, the Emacs version of Info normally |
| 1098 | The @kbd{s} command allows you to search a whole file for a string. | 1161 | hides some text in menus and cross-references. You can completely |
| 1099 | It switches to the next node if and when that is necessary. You | 1162 | disable this feature, by setting this option to @code{nil}. Setting |
| 1100 | type @kbd{s} followed by the string to search for, terminated by | 1163 | it to a value that is neither @code{nil} nor @code{t} produces an |
| 1101 | @key{RET}. To search for the same string again, just @kbd{s} followed | 1164 | intermediate behavior, hiding a limited amount of text, but showing |
| 1102 | by @key{RET} will do. The file's nodes are scanned in the order | 1165 | all text that could potentially be useful. |
| 1103 | they are in the file, which has no necessary relationship to the | ||
| 1104 | order that they may be in the tree structure of menus and @samp{next} | ||
| 1105 | pointers. But normally the two orders are not very different. In any | ||
| 1106 | case, you can always look at the echo area to find out what node you have | ||
| 1107 | reached, if the header is not visible (this can happen, because @kbd{s} | ||
| 1108 | puts your cursor at the occurrence of the string, not at the beginning | ||
| 1109 | of the node). | ||
| 1110 | 1166 | ||
| 1111 | @kindex M-s @r{(Info mode)} | 1167 | @item Info-scroll-prefer-subnodes |
| 1112 | In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}. That is for | 1168 | If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or |
| 1113 | compatibility with other GNU packages that use @kbd{M-s} for a similar | 1169 | @key{DEL}) keys in a menu visit subnodes of the current node before |
| 1114 | kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the | 1170 | scrolling to its end or beginning, respectively. For example, if the |
| 1115 | command @code{Info-search}. | 1171 | node's menu appears on the screen, the next @key{SPC} moves to a |
| 1172 | subnode indicated by the following menu item. Setting this option to | ||
| 1173 | @code{nil} results in behavior similar to the stand-alone Info reader | ||
| 1174 | program, which visits the first subnode from the menu only when you | ||
| 1175 | hit the end of the current node. The default is @code{nil}. | ||
| 1116 | 1176 | ||
| 1117 | @kindex C-s @r{(Info mode)} | 1177 | @item Info-isearch-search |
| 1118 | @kindex C-r @r{(Info mode)} | 1178 | If non-@code{nil}, isearch in Info searches through multiple nodes. |
| 1119 | @findex isearch | ||
| 1120 | Instead of using @kbd{s} in Emacs Info and in the stand-alone Info, | ||
| 1121 | you can use an incremental search started with @kbd{C-s} or @kbd{C-r}. | ||
| 1122 | It can search through multiple Info nodes. @xref{Incremental Search,,, | ||
| 1123 | emacs, The GNU Emacs Manual}. In Emacs, this behavior is enabled only | ||
| 1124 | if the variable @code{Info-isearch-search} is non-@code{nil} | ||
| 1125 | (@pxref{Emacs Info Variables}). | ||
| 1126 | 1179 | ||
| 1127 | @node Add, Menus, Info Search, Expert Info | 1180 | @item Info-enable-active-nodes |
| 1181 | When set to a non-@code{nil} value, allows Info to execute Lisp code | ||
| 1182 | associated with nodes. The Lisp code is executed when the node is | ||
| 1183 | selected. The Lisp code to be executed should follow the node | ||
| 1184 | delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like | ||
| 1185 | this: | ||
| 1186 | |||
| 1187 | @example | ||
| 1188 | ^_execute: (message "This is an active node!") | ||
| 1189 | @end example | ||
| 1190 | @end vtable | ||
| 1191 | |||
| 1192 | |||
| 1193 | @node Expert Info | ||
| 1194 | @chapter Info for Experts | ||
| 1195 | |||
| 1196 | This chapter explains how to write an Info as distinct from a | ||
| 1197 | Texinfo file. However, in most cases, writing a Texinfo file is | ||
| 1198 | better, since you can use it to make a printed manual or produce other | ||
| 1199 | formats, such as HTML and DocBook, as well as for generating Info | ||
| 1200 | files. | ||
| 1201 | |||
| 1202 | @code{makeinfo} is a utility that converts a Texinfo file into an Info | ||
| 1203 | file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are | ||
| 1204 | GNU Emacs functions that do the same. | ||
| 1205 | |||
| 1206 | @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU | ||
| 1207 | Documentation Format}, to learn how to write a Texinfo file. | ||
| 1208 | |||
| 1209 | @xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation | ||
| 1210 | Format}, to learn how to create an Info file from a Texinfo file. | ||
| 1211 | |||
| 1212 | @xref{Installing an Info File,,, texinfo, Texinfo: The GNU | ||
| 1213 | Documentation Format}, to learn how to install an Info file after you | ||
| 1214 | have created one. | ||
| 1215 | |||
| 1216 | However, if you want to edit an Info file manually and install it manually, | ||
| 1217 | here is how. | ||
| 1218 | |||
| 1219 | @menu | ||
| 1220 | * Add:: Describes how to add new nodes to the hierarchy. | ||
| 1221 | Also tells what nodes look like. | ||
| 1222 | * Menus:: How to add to or create menus in Info nodes. | ||
| 1223 | * Cross-refs:: How to add cross-references to Info nodes. | ||
| 1224 | * Tags:: How to make tags tables for Info files. | ||
| 1225 | * Checking:: Checking an Info File. | ||
| 1226 | @end menu | ||
| 1227 | |||
| 1228 | @node Add, Menus, , Expert Info | ||
| 1128 | @comment node-name, next, previous, up | 1229 | @comment node-name, next, previous, up |
| 1129 | @section Adding a new node to Info | 1230 | @section Adding a new node to Info |
| 1130 | 1231 | ||
| @@ -1137,14 +1238,6 @@ Create some nodes, in some file, to document that topic. | |||
| 1137 | Put that topic in the menu in the directory. @xref{Menus, Menu}. | 1238 | Put that topic in the menu in the directory. @xref{Menus, Menu}. |
| 1138 | @end enumerate | 1239 | @end enumerate |
| 1139 | 1240 | ||
| 1140 | Usually, the way to create the nodes is with Texinfo (@pxref{Top,, | ||
| 1141 | Overview of Texinfo, texinfo, Texinfo: The GNU Documentation Format}); | ||
| 1142 | this has the advantage that you can also make a printed manual or HTML | ||
| 1143 | from them. You would use the @samp{@@dircategory} and | ||
| 1144 | @samp{@@direntry} commands to put the manual into the Info directory. | ||
| 1145 | However, if you want to edit an Info file manually and install it | ||
| 1146 | manually, here is how. | ||
| 1147 | |||
| 1148 | @cindex node delimiters | 1241 | @cindex node delimiters |
| 1149 | The new node can live in an existing documentation file, or in a new | 1242 | The new node can live in an existing documentation file, or in a new |
| 1150 | one. It must have a @samp{^_} character before it (invisible to the | 1243 | one. It must have a @samp{^_} character before it (invisible to the |
| @@ -1324,7 +1417,7 @@ as new users should do when they learn a new package. | |||
| 1324 | something quickly in a manual---that is, when you need to use a manual | 1417 | something quickly in a manual---that is, when you need to use a manual |
| 1325 | as a reference rather than as a tutorial. We urge you to learn | 1418 | as a reference rather than as a tutorial. We urge you to learn |
| 1326 | these search commands as well. If you want to do that now, follow this | 1419 | these search commands as well. If you want to do that now, follow this |
| 1327 | cross reference to @ref{Info Search}. | 1420 | cross reference to @ref{Advanced}. |
| 1328 | 1421 | ||
| 1329 | Yet another set of commands are meant for experienced users; you can | 1422 | Yet another set of commands are meant for experienced users; you can |
| 1330 | find them by looking in the Directory node for documentation on Info. | 1423 | find them by looking in the Directory node for documentation on Info. |
| @@ -1382,8 +1475,7 @@ the beginning of the node's header (ending just after the node name), | |||
| 1382 | a @samp{DEL} character, and the character position in the file of the | 1475 | a @samp{DEL} character, and the character position in the file of the |
| 1383 | beginning of the node. | 1476 | beginning of the node. |
| 1384 | 1477 | ||
| 1385 | 1478 | @node Checking, , Tags, Expert Info | |
| 1386 | @node Checking, Emacs Info Variables, Tags, Expert Info | ||
| 1387 | @section Checking an Info File | 1479 | @section Checking an Info File |
| 1388 | 1480 | ||
| 1389 | When creating an Info file, it is easy to forget the name of a node when | 1481 | When creating an Info file, it is easy to forget the name of a node when |
| @@ -1402,112 +1494,6 @@ usually few. | |||
| 1402 | To check an Info file, do @kbd{M-x Info-validate} while looking at any | 1494 | To check an Info file, do @kbd{M-x Info-validate} while looking at any |
| 1403 | node of the file with Emacs Info mode. | 1495 | node of the file with Emacs Info mode. |
| 1404 | 1496 | ||
| 1405 | @node Emacs Info Variables, , Checking, Expert Info | ||
| 1406 | @section Emacs Info-mode Variables | ||
| 1407 | |||
| 1408 | The following variables may modify the behavior of Info-mode in Emacs; | ||
| 1409 | you may wish to set one or several of these variables interactively, or | ||
| 1410 | in your @file{~/.emacs} init file. @xref{Examining, Examining and Setting | ||
| 1411 | Variables, Examining and Setting Variables, emacs, The GNU Emacs | ||
| 1412 | Manual}. The stand-alone Info reader program has its own set of | ||
| 1413 | variables, described in @ref{Variables,, Manipulating Variables, | ||
| 1414 | info-stnd, GNU Info}. | ||
| 1415 | |||
| 1416 | @vtable @code | ||
| 1417 | @item Info-directory-list | ||
| 1418 | The list of directories to search for Info files. Each element is a | ||
| 1419 | string (directory name) or @code{nil} (try default directory). If not | ||
| 1420 | initialized Info uses the environment variable @env{INFOPATH} to | ||
| 1421 | initialize it, or @code{Info-default-directory-list} if there is no | ||
| 1422 | @env{INFOPATH} variable in the environment. | ||
| 1423 | |||
| 1424 | If you wish to customize the Info directory search list for both Emacs | ||
| 1425 | Info and stand-alone Info, it is best to set the @env{INFOPATH} | ||
| 1426 | environment variable, since that applies to both programs. | ||
| 1427 | |||
| 1428 | @item Info-additional-directory-list | ||
| 1429 | A list of additional directories to search for Info documentation files. | ||
| 1430 | These directories are not searched for merging the @file{dir} file. | ||
| 1431 | |||
| 1432 | @item Info-mode-hook | ||
| 1433 | Hooks run when @code{Info-mode} is called. By default, it contains | ||
| 1434 | the hook @code{turn-on-font-lock} which enables highlighting of Info | ||
| 1435 | files. You can change how the highlighting looks by customizing the | ||
| 1436 | faces @code{info-node}, @code{info-xref}, @code{info-xref-visited}, | ||
| 1437 | @code{info-header-xref}, @code{info-header-node}, @code{info-menu-header}, | ||
| 1438 | @code{info-menu-star}, and @code{info-title-@var{n}} (where @var{n} | ||
| 1439 | is the level of the section, a number between 1 and 4). To customize | ||
| 1440 | a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}}, | ||
| 1441 | where @var{face} is one of the face names listed here. | ||
| 1442 | |||
| 1443 | @item Info-fontify-maximum-menu-size | ||
| 1444 | Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}. | ||
| 1445 | |||
| 1446 | @item Info-fontify-visited-nodes | ||
| 1447 | If non-@code{nil}, menu items and cross-references pointing to visited | ||
| 1448 | nodes are displayed in the @code{info-xref-visited} face. | ||
| 1449 | |||
| 1450 | @item Info-use-header-line | ||
| 1451 | If non-@code{nil}, Emacs puts in the Info buffer a header line showing | ||
| 1452 | the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does | ||
| 1453 | not scroll with the rest of the buffer, making these links always | ||
| 1454 | visible. | ||
| 1455 | |||
| 1456 | @item Info-hide-note-references | ||
| 1457 | As explained in earlier nodes, the Emacs version of Info normally | ||
| 1458 | hides some text in menus and cross-references. You can completely | ||
| 1459 | disable this feature, by setting this option to @code{nil}. Setting | ||
| 1460 | it to a value that is neither @code{nil} nor @code{t} produces an | ||
| 1461 | intermediate behavior, hiding a limited amount of text, but showing | ||
| 1462 | all text that could potentially be useful. | ||
| 1463 | |||
| 1464 | @item Info-scroll-prefer-subnodes | ||
| 1465 | If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or | ||
| 1466 | @key{DEL}) keys in a menu visit subnodes of the current node before | ||
| 1467 | scrolling to its end or beginning, respectively. For example, if the | ||
| 1468 | node's menu appears on the screen, the next @key{SPC} moves to a | ||
| 1469 | subnode indicated by the following menu item. Setting this option to | ||
| 1470 | @code{nil} results in behavior similar to the stand-alone Info reader | ||
| 1471 | program, which visits the first subnode from the menu only when you | ||
| 1472 | hit the end of the current node. The default is @code{nil}. | ||
| 1473 | |||
| 1474 | @item Info-isearch-search | ||
| 1475 | If non-@code{nil}, isearch in Info searches through multiple nodes. | ||
| 1476 | |||
| 1477 | @item Info-enable-active-nodes | ||
| 1478 | When set to a non-@code{nil} value, allows Info to execute Lisp code | ||
| 1479 | associated with nodes. The Lisp code is executed when the node is | ||
| 1480 | selected. The Lisp code to be executed should follow the node | ||
| 1481 | delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like | ||
| 1482 | this: | ||
| 1483 | |||
| 1484 | @example | ||
| 1485 | ^_execute: (message "This is an active node!") | ||
| 1486 | @end example | ||
| 1487 | |||
| 1488 | @item Info-enable-edit | ||
| 1489 | Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command. A | ||
| 1490 | non-@code{nil} value enables it. @xref{Add, Edit}. | ||
| 1491 | @end vtable | ||
| 1492 | |||
| 1493 | |||
| 1494 | @node Creating an Info File | ||
| 1495 | @chapter Creating an Info File from a Texinfo File | ||
| 1496 | |||
| 1497 | @code{makeinfo} is a utility that converts a Texinfo file into an Info | ||
| 1498 | file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are | ||
| 1499 | GNU Emacs functions that do the same. | ||
| 1500 | |||
| 1501 | @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU | ||
| 1502 | Documentation Format}, to learn how to write a Texinfo file. | ||
| 1503 | |||
| 1504 | @xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation | ||
| 1505 | Format}, to learn how to create an Info file from a Texinfo file. | ||
| 1506 | |||
| 1507 | @xref{Installing an Info File,,, texinfo, Texinfo: The GNU | ||
| 1508 | Documentation Format}, to learn how to install an Info file after you | ||
| 1509 | have created one. | ||
| 1510 | |||
| 1511 | @node Index | 1497 | @node Index |
| 1512 | @unnumbered Index | 1498 | @unnumbered Index |
| 1513 | 1499 | ||