[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog doc/texinfo.txi
From: |
karl |
Subject: |
texinfo ChangeLog doc/texinfo.txi |
Date: |
Tue, 04 Sep 2012 17:28:27 +0000 |
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}
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/03
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/03
- texinfo ChangeLog doc/texinfo.txi,
karl <=
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/06
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/06
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/07
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/07
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/08
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/09
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/09
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/10
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/12
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/13