texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       10/08/10 00:25:45

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Output Elements Defined): node edit

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1097&r2=1.1098
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.283&r2=1.284

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1097
retrieving revision 1.1098
diff -u -b -r1.1097 -r1.1098
--- ChangeLog   9 Aug 2010 07:27:52 -0000       1.1097
+++ ChangeLog   10 Aug 2010 00:25:44 -0000      1.1098
@@ -1,3 +1,8 @@
+2010-08-09  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Output Elements Defined): rename/edit from
+       `The different elements'.
+
 2010-08-09  Patrice Dumas  <address@hidden>
 
        * texi2html/texi2html.pl (pass_texi): add line numbers when adding

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.283
retrieving revision 1.284
diff -u -b -r1.283 -r1.284
--- doc/texinfo.txi     6 Aug 2010 22:58:19 -0000       1.283
+++ doc/texinfo.txi     10 Aug 2010 00:25:44 -0000      1.284
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.283 2010/08/06 22:58:19 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.284 2010/08/10 00:25:44 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -19421,49 +19421,67 @@
 @section Output Elements
 
 @cindex Output elements
address@hidden Elements, main division of output documents
address@hidden Elements, main unit of output documents
 
-We will call the main unit of output documents an @dfn{element}.  An
-element's association with output files is determined by the split
-options (@pxref{Splitting output}).  This section describes what they
-are and details for customization.
+We will call the main unit of output documents an @dfn{element}
+(nodes, to a first approximation).  An element's association with
+output files is determined by the split options (@pxref{Splitting
+output}).  This section describes precisely how elements work, with
+details for customization.
 
 @menu
-* The different elements::
+* Output Elements Defined::
 * Elements informations::
 * Elements lines::
 @end menu
 
address@hidden The different elements
address@hidden The different elements
 
-The elements are:
address@hidden Output Elements Defined
address@hidden Output Elements Defined
+
address@hidden Output elements, defined
+
+The output elements are:
 
 @table @emph
 @item Normal elements
-These are normal sections and nodes.  In general nodes are associated 
-with the following sectioning command and a sectioning command is associated
-with the previous node and they both together make up
-the element.  Either the node or the sectioning command is considered to 
-be the main element component, depending on the value of 
address@hidden and @code{USE_SECTIONS}.  For example, if output 
-is Info, the nodes are the elements, if output is Docbook, sectioning commands
-are the main element component, and if output is HTML both cases may happen.  
address@hidden Paths}.
address@hidden Normal elements
+These are normal sections and nodes.  Usually a node is associated
+with a following sectioning command, while a sectioning command is
+associated with a previous node; they both together make up the
+element.  Either the node or the sectioning command is considered to
+be the main element component, depending on the values of the
+configuration variables @code{USE_NODES} and @code{USE_SECTIONS}
+(@pxref{makeinfo Configuration Variables}).
+
+For example, when generating Info, the nodes are the elements; when
+generating Docbook, sectioning commands are the main element
+component; and when generating HTML, either case may happen
+(@pxref{Two Paths}).
+
 @item Top element
-The top element is the higher element in the document structure.
-If there is a @code{@@top} section it is the element associated with
-that section. Otherwise it is the element associated with the 
address@hidden@@node Top}.  If there is no @code{@@node Top} the first element 
-is the top element.
-
-The top element may be formatted differently from normal elements if there
-is a @code{@@top} section or the @code{@@node Top} is not associated 
-with a sectioning command.
address@hidden Misc elements
-These elements are associated with different files if the document is split.
-And also if @code{MONOLITHIC} is not set.
-There are four misc elements:
address@hidden Top element
+The top element is the highest element in the document structure.  If
+the document has a @code{@@top} section (@pxref{makeinfo top}), it is
+the element associated with that section; otherwise, it is the element
+associated with the document's @code{@@node Top} (@pxref{The Top
+Node}).  If by chance there is no @code{@@node Top}, the first element
+in the document is the top element.
+
+The top element may end up formatted differently from normal elements
+if there is a @code{@@top} section or the @code{@@node Top} is not
+associated with a sectioning command.
+
address@hidden Miscellaneous elements
address@hidden Table of contents, output element
address@hidden Short table of contents, output element
address@hidden Overview, output element
address@hidden Footnotes, output element
address@hidden About page, output element
+The remaining elements are associated with different files if the
+document is split, and also if @code{MONOLITHIC} is not set.  There
+are four such miscellaneous elements:
+
 @enumerate
 @item Table of contents
 @item Short table of contents, also called Overview
@@ -19471,44 +19489,53 @@
 @item About page
 @end enumerate
 
-The @emph{About page} shouldn't be present for documents consisting
-in only one sectioning element, or for documents unsplit and without
-navigation information.  When generating HTML, 
-the @emph{Footnote page} should only
-be present if the footnotes appear on a separated page,
-(@pxref{Footnote Styles}) however a footnote element is present if
-the document isn't split.  The @emph{Table of contents} should only
-be formatted if @code{@@contents} is present in the document.
-Similarly the @emph{Overview} should only appear if @code{@@shortcontents}
-or @code{@@summarycontents} is present.  Corresponding configuration variables,
address@hidden and @code{shortcontents} may be set to trigger the 
-output of a @emph{Table of contents} or @emph{Overview}.  
-The Table of contents and 
-the Overview may also be directly included within the document, not
-as separate pages, in case @code{INLINECONTENTS} is set 
-(@pxref{Contents and Overview text}).
+More details:
 
address@hidden
address@hidden The @emph{Table of contents} should only be formatted if
address@hidden@@contents} is present in the document.
+
address@hidden Similarly the @emph{Overview} should only appear if
address@hidden@@shortcontents} or @code{@@summarycontents} is present.  
+
address@hidden The configuration variables @code{contents} and
address@hidden may be set to trigger the output of the
+respective elements.
+
address@hidden If @code{INLINECONTENTS} is set, the @emph{Table of contents} and
address@hidden elements are directly included within the document,
+rather than as separate pages (@pxref{Contents and Overview text}).
+
address@hidden When generating HTML, the @emph{Footnotes page} should only
+be present if the footnotes appear on a separate page (@pxref{Footnote
+Styles}).  However, a footnote element is present if the document is
+not split.
+
address@hidden The @emph{About page} shouldn't be present for documents
+consisting of only one sectioning element, or for monolithic documents
+without navigation information.
+
address@hidden itemize
address@hidden table
 
-It is common not to have anything by normal elements, especially in 
-case of non split output.  In case of HTML output, special element may
-be present.
address@hidden table
-
-The main component of elements are sections if @code{USE_SECTIONS} is set,
-or @code{USE_NODES} is set to 0, and, conversely, are nodes if 
address@hidden is set or @code{USE_SECTIONS} is 0.  If those configuration
-variables are undefined, heuristics are used, influenced by the presence of
-nodes or sectioning elements in the document, if there are no nodes, 
-sectioning elements are preferred and the reverse is true if there are no
-sectioning commands.
- 
-When sectioning commands are the main components of elements, 
-nodes not directly associated with a sectioning command are 
-associated with the following sectioning command, 
-and sectioning commands without nodes constitute an element.
-Conversely, when nodes are the main component of elements,
-sectioning commands not associated with nodes are associated with the
-previous node, and lone nodes are elements.
+It is common not to have anything but normal elements, especially in
+case of monolithic output.  In the case of HTML output, special
+elements may be present.
+
+The main component of elements is sections if @code{USE_SECTIONS} is
+set or @code{USE_NODES} is set to 0; conversely, the main component is
+nodes if @code{USE_NODES} is set or @code{USE_SECTIONS} is 0.  If both
+configuration variables are undefined, heuristics are used, influenced
+by the presence of nodes or sectioning elements in the document: if
+there are no nodes, sectioning elements are preferred and vice versa.
+ 
+When sections are the main components of elements, ``isolated'' nodes
+not directly associated with a sectioning command are associated with
+the following sectioning command, while sectioning commands without
+nodes constitute an element.  Conversely, when nodes are the main
+components of elements, isolated sections not associated with nodes
+are associated with the previous node, and isolated nodes are
+elements.
 
 
 @node Elements informations
@@ -19670,7 +19697,8 @@
 These are used for @code{<link>} elements if they are output in the
 headers.
 @item @@TOP_BUTTONS
-This array is used for the top element buttons (@pxref{The different 
elements}).
+This array is used for the top element buttons (@pxref{Output Elements
+Defined}).
 @end vtable
 
 The array specify the buttons displayed in navigation panels, 
@@ -20250,7 +20278,7 @@
 The other is used to
 customize the file names associated with each element, and the 
 name of the file associated with the special elements. 
address@hidden different elements}.
address@hidden Elements Defined}.
 
 @deftypefn {Function Reference} $file element_file_name \%element $type 
$docu_name
 @var{\%element} is undefined for the special elements (about, overview, 
@@ -20303,7 +20331,7 @@
 @var{$type} is @code{top} if the node is the top node.
 @end deftypefn
 
-For element (@pxref{The different elements}), the function 
+For element (@pxref{Output Elements Defined}), the function 
 reference is:
 
 @deftypefn {Function Reference} {($target,$id)} element_target_name \%element 
$default_target $default_id
@@ -24287,7 +24315,7 @@
 (@url{http://www.gnu.org/software/rcs}) version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.283 2010/08/06 22:58:19 pertusus Exp $
+$Id: texinfo.txi,v 1.284 2010/08/10 00:25:44 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -24366,7 +24394,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.283 2010/08/06 22:58:19 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.284 2010/08/10 00:25:44 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi