texinfo ChangeLog doc/texinfo.txi

[karl]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     karl <karl>     12/09/04 17:28:27

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Quotations and Examples): general updates

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1401&r2=1.1402
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.466&r2=1.467

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1401
retrieving revision 1.1402
diff -u -b -r1.1401 -r1.1402
--- ChangeLog   4 Sep 2012 00:27:30 -0000       1.1401
+++ ChangeLog   4 Sep 2012 17:28:26 -0000       1.1402
@@ -1,6 +1,11 @@
 2012-09-03  Patrice Dumas  <address@hidden>
         and Karl Berry  <address@hidden>
 
+       * doc/texinfo.txi (Quotations and Examples): general updates.
+
+2012-09-03  Patrice Dumas  <address@hidden>
+        and Karl Berry  <address@hidden>
+
        * doc/texinfo.txi (Breaks, Insertions): general updates.
 
 2012-09-02  Karl Berry  <address@hidden>

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.466
retrieving revision 1.467
diff -u -b -r1.466 -r1.467
--- doc/texinfo.txi     4 Sep 2012 00:27:31 -0000       1.466
+++ doc/texinfo.txi     4 Sep 2012 17:28:27 -0000       1.467
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.466 2012/09/04 00:27:31 karl Exp $
address@hidden $Id: texinfo.txi,v 1.467 2012/09/04 17:28:27 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.
 
@@ -380,7 +380,7 @@
 * raggedright::                 Avoiding justification on the right.
 * noindent::                    Preventing paragraph indentation.
 * indent::                      Forcing paragraph indentation.
-* cartouche::                   Drawing rounded rectangles around examples.
+* cartouche::                   Drawing rounded rectangles around text.
 
 Lists and Tables
 
@@ -8025,11 +8025,11 @@
 In Texinfo, you always begin a quotation or example by writing an
 @@-command at the beginning of a line by itself, and end it by writing
 an @code{@@end} command that is also at the beginning of a line by
-itself.  For instance, you begin an example by writing @code{@@example}
-by itself at the beginning of a line and end the example by writing
address@hidden@@end example} on a line by itself, at the beginning of that
-line, and with only one space between the @code{@@end} and the
address@hidden
+itself.  For instance, you begin an example by writing
address@hidden@@example} by itself at the beginning of a line and end the
+example by writing @code{@@end example} on a line by itself, at the
+beginning of that line, and with only one space between the
address@hidden@@end} and the @code{example}.
 
 @menu
 * Block Enclosing Commands::    Different constructs for different purposes.
@@ -8046,29 +8046,30 @@
 * raggedright::                 Avoiding justification on the right.
 * noindent::                    Preventing paragraph indentation.
 * indent::                      Forcing paragraph indentation.
-* cartouche::                   Drawing rounded rectangles around examples.
+* cartouche::                   Drawing rounded rectangles around text.
 @end menu
 
 
 @node Block Enclosing Commands
 @section Block Enclosing Commands
 
-Here are commands for quotations and examples, explained further in the
-following sections:
+Here is a summary of commands that enclose blocks of text, also known
+as @dfn{environments}.  They're explained further in the following
+sections.
 
 @table @code
 @item @@quotation
 Indicate text that is quoted. The text is filled, indented (from both
 margins), and printed in a roman font by default.
 
address@hidden @@smallquotation
-Same as @code{@@quotation}, except that in @TeX{} this command typesets
-text in a smaller font size.
-
 @item @@example
 Illustrate code, commands, and the like. The text is printed
 in a fixed-width font, and indented but not filled.
 
address@hidden @@lisp
+Like @code{@@example}, but specifically for illustrating Lisp code. The
+text is printed in a fixed-width font, and indented but not filled.
+
 @item @@verbatim
 Mark a piece of text that is to be printed verbatim; no character
 substitutions are made and all commands are ignored, until the next
@@ -8076,49 +8077,43 @@
 and not indented or filled.  Extra spaces and blank lines are
 significant, and tabs are expanded.
 
