[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: Doc updates for verson 2.4.
|
From: |
Peter Schaffter |
|
Subject: |
[groff] 01/01: Doc updates for verson 2.4. |
|
Date: |
Sat, 24 Nov 2018 15:48:01 -0500 (EST) |
PTPi pushed a commit to branch master
in repository groff.
commit f5c4e7fef397188c5036877bcfbf19989e8570d7
Author: Peter Schaffter <address@hidden>
Date: Sat Nov 24 15:47:20 2018 -0500
Doc updates for verson 2.4.
---
contrib/mom/momdoc/cover.html | 6 +-
contrib/mom/momdoc/images.html | 110 ++++++++++++++++++++++-------
contrib/mom/momdoc/macrolist.html | 42 +++++++----
contrib/mom/momdoc/tables-of-contents.html | 8 +++
contrib/mom/momdoc/toc.html | 4 +-
5 files changed, 128 insertions(+), 42 deletions(-)
diff --git a/contrib/mom/momdoc/cover.html b/contrib/mom/momdoc/cover.html
index 444ebf7..e18a1c3 100644
--- a/contrib/mom/momdoc/cover.html
+++ b/contrib/mom/momdoc/cover.html
@@ -404,7 +404,7 @@ what you want on the cover page:
<p>
Please note that in all cases, if you have passed
-a reference macro one of the optional arguments,
+a reference macro one of the optional arguments
<kbd>DOC_COVER</kbd> or <kbd>COVER</kbd> (e.g.
<kbd>.TITLE DOC_COVER "Title"</kbd>), mom will print the
appropriate string on the appropriate cover page. Thus,
@@ -556,8 +556,8 @@ or
to move it further down the page. Equally, if only
<kbd>COPYRIGHT</kbd> and/or <kbd>MISC</kbd> are to go on the pages,
cover text begins at the top margin. In all other cases, cover text
-begins below the last element on the page, separated by a blank
-line.
+begins below the last element on the page (excluding COPYRIGHT or
+MISC), separated by a blank line.
</p>
<p>
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index 4dae389..15ecbd7 100644
--- a/contrib/mom/momdoc/images.html
+++ b/contrib/mom/momdoc/images.html
@@ -428,10 +428,11 @@ which is to say that if an image doesn’t fit on the
output
page, she will defer it to the top of the next page while continuing
to process
<a href="definitions.html#running">running text</a>.
-<kbd>ADJUST</kbd> is ignored whenever an image is deferred, except
-when moving from column to column on the same page, when the image
-may need to be optically adjusted. Subsequent images that do not
-fit, if any, are output in order immediately after the first.
+<kbd>ADJUST</kbd> is ignored whenever an image is the first to be
+deferred, except when moving from column to column on the same page,
+when the image may need to be optically adjusted. Subsequent images
+that do not fit, if any, are output in order immediately after the
+first.
</p>
<p class="tip-bottom">
@@ -692,7 +693,7 @@ or
</div>
<div class="box-macro-args">
-Macro: <b>FLOAT</b> <kbd class="macro-args">[ ADJUST +|-<amount> ] [
FORCE ] [ SPAN ] [ NO_SHIM] [ NO_FLEX ] | TARGET "<name>" |
<anything></kbd>
+Macro: <b>FLOAT</b> <kbd class="macro-args">[ ADJUST +|-<amount> ] [
FORCE ] [ SPAN ] [ INDENT <value> ] [ CENTER ] [ RIGHT ] [ NO_SHIM] [
NO_FLEX ] | TARGET "<name>" | <anything></kbd>
</div>
<div class="box-tip">
@@ -702,12 +703,41 @@ FLOAT is intended for use with the document processing
macros only.
</p>
</div>
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+As a general rule, avoid consecutive floats that have no intervening
+<a href="definitions.html#running">running text</a>.
+Rather, wrap all the material into a single float.
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Deferred floats are output with the left indent that was in effect
+when they were input. If you do not want this behaviour, disable
+the indent prior to inputting the float and re-enable it afterward.
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Mom treats <b>pic</b> pre-processor directives and pdf images as
+floats so it is not necessary to wrap them inside FLOAT unless
+additional material is included in what is floated.
+</p>
+</div>
+
<p style="margin-top: -.5em">
To begin a float, simply invoke <kbd>.FLOAT</kbd> and follow it with
whatever you want the float to contain. When you’re done,
invoke <kbd>.FLOAT OFF</kbd> (or <kbd>QUIT, END, X</kbd>, etc).
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'ADJUST'</h5>
+
<p>
The optional <kbd>ADJUST</kbd> argument tells mom to raise
(<kbd>+</kbd>) or lower (<kbd>-</kbd>) the float <i>within
@@ -724,6 +754,14 @@ floats.
</p>
<p>
+<kbd>ADJUST</kbd> is ignored for the first float deferred to
+a following page but respected for subsequent deferred floats
+output immediately afterward.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'FORCE'</h5>
+
+<p>
The <kbd>FORCE</kbd> argument instructs mom to output the float
exactly where it occurs in the input file. With <kbd>FORCE</kbd>,
mom immediately breaks to a new page to output the float if it does
@@ -733,10 +771,13 @@ page), there are circumstances where it may be desirable.
</p>
<p>
-<kbd>ADJUST</kbd> is ignored whenever a float is deferred to
-the following page.
+If you need to force a page break after completion of a float that
+has been deferred to a subsequent page, insert <kbd>\!.bp</kbd>
+immediately before terminating the float.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'SPAN'</h5>
+
<p>
The <kbd>SPAN</kbd> argument tells mom that a float, if deferred,
may carry onto multiple pages. Please note that <kbd>SPAN</kbd> may
@@ -745,6 +786,30 @@ a warning should this occur. Unboxed tables, on the other
hand, are
acceptable within floats that are given the <kbd>SPAN</kbd> argument.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'INDENT'</h5>
+
+<p>
+<kbd>INDENT</kbd> allows you to indent a float from the left margin
+by a specified value. The value must have a
+(<a href="definitions.html#unitofmeasure">unit of measure</a>
+appended to it.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'CENTER'</h5>
+
+<p>
+<kbd>CENTER</kbd> instructs mom to center a float if it is not
+already centered by default.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'RIGHT'</h5>
+
+<p>
+<kbd>RIGHT</kbd> instructs mom to place a float a the right of the
+page; the longest line in the float will be flush with the page's
+right margin.
+</p>
+
<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_SHIM'</h5>
<p>
@@ -1218,12 +1283,12 @@ and do not wrap the table inside a float.
<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
-If you use <kbd>.TS H</kbd> to create a boxed table that spans
-multiple pages, do not attempt to wrap the table inside a float.
-For the purposes of boxed, multipage tables, <kbd>.TS H</kbd> and
-<kbd>.FLOAT</kbd> should be considered mutually exclusive. This
-restriction is imposed by the <kbd>tbl</kbd> preprocessor itself,
-not groff or mom.
+If you create a boxed table that will span several pages, do not
+wrap the table inside a float. Boxed, multipage tables and FLOAT
+should be considered mutually exclusive. This restriction is
+imposed by the <kbd>tbl</kbd> preprocessor itself, not groff or
+mom. Unboxed tables that span several pages, however, are
+acceptable within FLOAT.
</p>
</div>
@@ -1499,11 +1564,11 @@ number of rows.
<h5 class="docs" style="margin-top: 1em; text-transform: none">'ADJUST'</h5>
<p>
-<kbd>ADJUST</kbd> lets you raise (<kbd>+</kbd>) or lower (<kbd>-</kbd>) the
image
-<span style="font-style: italic">within the space allotted for it</span>
-by the amount you specify. This is useful for achieving good
-optical centering between surrounding blocks of type. A unit of
-measure is required.
+<kbd>ADJUST</kbd> lets you raise (<kbd>+</kbd>) or lower
+(<kbd>-</kbd>) the table <span style="font-style: italic">within
+the space allotted for it</span> by the amount you specify. This
+is useful for achieving good optical centering between surrounding
+blocks of type. A unit of measure is required.
</p>
<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_SHIM'</h5>
@@ -1645,11 +1710,9 @@ which, as of version 2.0-c, takes a single, optional
argument,
<kbd>SOURCE</kbd>. (Formerly, <kbd>TE</kbd> took a label/caption
argument along with arguments controlling placement.) The argument
is followed by the text of the table’s source, surrounded by
-double-quotes. The source will appear immediately beneath the label
-and/or caption underneath the table, or, if
+double-quotes. The SOURCE argument may only be used if
<a href="#mla">MLA</a>
-(Modern Language Association) is enabled, immediately below the
-table.
+(Modern Language Association) style is enabled.
</p>
<div class="rule-medium"><hr/></div>
@@ -2353,8 +2416,7 @@ will increment by one as expected.
<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
-For the purposes of labelling, mom
-treats
+For the purposes of labelling, mom treats
<a href="docprocessing.html#doctype">DOCTYPE DEFAULT</a>
as if it were <b>DOCTYPE CHAPTER</b>, hence, with
<kbd>PREFIX_CHAPTER</kbd>, each collated <b>DEFAULT</b>
diff --git a/contrib/mom/momdoc/macrolist.html
b/contrib/mom/momdoc/macrolist.html
index 55149ba..4b5d0db 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -76,6 +76,8 @@ elsewhere in the documentation.
<ul style="margin-top: .5em; margin-left: 0; padding-left: 0; list-style-type:
none;">
<li><a href="#qr-19">Reference macros (metadata)</a></li>
<li><a href="#qr-20">Document type and initial defaults</a></li>
+ <li><a href="#qr-20">Document type and initial defaults</a></li>
+ <li><a href="#qr-59"> – Slides</a></li>
<li><a href="#qr-23">TYPEWRITE control macros</a></li>
<li><a href="#qr-57">Vertical whitespace management</a></li>
<li><a href="#qr-47">Document and section cover (title) pages</a></li>
@@ -224,7 +226,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-4" class="quick-ref" colspan="2">+++ Linespacing (leading)</th>
+<th id="qr-4" class="quick-ref" colspan="2">
+<a href="typesetting.html#leading">+++ Linespacing (leading)</a></th>
</tr>
<tr>
<td><a href="typesetting.html#leading">LS</a></td><td>-- set the linespacing
(leading)</td>
@@ -267,7 +270,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-6" class="quick-ref" colspan="2">+++ Hyphenation</th>
+<th id="qr-6" class="quick-ref" colspan="2">
+<a href="typesetting.html#hy">+++ Hyphenation</a></th>
</tr>
<tr>
<td><a href="typesetting.html#hy">HY</a></td><td>-- automatic hyphenation
on/off</td>
@@ -279,7 +283,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-7" class="quick-ref" colspan="2">+++ Word and sentence spacing</th>
+<th id="qr-7" class="quick-ref" colspan="2">
+<a href="typesetting.html#ws">+++ Word and sentence spacing</a></th>
</tr>
<tr>
<td><a href="typesetting.html#ws">WS</a></td><td>-- set the minimum word space
size</td>
@@ -291,7 +296,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-8" class="quick-ref" colspan="2">+++ Kerning, ligatures,
smartquotes</th>
+<th id="qr-8" class="quick-ref" colspan="2">
+<a href="typesetting.html#kern">+++ Kerning, ligatures, smartquotes</a></th>
</tr>
<tr>
<td><a href="typesetting.html#kern">KERN</a></td><td>-- automatic character
pair kerning on/off</td>
@@ -420,7 +426,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-12" class="quick-ref" colspan="2">+++ Underscoring, underlining</th>
+<th id="qr-12" class="quick-ref" colspan="2">
+<a href="goodies.html#underscore">+++ Underscoring, underlining</a></th>
</tr>
<tr>
<td><a href="goodies.html#underscore">UNDERSCORE</a></td><td>-- underscore</td>
@@ -441,7 +448,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-13" class="quick-ref" colspan="2">+++ Superscipts</th>
+<th id="qr-13" class="quick-ref" colspan="2">
+<a href="goodies.html#sup">+++ Superscipts</a></th>
</tr>
<tr>
<td><a href="goodies.html#sup">\*[SUP]...\*[SUPX]</a></td><td>--
superscript</td>
@@ -500,7 +508,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-16" class="quick-ref" colspan="2">+++ Dropcaps</th>
+<th id="qr-16" class="quick-ref" colspan="2">
+<a href="goodies.html#dropcap">+++ Dropcaps</a></th>
</tr>
<tr>
<td><a href="goodies.html#dropcap">DROPCAP</a></td><td>-- set a dropcap</td>
@@ -524,7 +533,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-56" class="quick-ref" colspan="2">+++ Smallcaps</th>
+<th id="qr-56" class="quick-ref" colspan="2">
+<a href="typesetting.html#smallcaps">+++ Smallcaps</a></th>
</tr>
<tr>
<td><a href="typesetting.html#smallcaps">SMALLCAPS</a></td>
@@ -683,6 +693,9 @@ elsewhere in the documentation.
<td><a href="docprocessing.html#doctype">DOCTYPE</a></td><td>-- general
document type</td>
</tr>
<tr>
+<td id="qr-59"><a href="docprocessing.html#slides">DOCTYPE
SLIDES</a></td><td>-- create slide presentation</td>
+</tr>
+<tr>
<td><a href="docprocessing.html#copystyle">COPYSTYLE</a></td><td>-- draft or
final copy</td>
</tr>
<tr>
@@ -772,7 +785,7 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
<th id="qr-26" class="quick-ref" colspan="2">
-<a href="docelement.html#heading-intro">+++ HEADINGS</a></th>
+<a href="docelement.html#heading-intro">+++ Headings</a></th>
</tr>
<tr>
<td><a href="docelement.html#heading">HEADING</a></td><td>-- hierarchical
headings</td>
@@ -1181,7 +1194,7 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
<th id="qr-40" class="quick-ref" colspan="2">
-<a href="tables-of-contents.html#toc-intro">+++ Tables of contents</a></th>
+<a href="tables-of-contents.html">+++ Tables of contents</a></th>
</tr>
<tr>
<td><a href="tables-of-contents.html#toc">TOC</a></td><td>-- output a table of
contents</td>
@@ -1218,7 +1231,7 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
<th id="qr-41" class="quick-ref" colspan="2">
-<a href="letters.html#letters-intro">+++ Letter (correspondence)
macros</a></th>
+<a href="letters.html">+++ Letter (correspondence) macros</a></th>
</tr>
<tr>
<td><a href="letters.html#date">DATE</a></td><td>-- letter’s date</td>
@@ -1331,12 +1344,15 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
<th id="qr-45" class="quick-ref" colspan="2">
-<a href="rectoverso.html#rectoverso-intro">+++ Recto/verso page headers and
footers</a></th>
+<a href="rectoverso.html">+++ Recto/verso page headers and footers</a></th>
</tr>
<tr>
<td><a href="rectoverso.html#recto-verso">RECTO_VERSO</a></td><td>--
recto/verso headers and/or footers on/off</td>
</tr>
<tr>
+<td><a href="rectoverso.html#force-recto">FORCE_RECTO</a></td><td>-- insert
blank pages so chapters start recto</td>
+</tr>
+<tr>
<td><a href="rectoverso.html#switch-hdrftr">SWITCH_HEADERS</a></td><td>--
switch recto or verso header</td>
</tr>
<tr>
@@ -1401,7 +1417,7 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
<th id="qr-47" class="quick-ref" colspan="2">
-<a href="cover.html#cover-intro">+++ Document and section cover (title)
pages</a></th>
+<a href="cover.html">+++ Document and section cover (title) pages</a></th>
</tr>
<tr>
<td><a href="cover.html#cover">DOC_COVER</a></td><td>-- information to include
in a document cover</td>
diff --git a/contrib/mom/momdoc/tables-of-contents.html
b/contrib/mom/momdoc/tables-of-contents.html
index b1fb63a..4872039 100644
--- a/contrib/mom/momdoc/tables-of-contents.html
+++ b/contrib/mom/momdoc/tables-of-contents.html
@@ -200,6 +200,14 @@ of contents yourself with <strong>psselect</strong>,
described
below.
</p>
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Note: <kbd>.AUTO_RELOCATE_TOC</kbd> must come before
+<a href="docprocessing.html#start">START</a>.
+</p>
+</div>
+
<h4 id="psselect" class="docs"><span style="text-transform: none">Using
psselect to relocate the Table of Contents in PostScript documents</span></h4>
<p>
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index ec0fcca..eb1df1d 100644
--- a/contrib/mom/momdoc/toc.html
+++ b/contrib/mom/momdoc/toc.html
@@ -20,7 +20,7 @@ FDL in the main directory of the groff source package.
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8"/>
- <title>Mom, version 2.3-a -- Table of Contents</title>
+ <title>Mom, version 2.4 -- Table of Contents</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
</head>
@@ -31,7 +31,7 @@ FDL in the main directory of the groff source package.
<div class="page">
<div class="version">
- mom, version 2.3-a
+ mom, version 2.4
</div>
<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: Doc updates for verson 2.4.,
Peter Schaffter <=