15. Forcing and Preventing Breaks

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.

15.1 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.

These commands hold text together on a single line:

@w{text}

Prevent text from being split and hyphenated across two lines.

@tie{}

Insert a normal interword space at which a line break may not occur.

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.

15.2 @* and @/: Generate and Allow Line Breaks

The @* command forces a line break in both the printed manual and in Info. The @/ command allows a line break (printed manual only).

Here is an example with @*:

This line @* is broken @*in two places.

produces

This line
is broken
in two places.

The @/ command can be useful within a url (see section @uref), which tend to be long and are otherwise unbreakable. For example:

The official Texinfo home page is on the GNU web site:
@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}.

produces

The official Texinfo home page is on the GNU web site:
http://www.gnu.org/software/gnu/texinfo.

Without the @/ commands, TeX would have nowhere to break the line. @/ has no effect in the online output.

15.3 @- 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 section Overfull “hboxes”). TeX will not insert any hyphenation points itself into 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, such as plurals.

Info, HTML, and other non-TeX output is not hyphenated, so none of these commands have any effect there.

15.4 @allowcodebreaks: Control Line Breaks in @code

Ordinarily, TeX will consider breaking lines at ‘-’ and ‘_’ characters within @code and related commands (see section @code), more or less as if they were “empty” hyphenation points.

This is necessary as many manuals, especially for Lisp-family languages, must document very long identifiers. On the other hand, other manuals don’t have this problems, and you may not wish to allow a line break at the underscore in, for example, SIZE_MAX, or even worse, after any of the four underscores in __typeof__.

So Texinfo provides this command:

@allowcodebreaks false

to prevent TeX from breaking at ‘-’ or ‘_’ within @code. You can go back to allowing such breaks with @allowcodebreaks true. Write these commands on lines by themselves.

These commands can be given anywhere in the document. For example, you may have just one problematic paragraph where you need to turn off the breaks, but want them in general, or vice versa.

This command has no effect in Info, HTML, and other non-TeX output.

15.5 @w{text}: Prevent Line Breaks

@w{text} outputs text and prohibits line breaks within text, for both TeX and makeinfo.

Thus, you can use @w to produce a non-breakable space, fixed at the width of a normal interword space:

@w{ } @w{ } @w{ } indentation.

produces:

      indentation.

The space from @w{ }, as well as being non-breakable, also will not stretch or shrink. Sometimes that is what you want, for instance if you’re doing manual indenting. However, usually you want a normal interword space that does stretch and shrink (in the printed output); see the @tie command in the next section.

You can also 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. makeinfo does not ever hyphenate words.

You can also use @w to avoid unwanted keyword expansion in source control systems. For example, to literally write $Id$ in your document, use @w{$}Id$.

15.6 @tie{}: Inserting an Unbreakable Space

The @tie{} command produces a normal interword space at which a line break may not occur. Always write it with following (empty) braces, as usual for commands used within a paragraph. Here’s an example:

@TeX{} was written by Donald E.@tie{}Knuth.

produces:

TeX was written by Donald E. Knuth.

There are two important differences between @tie{} and @w{ }:

• The space produced by @tie{} will stretch and shrink slightly along with the normal interword spaces in the paragraph; the space produced by @w{ } will not vary.
• @tie{} allows hyphenation of the surrounding words, while @w{ } inhibits hyphenation of those words (for TeXnical reasons, namely that it produces an ‘\hbox’).

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

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

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

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

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.