File: texnfo-upd.el.html

Known bug: update commands fail to ignore @ignore, and fail to DTRT with the @if... directives (so expect trouble when the manual uses different @node lines or @menu items in @iftex and in @ifnottex).

Summary: how to use the updating commands

The node and menu updating functions automatically

  * insert missing @node lines,
  * insert the Next, Previous and Up pointers of a node,
  * insert or update the menu for a section,
  * create a master menu for a Texinfo source file.

With a prefix argument, the texinfo-update-node and texinfo-make-menu functions do their jobs in the region.

Important note: We do NOT recommend use of these commands to update the Next, Previous and Up pointers on @node lines. Most manuals, including those whose Texinfo files adhere to the structure described below, don't need these pointers, because makeinfo will generate them automatically (see the node "makeinfo Pointer Creation" in the Texinfo manual). By contrast, due to known bugs described above, texinfo-update-node etc. could produce incorrect pointers, and thus make a perfectly valid Texinfo file into an invalid one. You _have_ been warned!

In brief, the functions for creating or updating nodes and menus, are:

    texinfo-update-node (&optional beginning end)
    texinfo-every-node-update ()
    texinfo-sequential-node-update (&optional region-p)

    texinfo-make-menu (&optional beginning end)
    texinfo-all-menus-update ()
    texinfo-master-menu ()

    texinfo-insert-node-lines (&optional title-p)

    texinfo-indent-menu-description (column &optional region-p)

The texinfo-column-for-description variable specifies the column to which menu descriptions are indented.

Texinfo file structure
----------------------

To use the updating commands, you must structure your Texinfo file hierarchically. Each @node line, with the exception of the top node, must be accompanied by some kind of section line, such as an
@chapter or @section line. Each node-line/section-line
combination must look like this:

     @node Lists and Tables, Cross References, Structuring, Top
     @comment node-name, next, previous, up
     @chapter Making Lists and Tables

or like this (without the @comment line):

     @node Lists and Tables, Cross References, Structuring, Top
     @chapter Making Lists and Tables

If the file has a top node, it must be called top or Top and be the first node in the file.


; The update node functions described in detail

The texinfo-update-node command with no prefix argument inserts the correct next, previous and up pointers for the node in which point is located (i.e., for the node preceding point).

With prefix argument, the texinfo-update-node function inserts the correct next, previous and up pointers for the nodes inside the region.

It does not matter whether the @node line has pre-existing
Next, Previous, or Up pointers in it. They are removed.

Warning: Since the pre-existing pointers are replaced with the ones computed by texinfo-update-node, and since this function has known bugs with the more advanced Texinfo features (see above), it could produce an invalid Texinfo file. You are well advised not to use this function, except if you know what you are doing and exercise extreme caution. Keep in mind that most manuals do not need the Next, Previous, and Up pointers to be present on the
@node lines; makeinfo will automatically generate them when it
produces the Info or HTML versions of the manual.

The texinfo-every-node-update function runs texinfo-update-node on the whole buffer.

The texinfo-sequential-node-update function inserts the immediately following and preceding node into the Next or Previous pointers regardless of their hierarchical level. This is only useful for certain kinds of text, like a novel, which you go through sequentially.


; The menu making functions described in detail

The texinfo-make-menu function without an argument creates or updates a menu for the section encompassing the node that follows point. With an argument, it makes or updates menus for the nodes within or part of the marked region.

Whenever an existing menu is updated, the descriptions from that menu are incorporated into the new menu. This is done by copying descriptions from the existing menu to the entries in the new menu that have the same node names. If the node names are different, the descriptions are not copied to the new menu.

Menu entries that refer to other Info files are removed since they are not a node within current buffer. This is a deficiency.

The texinfo-all-menus-update function runs texinfo-make-menu on the whole buffer.

The texinfo-master-menu function creates an extended menu located
after the top node. (The file must have a top node.) This
function works only on Texinfo files all of whose menus are present in a single file; use texinfo-multiple-files-update for multi-file manuals. The function constructs a master menu that includes every entry from every other menu. Use this command to create or update the @detailmenu menu after you've created or updated all the menus in the file, including the menu in the Top node, using the texinfo-make-menu or the texinfo-all-menus-update command.

The texinfo-indent-menu-description function indents every description in the menu following point, to the specified column. Non-nil argument (prefix, if interactive) means indent every description in every menu in the region. This function does not indent second and subsequent lines of a multi-line description.

The texinfo-insert-node-lines function inserts @node before the
@chapter, @section, and such like lines of a region in a Texinfo
file where the @node lines are missing.

With a non-nil argument (prefix, if interactive), the function not only inserts @node lines but also inserts the chapter or section titles as the names of the corresponding nodes; and inserts titles as node names in pre-existing @node lines that lack names.

Since node names should be more concise than section or chapter titles, you will usually want to manually edit node names so inserted.

Defined variables (9)

Defined functions (51)

Defined faces (0)