-*-TAGS-*-

-*-Text-*-	This is The INFO Info file.

File: INFO,	Node: Top,	Up: (DIR)Top,

	INFO is the powerful Document Reading System On RSTS/E.

If this is your first time using INFO, Tyee the letter "H" to run the primer.

* Menu:

* Command Summary::
* Advanced Commands::
		Searching, Outputting to files, and GO-TO's
* Adding Documentation::
* Reporting Info Bugs::
* CCL Options::			Specifying things on the command line.
* Private INFO Branches::
					For developing documentation,
					or keeping references to private 
					information to yourself.








File: INFO, Node: Command Summary,		Up: Top,
	Next: Advanced Commands

	<	Last Half screen 		currently the half screen
	>	Next Half screen		commands are just for Teleray,
	SP	Next Screen			hewlett packard, and H19'
	BS	Last Screen			terminals.
	P	Prev node	
	N	Next node
	U  	Up  to Parent Node
	D	Returns to DIR node 
	L	Go to Last full INFO format  Node	 
	B	Beginning of Node	
	M	select Menu Item
	S	Search for string (in current and subsequent screens)
	O	Output node to File
	T  	like B (But types all of node on printing terminals
	Q	QUIT!!!
	H	Go to HELP Tutorial  			(? prints help lines)
	^L	Retypes Page and^O Stops Output 



File: INFO,	Node: Advanced Commands,	UP: Top,
	Prev: Command Summary, Next: Adding Documentation, Up: Top

  If You are ready to learn about the "advanced" INFO commands, then
INFO probably does not seem very challenging anymore.

Outputting to files:

Use the O command.  You will be prompted for a file name.  If you
just type a Return, the current node will be output to the file whose
name is displayed by the O command Prompt. This is the default. If you
specify another file name, INFO will try to write to that file, and if
successful, will make that file the default for next time.

Searching:

Use the S Command. INFO will prompt for you to type in a string. It will
display occurences as it finds them, and it will ask you if you wish to 
position the screen around where it found your string. Answering "Y"
will do this and "N" will search for the next occurence.

Jumping To Nodes:

The word "GOTO" is hated by structured programmers around the globe, but
thats what the "G" command does. If you know the full name of any node,
you can go directly to it, bypassing the tree structure with this command.

* Note:  All of the above commands can be aborted by typing Control-G to
the command's Prompt.



File: INFO,		Node: Adding Documentation,		Up: Top,
	 Prev: Advanced Commands,	Next: Reporting Info Bugs

	Adding New documentation to INFO is easy and straightforward.
	There are two classes of text files as far as info is concerned.
	The best type, in INFO's opinion is the "INFO format File".
	All files which are not in info format are called "Non-INFO files"
	INFO will handle both kinds, but it is preferable to install INFO
	format files, because they make locating information much simpler
	for the user.	


* Menu:


* How Info works::
* INFO nodes::	How to make nodes and put them together.
* Making Menus::
* Converting a Manual::		A good way to Add INFO nodes
* Non INFO format files::
				The quick and dirty approach
* Compiling an Info File::
				Using the INFO file compiler prior to 
				installing your documentation will speed up
				access to individual nodes by eliminating
				wasteful searches. (compiling is not required
				however)




File: INFO,	Node: How Info works, Up: Adding Documentation,
	Next: Info Nodes

An INFO file looks roughly like this:

	^_------|
	|	|		The file is broken Up into NODES.
	| Node	|		There is no requirement for any particular
	|	|		number of nodes in an INFO file. Generally
	^_------|		You create a new node when you wish to 
	|	|		distinguish one subtopic from another.
	| Node	|
	|	|		The horizontal lines shown here separating
	^_------|		the nodes are not "real lines". Instead, INFO
	|	|		knows that a node is separated from its
	| Node	|		neighbor by an ascii US (CHR$(31)).  This
	|	|		separator will echo as "^_" within Teco.
	^_------|		On telerays, use ^? to create it.

		See the Next node for details on Node Construction.



File: INFO,		Node: INFO nodes,	Up: Adding Documentation,
	Prev: How INFO works,		Next: Making Menus

	An INFO node Looks as follows:
^_
|---------------|
|  header	|	The header is composed of the first two lines
|		|	of the node, and the "body" is the rest.
|		|
|     body	|	The purpose of the header is to convey to INFO
|		|	(and the user) where INFO will go with the N,P,U,L
|---------------|	Commands.
^_
		NOTE:	A node ELEMENT must be terminated with one of the
			three characters: comma (,), tab, or carriage return.
			Comma is the on usually used.
		
There are up to five ELEMENTS of the node header.
 these are:
	1) "file:"	Name of File node is in.  This
			IS optional, but without it, INFO's
			memory for the L command is not 
			updated (which is occasionally useful)

	2) "Node:"	Mandatory. This is what INFO looks for when
			going to a new node. If this node's name is FOO,
			then this part of the header should read:
			"Node: FOO"

	3) "Up:"	Optional. If these are present, they tell info the
	4) "Prev:"	  names of the nodes to go to for the U, P, and N
	5) "Next:"	  commands respectively.

