[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: Documentation updates for 2.0-c_2
|
From: |
Peter Schaffter |
|
Subject: |
[groff] 01/01: Documentation updates for 2.0-c_2 |
|
Date: |
Mon, 01 Dec 2014 00:10:23 +0000 |
PTPi pushed a commit to branch master
in repository groff.
commit fd15172aa52e2a515b118eca35a6d794bb5a1284
Author: Peter Schaffter <address@hidden>
Date: Sun Nov 30 19:10:13 2014 -0500
Documentation updates for 2.0-c_2
---
contrib/mom/momdoc/docelement.html | 156 +++++++++++++++++++---------
contrib/mom/momdoc/macrolist.html | 2 +-
contrib/mom/momdoc/tables-of-contents.html | 116 ++++++++++++++++++++-
contrib/mom/momdoc/toc.html | 5 +-
4 files changed, 225 insertions(+), 54 deletions(-)
diff --git a/contrib/mom/momdoc/docelement.html
b/contrib/mom/momdoc/docelement.html
index 090352e..d34c585 100644
--- a/contrib/mom/momdoc/docelement.html
+++ b/contrib/mom/momdoc/docelement.html
@@ -469,11 +469,24 @@ or
<div class="box-tip">
<p class="tip">
-<span class="tip">Tip:</span>
+<span class="tip">Tips on vertical spacing around epigraphs:</span>
+If you wish to change the vertical position of an epigraph with
+<a href="typesetting.html#space">SPACE</a>/
+<a href="typesetting.html#ald">ALD</a>/
+<a href="typesetting.html#rld">RLD</a>,
+do so before invoking <kbd>.EPIGRAPH</kbd>, like this:
+<br/>
+<span class="pre-in-pp">
+ .SP -6p
+ .EPIGRAPH
+ A notable quote.
+ .EPIGRAPH OFF
+</span>
If you’re setting a document in
<a href="docprocessing.html#columns">columns</a>
-and you’d like to add or subtract space after the epigraph,
-the place to do it is inside the epigraph, like this:
+and you’d like to add or subtract space <i>after</i> the
+epigraph, which is centered over the top of both columns, the place
+to do it is inside the epigraph, like this:
<br/>
<span class="pre-in-pp">
.EPIGRAPH
@@ -1927,6 +1940,31 @@ This behaviour can be changed with the control macro
</p>
<div class="box-tip">
+<p class="tip">
+<span class="tip">Tips on vertical spacing around quotes:</span>
+If you wish to adjust the spacing before or after a quote or blockquote
+manually (with
+<a href="typesetting.html#space">SPACE</a>/
+<a href="typesetting.html#ald">ALD</a>/
+<a href="typesetting.html#rld">RLD</a>),
+do so <i>outside</i> the <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>,
+like this:
+<br/>
+<span class="pre-in-pp">
+ .SP -3p
+ .QUOTE
+ Candy is dandy
+ But liquor is quicker.
+ .QUOTE OFF
+ .SP -3p
+</span>
+</p>
+</div>
+
+
+
+
+<div class="box-tip">
<h2 id="quote-spacing-notes" class="docs" style="padding-top: 9px; font-size:
100%;">Further notes on quote spacing</h2>
<p clas"defaults">
@@ -4711,13 +4749,13 @@ appearance of endnotes pages, set them up prior to
<li><a href="#endnotes-hdrftr-center">Header/footer centre string when
doctype is CHAPTER</a></li>
<li><a href="#endnotes-allows-headers">Allow headers on endnotes
pages</a></li>
</ul></li>
- <li><a href="#endnotes-main-title"><b>Endnotes' first-page title
control</b></a>
+ <li><a href="#endnotes-header"><b>Endnotes header (first-page title)
control</b></a>
<ul style="margin-left: -.5em;">
- <li><a href="#endnote-string">Title string</a></li>
- <li><a href="#endnote-string-control">Title string control macros and
defaults</a></li>
- <li><a href="#endnote-string-placement">Title string placement</a></li>
- <li><a href="#endnote-string-underline">Title string underscoring</a></li>
- <li><a href="#endnote-string-caps">Title string capitalization</a></li>
+ <li><a href="#endnotes-header-string">Header string</a></li>
+ <li><a href="#endnotes-header-string-control">Header string control macros
and defaults</a></li>
+ <li><a href="#endnotes-header-placement">Header string placement</a></li>
+ <li><a href="#endnotes-header-underscore">Header string
underscoring</a></li>
+ <li><a href="#endnotes-header-caps">Header string capitalization</a></li>
</ul></li>
<li><a href="#endnotes-doc-title"><b>Endnotes document-identification string
control</b></a>
<ul style="margin-left: -.5em;">
@@ -5200,30 +5238,34 @@ ENDNOTES_ALLOWS_FOOTERS OFF.
</p>
</div>
-<h4 id="endnotes-main-title" class="docs">4. Endnotes' first-page title
control</h4>
+<h4 id="endnotes-header" class="docs">4. Endnotes header (first-page title)
control</h4>
-<!-- -ENDNOTE_STRING- -->
+<!-- -ENDNOTES_HEADER_STRING- -->
-<h5 id="endnote-string" class="docs" style="margin-top: 1em; margin-bottom:
.5em; margin-left: .5em;">• Title string</h5>
+<h5 id="endnotes-header-string" class="docs" style="margin-top: 1em;
margin-bottom: .5em; margin-left: .5em;">• Header (first-page title)
string</h5>
<div class="box-macro-args">
-Macro: <b>ENDNOTE_STRING</b> <kbd class="macro-args">"<head to print
at the top of endnotes>"</kbd>
+Macro: <b>ENDNOTES_HEADER_STRING</b> <kbd class="macro-args">"<title
to print at the top of endnotes>"</kbd>
</div>
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>ENDNOTE_STRING</b> (for compatibility with older documents)
+</p>
+
<p>
By default, mom prints the word “ENDNOTES” as a head
at the top of the first page of endnotes. If you want her to
-print something else, invoke <kbd>.ENDNOTE_STRING</kbd> with the
-endnotes-page head you want, surrounded by double-quotes. If you
-don’t want a head at the top of the first endnotes-page,
-invoke <kbd>.ENDNOTE_STRING</kbd> with a blank argument (either two
-double-quotes side by side—<kbd>""</kbd>—or no
-argument at all).
+print something else, invoke <kbd>.ENDNOTES_HEADER_STRING</kbd>
+with the endnotes-page head you want, surrounded by double-quotes.
+If you don’t want a head at the top of the first
+endnotes-page, invoke <kbd>.ENDNOTES_HEADER_STRING</kbd>
+with a blank argument (either two double-quotes side by
+side—<kbd>""</kbd>—or no argument at all).
</p>
-<!-- -ENDNOTE_STRING_CONTROL- -->
+<!-- -ENDNOTES_HEADER_CONTROL- -->
-<h5 id="endnote-string-control" class="docs" style="margin-top: -.5em;
margin-bottom: .5em; margin-left: .5em;">• Title control macros and
defaults</h5>
+<h5 id="endnotes-header-string-control" class="docs" style="margin-top: -.5em;
margin-bottom: .5em; margin-left: .5em;">• Header (first-page title)
control macros and defaults</h5>
<div class="defaults-container" style="padding-bottom: 8px;">
<p class="defaults" style="padding-top: 6px;">
@@ -5231,28 +5273,37 @@ See
<a href="#control-macro-args">Arguments to the control macros</a>.
</p>
<span class="pre defaults">
-.ENDNOTE_STRING_FAMILY default = prevailing document family
-.ENDNOTE_STRING_FONT default = bold
-.ENDNOTE_STRING_SIZE* default = +1
-.ENDNOTE_STRING_QUAD default = centred
-.ENDNOTE_STRING_COLOR default = black
+.ENDNOTES_HEADER_FAMILY default = prevailing document family
+.ENDNOTES_HEADER_FONT default = bold
+.ENDNOTES_HEADER_SIZE* default = +1
+.ENDNOTES_HEADER_QUAD default = centred
+.ENDNOTES_HEADER_COLOR default = black
*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE)
</span>
</div>
-<!-- -ENDNOTE_STRING_ADVANCE- -->
+<p style="margin-top: -2em">
+<b>Note:</b> <i>For compatibility with older documents, these macros are
aliased
+as</i> <kbd>.ENDNOTE_STRING_<SPEC></kbd>, e.g.
<kbd>.ENDNOTE_STRING_FAMILY</kbd>.
+</p>
+
+<!-- -ENDNOTES_HEADER_V_POS- -->
-<h5 id="endnote-string-placement" class="docs" style="margin-top: -1em;
margin-bottom: .5em; margin-left: .5em;">• Title string placement</h5>
+<h5 id="endnotes-header-placement" class="docs" style="margin-top: -.25em;
margin-bottom: .5em; margin-left: .5em;">• Header (first-page title)
placement</h5>
<div class="box-macro-args">
-Macro: <b>ENDNOTE_STRING_ADVANCE</b> <kbd class="macro-args"><distance from
top of page></kbd>
+Macro: <b>ENDNOTES_HEADER_V_POS</b> <kbd class="macro-args"><distance from
top of page></kbd>
</div>
<p class="requires">
• Argument requires a <a href="definitions.html#unitofmeasure">unit
of measusure</a>
</p>
+<p class="alias" style="margin-top: -1em; margin-bottom: 0;">
+<i>Alias:</i> <b>ENDNOTE_STRING_ADVANCE</b> (for compatibility with older
documents)
+</p>
+
<p>
By default, mom places the title (the docheader, as it were) of
endnotes pages (typically "ENDNOTES") on the same
@@ -5261,7 +5312,7 @@ that is used for the start of
<a href="definitions.html#running">running text</a>.
If you’d prefer another location, higher or lower on the page
(thereby also raising or lowering the starting position of the
-endnotes themselves), invoke <kbd>.ENDNOTE_STRING_ADVANCE</kbd> with
+endnotes themselves), invoke <kbd>.ENDNOTES_HEADER_V_POS</kbd> with
an argument stating the distance from the top edge of the page at
which you’d like the title placed.
</p>
@@ -5272,20 +5323,23 @@ to appear 1-1/2 inches from the top edge of the page,
you’d tell
mom about it like this:
<br/>
<span class="pre-in-pp">
- .ENDNOTE_STRING_ADVANCE 1.5i
+ .ENDNOTES_HEADER_V_POS 1.5i
</span>
</p>
-<!-- -ENDNOTE_STRING_UNDERLINE- -->
+<!--- ENDNOTES_HEADER_UNDERSCORE --->
-<h5 id="endnote-string-underline" class="docs" style="margin-top: -1em;
margin-bottom: .5em; margin-left: .5em;">• Title string
underscoring</h5>
+<h5 id="endnotes-header-underscore" class="docs" style="margin-top: -1em;
margin-bottom: .5em; margin-left: .5em;">• Header (first-page title)
underscoring</h5>
<div class="box-macro-args">
-Macro: <b>ENDNOTE_STRING_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE]
[<underscore weight> [<underscore gap> [<distance between double
rules]]] | <none> | <anything></kbd>
+Macro: <b>ENDNOTES_HEADER_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE]
[<underscore weight> [<underscore gap> [<distance between double
rules]]] | <none> | <anything></kbd>
</div>
<p class="alias" style="margin-bottom: 0;">
-<i>Alias:</i> <b>ENDNOTE_STRING_UNDERLINE</b>
+<i>Alias:</i> <b>ENDNOTES_HEADER_UNDERLINE</b>.
+<i>(For compatibility with older documents, also
+aliased as</i> <b>ENDNOTE_STRING_UNDERSCORE</b> <i>and</i>
+<b>ENDNOTE_STRING_UNDERLINE</b>.)
</p>
<p class="requires">
@@ -5298,16 +5352,16 @@ appended to it; all other arguments require a unit of
measure
</p>
<p>
-Invoked without an argument, <kbd>.ENDNOTE_STRING_UNDERSCORE</kbd>
+Invoked without an argument, <kbd>.ENDNOTES_HEADER_UNDERSCORE</kbd>
will place a single rule underneath the endnotes page title. Invoked
-with the argument, <kbd>DOUBLE</kbd>, ENDNOTE_STRING_UNDERSCORE will
+with the argument, <kbd>DOUBLE</kbd>, ENDNOTES_HEADER_UNDERSCORE will
double-underscore the title. Invoked with any other non-numeric
argument, (eg <kbd>OFF, NO, X</kbd>, etc.) the macro disables
underscoring of the title.
</p>
<p>
-In addition, you can use ENDNOTE_STRING_UNDERSCORE to control the
+In addition, you can use ENDNOTES_HEADER_UNDERSCORE to control the
weight of the underscore rule(s), the gap between the title and the
underscore, and, in the case of double-underscores, the distance
between the two rules.
@@ -5317,27 +5371,27 @@ between the two rules.
Some examples:
<br/>
<span class="pre-in-pp">
- .ENDNOTE_STRING_UNDERSCORE 1
+ .ENDNOTES_HEADER_UNDERSCORE 1
- turn underscoring on; set the rule weight to 1 point
- .ENDNOTE_STRING_UNDERSCORE 1 3p
+ .ENDNOTES_HEADER_UNDERSCORE 1 3p
- turn underscoring on; set the rule weight to 1 point; set
the gap between the title and the underscore to 3 points
- .ENDNOTE_STRING_UNDERSCORE DOUBLE .75 3p
+ .ENDNOTES_HEADER_UNDERSCORE DOUBLE .75 3p
- turn double-underscoring on; set the rule weight to 3/4 of
a point; set the gap between the title and the upper
underscore to 3 points; leave the gap between the upper
and the lower underunderscore at the default
- .ENDNOTE_STRING_UNDERSCORE DOUBLE 1.5 1.5p 1.5p
+ .ENDNOTES_HEADER_UNDERSCORE DOUBLE 1.5 1.5p 1.5p
- turn double-underscoring on; set the rule weight to 1-1/2
points; set the gap between the title and the upper
underscore to 1-1/2 points; set the gap between the upper
and the lower underscore to 1-1/2 points
</span>
Note, from the above, that in all instances, underscoring (single
-or double) is enabled whenever ENDNOTE_STRING_UNDERSCORE is used in
+or double) is enabled whenever ENDNOTES_HEADER_UNDERSCORE is used in
this way.
</p>
@@ -5347,16 +5401,20 @@ rules placed 2 points apart and 2 points below the
baseline of the
title.
</p>
-<!-- -ENDNOTE_STRING_CAPS- -->
+<!-- -ENDNOTES_HEADER_CAPS- -->
-<h5 id="endnote-string-caps" class="docs" style="margin-top: -.5em;
margin-bottom: .5em; margin-left: .5em;">• Title string
capitalization</h5>
+<h5 id="endnotes-header-caps" class="docs" style="margin-top: -.5em;
margin-bottom: .5em; margin-left: .5em;">• Header (first-page title)
capitalization</h5>
<div class="box-macro-args">
-Macro: <b>ENDNOTE_STRING_CAPS</b> <kbd class="macro-args">toggle</kbd>
+Macro: <b>ENDNOTES_HEADER_CAPS</b> <kbd class="macro-args">toggle</kbd>
</div>
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>ENDNOTE_STRING_CAPS</b> (for compatibility with older
documents)
+</p>
+
<p>
-Invoked by itself, <kbd>.ENDNOTE_STRING_CAPS</kbd> will
+Invoked by itself, <kbd>.ENDNOTES_HEADER_CAPS</kbd> will
automatically capitalize the endnotes-page title. Invoked with any
other argument, the macro disables automatic capitalization of the
title.
@@ -5366,8 +5424,8 @@ title.
If you’re generating a table of contents, you may want the
endnotes pages title to be in caps, but the toc entry in caps/lower
case. If the argument to
-<kbd><a href="#endnote-string">ENDNOTE_STRING</a></kbd>
-is in caps/lower case and ENDNOTE_STRING_CAPS is on, this is exactly
+<kbd><a href="#endnotes-header-string">ENDNOTES_HEADER_STRING</a></kbd>
+is in caps/lower case and ENDNOTES_HEADER_CAPS is on, this is exactly
what will happen.
</p>
diff --git a/contrib/mom/momdoc/macrolist.html
b/contrib/mom/momdoc/macrolist.html
index 4da8456..eea7438 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -1027,7 +1027,7 @@ elsewhere in the documentation.
<td><a href="docelement.html#endnotes-header-control">Header/footer
control</a></td>
</tr>
<tr>
-<td><a href="docelement.html#endnotes-main-title">Title control</a></td>
+<td><a href="docelement.html#endnotes-header-string-control">Title
control</a></td>
</tr>
<tr>
<td><a href="docelement.html#endnotes-doc-title">Document/section
identification control</a></td>
diff --git a/contrib/mom/momdoc/tables-of-contents.html
b/contrib/mom/momdoc/tables-of-contents.html
index 058b9f8..8683e81 100644
--- a/contrib/mom/momdoc/tables-of-contents.html
+++ b/contrib/mom/momdoc/tables-of-contents.html
@@ -580,6 +580,26 @@ example
</span>
</p>
+<h5 id="toc-header-style" class="docs" style="margin-top: 1em; text-transform:
none;">Header string vertical placement</h5>
+
+<div id="toc-header-v-pos" class="box-macro-args" style="margin-top: 1em">
+Macro: <b>TOC_HEADER_V_POS</b> <kbd class="macro-args"><distance from top
of page></kbd>
+</div>
+<p class="requires">
+• Requires a <a href="definitions.html#unitofmeasure">unit of
measure</a>
+</p>
+
+<p>
+Normally, the TOC header string falls at the same vertical position
+as the
+<a href="definitions.html#docheader">docheader</a>.
+If you’d like it to fall at a different position, say 2 inches, use
+<br/>
+<span class="pre-in-pp">
+ .TOC_HEADER_V_POS 2i
+</span>
+</p>
+
<h5 id="toc-header-style" class="docs" style="margin-top: -.5em;
text-transform: none;">Header string control macros and defaults</h5>
<div class="defaults-container" style="margin-top: 1em; padding-bottom: 8px;">
@@ -592,10 +612,101 @@ See
.TOC_HEADER_FONT default = bold
.TOC_HEADER_SIZE default = +4
.TOC_HEADER_QUAD default = left
+.TOC_HEADER_COLOR default = black
</span>
</div>
-<h4 id="toc-style" class="docs" style="margin-top: -1em;">4. Entries and
reference page numbers style</h4>
+<!-- -TOC_HEADER_CAPS- -->
+
+<h5 id="toc-header-caps" class="docs" style="margin-top: -1.5em;
margin-bottom: .5em; margin-left: .5em;">• Header (first-page title)
capitalization</h5>
+
+<div class="box-macro-args">
+Macro: <b>TOC_HEADER_CAPS</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+Invoked by itself, <kbd>.TOC_HEADER_CAPS</kbd> will automatically
+capitalize the the table of contents first-page title. Invoked with
+any other argument, the macro disables automatic capitalization of
+the title.
+</p>
+
+<p>
+You may want the table of contents first-page title to be in caps,
+but the title in subsequent page headers to be in caps/lower case.
+If the argument to
+<kbd><a href="#endnotes-header-string">TOC_HEADER_STRING</a></kbd>
+is in caps/lower case and TOC_HEADER_CAPS is on, this is exactly
+what will happen.
+</p>
+
+<p>
+Mom’s default is not to capitalize the table of contents
+first-page title string.
+</p>
+
+<!--- TOC_HEADER_UNDERSCORE- -->
+
+<h5 id="toc-header-underscore" class="docs" style="margin-top: -.25em;
margin-bottom: .5em; margin-left: .5em;">• Header (first-page title)
underscoring</h5>
+
+<div class="box-macro-args">
+Macro: <b>TOC_HEADER_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE]
[<underscore weight> [<underscore gap> [<distance between double
rules]]] | <none> | <anything></kbd>
+</div>
+
+<p class="requires">
+• The argument
+<span style="font-style: normal"><kbd><underscore weight></kbd></span>
+must not have the
+<a href="definitions.html#unitofmeasure">unit of measure</a>,
+<span style="font-style: normal;"><kbd>p</kbd></span>,
+appended to it; all other arguments require a unit of measure
+</p>
+
+<p>
+Invoked without an argument, <kbd>.TOC_HEADER_UNDERSCORE</kbd>
+will place a single rule underneath the table of contents
+first-page title. Invoked with the argument, <kbd>DOUBLE</kbd>,
+TOC_HEADER_UNDERSCORE will double-underscore the title. Invoked
+with any other non-numeric argument, (eg <kbd>OFF, NO, X</kbd>,
+etc.) the macro disables underscoring of the title.
+</p>
+
+<p>
+In addition, you can use TOC_HEADER_UNDERSCORE to control the
+weight of the underscore rule(s), the gap between the title and the
+underscore, and, in the case of double-underscores, the distance
+between the two rules.
+</p>
+
+<p>
+Some examples:
+<br/>
+<span class="pre-in-pp">
+ .TOC_HEADER_UNDERSCORE 1
+ - turn underscoring on; set the rule weight to 1 point
+
+ .TOC_HEADER_UNDERSCORE 1 3p
+ - turn underscoring on; set the rule weight to 1 point; set
+ the gap between the title and the underscore to 3 points
+
+ .TOC_HEADER_UNDERSCORE DOUBLE .75 3p
+ - turn double-underscoring on; set the rule weight to 3/4 of
+ a point; set the gap between the title and the upper
+ underscore to 3 points; leave the gap between the upper
+ and the lower underunderscore at the default
+
+ .TOC_HEADER_UNDERSCORE DOUBLE 1.5 1.5p 1.5p
+ - turn double-underscoring on; set the rule weight to 1-1/2
+ points; set the gap between the title and the upper
+ underscore to 1-1/2 points; set the gap between the upper
+ and the lower underscore to 1-1/2 points
+</span>
+Note, from the above, that in all instances, underscoring (single
+or double) is enabled whenever TOC_HEADER_UNDERSCORE is used in
+this way.
+</p>
+
+<h4 id="toc-style" class="docs" style="margin-top: -.5em;">4. Entries and
reference page numbers style</h4>
<p>
“Entries” refers to the hierarchical arrangement of
@@ -679,7 +790,8 @@ The default is zero.
<p>
<kbd>CAPS</kbd> instructs mom to capitalize title entries.
-Capitalization may be enabled or disabled on a per-title basis.
+Capitalization may be enabled or disabled on a per-entry-level
+basis.
</p>
<p>
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index da3b6b0..b01b891 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.1-c_1 -- Table of Contents</title>
+ <title>Mom, version 2.1-c_2 -- 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.1-c_1
+ mom, version 2.1-c_2
</div>
<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
@@ -47,6 +47,7 @@ FDL in the main directory of the groff source package.
<a href="#full-toc">Full Table of Contents</a>.
<br/>
If you've been using mom for a while, you may prefer the
+ <br/>
<a href="macrolist.html#top">Quick Reference Guide</a>.
</p>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: Documentation updates for 2.0-c_2,
Peter Schaffter <=