1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- This manual documents GNU troff version 1.23.0.
Copyright � 1994-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<title>ms keeps and displays (The GNU Troff Manual)</title>
<meta name="description" content="ms keeps and displays (The GNU Troff Manual)">
<meta name="keywords" content="ms keeps and displays (The GNU Troff Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Request-Index.html" rel="index" title="Request Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="ms-Body-Text.html" rel="up" title="ms Body Text">
<link href="ms-Insertions.html" rel="next" title="ms Insertions">
<link href="Indented-regions-in-ms.html" rel="prev" title="Indented regions in ms">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
</head>
<body lang="en">
<div class="subsubsection-level-extent" id="ms-keeps-and-displays">
<div class="nav-panel">
<p>
Next: <a href="ms-Insertions.html" accesskey="n" rel="next">Tables, figures, equations, and references</a>, Previous: <a href="Indented-regions-in-ms.html" accesskey="p" rel="prev">Indented regions</a>, Up: <a href="ms-Body-Text.html" accesskey="u" rel="up">Body Text</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsubsection" id="Keeps_002c-boxed-keeps_002c-and-displays">4.6.5.8 Keeps, boxed keeps, and displays</h4>
<a class="index-entry-id" id="index-ms-macros_002c-displays"></a>
<a class="index-entry-id" id="index-ms-macros_002c-keeps"></a>
<a class="index-entry-id" id="index-keeps-_005bms_005d"></a>
<p>On occasion, you may want to <em class="dfn">keep</em> several lines of text, or a
region of a document, together on a single page, preventing an automatic
page break within certain boundaries. This can cause a page break to
occur earlier than it normally would. For example, you may want to keep
two paragraphs together, or a paragraph that refers to a table, list, or
figure adjacent to the item it discusses. <samp class="file">ms</samp> provides the
<code class="code">KS</code> and <code class="code">KE</code> macros for this purpose.
</p>
<p>You can alternatively specify a <em class="dfn">floating keep</em>: if a keep cannot
fit on the current page, <samp class="file">ms</samp> holds its contents and
allows material following the keep (in the source document) to fill the
remainder of the current page. When the page breaks, whether by
reaching the end or <code class="code">bp</code> request, <samp class="file">ms</samp> puts the floating keep
at the beginning of the next page. This is useful for placing large
graphics or tables that do not need to appear exactly where they occur
in the source document.
</p>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eKS"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.KS</code></strong><a class="copiable-link" href='#index-_002eKS'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-KS-_005bms_005d"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eKF"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.KF</code></strong><a class="copiable-link" href='#index-_002eKF'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-KF-_005bms_005d"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eKE"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.KE</code></strong><a class="copiable-link" href='#index-_002eKE'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-KE-_005bms_005d"></a>
<p><code class="code">KS</code> begins a keep, <code class="code">KF</code> a floating keep, and <code class="code">KE</code> ends a
keep of either kind.
</p></dd></dl>
<p>As an alternative to the keep mechanism, the <code class="code">ne</code> request forces a
page break if there is not at least the amount of vertical space
specified in its argument remaining on the page (see <a class="pxref" href="Page-Control.html">Page Control</a>).
One application of <code class="code">ne</code> is to reserve space on the page for a
figure or illustration to be included later.
</p>
<a class="index-entry-id" id="index-boxes-_005bms_005d"></a>
<p>A <em class="dfn">boxed keep</em> has a frame drawn around it.
</p>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eB1"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.B1</code></strong><a class="copiable-link" href='#index-_002eB1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-B1-_005bms_005d"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eB2"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.B2</code></strong><a class="copiable-link" href='#index-_002eB2'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-B2-_005bms_005d"></a>
<p><code class="code">B1</code> begins a keep with a box drawn around it. <code class="code">B2</code> ends a
boxed keep.
</p></dd></dl>
<p>Boxed keep macros cause breaks; if you need to box a word or phrase
within a line, see the <code class="code">BX</code> macro in <a class="ref" href="Typeface-and-decoration.html">Typeface and decoration</a>.
Box lines are drawn as close as possible to the text they enclose so
that they are usable within paragraphs. If you wish to box one or more
paragraphs, you may improve the appearance by calling <code class="code">B1</code> after
the first paragraphing macro, and by adding a small amount of vertical
space before calling <code class="code">B2</code>.
</p>
<table class="cartouche" border="1"><tr><td>
<div class="example">
<pre class="example-preformatted">.LP
.B1
.I Warning:
Happy Fun Ball may suddenly accelerate to dangerous
speeds.
.sp \n[PD]/2 \" space by half the inter-paragraph distance
.B2
</pre></div>
</td></tr></table>
<p>If you want a boxed keep to float, you will need to enclose the
<code class="code">B1</code> and <code class="code">B2</code> calls within a pair of <code class="code">KF</code> and <code class="code">KE</code>
calls.
</p>
<a class="index-entry-id" id="index-displays-_005bms_005d"></a>
<p><em class="dfn">Displays</em> turn off filling; lines of verse or program code are
shown with their lines broken as in the source document without
requiring <code class="code">br</code> requests between lines. Displays can be kept on a
single page or allowed to break across pages. The <code class="code">DS</code> macro
begins a kept display of the layout specified in its first argument;
non-kept displays are begun with dedicated macros corresponding to their
layout.
</p>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eDS"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.DS</code></strong> <var class="def-var-arguments"><code class="t">L</code></var><a class="copiable-link" href='#index-_002eDS'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-DS-_005bms_005d"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eLD"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.LD</code></strong><a class="copiable-link" href='#index-_002eLD'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-LD-_005bms_005d"></a>
<p>Begin (<code class="code">DS</code>: kept) left-aligned display.
</p></dd></dl>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eDS-1"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.DS</code></strong> <var class="def-var-arguments">[<code class="t">I</code> [<span class="r"><i class="slanted">indent</i></span>]]</var><a class="copiable-link" href='#index-_002eDS-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-DS-_005bms_005d-1"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eID"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.ID</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">indent</i></span>]</var><a class="copiable-link" href='#index-_002eID'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-ID-_005bms_005d"></a>
<p>Begin (<code class="code">DS</code>: kept) display indented by <var class="var">indent</var> if specified,
and by the amount of the <code class="code">DI</code> register otherwise.
</p></dd></dl>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eDS-2"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.DS</code></strong> <var class="def-var-arguments"><code class="t">B</code></var><a class="copiable-link" href='#index-_002eDS-2'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-DS-_005bms_005d-2"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eBD"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.BD</code></strong><a class="copiable-link" href='#index-_002eBD'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-BD-_005bms_005d"></a>
<p>Begin a (<code class="code">DS</code>: kept) a block display: the entire display is
left-aligned, but indented such that the longest line in the display
is centered on the page.
</p></dd></dl>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eDS-3"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.DS</code></strong> <var class="def-var-arguments"><code class="t">C</code></var><a class="copiable-link" href='#index-_002eDS-3'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-DS-_005bms_005d-3"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eCD"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.CD</code></strong><a class="copiable-link" href='#index-_002eCD'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-CD-_005bms_005d"></a>
<p>Begin a (<code class="code">DS</code>: kept) centered display: each line in the display
is centered.
</p></dd></dl>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eDS-4"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.DS</code></strong> <var class="def-var-arguments"><code class="t">R</code></var><a class="copiable-link" href='#index-_002eDS-4'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-DS-_005bms_005d-4"></a>
</dd><dt class="deffnx defmacx-alias-deffnx def-cmd-deffn" id="index-_002eRD"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.RD</code></strong><a class="copiable-link" href='#index-_002eRD'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-RD-_005bms_005d"></a>
<p>Begin a (<code class="code">DS</code>: kept) right-aligned display. This is a GNU
extension.
</p></dd></dl>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_002eDE"><span class="category-def">Macro: </span><span><strong class="def-name"><code class="t">.DE</code></strong><a class="copiable-link" href='#index-_002eDE'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-DE-_005bms_005d"></a>
<p>End any display.
</p></dd></dl>
<p>The distance stored in the <code class="code">DD</code> register is inserted before and
after each pair of display macros; this is a Berkeley extension. In
<code class="code">groff</code> <samp class="file">ms</samp>, this distance replaces any adjacent
inter-paragraph distance or subsequent spacing prior to a section
heading. The <code class="code">DI</code> register is a GNU extension; its value is an
indentation applied to displays created with ‘<samp class="samp">.DS</samp>’ and ‘<samp class="samp">.ID</samp>’
without arguments, to ‘<samp class="samp">.DS I</samp>’ without an indentation argument, and
to indented equations set with ‘<samp class="samp">.EQ</samp>’. Changes to either register
take effect at the next display boundary.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="ms-Insertions.html">Tables, figures, equations, and references</a>, Previous: <a href="Indented-regions-in-ms.html">Indented regions</a>, Up: <a href="ms-Body-Text.html">Body Text</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