SAMPLE NODE:

	 ^_
	|File: baz,	 Node: Foo,	 Up: foo's up,   |
	|	Prev: Foo's Prev,	Next: Foo's Next |
	|						 |
	|	This node tells you all you ever	 |
	|	wanted to know about the topic FOO.	 |
	|						 |
	|* Menu:					 |
	|* Afoo::					 |
	|* Bfoo::					 |
	|* Cfood::					 |
	|						 |
	|	Some more text can convey info here.	 |
	 ^_

Notice that line "* Menu:" above! It tells Info that the node has a menu.
The following lines that begin with "* " are MENU ITEMS.  They tell how
to get to the other nodes.

Type "N" now to learn how to make a menu.



File: INFO,		Node: Making Menus,	Up: Adding Documentation
	Prev: INFO Nodes,	Next: Converting a manual

	A menu consists of two parts.  The first part is VERY IMPORTANT.
It consists of a line containing solely the text "* Menu:". This line
exists just to tell info that a list of Menu Items follows.

The rest of the menu consists of lines beginning with "* ".  Consider the
following example of a menu name:

* FOO::			;This tells INFO that there is a menu item named
			 "FOO".  Info should be able to find it later on
			 in the file.

The following is also a valid name:

* Languages: 	FOO	;This is a menu item that has info about Languages
			 but the Node has a different name. This form is
			 not used too often, but the following similar
			 form is used very frequently:

* Library Index: (LIB)Top
			;This is also a case of the node name being different
			 from the subject name. Here The subject Name is
			 "Library Index" but the NODE NAME is "(LIB)Top.
			 The Part in parenthesis is a FILE NAME. 

* Menu:

* Node Name Formats::		How to form Node Names in a menu
* File Name Formats::		How to form the file part of a node name



File: Info,	Node: Node Name Formats,	Up: Making Menus,
	Next: File Name Formats

	A NODE NAME can be of any length.  Concise names are reccommended,
	however. 

	When the Menu Item name is the same as the Node Name, it must be
	terminated with two colons as follows:

* Foo's Node::

	When the menu item name and the Node name need to be different,
	The menu name should be terminated with a single Colon followed by
	one or more spaces or tabs. The first non space/tab character is
	the first name of the "NODE NAME".  The Node Name should be
	terminated with either a TAB, or a Carriage Return as follows:

* FOOBAR:	Foo's Node
* FROBOZZ:	Foo's Node	following the preceding
				word "Node" is a TAB.

	Notice that these two menu items both point to the same node. This
	is both allowed and encouraged.  Also legal to achieve the same 
	effect are the following:

* Name One,			Both of the names to the left
* Name Two::			will get you to "Name Two"

* Name Three,			Both of the names at left will
* Name Four:	(FOO)Bar	Get node "Bar" in file "FOO"

	INFO's Menu Command will in the above special cases look for
	"* " followed by the MENU NAME, and then extract the NODE NAME
	from the first subsequent line containing a ":".

For INFO on File name formats, type an "N"



File: Info,	Node: File Name Formats,	Up: Making Menus,
	Prev: Node name Formats,

	To tell INFO that the node you are looking for is in a different
	file, the node name must include a file name. A node name that
	contains a file name looks like this:

	(Foo)Bar
		where (FOO) says that the file's name is FOO and the node's
	name is BAR. Actually the file's name is "FOO.INF".  The default
	extension for an INFO file is ".INF". If the file does not have
	an extension of ".INF" you must include it too:

	(QUE.HLP)

	There are several special characters that INFO recognizes in place
	of extension names. They are:
	#	for .HLP	(FOO.HLP) becomes (FOO#)
	=	for .EXE	(BAR.EXE) becomes (BAR=)
	!	for .INS	(BARFOO.INS) becomes (BARFOO!)

***	A file that is not in INFO format should not have a Null filename
	Instead, a nodename of "*" should be used. This disables INFO's
	node bounds checking.
	Example:
	(Myprog.BAS)*