address@hidden @@smallexample
-Same as @code{@@example}, except that in @TeX{} this command typesets
-text in a smaller font size.
-
address@hidden @@lisp
-Like @code{@@example}, but specifically for illustrating Lisp code. The
-text is printed in a fixed-width font, and indented but not filled.
-
address@hidden @@smalllisp
-Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
-
 @item @@display
 Display illustrative text.  The text is indented but not filled, and
 no font is selected (so, by default, the font is roman).
 
address@hidden @@smalldisplay
-Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
-
 @item @@format
-Like @code{@@display} (the text is not filled and no font is selected),
-but the text is not indented.
+Like @code{@@display} (the text is not filled and no font is
+selected), but the text is not indented.
 
address@hidden @@smallformat
-Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
address@hidden @@smallquotation
address@hidden @@smallexample
address@hidden @@smalllisp
address@hidden @@smalldisplay
address@hidden @@smallformat
+These @code{@@small...} commands are just like their non-small
+counterparts, except that they output text in a smaller font size,
+where possible.
+
address@hidden @@flushleft
address@hidden @@flushright
+Text is not filled, but is set flush with the left or right margin,
+respectively.
+
address@hidden @@raggedright
+Text is filled, but only justified on the left, leaving the right
+margin ragged.
+
address@hidden @@cartouche
+Highlight text, often an example or quotation, by drawing a box with
+rounded corners around it.
 @end table
 
 The @code{@@exdent} command is used within the above constructs to
 undo the indentation of a line.
 
-The @code{@@flushleft} and @code{@@flushright} commands are used to line
-up the left or right margins of unfilled text.
-
-The @code{@@raggedright} command fills text as usual, but only
-justifies it on the left, leaving the right margin ragged.
-
 The @code{@@noindent} command may be used after one of the above
-constructs to prevent the following text from being indented as a new
-paragraph.
-
-You can use the @code{@@cartouche} environment around one of the above
-constructs to highlight the example or quotation by drawing a box with
-rounded corners around it.  @xref{cartouche, , Drawing Cartouches Around
-Examples}.
+constructs (or anywhere) to prevent the following text from being
+indented as a new paragraph.
 
 
 @node quotation
@@ -8471,13 +8466,10 @@
 @cindex Display formatting
 @findex display
 
-The @code{@@display} command begins a kind of example, where each line
-of input produces a line of output, and the output is indented.  It is
-thus like the @code{@@example} command except that, in a printed
-manual, @code{@@display} does not select the fixed-width font.  In
-fact, it does not specify the font at all, so that the text appears in
-the same font it would have appeared in without the @code{@@display}
-command.
+The @code{@@display} command begins another kind of environment, where
+the font is left unchanged, not switched to typewriter as with
address@hidden@@example}.  Each line of input still produces a line of output,
+and the output is still indented.
 
 @display
 This is an example of text written between an @code{@@display} command
@@ -8486,22 +8478,22 @@
 @end display
 
 @findex smalldisplay
-Texinfo also provides a command @code{@@smalldisplay}, which is like
address@hidden@@display} but uses a smaller font size.  @xref{small}.
+Texinfo also provides the environment @code{@@smalldisplay}, which is
+like @code{@@display} but uses a smaller font size.  @xref{small}.
 
-The @code{@@table} command (@pxref{table}) does not work inside
+The @code{@@table} command (@pxref{table}) is not supported inside
 @code{@@display}.  Since @code{@@display} is line-oriented, it doesn't
 make sense to use them together.  If you want to indent a table, try
address@hidden@@quotation} (@pxref{quotation}).
address@hidden@@quotation} (@pxref{quotation,,@code{@@quotation}}).
 
 
 @node format
 @section @code{@@format}: Examples Using the Full Line Width
 @findex format
 
-The @code{@@format} command is similar to @code{@@example} except
-that, in the printed manual, @code{@@format} does not select the
-fixed-width font and does not narrow the margins.
+The @code{@@format} command is similar to @code{@@display}, except it
+leaves the text unindented.  Like @code{@@display}, it does not select
+the fixed-width font.
 
 @format
 This is an example of text written between an @code{@@format} command
@@ -8511,8 +8503,8 @@
 @end format
 
 @findex smallformat
