aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--man/info.texi480
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,
72type the command @kbd{h} now. It brings you to a programmed 72type the command @kbd{h} now. It brings you to a programmed
73instruction sequence. 73instruction sequence.
74 74
75To read about expert-level Info commands, type @kbd{n} twice. This 75To read about advanced Info commands, type @kbd{n} twice. This
76brings you to @cite{Info for Experts}, skipping over the `Getting 76brings you to @cite{Advanced Info Commands}, skipping over the `Getting
77Started' chapter. 77Started' 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
92This first part of this Info manual describes how to get around inside 92This first part of this Info manual describes how to get around inside
93of Info. The second part of the manual describes various advanced 93of Info. The second part of the manual describes various advanced
94Info commands, and how to write an Info as distinct from a Texinfo 94Info commands. The third part briefly explains how to generate Info
95file. The third part briefly explains how to generate Info files from 95files from Texinfo files, and describes how to write an Info as
96Texinfo files. 96distinct from a Texinfo file.
97 97
98@ifnotinfo 98@ifnotinfo
99This manual is primarily designed for browsing with an Info reader 99This 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
848that for you. It searches the index for a given topic (a string) and 848that for you. It searches the index for a given topic (a string) and
849goes to the node which is listed in the index for that topic. 849goes 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
917are using a stand-alone Info reader, there are additional commands 917are using a stand-alone Info reader, there are additional commands
918specific to it, which are documented in several chapters of @ref{Top,, 918specific to it, which are documented in several chapters of @ref{Top,,
919GNU Info, info-stnd, GNU Info}.) 919GNU Info, info-stnd, GNU Info}.)
920 920
921 This chapter also explains how to write an Info as distinct from a
922Texinfo file. (However, in most cases, writing a Texinfo file is
923better, since you can use it to make a printed manual or produce other
924formats, such as HTML and DocBook, as well as for generating Info
925files.) @xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
926Documentation 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
937the entire manual or its large portions. But what if you need to find
938some information in the manual as fast as you can, and you don't know
939or don't remember in what node to look for it? This need arises when
940you use a manual as a @dfn{reference}, or when it is impractical to
941read the entire manual before you start using the programs it
942describes.
943
944 Info has powerful searching facilities that let you find things
945quickly. 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.
950It switches to the next node if and when that is necessary. You
951type @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
953by @key{RET} will do. The file's nodes are scanned in the order
954they are in the file, which has no necessary relationship to the
955order that they may be in the tree structure of menus and @samp{next}
956pointers. But normally the two orders are not very different. In any
957case, you can always look at the echo area to find out what node you have
958reached, if the header is not visible (this can happen, because @kbd{s}
959puts your cursor at the occurrence of the string, not at the beginning
960of the node).
961
962@kindex M-s @r{(Info mode)}
963 In Emacs, @kbd{Meta-s} is equivalent to @kbd{s}. That is for
964compatibility with other GNU packages that use @kbd{M-s} for a similar
965kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the
966command @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,
972you can use an incremental search started with @kbd{C-s} or @kbd{C-r}.
973It can search through multiple Info nodes. @xref{Incremental Search,,,
974emacs, The GNU Emacs Manual}. In Emacs, this behavior is enabled only
975if 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
986indexed, you should try the index search first. The @kbd{i} command
987prompts you for a subject and then looks up that subject in the
988indices. If it finds an index entry with the subject you typed, it
989goes to the node to which that index entry points. You should browse
990through that node to see whether the issue you are looking for is
991described there. If it isn't, type @kbd{,} one or more times to go
992through additional index entries which match your subject.
943 993
944Here 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
995you typed @emph{as a substring}. For each match, Info shows in the
996echo area the full index entry it found. Often, the text of the full
997index entry already gives you enough information to decide whether it
998is relevant to what you are looking for, so we recommend that you read
999what Info shows in the echo area before looking at the node it
1000displays.
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
1003if you are not sure how they are spelled in the index. For example,
1004suppose you want to find something that is pertinent to commands which
1005complete partial input (e.g., when you type @key{TAB}). If you want
1006to 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,
1010options, and key sequences that the program provides. If you are
1011looking for a description of a command, an option, or a key, just type
1012their names when @kbd{i} prompts you for a topic. For example, if you
1013want 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
1016you 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
1022If you don't know what manual documents something, try the @kbd{M-x
1023info-apropos} command in Emacs, or the @kbd{M-x index-apropos} command
1024in the stand-alone reader. It prompts for a string and then looks up
1025that string in all the indices of all the Info documents installed on
1026your 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
952name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node 1036name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node
953called @samp{Top} in this file. (This is equivalent to @kbd{t}, see 1037called @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,
969all of the current file by typing @kbd{g*@key{RET}} or all of any 1053all of the current file by typing @kbd{g*@key{RET}} or all of any
970other file with @kbd{g(@var{filename})*@key{RET}}. 1054other 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
995move between menu items. 1081move 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
1003Emacs editing mode, so that you can edit the text of the current node.
1004Type @kbd{C-c C-c} to switch back to Info. The @kbd{e} command is allowed
1005only 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
1009edit the Info file, so typing @kbd{e} there goes to the end of the
1010current 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
1031switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} 1104switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i}
1032switches to the buffer @samp{*info*<2>}, creating it if necessary. 1105switches 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 1111The following variables may modify the behavior of Info-mode in Emacs;
1039@cindex Info document as a reference 1112you 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 1113in your @file{~/.emacs} init file. @xref{Examining, Examining and Setting
1041the entire manual or its large portions. But what if you need to find 1114Variables, Examining and Setting Variables, emacs, The GNU Emacs
1042some information in the manual as fast as you can, and you don't know 1115Manual}. The stand-alone Info reader program has its own set of
1043or don't remember in what node to look for it? This need arises when 1116variables, described in @ref{Variables,, Manipulating Variables,
1044you use a manual as a @dfn{reference}, or when it is impractical to 1117info-stnd, GNU Info}.
1045read the entire manual before you start using the programs it
1046describes.
1047 1118
1048 Info has powerful searching facilities that let you find things 1119@vtable @code
1049quickly. You can search either the manual indices or its text. 1120@item Info-directory-list
1121The list of directories to search for Info files. Each element is a
1122string (directory name) or @code{nil} (try default directory). If not
1123initialized Info uses the environment variable @env{INFOPATH} to
1124initialize 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)} 1127If you wish to customize the Info directory search list for both Emacs
1052@findex Info-index 1128Info and stand-alone Info, it is best to set the @env{INFOPATH}
1053 Since most subjects related to what the manual describes should be 1129environment variable, since that applies to both programs.
1054indexed, you should try the index search first. The @kbd{i} command
1055prompts you for a subject and then looks up that subject in the
1056indices. If it finds an index entry with the subject you typed, it
1057goes to the node to which that index entry points. You should browse
1058through that node to see whether the issue you are looking for is
1059described there. If it isn't, type @kbd{,} one or more times to go
1060through 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
1063you typed @emph{as a substring}. For each match, Info shows in the 1132A list of additional directories to search for Info documentation files.
1064echo area the full index entry it found. Often, the text of the full 1133These directories are not searched for merging the @file{dir} file.
1065index entry already gives you enough information to decide whether it
1066is relevant to what you are looking for, so we recommend that you read
1067what Info shows in the echo area before looking at the node it
1068displays.
1069 1134
1070 Since @kbd{i} looks for a substring, you can search for subjects even 1135@item Info-mode-hook
1071if you are not sure how they are spelled in the index. For example, 1136Hooks run when @code{Info-mode} is called. By default, it contains
1072suppose you want to find something that is pertinent to commands which 1137the hook @code{turn-on-font-lock} which enables highlighting of Info
1073complete partial input (e.g., when you type @key{TAB}). If you want 1138files. You can change how the highlighting looks by customizing the
1074to catch index entries that refer to ``complete'', ``completion'', and 1139faces @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}
1142is the level of the section, a number between 1 and 4). To customize
1143a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}},
1144where @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
1078options, and key sequences that the program provides. If you are 1147Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}.
1079looking for a description of a command, an option, or a key, just type
1080their names when @kbd{i} prompts you for a topic. For example, if you
1081want 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
1084you 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
1150If non-@code{nil}, menu items and cross-references pointing to visited
1151nodes 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 1154If non-@code{nil}, Emacs puts in the Info buffer a header line showing
1090If you don't know what manual documents something, try the @kbd{M-x 1155the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does
1091info-apropos} command in Emacs, or the @kbd{M-x index-apropos} command 1156not scroll with the rest of the buffer, making these links always
1092in the stand-alone reader. It prompts for a string and then looks up 1157visible.
1093that string in all the indices of all the Info documents installed on
1094your system.
1095 1158
1096@kindex s @r{(Info mode)} 1159@item Info-hide-note-references
1097@findex Info-search 1160As 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. 1161hides some text in menus and cross-references. You can completely
1099It switches to the next node if and when that is necessary. You 1162disable this feature, by setting this option to @code{nil}. Setting
1100type @kbd{s} followed by the string to search for, terminated by 1163it 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 1164intermediate behavior, hiding a limited amount of text, but showing
1102by @key{RET} will do. The file's nodes are scanned in the order 1165all text that could potentially be useful.
1103they are in the file, which has no necessary relationship to the
1104order that they may be in the tree structure of menus and @samp{next}
1105pointers. But normally the two orders are not very different. In any
1106case, you can always look at the echo area to find out what node you have
1107reached, if the header is not visible (this can happen, because @kbd{s}
1108puts your cursor at the occurrence of the string, not at the beginning
1109of 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 1168If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or
1113compatibility 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
1114kind of search command. Both @kbd{s} and @kbd{M-s} run in Emacs the 1170scrolling to its end or beginning, respectively. For example, if the
1115command @code{Info-search}. 1171node's menu appears on the screen, the next @key{SPC} moves to a
1172subnode indicated by the following menu item. Setting this option to
1173@code{nil} results in behavior similar to the stand-alone Info reader
1174program, which visits the first subnode from the menu only when you
1175hit 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)} 1178If 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,
1121you can use an incremental search started with @kbd{C-s} or @kbd{C-r}.
1122It can search through multiple Info nodes. @xref{Incremental Search,,,
1123emacs, The GNU Emacs Manual}. In Emacs, this behavior is enabled only
1124if 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
1181When set to a non-@code{nil} value, allows Info to execute Lisp code
1182associated with nodes. The Lisp code is executed when the node is
1183selected. The Lisp code to be executed should follow the node
1184delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like
1185this:
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
1197Texinfo file. However, in most cases, writing a Texinfo file is
1198better, since you can use it to make a printed manual or produce other
1199formats, such as HTML and DocBook, as well as for generating Info
1200files.
1201
1202@code{makeinfo} is a utility that converts a Texinfo file into an Info
1203file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
1204GNU Emacs functions that do the same.
1205
1206@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
1207Documentation Format}, to learn how to write a Texinfo file.
1208
1209@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation
1210Format}, to learn how to create an Info file from a Texinfo file.
1211
1212@xref{Installing an Info File,,, texinfo, Texinfo: The GNU
1213Documentation Format}, to learn how to install an Info file after you
1214have created one.
1215
1216However, if you want to edit an Info file manually and install it manually,
1217here 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.
1137Put that topic in the menu in the directory. @xref{Menus, Menu}. 1238Put 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,,
1141Overview of Texinfo, texinfo, Texinfo: The GNU Documentation Format});
1142this has the advantage that you can also make a printed manual or HTML
1143from them. You would use the @samp{@@dircategory} and
1144@samp{@@direntry} commands to put the manual into the Info directory.
1145However, if you want to edit an Info file manually and install it
1146manually, 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
1150one. It must have a @samp{^_} character before it (invisible to the 1243one. 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.
1324something quickly in a manual---that is, when you need to use a manual 1417something quickly in a manual---that is, when you need to use a manual
1325as a reference rather than as a tutorial. We urge you to learn 1418as a reference rather than as a tutorial. We urge you to learn
1326these search commands as well. If you want to do that now, follow this 1419these search commands as well. If you want to do that now, follow this
1327cross reference to @ref{Info Search}. 1420cross reference to @ref{Advanced}.
1328 1421
1329Yet another set of commands are meant for experienced users; you can 1422Yet another set of commands are meant for experienced users; you can
1330find them by looking in the Directory node for documentation on Info. 1423find 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),
1382a @samp{DEL} character, and the character position in the file of the 1475a @samp{DEL} character, and the character position in the file of the
1383beginning of the node. 1476beginning 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
1389When creating an Info file, it is easy to forget the name of a node when 1481When creating an Info file, it is easy to forget the name of a node when
@@ -1402,112 +1494,6 @@ usually few.
1402To check an Info file, do @kbd{M-x Info-validate} while looking at any 1494To check an Info file, do @kbd{M-x Info-validate} while looking at any
1403node of the file with Emacs Info mode. 1495node of the file with Emacs Info mode.
1404 1496
1405@node Emacs Info Variables, , Checking, Expert Info
1406@section Emacs Info-mode Variables
1407
1408The following variables may modify the behavior of Info-mode in Emacs;
1409you may wish to set one or several of these variables interactively, or
1410in your @file{~/.emacs} init file. @xref{Examining, Examining and Setting
1411Variables, Examining and Setting Variables, emacs, The GNU Emacs
1412Manual}. The stand-alone Info reader program has its own set of
1413variables, described in @ref{Variables,, Manipulating Variables,
1414info-stnd, GNU Info}.
1415
1416@vtable @code
1417@item Info-directory-list
1418The list of directories to search for Info files. Each element is a
1419string (directory name) or @code{nil} (try default directory). If not
1420initialized Info uses the environment variable @env{INFOPATH} to
1421initialize it, or @code{Info-default-directory-list} if there is no
1422@env{INFOPATH} variable in the environment.
1423
1424If you wish to customize the Info directory search list for both Emacs
1425Info and stand-alone Info, it is best to set the @env{INFOPATH}
1426environment variable, since that applies to both programs.
1427
1428@item Info-additional-directory-list
1429A list of additional directories to search for Info documentation files.
1430These directories are not searched for merging the @file{dir} file.
1431
1432@item Info-mode-hook
1433Hooks run when @code{Info-mode} is called. By default, it contains
1434the hook @code{turn-on-font-lock} which enables highlighting of Info
1435files. You can change how the highlighting looks by customizing the
1436faces @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}
1439is the level of the section, a number between 1 and 4). To customize
1440a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}},
1441where @var{face} is one of the face names listed here.
1442
1443@item Info-fontify-maximum-menu-size
1444Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}.
1445
1446@item Info-fontify-visited-nodes
1447If non-@code{nil}, menu items and cross-references pointing to visited
1448nodes are displayed in the @code{info-xref-visited} face.
1449
1450@item Info-use-header-line
1451If non-@code{nil}, Emacs puts in the Info buffer a header line showing
1452the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does
1453not scroll with the rest of the buffer, making these links always
1454visible.
1455
1456@item Info-hide-note-references
1457As explained in earlier nodes, the Emacs version of Info normally
1458hides some text in menus and cross-references. You can completely
1459disable this feature, by setting this option to @code{nil}. Setting
1460it to a value that is neither @code{nil} nor @code{t} produces an
1461intermediate behavior, hiding a limited amount of text, but showing
1462all text that could potentially be useful.
1463
1464@item Info-scroll-prefer-subnodes
1465If 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
1467scrolling to its end or beginning, respectively. For example, if the
1468node's menu appears on the screen, the next @key{SPC} moves to a
1469subnode indicated by the following menu item. Setting this option to
1470@code{nil} results in behavior similar to the stand-alone Info reader
1471program, which visits the first subnode from the menu only when you
1472hit the end of the current node. The default is @code{nil}.
1473
1474@item Info-isearch-search
1475If non-@code{nil}, isearch in Info searches through multiple nodes.
1476
1477@item Info-enable-active-nodes
1478When set to a non-@code{nil} value, allows Info to execute Lisp code
1479associated with nodes. The Lisp code is executed when the node is
1480selected. The Lisp code to be executed should follow the node
1481delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like
1482this:
1483
1484@example
1485^_execute: (message "This is an active node!")
1486@end example
1487
1488@item Info-enable-edit
1489Set to @code{nil}, disables the @samp{e} (@code{Info-edit}) command. A
1490non-@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
1498file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
1499GNU Emacs functions that do the same.
1500
1501@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU
1502Documentation Format}, to learn how to write a Texinfo file.
1503
1504@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation
1505Format}, to learn how to create an Info file from a Texinfo file.
1506
1507@xref{Installing an Info File,,, texinfo, Texinfo: The GNU
1508Documentation Format}, to learn how to install an Info file after you
1509have created one.
1510
1511@node Index 1497@node Index
1512@unnumbered Index 1498@unnumbered Index
1513 1499