File: INFO,	Node: Converting a Manual, Up: Adding Documentation
	Prev: Making Menus,	 Next: NON Info Format files


Converting an existing manual to INFO format is a common approach.

Each chapter can be a Node, with subchapters being subnodes.  

Step 1)
	Edit in Nodenames in place of the chapter names.
Step 2)
	Run The INFO compiler. This will generate a list of nodenames
	one after the other just before the enad of the file. Copy 
	this to the top of the file, and edit it into a Menu. 

Step 3)
	For each node that you think should have its own menu too, perform
	Steps 1 and 2.




		
File: INFO,	Node: Non INFO format files, Up: Adding Documentation
	Prev: converting a Manual,	Next: Compiling An Info File


	It is preferred that all files in the tree be in INFO format,
	but some times you might want to add an existing Non INFO file

	In such a case, Use the nodename "*" after the file name.
	This disables INFO's	node bounds checking.
	
	Example:
	(PIP.TXT)*

***	A file that is not in INFO format should not have a Null Node name.
***





File: INFO,	Node: Compiling an Info File, Up: Adding Documentation
	Prev: Non INFO format files


	"Compiling" is kind of a Misnomer. There is no major conversion
	done by the INFO compiler.

	What the INFO compiler does is to create a table at the end of
	the file that INFO uses in node searches. This allows INFO to
	directly go to the node without having to search the whole file.

	The compiler may not be called from within a macro such as VTEDIT.

	the compiler does not save your file. You must still exit Teco
	normally.  This allows you to make any changes, and recompile
	before leaving TECO.



File: INFO,	 Node: Reporting INFO bugs,		Up: Top,
	Prev: Adding Documentation,	Next: CCL Options

If you have had any problems using INFO, there is a facility for reporting
problems when they are still fresh in your mind.

do:
MU [44,12]BUG INFO

After a few seconds,the screen will clear and a message header will be
printed. At this point you may type your message. There will always be
a funny mark after the cursor. This can be ignored. when you
have finished typing your message, Control Z will send it, or you can abort
your bug report with control G.

At the present time, the BUG program may ONLY be run from a terminal that
from which VTEDIT or EDMACS can be run from.



File: INFO,	Node: CCL Options,	Up: Top,
	Prev: Reporting INFO bugs,	Next: Private INFO Branches

  CCL Options are things that you specially tell INFO
  when you start it. There are two kinds. The first kind are
  "Menu Options". You can Specify  at the end of the command line,
  the name of one of the Menu items in the DIR node.

  example:	 MU [44,12]INFO Lib Index


  Other CCL Options, called "switches" tell INFO what
  kind of terminal you are using.

  When Starting INFO, you can use any of the following on the command
  line:
		/H19	/VT52	/T10	/Vt100	/HP	/PRINTING

  The above switches represent in order, the following terminal types:
	Heath H19, Dec Vt52, Teleray 10, Dec Vt100, Hewlett Packard, Printing

  If you are on a Campus teleray 10, You normally need not specify
  your terminal.  Most hardwired terminals are known to the system
  as Teleray 10's.

  HEWLETT Packard terminals ALWAYS require the /HP option, and terminals
  that are not in the above list will almost always need to use the 
  /PRINTING option



File: INFO, 	Node: Private INFO Branches, 	Up: top,
	Prev: CCL Options

The main node of the INFO tree (the node called "(DIR)Top" ) contains
a menu Item called "Private Information"

If you select this menu Item with the Menu command, INFO will look in your
directory for a file called MYDIR.INF, and then look for a node called "Top"
in that file.

  You can use this node as the Top node of new documentation, if you are
documenting something, whether for yourself, or for the computer center.
If you are an instructor, you can make it point to copies of the assignments
you give your students.  This can help both the consultants and the
students, who can print out copies with the "O" command. (Your students
will need to use the "G" command to get to your private node. )

This last example will only work if you allow read access to your private
directory node, but you can still make it point to files that can only be
read by you. INFO will then give an error message to anyone else trying 
to access these files.



TAGS: :SGAT
Top:57
Command Summary:601
Advanced Commands:1261
Adding Documentation:2507
How Info works:3501
INFO nodes:4260
FOO":5224
Foo:5429
Making Menus:5989
Node Name Formats:7170
File Name Formats:8483
Converting a Manual:9432
Non INFO format files:10051
Compiling an Info File:10534
Reporting INFO bugs:11160
CCL Options:11862
Private INFO Branches:12933