What is Para mode?
=================

Para mode is an extension of Texinfo and Infosim mode that includes some hypertext-like features.  I chose the name `Para mode' (from the Greek word for `beyond') to suggest that it is `beyond' Texinfo mode or Infosim mode, but not to claim that it is a full-fledged hypertext system.  (Suggestions for a better name are welcome.  One alternative is to call this `Notetaker'.)

This mode may turn out to be useful for writing Texinfo source files, although the original inspiration was to create a small hypertext-like system.   You may edit any Texinfo source file using Para mode.

Indeed, my plan is to fully integrate Para mode into Texinfo mode. Also, the name will be changed.

The code for this mode is in `alpha-test'.  Please do not distribute it widely.

Robert J. Chassell      17 Dec 1989      bob at ai.mit.edu    Thank you Copyright (C) 1989, 1990, 1991 Free Software Foundation

Changes:

17 Apr 91 - 0.13 - Put two at-signs in front of sample commands, so you can format file for Info.

27 Mar 91 - 0.12 - Para mode indexing commands explained.

5 Mar 91 - 0.11 - Added new commands with both Info-like keybindings and C-c C-p prefix keybindings: para-top-node, para-final, para-goto-next-node-in-sequence, para-goto-previous-node-in-sequence. Added `para-tagify', which is bound to `C-c C-p t' Changed `scroll-up' to `para-scroll-up', which leaves point in same location. Rebound `para-directory' to `C-c C-p d' to make consistent with other commands.

12 Feb 91 - 0.10 - Extensively edited and reorganized; confirms to new keybindings and new commands.

4 Jan 90 - 0.07 - Re-organized and re-ordered whole file.  Revised description of `para-directory', which now displays the first menu in a temporary buffer; also, the cross reference commands in the temporary buffer now offer default node names and topics. Similar for para-visited-xref'.  The `para-xref' command offers node name completion and a default value for the topic description.

26 Dec 89 - 0.06 - Revised description of `para-add-node' 26 Dec 89 - 0.05 - `para-master-menu' now updates node pointers as well as menus and is bound to a key 23 Dec 89 - 0.04 - Added `para-list-visited-nodes', `para-goto-visited-node', and `para-visited-xref' information 22 Dec 89 - 0.03 - Added `para-master-menu' and `para-directory' information 21 Dec 89 - 0.02 - Changed description of `para-add-node' to reflect new changes.

How to try this
===============

Load `para.el' and then type `M-x para-mode' in this file to convert it to para-mode; or else find this file after loading `para.el'.  In the latter case, the mode specification line will automatically cause Emacs to select Para mode.  For more information about loading para automatically, see Loading Para Automatically.

If you are not in Para mode right now, as you read this, type `M-x para-mode'.  You should see `Para Narrow' in your mode line.  Also, this should be the next to last line visible to you in this buffer.  Now type `C-c C-p C-n' (para-next) to reach the next node.

To get here from the top of the file, you typed `C-c C-p C-n' (para-next), which is the command for going to the next file.

To return to the beginning of the file type `C-c C-p C-b' (para-beginning).

This top node has no `previous' node, but in nodes that do have a `previous' node, type `C-c C-p C-p' (para-prev) to go to it.

If you are reading this the first time, you will want to select the first entry on the menu by typing `C-c C-p 1' or else by putting the cursor in the upper left corner of the window and typing `1'.

(Or you can use the `para-goto-next-node-in-sequence' command.)

Here is the menu:

Quick Directions
****************

You can move through the file from node to node in strict sequence by typing `C-c C-p C-[' (para-goto-previous-node-in-sequence) or `C-c C-p C-]' (para-goto-next-node-in-sequence)

Also, if your cursor is in the upper left hand corner of the window, or if the buffer is read-only, you can use the Info mode commands, which are single keys such as `b' and `n'.  These commands execute `para-beginning' and `para-next' just as `C-c C-p C-b' and `C-c C-p C-n' do.  All the movement commands have keybindings.

If your cursor is in the upper left hand corner of the window, or if the buffer is read-only, you can scroll forward by typing SPC and scroll backward by typing DEL.  You can combind the SPC scrolling command and the `]' node movement command to move though the complete file.

You can select a node listed in a menu by typing `C-c C-p 1', `C-c C-p 2', etc., to go to the first node listed, the second node listed, etc.; or you can place the cursor over the name of the node, type `C-c C-p C-m' (para-menu) and then type the menu name (or part of it), followed by pressing RET.  (The `para-menu' command will even take you to another file.)

To go to the next node in this file, type `C-c C-p C-n'.

Or, if your cursor is in the upper left hand corner of the window, or if the buffer is read-only, type `n'.

Summary of How Para Mode Works
******************************

Within Para Mode, it is easy to create new nodes and provide references for them.  It might be more appropriate to call `Para mode' `Notetaker mode' except that the latter name is long.

What you do is create a Texinfo source file, using several helpful commands, and then move around the file using Para mode.

You can use Para mode as a convenient way to write Texinfo source files or as a hypertext-like system.  In the latter case, you use Para mode to write `notes'.  The rest of this document is designed for this use.

Notes are `nodes' in Texinfo.  You reach such nodes either by following menus to them or by following cross references or by searching through the file for a regular expression within the node.

Para mode has special commands for writing cross references as well as for other tasks.  A cross reference look like this: see Making Cross References.

Para mode offers commands similar to those in Info mode, even though the file is in Texinfo format rather than in Info format.  (This is a feature of Infosim mode from which Para mode derives.)  Using the Info inspired commands, you can move forward and backward in the Texinfo file.

Using commands adapted from Texinfo mode, you can create a master menu of all the nodes in a file.  In the menu, you can use the Emacs search commands to search for node names or for words mentioned in node names and thereby easily find a node on a specific topic.

If you wish, after creating your Texinfo file, you may convert it to an Info file or even print it out as hardcopy; or you may continue to use Para mode.  (Note that this version of this file is not written to be run through TeX or converted to Info, although it might be possible to do that.)

What a Para Mode File Is
========================

A Para Mode file is a Texinfo file.  Minimally, you need a `top' node in the file.  The node name `top' must be followed by a comma.

A top node looks like the following, except that in the source version of this file, two `@' are used together, so Emacs does not interpret this example as a node:

@node Top,

Of course, the node should also list the `Next', `Previous' and `Up' pointers.  Fortunately, you do not have to do this yourself.  If you use the `C-c C-p a' (para-add-node) command, the pointers and immediate menu are updated.  And you employ the `C-c C-p m' (para-make-master-menu) command to update every node pointer and menu and create a master menu.  See Using the Main Menu.

With its next, previous, and up pointers, a top node looks like this:

@node Top, Next-node, (dir), (dir)

You may also include a header at the beginning of a Para Mode file.

You can see the heading at the beginning of this file by typing `C-c C-p C-b' (para-beginning).  (You can return to this node by typing `C-c C-p C-l' (para-last).)  Strictly speaking, such a full heading is not necessary for Para Mode, but it is useful.  The heading is standard for Texinfo source files.

The `\input texinfo' in the first line is for when you run TeX on the file. The command tells TeX to use the texinfo.tex macro file.  The `-*-para-*-' in the first line is a mode specification that causes Emacs to select Para mode automatically when you load the file.

Para Mode Commands
******************

The default Para mode keybindings are compatible with Texinfo mode and all the Texinfo mode keybindings are provided.  For example, you can use `C-c C-u C-e' (texinfo-every-node-update) to update every node in a Para mode file.

The prefix keys for the different groups of Texinfo commands are:

; TeX commands              prefix key: `C-c C-t'
; Elisp formatting commands prefix key: `C-c C-e'
; C code commands           prefix key: `C-c C-m'
; Updating commands         prefix key: `C-c C-u'
; String insertion commands prefix key: `C-c C-c'

The prefix keys for the commands specific to Para mode are:

Para indexing commands    prefix key: `C-c C-x'
Para mode general         prefix key: `C-c C-p'

In addition, there are `shortcut' keybindings you can use in certain circumstances.  See Shortcut Commands.

Prefix Command Conventions
==========================

Two forms of Para mode command use the `C-c C-p' prefix:

* movement commands similar to those you use in Info: type the Para mode general prefix key followed by a control key, for example, `C-c C-p C-n' (para-next)

* insertion and listing commands: type the Para mode general prefix key followed by a letter, for example, `C-c C-p a' (para-add-node)

(The keybinding for `C-c C-p n' (para-narrow-to-node) is the exception to this rule.)

Info-like `Shortcut' Movement Commands
======================================

When point is at the upper left of the window or the buffer is read-only, you can use the Info commands as is, `n' for next, `p' for previous, and so on.  But when point is elsewhere, the key strokes merely insert themselves as you would expect (so you can edit the file) and you have to use commands with a control prefix, as in `C-c C-p C-n' (para-next).

The commands are:

1        para-menu-1            go to the node of the first menu
2                                 item, etc.
...

b        para-beginning         go to the very beginning of the file
<        para-top-node          go to the top node
>        para-final

d        para-directory         display the first menu from the file
in a special buffer.
f        para-follow            follow a cross reference
g        para-goto-node         go to the named node
l        para-last              go to the last node you visited
m        para-menu              select a menu item
n        para-next              go to the next node
p        para-prev              go to the previous node
[        para-goto-previous-node-in-sequence
]        para-goto-next-node-in-sequence

q        para-quit              switches you to Texinfo mode.
s        para-search            regular expression search through file
u        para-up                go to the up node

SPC      para-scroll-up         scroll the text upwards
DEL      para-scroll-down       scroll the text downwards

Basic Para Mode Movement Commands
=================================

You can move through a Para mode file using the regular Emacs commands if you widen the buffer with the `C-x w' (widen) command.  Also, you can move from one to the next or previous node in strict sequence, regardless of the next or previous node's hierarchical level, by typing `C-u C-c C-p C-n' or `C-u C-c C-p C-p' (`para-next' or `para-prev' with a prefix argument) or by using the `C-c C-p C-[' and `C-c C-p C-]' commands.  Otherwise, the movement commands work as they do in Info.

Here is a list of the Para mode movement commands:

* Quit:

C-c C-p C-q         para-quit           switches you to Texinfo mode.

* Move:

C-c C-p C-n         para-next           go to the next or previous node;
C-c C-p C-p         para-prev           with prefix arg, go to next
node in strict sequence

C-c C-p C-[         para-goto-previous-node-in-sequence
C-c C-p C-]         para-goto-next-node-in-sequence
go to next or previous node
in strict sequence

C-c C-p C-u         para-up             go to the up node
C-c C-p C-l         para-last           go to the last node you visited

C-c C-p C-b         para-beginning      go to the beginning of the file
C-c C-p C-<         para-top-node       go to the top node
C-c C-p C->         para-final   go to the end of the file

C-c C-p C-g         para-goto-node       go to the named node

C-c C-p C-f         para-follow         follow a cross reference, even to another file

* Goto menu items:

C-c C-p C-m         para-menu           select a menu item (commands with the same keybinding work in the special buffers listing nodes)

C-c C-p 1           para-menu-1         go to the node of the first menu
item, etc.
C-c C-p 2           para-menu-2
C-c C-p 3           para-menu-3
C-c C-p 4           para-menu-4
C-c C-p 5           para-menu-5

* Make directories---rather like tables of contents:

C-c C-p d           para-list-directory display the first menu from the file in a special buffer. Use `m' or `C-c C-p C-m' in buffer to go to menu item.

C-c C-p l           para-list-visited-nodes display the most recently visited nodes in a special buffer use `m' or `C-c C-p C-m' in buffer to go to menu item.

* Search:

C-c C-p C-s         para-search         regular expression search through file from point

* Don't forget:

C-g                 keyboard-quit       the standard Emacs key to cancel a command or escape a problem

Movement to Other files
=======================

The `para-menu' and `para-follow' commands not only take you to nodes in the current buffer, but also find other files.  Files must be located in the current directory, or else their names must be spelled out completely.

Referenced files should be Texinfo mode or Para mode files; other kinds of file will be found, but Emacs will signal an error, that no node is found.

The `para-menu' and `para-follow' commands act on the other file as if it were a Para mode file.

In a menu, an entry for another file has to possess either of the two following formats:

* item:(filename).             description.
* item:(filename)nodename.     description.

(The `description' is optional.)

The file name must either be to a file in the current directory or a full, absolute pathname. Para mode finds the file and attempts to visit it in Para mode.

In a cross reference, the format must follow the format used in Texinfo, with one difference: instead of providing the Info file name, provide the Texinfo file name, including the absolute path name, as in this example:

See Making Cross References (The Texinfo Manual), for details.

As with the `para-menu' command, `para-follow' finds the file and attempts to visit it in Para mode.

Note: it would be desireable to enhance Para mode to select automatically the mode for a visited file according to the type of file; this would make it possible to make references to Info files.

How to Create Files and Add Nodes
=================================

By convention,the keybindings for the Para mode creation commands consist of the Para mode prefix followed by a letter.

Para Mode has two fundamental creation commands: one for creating a Para mode file, and the other for creating nodes within the file.

C-c C-p f       para-make-file      create a Para mode file

C-c C-p a       para-add-node       create a node

Use `para-make-file' to create a Para mode file. If you are not visiting a buffer in Para mode mode type:

M-x para-make-file

If you are visiting a buffer in Para mode mode type:

C-c C-p f

Emacs will prompt you for the filename and for the hardcopy title.  To make the Info file name, `.info' is appended to the filename.  You may wish to edit this by hand.  If the file already exists, an error is signaled.

Of course, you may edit any Texinfo source file using Para mode.  Just type `M-x para-mode' while visiting a buffer in Texinfo mode.

When you are visiting a file in Para Mode, you may create menus and nodes within it using the `C-c C-p a' (para-add-node) command.

As an exercise, you may create a new Para mode file called `foo' by typing `C-c C-p f' (para-make-file) and then `foo' when prompted.

To create a node, type:

C-c C-p a

If the new node is at the same or lower hierarchical level as the preceding node, the `C-c C-p a' (para-add-node) command creates new node and section headers and inserts them at point.

But if the new node is at a higher hierarchical level, the command inserts the new node and section headers just before next node at the same level of the new node.

Usually, you type `C-c C-p a' without a prefix argument.  In this case, the new node is the same type as the preceding node and the new headers are inserted at point.  You are prompted for the node name and title.

However, if you type a prefix argument before typing `C-c C-p a', Emacs will prompt you for the type (that is, for the hierarchical level) of the node.  This command looks like this:

C-u C-c C-p a

In this case, the default type is one level lower than the preceding node (unless the previous node is already at the lowest level).

In addition, the `C-c C-p a' (para-add-node) command updates pointers in the relevant previous and next node lines and updates the appropriate menu (but not the master menu, unless the added node is a chapter).

After you have created a node, you may type within it.

How to Narrow and Widen
=======================

After your have created a new node, you may want to narrow to it; and you may want to widen the file.  The commands are:

C-c C-p n       para-narrow-to-node narrow the region so you have access only to the current node

C-x w           widen remove restrictions from current buffer, allowing full text to be seen and edited

(The `widen' command is the standard Emacs command; the default keybinding for `para-narrow-to-node' is the exception to the rule that letters are for creation or insertion commands.)

If you remove restrictions from current buffer, you may still use one of the Info movement commands, but if you do, the buffer will automatically become narrowed.

How to Create Menus and Outlines
================================

Inside a node you can create a template for a menu and position point within it with the `C-c C-p i' (para-insert-menu) command.  You can type your entries in the menu.  Then you can create nodes for each entry.  Each node uses the node name for the entry and uses the text from the description for the section title.  This way you can use the menu as an outline and then expand on the outline in each node.

This provides an alternative method for writing Para documents than the method that uses the node and menu updating commands for creating or updating node pointers and menus.  The one method is a `top down' writing technique; the other is a `bottom up' technique.  Or you can combine the two techniques.

C-c C-p i       para-insert-menu insert a Texinfo menu template and position point in it

C-c C-p e       para-menu-explode create new node and section headers at the end of the current node, using the existing menu for the names of the nodes and for the titles for the sections

For more information about `para-menu-explode', see Expanding an Outline.

Expanding an Outline
====================

You can write menus in Para mode and then use the `C-c C-p e' (para-menu-explode) to create new node and section headers at the end of the current node, one for each entry in the menu.

Each node name is the same as in the menu, and the section title following the node is the same as the descriptive string for the menu entry.

The command is:

C-c C-p e           para-menu-explode

The section titles are automatically inserted one hierarchical level lower than the node preceding the menu.

If you want to create chapters following a menu written after a `Top' node, write an `@top' command after the `Top' node line, like this

@node Top @top

(except that in the source version of this file, two `@' are used together, so Emacs does not interpret the example as a node.)

The `@top' command is a command that produces results like `@unnumbered' in Texinfo mode but is understood by `para-menu-explode' to indicate the top node.

Indexing
========

You can insert index entries in a Para mode file and use these to create indices similar to those in Info.  You can use the regular Para mode menu command to go to nodes listed in the index.

The indexing commands use `C-c C-x' as the prefix key.

Para mode has six index entries commands, one for each of the predefined index types:

C-c C-x c       para-index-concept
C-c C-x f       para-index-function
C-c C-x k       para-index-keystroke
C-c C-x p       para-index-program
C-c C-x t       para-index-datatype
C-c C-x v       para-index-variable

The `para-insert-index' command causes @printindex to insert the appropriate index menu in the Para mode file just after each @printindex command.  (The index menu is inserted between @ignore and @end ignore so you can safely format the file for TeX or Info if you wish.

C-c C-x x       para-insert-index

To insert an index entry at the end of the paragraph type `C-c C-x' and then a key corrsponding to the type of index entry you wish to make, `f' for function index, `c' for concept index, etc.  For example, you would type the following to make an entry in the index of variables:

C-c C-x v

An indexing commands attempts to offer you a default entry, based on the characteristics of the text following point.

Also, the indexing functions insert index entries after moving point forward one paragraph.  Usually, this is just what you want.  But if not, you can type `C-u' first and then the command will insert the entry at point, but in this case it will not offer you a default, either.

A `C-c C-x f' (para-index-function) command offers the first symbol following point within paragraph that is enclosed by the braces of @code command.

A `C-c C-x v' (para-index-variable), `C-c C-x p' (para-index-program), or `C-c C-x t' (para-index-datatype) command works similarly to `para-index-function'.

A `C-c C-x c' (para-index-concept) command offers you the word following point as the default; with a numeric prefix arg, the command offers you that many words following point as default.  However, with a prefix arg that is not a numeric prefix arg, the command does not offer a default and inserts the entry at point.

A `C-c C-x k' (para-index-keystroke) command offers a default that depends on where point is located:

1. If point is at beginning of an @item or @itemx line, `para-index-keystroke' offers rest of that line as default.

2. Else, `para-index-keystroke' offers the first symbol following point within the paragraph that is enclosed by the braces of a @kbd command.

As with the other commands, with a prefix arg, `para-index-keystroke' the command does not offer a default, but insert the entry at point instead of at the end of the paragraph.

Node and Menu Updating Commands
===============================

Use the `C-c C-p m' (para-make-master-menu) command to create and update all the node pointers and menus, and to create a master menu for the Texinfo file.

C-c C-p m           para-make-master-menu

The `para-make-master-menu' command is very useful.  Use it to make a master reference for all your notes.  The command creates an extended menu located after the top node.  (The file must have a top node.)

In interactive use:

1. With no prefix arg, make a regular master menu, first removing detailed part of pre-existing master menu, if there is one.

2. With prefix arg, first update all existing nodes and menus (incorporating descriptions from pre-existing menus), first removing detailed part of pre-existing master menu, if there is one.  The command is:

C-u C-c C-p m

3. With numeric prefix arg, insert an indented master menu.  All the nodes are in sequence.  The command is:

C-u 7 C-c C-p m

4. With negative numeric prefix arg, first update all existing nodes and menus (incorporating descriptions from pre-existing menus).  First remove detailed part of pre-existing master menu, if there is one, then insert an indented master menu. The command is:

C-u -7 C-c C-p m

The `para-make-master-menu' command constructs a master menu that that follows the top node and includes every entry from every other menu. On a large file, the whole process may take quite awhile.

The command replaces any existing master menu, first removing the detailed part of an already existing master.  (This action depends on the pre-exisitng master menu using the standard `texinfo-master-menu-header'.)

A regular master menu has the following format, which is adapted from the recommendation in the Texinfo Manual:

* The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections, and the major appendices.  This includes the indices, so long as they are in chapter-like sections, such as unnumbered sections.

* The second and subsequent parts contain a listing of the other, lower level menus, in order.  This way, an inquirer can go directly to a particular node if he or she is searching for specific information.

Each of the menus in the detailed node listing is introduced by the title of the section containing the menu.

An indented master menu consists of all the menu entries in the buffer, in sequence, with lower level menus indented according to their hierarchical level.

NOTE: In Para mode, the menu commands work with indented menus. However, they do not work with indented menus in Info.  Do not construct an indented menu for a Para mode file that you plan to convert to Info.

Here is a sample indented menu:

* Context::                     The basis of the discussion
* Locating Info::               Locating information in large stores
* Locating Interface::          Need for a good user interface
* Inferior Processes::          Running processes inside of Emacs
* Notetaking Tool::             Taking random notes
* Enhancements::                What to do next
* Semi-structured Notes::       Organizing as best you can
* Lost in Hyperspace::          Where is that note?

Indented menus make it easy to see the structure of a file with fewer than 15 or 20 nodes.  However, the standard Texinfo master menu format provides a clearer outline of a document with many nodes.

The master menu is the first menu in a file and is the menu for which the `C-c C-p d' (para-directory) creates its special buffer.

Two other sometimes useful commands are:

C-c C-u C-e     texinfo-every-node-update update every next, previous and up pointer in the file

C-c C-u C-a     texinfo-all-menus-update create as needed and to update every menu in the file

You are most likely to use these two commands when you rearrange a file by moving nodes around.  Generally, this is rare.  Also, the `para-make-master-menu' command automatically runs both these commands whenever it is executed.  Widen the file before using either of these two commands.

The `texinfo-all-menus-update' command preserves pre-existing description lines.

Creating A Tag Table
====================

Large files slow the Para mode movement commands.  Typing `C-c C-p t' (para-tagify) creates a tag table at the end of the Para mode file that similar to the tag table used in Info.  This table lists the locations of every node.  The various movment commands first look for a tag table and use the information in it if it is there.  (A tag table is optional.)  The tag table does not have to be up-to-date---the movement commands go to the location specified by the tag table and search in every widening circles around that location for the desired node.  And if you have a node that is not yet listed in the tag table, the movement commands will still find it, but take longer.

C-c C-p t       para-tagify create tag table at the end of the Para mode file

The tag table is enclosed in @ignore and @end ignore commands so that you can format the Para mode file without trouble.

Using the Main Menu
===================

The `C-c C-p d' (para-directory) command displays the first menu in the Para mode file in a temporary buffer called the `*Main Menu*' buffer. Usually, the first menu is the master menu.

C-c C-p d       para-directory display the first menu in a special buffer

The `*Main Menu*' buffer has keybindings that are similar to the commands in the Para mode buffer; you can type just the single letter or the longer version of the command using control keys.

Use `C-n',`n', or SPC for `next-line' and `C-p', `p', or DEL for `previous-line'.  Use `q' to bury the `*Main Menu*' buffer.

Here are the goto and reference commands:

m C-c C-p C-m     para-main-menu-goto-node goto the node whose name is under the cursor. (parallel to `para-menu') r C-c C-p r       para-main-menu-buffer-xref (based on `para-xref')

The `m' and `C-c C-p C-m' commands are bound to `para-main-menu-goto-node', which will jump you to the prompted for node in the Para Mode file. The default node is the node whose name is under the cursor; or you can type a node name (or just the beginning of one).  This command is similar to `para-menu', which has the same keybinding in Para mode.

Also, in the `*Main Menu*' buffer, `r' and `C-c C-p r' are bound to `para-main-menu-buffer-xref', which inserts a Texinfo cross reference in the associated Para mode file at the current position of point in the Para mode file.  When you type `r' or `C-c C-c C-r', you are offered the name of the node under the cursor as the default.  This saves your having to type the name.  This command is similar to `para-xref', which has the same keybinding in the Para mode file, except that this version of the command offers you default values depending on which node name the cursor is over.  See Making Cross References.

The `para-main-menu-buffer-xref' command takes an optional argument (prefix, if interactive, meaning you type `C-u C-c C-c C-r'.)  When you execute the command with the optional argument, Emacs will prompt you for a topic description as well as for the node name.

The `para-main-menu-buffer-xref' command makes it easier to insert cross references, expecially when you cannot readily remember the node names.

Listing Recently Visited Nodes
==============================

The `para-list-visited-nodes' command displays a list of the nodes you have visited in the Para mode file, most recent first.  Thus, it is similar to the `para-directory' command, except this command lists only those nodes you have visisted.  The nodes are displayed in a temporary buffer called the `*Recently Visited Nodes*' buffer.

To make the list, type:

C-c C-p l       para-list-visited-nodes

The `*Recently Visited Nodes*' buffer has keybindings just like those in the `*Main Menu*' buffer.

Use `C-n',`n', or SPC for `next-line' and `C-p', `p', or DEL for `previous-line'.  Use `q' to bury the `*Main Menu*' buffer.

Here are the goto and reference commands:

m C-c C-p C-m     para-goto-visited-node  (parallel to `para-menu')

r C-c C-p r       para-visited-xref       (based on `para-xref')

The two commands are similar to the commands in the Para mode buffer.

The `para-goto-visited-node' command carries you to a node in the Para Mode file.  It is like the `para-menu' command.  In the `*Recently Visited Nodes*' buffer, the `para-goto-visited-node' command offers you the name of the node under the cursor as a default, so you can use the list as a menu.  If the default name is what you want, just type RET; otherwise type the node name you wish.  If you type just the beginning of the node name (in either upper or lower case) and then press TAB, Emacs will attempt to complete the name of the node, thereby saving keystrokes.  But you can do this only for the node names in the list.

The `para-visited-xref' command inserts a cross reference in the current Para mode buffer at point in that buffer.  You are prompted for a node name and offered, as a default, the name of the node under the cursor in the `*Recently Visited Nodes*' buffer.  Completion is offered for other node names, but only for node names listed in the `*Recently Visited Nodes*' buffer.

The `para-visited-xref' command takes an optional argument (prefix, if interactive).  When you execute the command with the optional argument, Emacs will prompt you for a topic description as well as for the node name.

The `para-visited-xref' command makes it easier to insert cross references, expecially when you cannot readily remember the node names.

Cross References
================

You can create cross references using the `*Main Menu*' buffer or recently visited nodes buffer; or you can create cross references in the Para buffer itself.  Similarly, you can visit cross references.

The two commands are:

C-c C-p r           para-xref               create a cross reference

f C-c C-p C-f         para-follow             go to a cross referenced node, even in another file

(In the Para mode buffer itself, you cannot use the `r' command for `para-xref' since point must be located at the spot you want to insert the reference.  However, you can use the `f' command, as usual.)

To create a cross reference, type the  `C-c C-p r' (para-xref) command.

The `para-xref' command inserts a standard Texinfo `xref' cross reference into the source file, and inserts a period after it.  The command offers name completion, that is, if you type the beginning of the node name, and then type TAB, Emacs will provide the rest of the name.  This is very helpful if you are not sure of the name; and it saves typing.

(NOTE: Completion only works if the node name is listed in the `*Main Menu*' buffer by the `para-directory' command.  Type `C-c C-p d' (para-directory) to list the main menu.  If necessary, type `C-c C-p m' (para-master-menu) to create the detailed master menu for `C-c C-p d' to list. See Using the Main Menu.)

With a prefix, the `para-xref' command inserts the topic description in the reference as well as the node name.  The command looks like this:

C-u C-c C-p r

When it can, the function offers the description line for the node in the main menu as the default for the topic description.

For example, here is a reference to the chapter summarizing how Para mode works.   See Summary of How Para Mode Works.

(The same keystrokes, `C-c C-p r', may be used inside both the `*Main Menu*' buffer and the `*Recently Visited Nodes*' buffer; in those buffers, the keys are bound to special versions of the command which offer you the node name on which the cursor is placed. See Listing Recently Visited Nodes, and see Using the Main Menu.)

To follow a reference, use the `f' or `C-c C-p C-f' (para-follow) command.

The `para-follow' command will automatically bring you to the referenced node if the node you are in has only one cross reference within it.  If the node you are within has two or more cross references, the command will prompt you for the node name.  If you type just a part of the node name (in either upper or lower case) and then press TAB, Emacs will attempt to complete the name of the node, thereby saving keystrokes.

Loading Para Automatically
**************************

You must load Para mode before using it.  In particular, you must have alreaded loaded `para.el' before loading a file with a Para mode specification; otherwise, Emacs signals an error saying `void function: para-mode'.

You may load `para.el' manually or automatically.  To load it manually, find the file and then evaluate the buffer with the `M-x `eval-current-buffer' command; or else type `M-x load-file' and then type the pathname for `para.el' when prompted.

To load `para.el' automatically, you could put either of the following in your `.emacs' file:

(load "para")

or

(autoload 'para-mode "para" "Hypertext-like extension of Texinfo. Provides editing and Info-like movement commands for Texinfo files." t nil)

Be sure that `para.el' or `para.elc' is in your load path.

NOTE: The standard Emacs 18 distribution loads version 1 Texinfo files.  You need to place version 2 Texinfo files in the load path in such a manner that the load commands will load the version 2 Texinfo files and override the version 1 Texinfo files.

In your `.emacs' file, you might set your load path in a manner similar to the following example:

(setq load-path '(nil "/u/texinfo2" "/u/para" "/usr/local/lib/emacs/lisp")

(If the first element of path is nil, it signifies the current directory.)

(You may want to byte-compile `para.el'.)

The autoload function is usually preferred to the straight use of load, since autoload will load a file only when you need it.

If you either load or autoload Para mode, a file with `-*-para-*-' on the first line of the file will start out in Para mode.

You may also place the following autoload command in your `.emacs' file:

(autoload 'para-make-file "para" "Create a Para Mode file and insert its header." t nil)

This command will load Para if you are creating a Para Mode file.

Finally, you might want to add the following autoload command:

(autoload 'para-add-node "para" "Add a node to a Para mode file." t nil)

Brief Command Listing
*********************

Here is a brief listing of the commands in Para Mode:

C-c C-p f       para-make-file
C-c C-p C-q     para-quit

C-c C-p a       para-add-node
C-c C-p i       para-insert-menu
C-c C-p e       para-menu-explode
C-c C-p n       para-narrow-to-node

C-c C-p m       para-make-master-menu
C-c C-p t       para-tagify

Directory listing and related movement commands

C-c C-p d       para-directory
C-c C-p l       para-list-visited-nodes

C-c C-p C-m     para-main-menu-goto-node        (these commands parallel
C-c C-p C-m     para-goto-visited-node           each other in
C-c C-p C-m     para-menu                        different buffers)

Other movement commands

C-c C-p C-b     para-beginning
C-c C-p C-<     para-top-node
C-c C-p C->     para-final

C-c C-p C-u     para-up
C-c C-p C-p     para-prev
C-c C-p C-n     para-next
C-c C-p C-[     para-goto-previous-node-in-sequence
C-c C-p C-]     para-goto-next-node-in-sequence

C-c C-p RET     para-menu        (i.e., key chord is `C-p C-c C-m')
C-c C-p C-l     para-last
C-c C-p C-g     para-goto-node
C-c C-p C-f     para-follow

C-c C-p 1       para-menu-1      go to the node of the first menu item, etc., up to `9'

C-c C-p C-s     para-search

Cross reference creation commands

C-c C-p r       para-main-menu-buffer-xref      (these commands parallel
C-c C-p r       para-visited-xref                each other in
C-c C-p r       para-xref                        different buffers)

Indexing commands

C-c C-x c       para-index-concept
C-c C-x f       para-index-function
C-c C-x k       para-index-keystroke
C-c C-x p       para-index-program
C-c C-x t       para-index-datatype
C-c C-x v       para-index-variable

C-c C-x x       para-insert-index              (cause @printindex to insert indices)

Texinfo updating commands  (other Texinfo commands work also)

C-c C-u C-e     texinfo-every-node-update
C-c C-u C-a     texinfo-all-menus-update

When point is at the upper left of the window or the buffer is read-only, you can use the Info commands as is, `n' for next, `p' for previous, and so on.

Also, in this circumstance you can type the number `1' or `2', up to `9' go to the node of the first menu item, etc.

Don't forget:

C-g                 keyboard-quit       the standard Emacs key to cancel a command or escape a problem