-Texinfo also provides a command @code{@@smallformat}, which is like
address@hidden@@format} but uses a smaller font size.  @xref{small}.
+Texinfo also provides the environment @code{@@smallformat}, which is
+like @code{@@format} but uses a smaller font size.  @xref{small}.
 
 
 @node exdent
@@ -8551,9 +8543,11 @@
 @end group
 @end example
 
-In practice, the @code{@@exdent} command is rarely used.
-Usually, you un-indent text by ending the example and
-returning the page to its normal width.
+In practice, the @code{@@exdent} command is rarely used.  Usually, you
+un-indent text by ending the example and returning the page to its
+normal width.
+
address@hidden@@exdent} has no effect in HTML output.
 
 
 @node flushleft & flushright
@@ -8752,15 +8746,15 @@
 
 
 @node cartouche
address@hidden @code{@@cartouche}: Rounded Rectangles Around Examples
address@hidden @code{@@cartouche}: Rounded Rectangles
+
 @findex cartouche
 @cindex Box with rounded corners
address@hidden Rounded rectangles, around examples
address@hidden Rounded rectangles, around text
 
 In a printed manual, the @code{@@cartouche} command draws a box with
 rounded corners around its contents.  In HTML, a normal rectangle is
-drawn (that's the best HTML can do).  @code{@@cartouche} has no effect
-in Info output.
+drawn.  @code{@@cartouche} has no effect in Info output.
 
 You can use this command to further highlight an example or quotation.
 For instance, you could write a manual in which one type of example is
@@ -8791,10 +8785,6 @@
 @end example
 @end cartouche
 
-For proper output in HTML, it's necessary to put the
address@hidden@@cartouche} around the @code{@@example}, and not the other way
-around.  This limitation of @command{makeinfo} may be removed one day.
-
 @code{@@cartouche} also implies @code{@@group} (@pxref{group}).
 
 @node Lists and Tables
@@ -8923,8 +8913,8 @@
 very brief, these blank lines make the list look better.
 
 Here is an example of the use of @code{@@itemize}, followed by the
-output it produces.  @code{@@bullet} produces an @samp{*} in Info and a
-round dot in @TeX{}.
+output it produces.  @code{@@bullet} produces an @samp{*} in Info and
+a round dot in other output formats.
 
 @example
 @group
@@ -9371,9 +9361,9 @@
 @cindex @code{<thead>} HTML/XML tag
 You can also use @code{@@headitem} instead of @code{@@item} to produce
 a @dfn{heading row}.  The @TeX{} output for such a row is in bold, and
-the HTML, Docbook, and XML output uses the @code{<thead>} tag.  In
-Info, the heading row is followed by a separator line made of dashes
-(@samp{-} characters).
+the HTML and Docbook output uses the @code{<thead>} tag.  In Info, the
+heading row is followed by a separator line made of dashes (@samp{-}
+characters).
 
 @findex headitemfont
 @cindex Font for multitable heading rows
@@ -9582,9 +9572,11 @@
 @@end float
 @end example
 
-The text for @code{@@caption} and @code{@@shortcaption} may not
-contain comments (@code{@@c}), verbatim text (@code{@@verb}),
-environments such as @code{@@example}, or other complex constructs.
+The text for @code{@@shortcaption} may not contain comments
+(@code{@@c}), verbatim text (@code{@@verb}), environments such as
address@hidden@@example}, footnotes (@code{@@footnote}) or other complex
+constructs.  The same constraints apply to @code{@@caption} unless
+there is a @code{@@shortcaption}.
 
 
 @node listoffloats
@@ -9679,21 +9671,38 @@
 format does not support EPS images, so such must be converted first.
 
 @item
