PTPi pushed a commit to branch master in repository groff. commit 9e1f67c9f7b0eda150e3fa1ed61d988be0068db3 Author: Peter Schaffter <pe...@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> _______________________________________________ Groff-commit mailing list Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit