[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[6582] rework of Nodes and Menus
|
From: |
Gavin D. Smith |
|
Subject: |
[6582] rework of Nodes and Menus |
|
Date: |
Thu, 27 Aug 2015 18:44:50 +0000 |
Revision: 6582
http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6582
Author: gavin
Date: 2015-08-27 18:44:47 +0000 (Thu, 27 Aug 2015)
Log Message:
-----------
rework of Nodes and Menus
Modified Paths:
--------------
trunk/ChangeLog
trunk/doc/texinfo.texi
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2015-08-26 16:54:20 UTC (rev 6581)
+++ trunk/ChangeLog 2015-08-27 18:44:47 UTC (rev 6582)
@@ -1,3 +1,18 @@
+2015-08-27 Gavin Smith <address@hidden>
+
+ * doc/texinfo.texi (Chapter Structuring): Remove reference to
+ node pointer deduction. Abbreviate explanation of when to use
+ @node.
+ (Nodes): Move some of that material here.
+ (Menus): Make this chapter a section of the Nodes chapter.
+ (@node): Merge this into Nodes node, raising level of
+ subsections to sections. Move @findex line to Writing a Node.
+ Move material about optional arguments to @node to Writing a Node.
+ (Texinfo Document Structure): Make a section of the Nodes
+ chapter. Surround "child nodes" in @dfn. Don't say that the
+ first child has its parent as its Prev node, as this appears not
+ to be true. Merge some material from Nodes into this section.
+
2015-08-26 Gavin Smith <address@hidden>
* doc/texinfo.tex (\pxref, \xref, \ref): If there isn't
Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi 2015-08-26 16:54:20 UTC (rev 6581)
+++ trunk/doc/texinfo.texi 2015-08-27 18:44:47 UTC (rev 6582)
@@ -133,7 +133,6 @@
* Writing a Texinfo File:: Format of a Texinfo source file.
* Beginning and Ending a File:: Beginning and end of a Texinfo file.
* Nodes:: Writing nodes, the basic unit of Texinfo.
-* Menus:: Writing menus.
* Chapter Structuring:: Creating chapters, sections, appendices, etc.
* Cross References:: Writing cross references.
* Marking Text:: Marking words and phrases as code,
@@ -189,7 +188,6 @@
* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
* Short Sample:: A short sample Texinfo file.
-* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
Beginning and Ending a Texinfo File
@@ -244,17 +242,15 @@
Nodes
-* @code{@@node}:: Creating nodes, in detail.
-* Node Menu Illustration:: A diagram, and sample nodes and menus.
-* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node
pointers.
-
-The @code{@@node} Command
-
+* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
* Node Names:: How to choose node names.
* Writing a Node:: How to write an @code{@@node} line.
* Node Line Requirements:: Keep names unique.
* First Node:: How to write a `Top' node.
* @code{@@top} Command:: How to use the @code{@@top} command.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node
pointers.
+* Menus:: Listing subordinate nodes.
Menus
@@ -1271,7 +1267,6 @@
* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
* Short Sample:: A short sample Texinfo file.
-* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
@end menu
@node Command Syntax
@@ -1783,62 +1778,6 @@
@end quotation
address@hidden Texinfo Document Structure
address@hidden Texinfo Document Structure
address@hidden Texinfo document structure
address@hidden Document structure, of Texinfo
address@hidden Structure, of Texinfo documents
address@hidden Double structure, of Texinfo documents
-
address@hidden address@hidden node name
-Texinfo documents most usefully have a double structure, reflecting
-the double purposes of printed and online output. For printed output
-(DVI, PDF, @dots{}), with physical pages, there are chapters,
-sections, subsections, etc. For online output (Info, HTML, @dots{}),
-with interactive navigation and no physical pages, there are so-called
-``nodes''.
-
-Typically, the sectioning structure and the node structure are
-completely parallel, with one node for each chapter, section, etc.,
-and with the nodes following the same hierarchical arrangement as the
-sectioning. Thus, if a node is at the logical level of a chapter, its
-child nodes are at the level of sections; similarly, the child nodes
-of sections are at the level of subsections.
-
-Each @dfn{node} has a name, and contains the discussion of one topic.
-Along with the text for the user to read, each node also has pointers
-to other nodes, identified in turn by their own names. Info readers
-display one node at a time, and provide commands for the user to move
-to related nodes. The HTML output can be similarly navigated.
-
-The names of child nodes are listed in a @dfn{menu} within the parent
-node; for example, a node corresponding to a chapter would have a menu
-of the sections in that chapter. The menus allow the user to move to
-the child nodes in a natural way in the online output.
-
-In addition, nodes at the same level are formed into a chain with
-`Next' and `Previous' pointers. As you might imagine, the `Next'
-pointer links to the next node (section), and the `Previous' pointer
-links to the previous node (section). Thus, for example, all the
-nodes that are at the level of sections within a chapter are linked
-together, and the order in this chain is the same as the order of the
-children in the menu of parent chapter. Each child node records the
-parent node name as its `Up' pointer. The last child has no `Next'
-pointer, and the first child has the parent both as its `Previous' and
-as its `Up' pointer.
-
-In addition to menus and `Next', `Previous', and `Up' pointers,
-Texinfo provides pointers of another kind for cross references, that
-can be sprinkled throughout the text. This is usually the best way to
-represent links that do not fit a hierarchical structure.
-
-Although it is technically possible to create Texinfo documents with
-only one structure or the other, or for the two structures not to be
-parallel, or for either the sectioning or node structure to be
-abnormally formed, etc., this is @emph{not at all recommended}. To
-the best of our knowledge, all the Texinfo manuals currently in
-general use do follow the conventional parallel structure.
-
@node Beginning and Ending a File
@anchor{Beginning a File} @c old name
@chapter Beginning and Ending a Texinfo File
@@ -3273,94 +3212,105 @@
@node Nodes
@chapter Nodes
address@hidden@anchor{@@node} @c old names
address@hidden are the primary segments of a Texinfo file. Nodes contain
address@hidden pointers} that name other nodes, and can contain @dfn{menus}
-which are lists of nodes. In Info, the movement commands can carry
-you to a pointed-to node or to a node listed in a menu.
address@hidden Node, defined
+A @dfn{node} is a region of text that begins at a @code{@@node}
+command, and continues until the next @code{@@node} command.
+To specify a node, write a @code{@@node} command at the beginning of
+a line, and follow it with the name of the node.
+Each node contains the discussion of one topic. Info readers
+display one node at a time, and provide commands for the user to move
+to related nodes. The HTML output can be similarly navigated.
-Node pointers and menus provide structure for Info files just as
-chapters, sections, subsections, and the like provide structure for
-printed books. The two structures are theoretically distinct; in
-practice, however, the tree structure of printed books is essentially
-always used for the node and menu structure also, as this leads to a
-document which is easiest to follow. @xref{Texinfo Document
-Structure}.
+Nodes are used as the targets of cross-references. Cross-references,
+such as the one at the end of this sentence, are made with @code{@@xref}
+and related commands; see @ref{Cross References}. Cross-references can
+be sprinkled throughout the text, and provide a way to represent links
+that do not fit a hierarchical structure.
-Nodes may be the targets of cross-references. Cross-references, such
-as the one at the end of this sentence, are made with @code{@@xref}
-and related commands; see @ref{Cross References}. You can use
address@hidden@@anchor} (@address@hidden@@anchor}}) to make cross-references
-to an arbitrary position in a document.
+Normally, you put a node command immediately before each chapter
+structuring command---for example, an @code{@@section} or
address@hidden@@subsection} line. (@xref{Chapter Structuring}.).
+You must do this even if you do not intend to format the file for Info.
+This is because @TeX{} uses both @code{@@node} names and
+chapter-structuring names in the output for cross-references. The only
+time you are likely to use the chapter structuring commands without also
+using nodes is if you are writing a document that contains no cross
+references and will only be printed, not transformed into Info, HTML, or
+other formats.
@menu
-* @code{@@node}:: Creating nodes, in detail.
+* Texinfo Document Structure:: Double structure of documents.
+* Node Names:: How to choose node names.
+* Writing a Node:: How to write an @code{@@node} line.
+* Node Line Requirements:: Keep names unique.
+* First Node:: How to write a `Top' node.
+* @code{@@top} Command:: How to use the @code{@@top} command.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node
pointers.
+* Menus:: Listing subordinate nodes.
@end menu
address@hidden @code{@@node}
address@hidden The @code{@@node} Command
address@hidden Texinfo Document Structure
address@hidden Texinfo Document Structure
address@hidden Texinfo document structure
address@hidden Document structure, of Texinfo
address@hidden Structure, of Texinfo documents
address@hidden Double structure, of Texinfo documents
address@hidden@c node
address@hidden node
address@hidden Node, defined
address@hidden address@hidden node name
-A @dfn{node} is a region of text that begins at a @code{@@node}
-command, and continues until the next @code{@@node} command.
-To specify a node, write a @code{@@node} command at the beginning of
-a line, and follow it with the name of the node. For details of node
-name requirements, @pxref{Node Line Requirements}.
+Nodes can contain @dfn{menus}, which contain the names of @dfn{child
+nodes} within the parent node; for example, a node corresponding to a
+chapter would have a menu of the sections in that chapter. The menus
+allow the user to move to the child nodes in a natural way in the online
+output.
-Usually, you write one of the chapter-structuring command lines
-immediately after an @code{@@node} line---for example, an
address@hidden@@section} or @code{@@subsection} line. @xref{Structuring
-Command Types}.
+In addition, nodes contain @dfn{node pointers} that name other nodes.
+The `Next' and `Previous' pointers form nodes at the same sectioning
+level into a chain. As you might imagine, the `Next' pointer links to
+the next node, and the `Previous' pointer links to the previous node.
+Thus, for example, all the nodes that are at the level of sections
+within a chapter are linked together, and the order in this chain
+is the same as the order of the children in the menu of the parent
+chapter. Each child node records the parent node name as its `Up'
+pointer.
-You must write @code{@@node} lines in a Texinfo file that you intend
-to format for printing, and follow each @code{@@node} line with a
-valid chapter-structuring command, even if you do not intend to format
-the file for Info. This is because @TeX{} uses both @code{@@node}
-names and chapter-structuring names in the output for cross-references.
-
-You may optionally follow the node name argument to @code{@@node}
-with up to three optional arguments on the rest of the same line,
-separating the arguments with commas. These are the names of the
-`Next', `Previous', and `Up' pointers, in that order. We recommend
-omitting them if your Texinfo document is hierarchically organized,
-as virtually all are (@address@hidden Pointer Creation}).
-Any spaces before or after each name on the @code{@@node} line are
-ignored.
-
-The definition of node is different from that for chapter or section.
-A chapter may contain sections and a section may contain subsections,
-but a node cannot contain subnodes: the text of a node continues only
-until the next @code{@@node} command in the file. A node usually
-contains only one chapter structuring command, immediately following
-the @code{@@node} line.
-
@opindex address@hidden, in HTML output of nodes}
-Whether the node pointers are specified implicitly or explicitly, the
-Info and HTML output from @command{makeinfo} for each node includes
+The Info and HTML output from @command{makeinfo} for each node includes
links to the `Next', `Previous', and `Up' nodes. The HTML also uses
the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and
@samp{u} respectively. This allows people using web browsers to
follow the navigation using (typically) @address@hidden, e.g.,
@kbd{M-n} for the `Next' node, from anywhere within the node.
+Node pointers and menus provide structure for Info files just as
+chapters, sections, subsections, and the like provide structure for
+printed books. The two structures are theoretically distinct; in
+practice, however, the tree structure of printed books is essentially
+always used for the node and menu structure also, as this leads to a
+document which is easiest to follow. @xref{Texinfo Document
+Structure}.
address@hidden
-* Node Names:: How to choose node names.
-* Writing a Node:: How to write an @code{@@node} line.
-* Node Line Requirements:: Keep names unique.
-* First Node:: How to write a `Top' node.
-* @code{@@top} Command:: How to use the @code{@@top} command.
address@hidden menu
+Typically, the sectioning structure and the node structure are
+completely parallel, with one node for each chapter, section, etc.,
+and with the nodes following the same hierarchical arrangement as the
+sectioning. Thus, if a node is at the logical level of a chapter, its
+child nodes are at the level of sections; similarly, the child nodes
+of sections are at the level of subsections.
+Although it is technically possible to create Texinfo documents with
+only one structure or the other, or for the two structures not to be
+parallel, or for either the sectioning or node structure to be
+abnormally formed, etc., this is @emph{not at all recommended}. To
+the best of our knowledge, all the Texinfo manuals currently in
+general use do follow the conventional parallel structure.
+
@node Node Names
address@hidden Choosing Node Names
address@hidden Choosing Node Names
@cindex Node names, choosing
The name of a node identifies the node. For all the details of node
@@ -3413,11 +3363,12 @@
@node Writing a Node
address@hidden Writing an @code{@@node} Line
address@hidden Writing an @code{@@node} Line
@cindex Writing an @code{@@node} line
@cindex @code{@@node} line writing
@cindex Node line writing
address@hidden node
The easiest way to write an @code{@@node} line is to write @code{@@node}
at the beginning of a line and then the name of the node, like this:
@@ -3447,6 +3398,16 @@
appear in the output. For Info format one can imagine that the order
may not matter, but it matters for the other formats.
+You may optionally follow the node name argument to @code{@@node}
+with up to three optional arguments on the rest of the same line,
+separating the arguments with commas. These are the names of the
+`Next', `Previous', and `Up' pointers, in that order. We recommend
+omitting them if your Texinfo document is hierarchically organized,
+as virtually all are (@address@hidden Pointer Creation}).
+
+Any spaces before or after each name on the @code{@@node} line are
+ignored.
+
The template for a fully-written-out node line with `Next', `Previous',
and `Up' pointers looks like this:
@@ -3477,7 +3438,7 @@
@node Node Line Requirements
address@hidden @code{@@node} Line Requirements
address@hidden @code{@@node} Line Requirements
@cindex Node line requirements
@cindex Restrictions on node names
@@ -3605,7 +3566,7 @@
@node First Node
address@hidden The First Node
address@hidden The First Node
@cindex Top node is first
@cindex First node
@@ -3670,7 +3631,7 @@
@node @code{@@top} Command
address@hidden The @code{@@top} Sectioning Command
address@hidden The @code{@@top} Sectioning Command
@anchor{top address@hidden old name
@anchor{makeinfo address@hidden another old name
@@ -3885,7 +3846,7 @@
@node Menus
address@hidden Menus
address@hidden Menus
@cindex Menus
@findex menu
@@ -3904,7 +3865,7 @@
@node Writing a Menu
address@hidden Writing a Menu
address@hidden Writing a Menu
@cindex Writing a menu
@cindex Menu writing
@@ -3965,7 +3926,7 @@
@kbd{M-1} for the first entry.
@node Menu Example
address@hidden A Menu Example
address@hidden A Menu Example
@cindex Menu example
@cindex Example menu
@@ -4037,7 +3998,7 @@
@node Menu Location
address@hidden Menu Location
address@hidden Menu Location
@cindex Menu location
@cindex Location of menus
@@ -4071,7 +4032,7 @@
@node Menu Parts
address@hidden The Parts of a Menu
address@hidden The Parts of a Menu
@cindex Parts of a menu
@cindex Menu parts
@cindex @code{@@menu} parts
@@ -4125,7 +4086,7 @@
@node Less Cluttered Menu Entry
address@hidden Less Cluttered Menu Entry
address@hidden Less Cluttered Menu Entry
@cindex Two part menu entry
@cindex Double-colon menu entries
@cindex Menu entries with two colons
@@ -4156,7 +4117,7 @@
@node Other Info Files
address@hidden Referring to Other Info Files
address@hidden Referring to Other Info Files
@cindex Referring to other Info files
@cindex Nodes in other Info files
@cindex Other Info files' nodes
@@ -4218,17 +4179,10 @@
hierarchy of chapters, sections, subsections, and subsubsections. These
commands generate large headings in the text, like the one above. They
also provide information for generating the table of contents
-(@pxref{Contents,, Generating a Table of Contents}), and for implicitly
-determining node pointers, as is recommended (@address@hidden
-Pointer Creation}).
+(@pxref{Contents,, Generating a Table of Contents}).
-The chapter structuring commands do not create a node structure, so
-normally you put a @code{@@node} command immediately before each
-chapter structuring command (@pxref{Nodes}). The only time you are
-likely to use the chapter structuring commands without also using
-nodes is if you are writing a document that contains no cross
-references and will only be printed, not transformed into Info, HTML,
-or other formats.
+Normally you put a @code{@@node} command immediately before each
+chapter structuring command. @xref{Nodes}.
@menu
* Tree Structuring:: A manual is like an upside down tree @dots{}
@@ -4298,7 +4252,7 @@
The chapter structuring commands are described in the sections that
follow; the @code{@@node} command is described in
-the following chapter (@pxref{Nodes}).
+the previous chapter (@pxref{Nodes}).
@node Structuring Command Types
@@ -20469,7 +20423,7 @@
@address@hidden@@need}}.
@item @@node @var{name}, @var{next}, @var{previous}, @var{up}
-Begin a new node. @address@hidden@@node}}.
+Begin a new node. @xref{Writing a Node}.
@item @@noindent
Prevent text from being indented as if it were a new paragraph.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [6582] rework of Nodes and Menus,
Gavin D. Smith <=