Making and Preventing Breaks

Next: Definition Commands  Prev: Special Insertions

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

The break commands create or allow line and paragraph breaks:

@*
Force a line break.

@sp n
Skip n blank lines.

@-
Insert a discretionary hyphen.

@hyphenation{hy-phen-a-ted words}
Define hyphen points in hy-phen-a-ted words.
The line-break-prevention command holds text together all on one line:

@w{text}
Prevent text from being split and hyphenated across two lines.

The pagination commands apply only to printed output, since Info files do not have pages.

@page
Start a new page in the printed manual.

@group
Hold text together that must appear on one printed page.

@need mils
Start a new printed page if not enough space on this one.

@*: 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 @refill command 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 hyphenate

Although 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:

@-
Insert a discretionary hyphen, i.e., a place where TEX can (but does not have to) hyphenate. This is especially useful when you notice an overfull hbox is due to TEX missing a hyphenation (See Overfull hboxes). TEX will not insert any hyphenation points in a word containing @-.

@hyphenation{hy-phen-a-ted words}
Tell TEX how to hyphenate hy-phen-a-ted words. As shown, you put a `-' at each hyphenation point. For example: 
@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.

You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
produces

You can copy GNU software from `ftp.gnu.ai.mit.edu'.
Caution: Do not write an @refill command at the end of a paragraph containing an @w command; it will cause the paragraph to be refilled and may thereby negate the effect of the @w command.

@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 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).