INFO: Basic Help for learning the Info online documentation reader. * What is Info? Why should I use Info? How is it different from the manpages? The Short Answer: (read The Long Answer, if this is nonsense to you.) Info is a hypertext browsing program that allows you to move through hypertext documents that have been formatted a certain way and arranged into a kind of tree structure, making it easier for you to use the same documentation to get a quick overview of something or to learn about in great low-level detail. It also allows you to follow cross-references easily, and it is not difficult to add documentation to the tree, in general. The Long Answer: Info is a program intended to be a substitute for manpages, created because people found the "manpage" format rather difficult when trying to learn about things that they didn't already know everything about. One of the biggest complaints about manpages is that although there is some structure to them, it's not always easy to search through them for the particular information you need. Info addresses this problem by arranging documentation into a "tree-structure" (outlined below), and then supplying the user with various commands for moving around in that tree. This is known as "hypertext", and it is becoming more and more common for computer programs to be documented in this way, as opposed to plain pages of text, since the computer can be used as a tool for moving around in the hypertext document. The tree structure that Info-style documentation is arranged in is similar to the directory structure of the filesystem, but Info gives you more commands for moving through the tree. It is this arrangement that allows you to look at, say, only the very basic, introductory material for some program (call it the "Foobar" program), while ignoring the dirty details by simply not ever referencing the parts of the tree that are labeled "Dirty Details of the Foobar Program", or something to that effect. But the dirty details are there, should you ever choose to look at them. This flexibility makes Info both a great reference tool and a great document-browsing system for when you just want to "poke around" and see what there is to see. * How Info works and basic commands for moving around in it. (This assumes that you already have Info installed on your system, either in Emacs, or as a free-standing program started from the command line. If you don't have it installed, see the section below entitled "* Getting and Installing Info.") From the command line, just type "info", assuming the executable is in your path. If you are in Emacs (the more common way to enter Info), then type either "Ctl-h i" (control-h is help, the "i" is for "Info", obviously :-), or "Esc-x info" ("M-x info") to start it up. The makers of Info have kindly provided you with a a primer for beginning users of Info, and that's probably a good way to start. Type "h" to enter it, unless the instructions you see on the screen are different. However, a picture is worth a thousand words, and a diagram of how Info is structured would be of help here: Figure (1) *Main Menu (Dir)* | . | . . . . . . . . . . . . . . . . . . . . . Info (yes, info Bison (a yacc GAWK (the GNU about Info!!!) compatible parser version of awk) generator) The preceding diagram is not what you actually see when you enter Info; rather, it's an outline to help explain the structure of Info documentation and how to move around in it. There will also be a lot more than just three entries visible when you are at the top of the Info tree, but this picture is just a simplified example. In Info, what you see above would be represented by this: File: dir Node: Top This is the top of the INFO tree This (the Directory node) gives a menu of major topics. Typing "d" returns here, "q" exits, "?" lists all INFO commands, "h" gives a primer for first-timers, "mTexinfo" visits Texinfo topic, etc. --- PLEASE ADD DOCUMENTATION TO THIS TREE. (See INFO topic first.) --- * Menu: The list of major topics begins on the next line. * Info: (info).Yes, info about Info!!! * Bison: (bison). a yacc compatible parser generator * GAWK: (gawk). The GNU version of awk This is what the first page and first three entries of the Main Menu, also known as DIR, looks like in the Info I run on my machine. Yours should look similar, although the actual order of the programs listed might be different and have different descriptions on the right. For now ignore the names in parentheses next that appear next to each Menu entry -- they are there for the program's use, not yours. What you are interested in is the stuff in the menu immediately following the "*" and before the ":" on each line of the menu... these are the names of the menu entries that you would choose to learn more about the named topic. Each of them represents a "node" in the Info tree. A "node" is just place, a location that has some text documenting whatever topic it is a node of, and -- most importantly -- might have some more menu entries that lead to more nodes also devoted to that topic. Just like the directory structure, nodes may have many children, but generally only one parent (some nodes are cross-linked to more than one parent, but this is rare). Let's follow the Bison node. To do this, press "m" (for "menu", and notice the little message that appears in the one-line minibuffer at the bottom of the screen), type "Bison", and hit Return. (Capitalization is not important, and the Tab key does completion on unique strings, meaning that if you have already typed "bis" you can just hit the Tab key and it will type the rest for you, assuming that there are no other menu entries beginning with "bis" to confuse it). (If your Main Menu is too large for your screen and runs off the bottom, you can see it by hitting the space bar. The Backspace key pages up, Space pages down; this is universal throughout Info, not just at the Main Menu. Most nodes do go off the screen, so these are two commands you'll be using often in Info.) If you have gone to the Bison node, you should see something like this: File: bison.info, Node: Top, Next: Introduction, Prev: (DIR), Up: (DIR) This manual documents version 1.16 of Bison. * Menu: * Introduction:: * Conditions:: * Copying:: The GNU General Public License says how you can copy and share Bison Tutorial sections: * Concepts:: Basic concepts for understanding Bison. * Examples:: Three simple explained examples of using Bison. Reference sections: * Grammar File:: Writing Bison declarations and rules. * Interface:: C-language interface to the parser function `yyparse'. * Algorithm:: How the Bison parser works at run-time. * Error Recovery:: Writing rules for error recovery. * Context Dependency::What to do if your language syntax is too messy for Bison to handle straightforwardly. * Debugging:: Debugging Bison parsers that parse wrong. * Invocation:: How to run Bison (to produce the parser source file). * Table of Symbols:: All the keywords of the Bison language are explained. * Glossary:: Basic concepts are explained. * Index:: Cross-references to the text. If Bison documentation is not included in you version of Info, don't worry about it. Just choose something else from the menu the same way, by pressing "m" and then entering the name, and follow along. The principles of Info are the same no matter what you are reading about. I will try to show some of this with the same tree diagram I used in Figure (1), but not all of it, as the complete menu at this node is quite large, as you can see. Figure (2) *Main Menu (Dir)* | . | . . . . . . . . . . . . . . . . . . . . . Info (yes, info Bison (a yacc GAWK (the GNU about Info!!!) compatible parser version of awk) generator) | | | . . . . . . . . . . . . . . . . . . . . . Grammar File Interface Algorithm I have chosen the first three entries in the section of the menu entitled "Reference Section" .. you'll have to imagine the ones before and after these three as being off to the right and left respectively, and all being children of the Bison node of the Main Menu. Suppose that I want to just browse through the reference section for Bison, starting with the Grammar and moving on through Algorithm. I'd choose Grammar File from the Bison menu the same way I chose Bison itself from the Main Menu: by pressing "m" for menu and typing "Grammar File" (well, really, I'd just type "gram" and hit Tab, then Return, because I'm a lazy child of the computer age!). Now I see the following: File: bison.info, Node: Grammar File, Next: Interface, Prev: Examples, Up: Top Bison Grammar Files ******************* Bison takes as input a context-free grammar specification and produces a C-language function that recognizes correct instances of the grammar. The Bison grammar input file conventionally has a name ending in `.y'. * Menu: * Grammar Outline:: Overall layout of the grammar file. * Symbols:: Terminal and nonterminal symbols. * Rules:: How to write grammar rules. * Recursion:: Writing recursive rules. * Semantics:: Semantic values and actions. * Declarations:: All kinds of Bison declarations are described here. * Multiple Parsers:: Putting more than one Bison parser in one program. Suppose that this is all I want to read about the Grammar right now. I'd like to avoid the dirty details offered by the menu, tempting as they are, and move on to Interface. There is no need for me to move up to the main Bison node and then choose interface from the menu, I can just type "n" (for "next") and that will automatically move me in the fashion shown by the arrow in the following diagram: Figure (3) *Main Menu (Dir)* | . | . . . . . . . . . . . . . . . . . . . . . Info (yes, info Bison (a yacc GAWK (the GNU about Info!!!) compatible parser version of awk) generator) | | | . . . . . . . . . . . . . . . . . . . . . Grammar File --------> Interface Algorithm /\ /\ || || || || (we were here, || and we moved to) ------> (here) In other words, the "n" command will move you to the "next" node to the right on the same level of the tree that you are currently at!! This is what makes Info such a powerful browsing tool. Now that we are at the node Interface, we see this: File: bison.info, Node: Interface, Next: Algorithm, Prev: Grammar File, Up: Top Parser C-Language Interface *************************** The Bison parser is actually a C function named `yyparse'. Here we describe the interface conventions of `yyparse' and the other functions that it needs to use. Keep in mind that the parser uses many C identifiers starting with `yy' and `YY' for internal purposes. If you use such an identifier (aside from those in this manual) in an action or in additional C code in the grammar file, you are likely to run into trouble. * Menu: * Parser Function:: How to call `yyparse' and what it returns. * Lexical:: You must supply a function `yylex' which reads tokens. * Error Reporting:: You must supply a function `yyerror'. * Action Features:: Special features for use in actions. From here, you can use the "n" command to move to Algorithm, or "p" (for "previous") to move to the one we were just at, Interface. Or, if you want to learn more about the algorithm in detail, choose something from the Menu here at the node Algorithm. If you're just trying to get an overview of the algorithm, the recommended way is of course to choose Parser Function fom the menu, and then use a chain of "n" commands to move you through Lexical, Error Reporting, and Action Features. They too have their own menus, and you can follow them if you choose. Notice also that the top of each node shows information about its location in the Info tree. The header line of this node says: File: bison.info, Node: Interface, Next: Algorithm, Prev: Grammar File, Up: Top The "File:" tells you the name of the actual file on disk that this stuff is contained in. "Node:" just tells you which node you are at currently, "Next:" tells you which node you'll go to if you type "n", and "Prev:" tells you the "p"revious node. "Up:" tells you the name of the parent node. This header says "Up: Top", meaning that if you go up to this node's parent, you'll be at the top level of the Bison Info, which is itself a child node of DIR, the absolute top-level node for all of Info (I've been calling it the Main Menu). Moving up to a parent node is done by pressing "u". There are two other commands that you will want to know about: "l" and "f". "l" (for "last") moves you to the last node you were at before you came to the current one... however, pressing "l" twice does not flip you back and forth between two nodes. It moves you back through the nodes you have visited, in the order you visited them in. In technical terms, the node you move out from by pressing "l" is not pushed onto the "stack" history of nodes that Info keeps as you go, but any other method of leaving a node *will* put that node on the stack, so that if you get lost, you can get back to familiar territory by pressing "l" some number of times in succession. The other command, "f" (for follow) is to be used when you see something in the text like this (*note Language and Grammar::.) . I just picked that out of the Bison Info. It's a cross-reference to some other page in Info that has relevance to whatever node you are at at the moment, and it might be somewhere totally different in the Bison Info. If you choose to follow this link, the "l" command is probably the handiest way to get back to where you were. Cross-references are usually not as important to read as menu items -- if they were, they'd be on the menu, after all! So, a short summary of commands for Info, including a couple of new, self-explanatory ones: n Move to the "next" node of this node. (move sideways in the tree structure, to the right) p Move to the "previous" node of this node. (move sideways in the tree structure, to the left) u Move "up" from this node. m Pick menu item specified by name (or abbreviation). (Picking a menu item causes another node to be selected.) f Follow a cross reference. Reads name of reference. l Move to the last node you were at. Space scroll forward a page. DEL scroll backward. b Go to beginning of node. q Quit Info: (reselect previously selected buffer, if in Emacs). ? Get a short summary of Info commands, like this one. The online Info tutorial is highly recommended, as well, it can be invoked with "h". The best way to get a feel for Info is to browse through it for a while. After getting used to Info, you may find manpages hard to go back to, though! Also, read the Info on Info itself, to learn how to add new documentation to the tree (not hard at all: I learned how to do it after about five minutes reading). * Getting and Installing Info. The easiest way is to get it is with Emacs as a package and let it unpack itself into the correct directory. My info files live in /usr/local/emacs/info, and I assume it's the same on most Linux systems. There are 166 files in my info directory, but you will probably have fewer than that to start out with. The most important one to make sure you have is the one called dir, since it contains the DIR node, the one that is parent to everything. I guess the next most important one is the file "info", since info about Info is most necessary of all. You should never have to worry about these files, since as long as they're in the right place, Info will deal with them correctly. All you need to do is deal with Info :-) The actual Info program executable is located in /usr/TeX/bin, but that's just my system. /usr/bin or /usr/local/bin is probably a better spot. That executable should only be necessary for the free-standing Info program. If you just want to run Info in Emacs, you don't need it, since the elisp code in info.el is what Emacs runs when you do Info from it.