Line Breaks & Spacing

Line Breaks

Compare the following three presentations of the ICG contact card.

Itasca Consulting Group, Inc. 111 Third Avenue South, Suite 310 Minneapolis, MN 55418

phone: 612 371-4717 fax: 612 371-4711

Itasca Consulting Group, Inc.

111 Third Avenue South, Suite 310

Minneapolis, MN 55418

phone: 612 371-4717

fax: 612 371-4711

Itasca Consulting Group, Inc.
111 Third Avenue South, Suite 310
Minneapolis, MN 55418
    phone: 612 371-4717
    fax: 612 371-4711

Itasca Consulting Group, Inc.
111 Third Avenue South, Suite 310
Minneapolis, MN 55418
   phone: 612 371-4717
   fax: 612 371-4711

| Itasca Consulting Group, Inc.
| 111 Third Avenue South, Suite 310
| Minneapolis, MN 55418
|   phone: 612 371-4717
|   fax: 612 371-4711

Itasca Consulting Group, Inc. |br|
111 Third Avenue South, Suite 310 |br|
Minneapolis, MN 55418 |br|
|sp3| phone: 612 371-4717 |br|
|sp3| fax: 612 371-4711

The first listing illustrates how reST ignores the return characters, but then “sees” the three space characters ahead of the phone number — it both ignores and uses whitespace.

The reST documentation on line blocks covers the second instance above (the one using pipe (|) characters). Note the three space characters ahead of the phone and fax are still ignored.

The |br| substitution in the third case is an ICG customization that allows placement of line break markup at the end of the lines where it is used. The |sp3| substitution is being used to obtain the desired horizontal offset.

Extra Vertical Space

Please Don’t

Please don’t use pipe to add vertical space in a document.

There is no mechanism for adding additional vertical space in Sphinx. All spacing between elements on the page (paragraphs, headings, tables, figures, etc.) is handled solely in the style sheet. Get help in cases where it seems additional vertical space is needed.

Extra Horizontal Space

There is no mechanism in reST for adding horizontal white space in a doc. Though it is strongly recommended that white-space-controlling efforts be avoided at all times, inevitably there are exceptional cases where obtaining forced white space is necessary. For this purpose |sp| and its children |sp2| - |sp6| are used.

Though rare, there will be contexts where eliminating the breaking space elements within a string is needed to “fool” line wrapping. This can be done with the combination of |sp| and \ (the \ will eliminate a typed space character that follows it).

Sometimes some text is best kept together and not broken up: “To be, or not to be.” This is a rare occurrence, but it happens.

Sometimes some text is best kept together and not broken up: "To\ |sp|\ be,\
|sp|\ or\ |sp|\ not\ |sp|\ to\ |sp|\ be."  This is a rare occurrence, but it
happens.

In paragraphs this kind of thing probably will be very rare. In the silly case above, simply using |br| would achieve the purpose, but the non-breaking space approach is assured to look better across all possible screen widths. The need to eliminate breaking characters in strings pops up a little more frequently in tables, where narrower column widths will cause breaks in entries that are unwanted.

Note

It is true, there is a Unicode non-breaking character (U+00A0) that can be put into .rst files instead of using |sp|. This would be a preferable approach were it not for the fact that those characters are effectively imperceptible when looking at a source document. There are two right in here (  ). Open the .rst for this document and see if you can tell.