address@hidden includes @address@hidden verbatim for
-Info output (more or less as if it was an @code{@@example}).
+For Info, @code{makeinfo} includes @address@hidden verbatim
+(more or less as if it were in @code{@@verbatim}).  The Info output
+may also include a reference to @address@hidden or
address@hidden@var{filename}.jpg}.  (See below.)
+
address@hidden
+For HTML, @code{makeinfo} outputs a reference to
address@hidden@var{filename}.png}, @address@hidden,
address@hidden@var{filename}.jpeg} or @address@hidden (in that
+order).  If none of those exist, it gives an error, and outputs a
+reference to @address@hidden anyway.
+
address@hidden
address@hidden SVG images, used in Docbook
+For DocBook, @code{makeinfo} outputs references to
address@hidden@var{filename}.eps}, @address@hidden
address@hidden@var{filename}.jpg}, @address@hidden,
address@hidden@var{filename}.png} and @address@hidden, for every
+file found.  Als, @address@hidden is included verbatim, if
+present.
 
 @item
address@hidden uses the optional fifth argument @var{extension} to
address@hidden@@image} for the filename extension, if it is specified.  Any
-leading period should be included in @var{extension}.  For example:
+For Info and HTML output, @code{makeinfo} uses the optional fifth
+argument @var{extension} to @code{@@image} for the filename extension,
+if it is specified and the file is found.  Any leading period should
+be included in @var{extension}.  For example:
 
 @pindex XPM image format
 @example
 @@address@hidden,,,,address@hidden
 @end example
 
address@hidden
-will cause @code{makeinfo} to look for @file{foo.xpm} before any others.
 @end itemize
 
 If you want to install image files for use by Info readers too, we
@@ -9718,22 +9727,15 @@
 inline images to the optional @var{alttext} (fourth) argument to
 @code{@@image}, if supplied.  If not supplied, @code{makeinfo} uses
 the full file name of the image being displayed.  The @var{alttext} is
-taken as Texinfo text, so special characters such as @samp{"} and
address@hidden<} and @samp{&} are escaped in the HTML and XML output; also,
-you can get an empty @code{alt} string with @code{@@-} (a command
-that produces no output; @pxref{- and hyphenation}).
+processed as Texinfo text, so special characters such as @samp{"} and
address@hidden<} and @samp{&} are escaped in the HTML output; also, you can
+get an empty @code{alt} string with @code{@@-} (a command that
+produces no output; @pxref{- and hyphenation}).
 
 For Info output, the @code{alt} string is also processed as Texinfo
 text and output.  In this case, @samp{\} is escaped as @samp{\\} and
 @samp{"} as @samp{\"}; no other escapes are done.
 
address@hidden PNG image format
address@hidden JPEG image format
-If you do not supply the optional @var{extension} (fifth) argument,
address@hidden first tries @address@hidden; if that does
-not exist, it tries @address@hidden  If that does not exist
-either, it complains.
-
 In Info output, @code{makeinfo} writes a reference to the binary image
 file (trying @var{filename} suffixed with @address@hidden,
 @address@hidden, @file{.png}, or @file{.jpg}, in that order)
@@ -9772,11 +9774,11 @@
 @cindex Distorting images
 The optional @var{width} and @var{height} arguments to the
 @code{@@image} command (see the previous section) specify the size to
-scale the image to.  They are ignored for Info output.  If neither is
-specified, the image is presented in its natural size (given in the
-file); if only one is specified, the other is scaled proportionately;
-and if both are specified, both are respected, thus possibly distorting
-the original image by changing its aspect ratio.
+which to scale the image.  They are only taken into account in @TeX{}.
+If neither is specified, the image is presented in its natural size
+(given in the file); if only one is specified, the other is scaled
+proportionately; and if both are specified, both are respected, thus
+likely distorting the original image by changing its aspect ratio.
 
 @cindex Dimensions and image sizes
 The @var{width} and @var{height} may be specified using any valid @TeX{}
@@ -9895,8 +9897,8 @@
 
 In Info, the reference mark for a footnote is a pair of parentheses
 with the footnote number between them, like this: @samp{(1)}.  The
-reference mark is followed by a cross reference link to the footnote's
-text.
+reference mark is followed by a cross reference link to the footnote
+text if footnotes are put in separate nodes (@pxref{Footnote Styles}).
 
 In the HTML output, footnote references are generally marked with a
 small, superscripted number which is rendered as a hypertext link to
@@ -21872,7 +21874,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.466 2012/09/04 00:27:31 karl Exp $
+$Id: texinfo.txi,v 1.467 2012/09/04 17:28:27 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}