Usually, a Texinfo file is processed both by TeX and by one of the Info formatting commands. Line, paragraph, or page breaks sometimes occur in the `wrong' place in one or other form of output. You must ensure that text looks right both in the printed manual and in the Info file.
For example, in a printed manual, page breaks may occur awkwardly in the middle of an example; to prevent this, you can hold text together using a grouping command that keeps the text from being split across two pages. Conversely, you may want to force a page break where none would occur normally. Fortunately, problems like these do not often arise. When they do, use the break, break prevention, or pagination commands.
The break commands create or allow line and paragraph breaks:
@*
@sp n
@-
@hyphenation{hy-phen-a-ted words}
The line-break-prevention command holds text together all on one line:
@w{text}
The pagination commands apply only to printed output, since Info files do not have pages.
@page
@group
@need mils
@*: Generate Line Breaks
The @* command forces a line break in both the printed manual and
in Info.
For example,
This line @* is broken @*in two places.
produces
This line is broken in two places.
(Note that the space after the first @* command is faithfully
carried down to the next line.)
The @* command is often used in a file's copyright page:
This is edition 2.0 of the Texinfo documentation,@* and is for ...
In this case, the @* command keeps TeX from stretching the
line across the whole page in an ugly manner.
Please note: Do not write braces after an
@*command; they are not needed.Do not write an
@refillcommand at the end of a paragraph containing an@*command; it will cause the paragraph to be refilled after the line break occurs, negating the effect of the line break.
@- and @hyphenation: Helping TeX hyphenateAlthough TeX's hyphenation algorithm is generally pretty good, it does miss useful hyphenation points from time to time. (Or, far more rarely, insert an incorrect hyphenation.) So, for documents with an unusual vocabulary or when fine-tuning for a printed edition, you may wish to help TeX out. Texinfo supports two commands for this:
@-
@-.
@hyphenation{hy-phen-a-ted words}
@hyphenation{man-u-script man-u-scripts}
TeX only uses the specified hyphenation points when the
words match exactly, so give all necessary variants.
Info output is not hyphenated, so these commands have no effect there.
@w{text}: Prevent Line Breaks
@w{text} outputs text and prohibits line breaks
within text.
You can use the @w command to prevent TeX from automatically
hyphenating a long name or phrase that happens to fall near the end of a
line. For example:
You can copy GNU software from @w{@samp{ftp.gnu.org}}.
produces
You can copy GNU software from `ftp.gnu.org'.
You can also use @w to produce a non-breakable space:
None of the formatters will break at this@w{ }space.
@sp n: Insert Blank Lines
A line beginning with and containing only @sp n
generates n blank lines of space in both the printed manual and
the Info file. @sp also forces a paragraph break. For
example,
@sp 2
generates two blank lines.
The @sp command is most often used in the title page.
@page: Start a New Page
A line containing only @page starts a new page in a printed
manual. The command has no effect on Info files since they are not
paginated. An @page command is often used in the @titlepage
section of a Texinfo file to start the copyright page.
@group: Prevent Page Breaks
The @group command (on a line by itself) is used inside an
@example or similar construct to begin an unsplittable vertical
group, which will appear entirely on one page in the printed output.
The group is terminated by a line containing only @end group.
These two lines produce no output of their own, and in the Info file
output they have no effect at all.
Although @group would make sense conceptually in a wide
variety of contexts, its current implementation works reliably only
within @example and variants, and within @display,
@format, @flushleft and @flushright.
See section 10. Quotations and Examples. (What all these commands have in
common is that each line of input produces a line of output.) In
other contexts, @group can cause anomalous vertical
spacing.
This formatting requirement means that you should write:
@example @group ... @end group @end example
with the @group and @end group commands inside the
@example and @end example commands.
The @group command is most often used to hold an example
together on one page. In this Texinfo manual, more than 100 examples
contain text that is enclosed between @group and @end
group.
If you forget to end a group, you may get strange and unfathomable
error messages when you run TeX. This is because TeX keeps
trying to put the rest of the Texinfo file onto the one page and does
not start to generate error messages until it has processed
considerable text. It is a good rule of thumb to look for a missing
@end group if you get incomprehensible error messages in
TeX.
@need mils: Prevent Page Breaks
A line containing only @need n starts
a new page in a printed manual if fewer than n mils (thousandths
of an inch) remain on the current page. Do not use
braces around the argument n. The @need command has no
effect on Info files since they are not paginated.
This paragraph is preceded by an @need command that tells
TeX to start a new page if fewer than 800 mils (eight-tenths
inch) remain on the page. It looks like this:
@need 800 This paragraph is preceded by ...
The @need command is useful for preventing orphans (single
lines at the bottoms of printed pages).
Go to the first, previous, next, last section, table of contents.