diff options
Diffstat (limited to 'doc/groff.html.node/ms-keeps-and-displays.html')
| -rw-r--r-- | doc/groff.html.node/ms-keeps-and-displays.html | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/doc/groff.html.node/ms-keeps-and-displays.html b/doc/groff.html.node/ms-keeps-and-displays.html new file mode 100644 index 0000000..47088aa --- /dev/null +++ b/doc/groff.html.node/ms-keeps-and-displays.html @@ -0,0 +1,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> |