[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: 2.5_a doc fixes and updates.
|
From: |
Peter Schaffter |
|
Subject: |
[groff] 01/01: 2.5_a doc fixes and updates. |
|
Date: |
Mon, 13 Dec 2021 15:01:56 -0500 (EST) |
PTPi pushed a commit to branch master
in repository groff.
commit 9e1f67c9f7b0eda150e3fa1ed61d988be0068db3
Author: Peter Schaffter <peter@schaffter.ca>
AuthorDate: Mon Dec 13 14:58:36 2021 -0500
2.5_a doc fixes and updates.
* LEFT_HANG entry re-written to reflect changes in the macro
---
contrib/mom/momdoc/goodies.html | 142 ++++++++++++++++++++++++++++--------
contrib/mom/momdoc/macrolist.html | 12 +--
contrib/mom/momdoc/toc.html | 4 +-
contrib/mom/momdoc/typesetting.html | 16 +++-
4 files changed, 134 insertions(+), 40 deletions(-)
diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html
index 5200873..b80dd8e 100644
--- a/contrib/mom/momdoc/goodies.html
+++ b/contrib/mom/momdoc/goodies.html
@@ -1571,67 +1571,149 @@ with <kbd>.CENTER_BLOCK/.CENTER_BLOCK OFF</kbd> (or
<kbd>QUIT</kbd>,
</div>
<br/>
<div class="box-macro-args">
-Macro: <b>LEFT_HANG</b> <kbd class="macro-args"><character></kbd>
+Macro: <b>LEFT_HANG</b> <kbd class="macro-args"><character> [
<gutter></kbd> ]
</div>
+<p class="requires">
+• left-hung characters
+</p>
<div class="box-macro-args" style="margin-top: 1em">
Inline: <b>\*[HANG <kbd class="macro-args"><character></kbd>]</b>
</div>
+<p class="requires">
+• right-hung characters
+</p>
+<p>
+Hung characters, frequently punctuation, fall outside the left or
+right margin. Their purpose is usually to fine-tune justification.
+Consider the following:
+<table style="margin-left: 3%; margin-right: 6%; text-align: justify">
+<tr>
+<td style="padding-right: 1em">
+“Play the man, Master Ridley; we
+shall this day light such a candle,
+by God's grace, in England, as I
+trust shall never be put out.”
+</td>
+<td>
+
+</td>
+<td style="margin-right: 0; padding-right: 0">
+“
+<br/>
+<br/>
+<br/>
+<br/>
+</td>
+<td style="margin-left: 0; padding-left: 0">
+Play the man, Master Ridley; we
+shall this day light such a candle,
+by God's grace, in England, as I
+trust shall never be put out.”</td>
+</td>
+</tr>
+</table>
+</p>
<p>
-LEFT_HANG hangs its argument to the left of the left margin.
-If enclosed in double-quotes, the argument may contain local
-horizontal motions.
+In the right hand example, the opening double-quote hangs outside
+the left margin, creating a uniform left margin for the text.
</p>
+<h4 class="docs">Left hung characters</h4>
+
<p>
-Input text after LEFT_HANG must begin by repeating the text of the
-argument, including horizontal motions. If the hung character is
-a left double-quote, <kbd>\[lq]</kbd> must be used in the argument
-and the usual keyboard double-quote (<kbd>"</kbd>) used for the
-input text so as not to confuse SMARTQUOTES.
+LEFT_HANG hangs its first argument, the character to be hung, to
+the left of the left margin. The optional second argument lets you
+specify an amount of space to insert between the hung character and
+the text.
</p>
<p>
+Input text after LEFT_HANG must begin with the character to be hung
+PLUS a
+<a href="inlines.html#inline-horizontal-mom">horizontal motion</a>
+corresponding to <kbd><gutter></kbd> if one was given.
+If the hung character is a left double-quote, <kbd>\[lq]</kbd>
+must be used as the argument to LEFT_HANG and the usual keyboard
+double-quote (<kbd>"</kbd>) entered as the input text so as not to
+confuse
+<a href="goodies.html#smartquotes">SMARTQUOTES</a>
The following example demonstrates:
<br>
<span class="pre-in-pp">
- .LEFT_HANG "\[lq]\*[FU3]"
- "\*[FU3]This line will have its opening double-quote
- plus three kern units of space hung outside the
- left margin."
+ .LEFT_HANG \[lq] 1p
+ "\*[FWD 1p]This line will have its opening double-quote
+ plus one point of space hung outside the left margin."
</span>
</p>
<p style="margin-top: -1em">
-The <kbd>\*[HANG]</kbd> inline escape hangs its single-character
-argument, typically a punctuation mark, outside the right margin of
-justified copy, like this:
-<br>
-<span class="pre-in-pp">
- This line will have its closing period hung outside
- the right margin\*[HANG .]
-</span>
-For the exceptionally fussy, <kbd><nobr>\*[HANG]</nobr></kbd> may
-also be used with centred text to centre the text visually without
-taking the hung punctuation into account.
+Note that what follows LEFT_HANG must be an input line and therefore
+it cannot be used to left-hang a
+<a href="docelement.html#heading">HEADING</a>
+character.
</p>
+<div class="box-tip">
+<p class="tip">
+<span class="important">Important:</span>
+Versions of mom lower than 2.5_a that included LEFT_HANG required
+that the character and its gutter be entered as a single,
+concatenated argument, using horizontal motions to establish the
+gutter
+(e.g.
+<a href="inlines.html#inline-horizontal-mom">FWD</a>,
+<a href="inlines.html#inline-horizontal-mom">BCK</a>).
+Documents created with versions prior to 2.5_a may have to be
+updated.
+</p>
+</div>
+
+<h4 class="docs">Right hung characters</h4>
+
<p>
+The <kbd>\*[HANG c]</kbd> inline escape hangs its argument outside
+the right margin of justified or quad right copy. The argument may
+be a single character, or a single character preceded by a
+horizontal motion, effectively establishing a gutter between the
+right margin and the hung character:
+<br>
+<span class="pre-in-pp" style="margin-bottom: .25em">
+ This line will have its closing period hung outside
+ the right margin with a one point gutter\*[HANG \*[FWD 1p].]
+</span>
If the hung character is a right double-quote, <kbd>"\[rq]"</kbd>
-must be used as the argument (that is, the <kbd>\[rq]</kbd> character
surrounded
-by double-quotes). The double-quotes are required for all special
-characters of the form <kbd>\[xx]</kbd>.
+must be used as the argument (that is, the <kbd>\[rq]</kbd>
+character surrounded by double-quotes). The double-quotes are
+required for all special characters of the form
+<kbd style="whitespace: nowrap">\[name]</kbd>.
+Horizontal motion, if any, must fall inside the double-quotes:
+<br>
+<span class="pre-in-pp">
+ ...and they all lived happily ever after.\*[HANG "\*[FWD 1p]\[rq]"]
+</span>
</p>
<p>
If the hung character is a hyphen,
-<kbd><nobr>\*[HANG -]</nobr></kbd> must come at the end of an
+<kbd style="whitespace: nowrap"><nobr>\*[HANG -]</nobr></kbd>
+must come at the end of an
<a href="definitions.html#inputline">input line</a>.
-All other characters may be used mid-line if groff breaks the line
-naturally at the point the hung character is introduced.
+This restriction does not apply to other characters, which may come
+anywhere in an input line provided that, on output, the line breaks
+at the point you introduced the hung character.
</p>
+
+<p>
+For the exceptionally fussy, <kbd>\*[HANG]</kbd> may also be used to
+improve visual centring; when text is centred, <kbd
+style="whitespace: nowrap">\*[HANG c]</kbd>
+hangs the character to the right of the centred line instead of the
+margin.
+</p>
+
<div class="rule-long"><hr/></div>
<!-- Navigation links -->
diff --git a/contrib/mom/momdoc/macrolist.html
b/contrib/mom/momdoc/macrolist.html
index e7f257f..aed89b9 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -239,7 +239,7 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
<th id="qr-5" class="quick-ref" colspan="2">
-<a href="typesetting.html#justification-intro">+++ Justification, quad
direction, line-by-line setting, breaking lines</a></th>
+<a href="typesetting.html#justification-intro">+++ Justification, quad,
line-by-line setting, breaking lines</a></th>
</tr>
<tr>
<td><a href="typesetting.html#justify">JUSTIFY</a></td><td>-- justify text to
both margins</td>
@@ -588,7 +588,7 @@ elsewhere in the documentation.
<td><a href="inlines.html#inline-rule-mom">\*[RULE]</a></td><td>-- draw a full
measure rule</td>
</tr>
<tr>
-<td><a href="goodies.html#sizespecs">SIZESPECS</a></td><td>-- get cap-height,
x-height and descender depth</td>
+<td><a href="goodies.html#sizespecs">SIZESPECS</a></td><td>-- cap-height,
x-height, descender depth</td>
</tr>
<tr>
<td><a href="goodies.html#silent">SILENT</a></td><td>-- output processing off
or on</td>
@@ -596,6 +596,9 @@ elsewhere in the documentation.
<tr>
<td><a href="goodies.html#trap">TRAP</a></td><td>-- enable or disable page
position traps</td>
</tr>
+<tr>
+<td><a href="goodies.html#left-hang">LEFT_HANG / \*[HANG]</a></td><td>--
hanging punctuation</td>
+</tr>
</table>
<table class="quick-ref">
@@ -637,7 +640,7 @@ elsewhere in the documentation.
<td><a href="docprocessing.html#title">TITLE</a></td><td>-- document title</td>
</tr>
<tr>
-<td><a href="docprocessing.html#doc-title">DOCTITLE</a></td><td>-- overall
document title (if different from TITLE)</td>
+<td><a href="docprocessing.html#doc-title">DOCTITLE</a></td><td>-- document
title (if different from TITLE)</td>
</tr>
<tr>
<td><a href="docelement.html#endnote-title">ENDNOTE_TITLE</a></td><td>--
document/chapter id string for endnotes</td>
@@ -1503,9 +1506,6 @@ elsewhere in the documentation.
<tr>
<td><a href="goodies.html#center-block">CENTER_BLOCK</a></td><td>-- centre
blocks of type</td>
</tr>
-<tr>
-<td><a href="goodies.html#left-hang">LEFT_HANG / \*[HANG c]</a></td><td>--
hanging punctuation</td>
-</tr>
</table>
<div class="rule-long"><hr/></div>
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index a276bd3..ef6bcf4 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.5 -- Table of Contents</title>
+ <title>Mom, version 2.5_a -- 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.5
+ mom, version 2.5_a
</div>
<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
diff --git a/contrib/mom/momdoc/typesetting.html
b/contrib/mom/momdoc/typesetting.html
index 78a7cc5..4e0acfe 100644
--- a/contrib/mom/momdoc/typesetting.html
+++ b/contrib/mom/momdoc/typesetting.html
@@ -1804,10 +1804,21 @@ line space (or multiple thereof), and ALD whenever you
want some
other value of space after a line.
</p>
-<p class="tip-bottom">
+<p>
<span class="experts">Experts:</span> SPACE is an alias of
<kbd>.sp</kbd>. You can use either, or mix ’n’ match
-with impunity.
+with impunity. Because SPACE aliases <kbd>.sp</kbd>, it may be used
+with groff’s absolute position modifier
+“<kbd>|</kbd>” (the pipe
+character) to move to a specified vertical location on the page.
+Consult
+<span class="pre-in-pp">
+ info groff “Manipulating Spacing”
+</span>
+or, more simply,
+<span class="pre-in-pp">
+ info groff sp.
+</span>
</p>
</div>
@@ -3106,6 +3117,7 @@ page relative to the current
<ul class="macro-list">
<li><a href="#ald">ALD</a> – Advance Lead</li>
<li><a href="#rld">RLD</a> – Reverse Lead</li>
+ <li>(see also <a href="#space">SPACE</a>)
</ul>
</div>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: 2.5_a doc fixes and updates.,
Peter Schaffter <=