[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: Version 2.0 doc updates
|
From: |
Peter Schaffter |
|
Subject: |
[groff] 01/01: Version 2.0 doc updates |
|
Date: |
Wed, 05 Mar 2014 02:26:21 +0000 |
PTPi pushed a commit to branch master
in repository groff.
commit ca927f6ad9e8ff21a2f2a062622a02bc29a8cfaa
Author: Peter Schaffter <address@hidden>
Date: Tue Mar 4 21:26:04 2014 -0500
Version 2.0 doc updates
---
contrib/mom/momdoc/appendices.html | 2 +-
contrib/mom/momdoc/color.html | 2 +-
contrib/mom/momdoc/cover.html | 2 +-
contrib/mom/momdoc/definitions.html | 2 +-
contrib/mom/momdoc/docelement.html | 162 ++-
contrib/mom/momdoc/docprocessing.html | 35 +-
contrib/mom/momdoc/goodies.html | 2 +-
contrib/mom/momdoc/graphical.html | 87 ++-
contrib/mom/momdoc/headfootpage.html | 2 +-
contrib/mom/momdoc/images.html | 1752 ++++++++++++++++++++++++----
contrib/mom/momdoc/inlines.html | 2 +-
contrib/mom/momdoc/intro.html | 2 +-
contrib/mom/momdoc/letters.html | 2 +-
contrib/mom/momdoc/macrolist.html | 118 ++-
contrib/mom/momdoc/rectoverso.html | 2 +-
contrib/mom/momdoc/refer.html | 2 +-
contrib/mom/momdoc/reserved.html | 29 +-
contrib/mom/momdoc/tables-of-contents.html | 2 +-
contrib/mom/momdoc/toc.html | 46 +-
contrib/mom/momdoc/typesetting.html | 15 +-
contrib/mom/momdoc/using.html | 2 +-
contrib/mom/momdoc/version-2.html | 12 +-
22 files changed, 1901 insertions(+), 381 deletions(-)
diff --git a/contrib/mom/momdoc/appendices.html
b/contrib/mom/momdoc/appendices.html
index d425f07..56d605c 100644
--- a/contrib/mom/momdoc/appendices.html
+++ b/contrib/mom/momdoc/appendices.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html
index e05941a..eaf7831 100644
--- a/contrib/mom/momdoc/color.html
+++ b/contrib/mom/momdoc/color.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/cover.html b/contrib/mom/momdoc/cover.html
index f65f45e..c8154f9 100644
--- a/contrib/mom/momdoc/cover.html
+++ b/contrib/mom/momdoc/cover.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/definitions.html
b/contrib/mom/momdoc/definitions.html
index 192c4cc..2cf0d8b 100644
--- a/contrib/mom/momdoc/definitions.html
+++ b/contrib/mom/momdoc/definitions.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/docelement.html
b/contrib/mom/momdoc/docelement.html
index 01cef92..34345ce 100644
--- a/contrib/mom/momdoc/docelement.html
+++ b/contrib/mom/momdoc/docelement.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -35,7 +35,7 @@ FDL in the main directory of the groff source package.
<table style="width: 100%;">
<tr>
<td><a href="toc.html">Back to Table of Contents</a></td>
- <td style="text-align: right;"><a href="images.html#top">Next: Inserting
images</a></td>
+ <td style="text-align: right;"><a href="images.html#top">Next: Graphics,
floats, preprocessor support</a></td>
</tr>
</table>
@@ -796,8 +796,8 @@ For example, assuming you have defined the colour, blue,
.PP
.COLOR blue
<first paragraph>
- .HEAD "Monty Python"
- .SUBHEAD "The Origins of Spam"
+ .HEADING 1 "Monty Python"
+ .HEADING 2 "The Origins of Spam"
.PP
<second paragraph>
</span>
@@ -1288,20 +1288,27 @@ HEADING_STYLE takes any or all of the following
arguments,
which may be given in any order:
<br/>
<span class="pre defaults">
- FAMILY <family>
- FONT <font>
- SIZE <+|-size>
- QUAD <direction>
- COLOR <colour>
- UNDERSCORE <weight> <gap> | NO_UNDERSCORE
- UNDERSCORE2 <weight> <gap1> <gap2> | NO_UNDERSCORE2
- CAPS | NO_CAPS
- BASELINE_ADJUST <amount to raise heading from the baseline>
- SPACE_AFTER | NO_SPACE_AFTER
+ FAMILY <family> \
+ FONT <font> \
+ SIZE <+|-size> \
+ QUAD <direction> \
+ COLOR <colour> \
+ UNDERSCORE <weight> <gap> | NO_UNDERSCORE \
+ UNDERSCORE2 <weight> <gap1> <gap2> | NO_UNDERSCORE2 \
+ CAPS | NO_CAPS \
+ BASELINE_ADJUST <amount to raise heading from the baseline> \
+ SPACE_AFTER | NO_SPACE_AFTER \
NUMBER | NO_NUMBER
</span>
</p>
+<p>
+You may enter your entire argument list on a single line, or, if it
+is very long, break it into shorter lines with the
+“line-continued” backslash {<kbd>\</kbd>), as shown
+above.
+</p>
+
<p class="defaults" style="margin-bottom: 1em">
The arguments to <kbd>FAMILY</kbd>, <kbd>FONT</kbd>,
<kbd>SIZE</kbd>, <kbd>QUAD</kbd>, and
@@ -1361,7 +1368,7 @@ entries is controlled separately with
<a href="tables-of-contents.html#toc-entry-numbers">TOC_ENTRY_NUMBERS</a>.
Mom also has a special macro to toggle whether to prefix a chapter
number to numbered headings and Table of Contents entries,
-<a href="prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>.
+<a href="#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>.
</p>
<p class="defaults" style="padding-bottom: .5em">
@@ -2317,7 +2324,7 @@ This macro also sets mom’s spacing policy for
<!-- ==================================================================== -->
-<h2 id="code-intro" class="macro-group">Inserting code snippets</h2>
+<h2 id="code-intro" class="macro-group">Inserting code into a document</h2>
<ul style="margin-left: -.5em;">
<li><a href="#code">Tag: CODE</a></li>
@@ -2325,7 +2332,7 @@ This macro also sets mom’s spacing policy for
</ul>
<p>
-CODE is a convenience macro that facilitates entering code snippets
+CODE is a convenience macro that facilitates entering code blocks
into documents. Its use is not restricted to documents created
using mom’s document processing macros; it can be used for
“manually” typeset documents as well.
@@ -2344,35 +2351,16 @@ Inline escape: <b><kbd>\*[CODE]</kbd></b>
</p>
<p>
-When you invoke <kbd>.CODE</kbd> without an argument, or use the
-<a href="definitions.html#inlines">inline escape</a>,
-<kbd>\*[CODE]</kbd>,
-mom changes the font to a
+When you invoke the macro, <kbd>.CODE</kbd>, or insert <kbd>\*[CODE]</kbd> into
+running text, mom switches to a
<a href="definitions.html#fixedwidthfont">fixed-width font</a>
(Courier, by default) and turns
<a href="goodies.html#smartquotes">SMARTQUOTES</a>
-off. Additionally, if you invoke <kbd>.CODE</kbd> inside
-<a href="#quote">QUOTE</a>
-while in
-<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>
-with the default underlining of quotes turned on, it disables the
-underlining for the duration of CODE.
+off.
</p>
<p>
-Passing any argument other than <kbd>BR</kbd>, <kbd>BREAK</kbd>
-or <kbd>SPREAD</kbd> to CODE (eg <kbd>OFF, QUIT, END, X,</kbd>
-etc.) turns CODE off and returns the family, font, smartquotes
-and (if applicable) underlining of quotes to their former state.
-If you’ve used the inline escape, <kbd>\*[CODE]</kbd>, to
-initiate a section of code, <kbd>\*[CODE OFF]</kbd> equally returns
-things to their former state.
-</p>
-
-<div class="box-tip">
-<p class="tip">
-<span class="note">Note:</span>
-If your code snippet includes the backslash character, which is
+If your code includes the backslash character, which is
groff’s escape character, you will have to change the
escape character temporarily to something else with the macro,
<a href="goodies.html#esc-char">ESC_CHAR</a>.
@@ -2380,11 +2368,27 @@ Mom has no way of knowing what special characters
you’re going
to use in code snippets, therefore she cannot automatically replace
the escape character with something else.
</p>
-</div>
-<div class="box-important">
+<p>
+The correct order for changing the escape character inside
+<kbd>CODE</kbd> is
+<span class="pre-in-pp">
+ .CODE
+ .ESC_CHAR character
+ <code>
+ .ESC_CHAR .
+ .CODE OFF
+</span>
+</p>
+
+<p>
+Alternatively, you can enter the backslash character as
+<kbd>\e</kbd>, which tells groff to print a literal backslash.
+</p>
+
+<div class="box-tip">
<p class="tip-top">
-<span class="important">Important:</span>
+<span class="tip">Note:</span>
<kbd>.CODE</kbd> does not cause a line break when
you’re in a
<a href="definitions.html#filled">fill mode</a>
@@ -2407,7 +2411,7 @@ a break (eg
<a href="#pp">PP</a>).
</p>
-<p>
+<p class="tip-bottom">
In all likelihood, if you want the situation described above (ie a
break before and after CODE), what you probably want is to use
<a href="quote">QUOTE</a>
@@ -2425,15 +2429,66 @@ indenting the code and offsetting it from
<a href="definitions.html#running">running text</a>
with vertical whitespace.
</p>
+</div>
-<p class="tip-bottom">
-<span class="note">Note:</span>
-<kbd>BR</kbd>, <kbd>BREAK</kbd> and <kbd>SPREAD</kbd> have no
-effect when used with the inline escape, <kbd>\*[CODE]</kbd>. The
-assumption behind <kbd>\*[CODE]</kbd> is that you’re inserting
-a bit of code into a line, not creating a distinct code block.
+<p>
+Passing any argument other than <kbd>BR</kbd>, <kbd>BREAK</kbd> or
+<kbd>SPREAD</kbd> to CODE (eg <kbd>OFF, QUIT, END, X,</kbd> etc.)
+turns CODE off and returns the family, font, and smartquotes back to
+their former state.
+</p>
+
+<h4 class="docs" style="font-size: 102%">Using <kbd>\*[CODE]</kbd> inline</h4>
+
+<p>
+<kbd>\*[CODE]</kbd> invokes <kbd>.CODE</kbd>, allowing you to
+bracket code snippets inline. It does not accept the <kbd>BR</kbd>,
+<kbd>BREAK</kbd>, or <kbd>SPREAD</kbd> arguments. It is most useful
+for short snippets, as in the following example.
+<br/>
+<span class="pre-in-pp">
+ \*[CODE]apropos\*[CODE OFF] and \*[CODE]man -k\*[CODE] are identical.
+</span>
</p>
-</div>
+
+<p>
+<kbd>\*[CODE]</kbd> does not permit changing the escape character,
+so <kbd>\e</kbd> must be used. Furthermore, if your code starts
+with a period, you must enter it as “<kbd>\&.</kbd>”.
+<br/>
+<span class="pre-in-pp">
+ Registers are created with the \*[CODE]\&.nr\*[CODE OFF] request.
+</span>
+</p>
+
+<h4 class="docs" style="font-size: 102%; margin-top: -1em">CODE and
punctuation</h4>
+
+<p>
+<kbd>.CODE OFF</kbd> automatically inserts a word space into
+running text. If your CODE block is to be followed by punctuation
+with the parameters of
+<a href="definitions.html#running">running text</a>,
+you must terminate the block with “<kbd>\c</kbd>” and
+enter the punctuation at the beginning of the next input line. If
+the punctuation mark is a period, you must precede it with
+“<kbd>\&</kbd>”.
+<br/>
+<span class="pre-in-pp">
+ ...for example,
+ .CODE
+ echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/'\c
+ .CODE OFF
+ \&. As this demonstrates...
+</span>
+Use of <kbd>\*[CODE]</kbd> inline does not require the
+<kbd>\c</kbd>, however periods after <kbd>\*[CODE OFF]</kbd>
+still need to be introduced with <kbd>\&</kbd>, as in this example:
+<br/>
+<span class="pre-in-pp">
+ ...append the unit of measure \*[CODE]p\*[CODE OFF]\&. New sentence...
+</span>
+</p>
+
<div class="defaults-container" style="background-color: #ded4bd; border:
none;">
<h3 id="code-control" class="docs defaults">CODE control macros and
defaults</h3>
@@ -4452,7 +4507,7 @@ by superscript numbers. The text of the endnotes
themselves is
indented to the right of the numbers.
</p>
-<div class="box-tip" style="margin-top: -1.25em;">
+<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
The one-half linespace between section identifiers and the endnotes
@@ -4472,7 +4527,6 @@ themselves, and therefore need not be bound by the style
parameters
of the body of the document.
</p>
-
<h3 id="endnote-columns" class="docs">Endnotes and columnar documents</h3>
<p>
@@ -6264,7 +6318,7 @@ new colour; the em-dashes will be in the default document
colour
<tr>
<td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
<td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
- <td style="width: 33%; text-align: right;"><a href="images.html#top">Next:
Inserting images</a></td>
+ <td style="width: 33%; text-align: right;"><a href="images.html#top">Next:
Graphics, floats, and preprocessor support</a></td>
</tr>
</table>
diff --git a/contrib/mom/momdoc/docprocessing.html
b/contrib/mom/momdoc/docprocessing.html
index 9d1c504..a044dcc 100644
--- a/contrib/mom/momdoc/docprocessing.html
+++ b/contrib/mom/momdoc/docprocessing.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -301,12 +301,7 @@ leading back on track.
<p>
For example, say you want to insert an image into a document with
-<a href="images.html#pdf-image">PDF_IMAGE</a>
-or
<a href="images.html#pspic">PSPIC</a>.
-</p>
-
-<p>
Images and graphics aren’t usually conveniently sized in
multiples of the document leading, which means that when you insert
the picture, you disrupt mom’s ordered placement of baselines
@@ -320,7 +315,7 @@ The solution is to insert SHIM after the image, like this:
<br/>
<span class="pre-in-pp">
<text>
- .PDF_IMAGE <args> <span style="font-family: arial,sans-serif;
font-weight: normal;">or</span> .PSPIC <args>
+ .PSPIC <args>
.SHIM
<text>
</span>
@@ -337,8 +332,7 @@ flow of output lines with the picture.
<p>
And say, on previewing the above example, you find the image
doesn’t centre nicely between the lines of text, you can
-adjust the image position either by passing a baseline adjustment
-to PDF_IMAGE, or by using
+adjust the image position by using
<a href="typesetting.html#ald">ALD</a>
or
<a href="typesetting.html#rld">RLD</a>
@@ -346,22 +340,26 @@ before PSPIC. To demonstrate,
<br/>
<span class="pre-in-pp">
<text>
- .PDF_IMAGE <args> -3p
- .SHIM
- <text>
-</span>
-and
-<span class="pre-in-pp">
- <text>
.RLD 3p
.PSPIC <args>
.SHIM
<text>
</span>
-both raise an image slightly within the space allotted for it while
-ensuring that text underneath falls exactly where should.
+which raises the image slightly and thereby balances the whitespace around it.
</p>
+<p>
+You may sometimes find the amount of space generated by
+<kbd>SHIM</kbd> looks too big, whether inserted manually into a
+document or as a result of automatic shimming (see immediately
+below). The situation occurs when the amount of shimming applied
+comes close to the leading currently in effect, making it seem as if
+there’s one linespace too much whitespace. The solution is
+simply to add <kbd>.SPACE -1v</kbd> or <kbd>.RLD 1v</kbd>
+to the document immediately after <kbd>.SHIM</kbd>. (Both
+<kbd>.SPACE -1v</kbd> and <kbd>.RLD 1v</kbd> back up
+by one linespace.)
+</p>
<h4 id="automatic-shimming" class="docs">Automatic shimming of headings,
quotes, blockquotes, PDF images, and floats</h4>
<p style="margin-bottom: -1em">
@@ -3303,6 +3301,7 @@ the tops of pages after the first.)
document’s default leading.
+<a id="autolead"></a>
AUTOLEAD •Invoked before START, sets the overall document
leading as a function of the overall document
point size (ie the point size used in paragraphs);
diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html
index e624a92..5a4eb03 100644
--- a/contrib/mom/momdoc/goodies.html
+++ b/contrib/mom/momdoc/goodies.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/graphical.html
b/contrib/mom/momdoc/graphical.html
index 54559a6..ace548b 100644
--- a/contrib/mom/momdoc/graphical.html
+++ b/contrib/mom/momdoc/graphical.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -228,14 +228,25 @@ Macro: <b>DRH</b> <kbd class="macro-args"><none> |
<weight> <ind
</div>
<p class="requires">
-• The argument to <kbd class="normal"><weight></kbd> is in
+•
+the argument to <kbd class="normal"><weight></kbd> is in
<a href="definitions.html#picaspoints" class="normal">points</a>,
but do <span class="normal">NOT</span> append the
<a href="definitions.html#unitsofmeasure">unit of measure</a>,
-<kbd class="normal">p</kbd>.
+<kbd class="normal">p</kbd>
<br/>
-• The arguments, <kbd class="normal"><indent></kbd> and
-<kbd class="normal"><length></kbd>, require a unit of measure.
+•
+<kbd class="normal"><indent></kbd>
+and
+<kbd class="normal"><length></kbd>
+require a unit of measure
+<br/>
+•
+arithmetic expressions to
+<kbd class="normal"><indent></kbd>
+and
+<kbd class="normal"><length></kbd>
+must be surrounded by parentheses
</p>
<p>
@@ -324,14 +335,25 @@ Macro: <b>DRV</b> <kbd class="macro-args"><weight>
<indent> <dep
</div>
<p class="requires">
-• The argument to <kbd class="normal"><weight></kbd> is in
+•
+the argument to <kbd class="normal"><weight></kbd> is in
<a href="definitions.html#picaspoints" class="normal">points</a>,
but do <span class="normal">NOT</span> append the
<a href="definitions.html#unitsofmeasure">unit of measure</a>,
-<kbd class="normal">p</kbd>.
+<kbd class="normal">p</kbd>
+<br/>
+•
+<kbd class="normal"><indent></kbd>
+and
+<kbd class="normal"><depth></kbd>
+require a unit of measure
<br/>
-• The arguments, <kbd class="normal"><indent></kbd> and
-<kbd class="normal"><depth></kbd>, require a unit of measure.
+•
+arithmetic expressions to
+<kbd class="normal"><indent></kbd>
+and
+<kbd class="normal"><depth></kbd>
+must be surrounded by parentheses
</p>
<p>
@@ -401,15 +423,26 @@ Macro: <b>DBX</b> <kbd class="macro-args"><
<weight> | SOLID > <i
</div>
<p class="requires">
-• The argument to <kbd class="normal"><weight></kbd> is in
+•
+the argument to <kbd class="normal"><weight></kbd> is in
<a href="definitions.html#picaspoints" class="normal">points</a>,
but do <span class="normal">NOT</span> append the
-<a href="definitions.html#unitsofmeasure">unit of measure</a>,
-<kbd class="normal">p</kbd>.
+<a href="definitions.html#unitsofmeasure">unit of measure</a>
+<kbd class="normal">p</kbd>
<br/>
-• The arguments, <kbd class="normal"><indent></kbd>,
-<kbd class="normal"><length></kbd> and
-<kbd class="normal"><depth></kbd>, require a unit of measure.
+• <kbd class="normal"><indent></kbd>,
+<kbd class="normal"><length></kbd>,
+and
+<kbd class="normal"><depth></kbd>
+require a unit of measure
+<br/>
+•
+arithmetic expressions to
+<kbd class="normal"><indent></kbd>,
+<kbd class="normal"><length></kbd>,
+and
+<kbd class="normal"><depth></kbd>
+must be surrounded by parentheses
</p>
<p>
@@ -488,15 +521,27 @@ Macro: <b>DCL</b> <kbd class="macro-args"><
<weight> | SOLID > <i
</div>
<p class="requires">
-• The argument to <kbd class="normal"><weight></kbd> is in
+• the argument to <kbd class="normal"><weight></kbd> is in
<a href="definitions.html#picaspoints" class="normal">points</a>,
but do <span class="normal">NOT</span> append the
<a href="definitions.html#unitsofmeasure">unit of measure</a>,
-<kbd class="normal">p</kbd>.
+<kbd class="normal">p</kbd>
+<br/>
+•
+the arguments
+<kbd class="normal"><indent></kbd>,
+<kbd class="normal"><length></kbd>
+and
+<kbd class="normal"><depth></kbd>
+require a unit of measure
<br/>
-• The arguments, <kbd class="normal"><indent></kbd>,
-<kbd class="normal">length</kbd> and
-<kbd class="normal"><depth></kbd>, require a unit of measure.
+•
+arithmetic expressions to
+<kbd class="normal"><indent></kbd>,
+<kbd class="normal"><length></kbd>
+and
+<kbd class="normal"><depth></kbd>
+must be surrounded by parentheses
</p>
<p>
@@ -526,7 +571,7 @@ centimeters. To do so, you'd invoke <kbd>.DCL</kbd> like
this:
| |
.DCL .5 1i 6c 3c
| |
- weight ength
+ weight length
</span>
(Note that the box weight argument, which is expressed in points,
must NOT have the unit of measure <kbd>p</kbd> appended to it.)
diff --git a/contrib/mom/momdoc/headfootpage.html
b/contrib/mom/momdoc/headfootpage.html
index 67fed27..ae87c36 100644
--- a/contrib/mom/momdoc/headfootpage.html
+++ b/contrib/mom/momdoc/headfootpage.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index 8754d72..5236f9f 100644
--- a/contrib/mom/momdoc/images.html
+++ b/contrib/mom/momdoc/images.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -41,33 +41,64 @@ FDL in the main directory of the groff source package.
<h1 class="docs">Graphics, floats, and preprocessor support</h1>
-<div style="width: 55%; margin: auto;">
+<div style="width: 80%; margin: auto;">
<ul class="no-enumerator" style="margin-left: -1em;">
- <li><a href="#images-intro">Introduction to inserting images and graphics</a>
- <li><a href="#converting">Image conversion and file processing</a>
- <ul style="margin-left: -.5em; list-style-type: disc;">
- <li><a href="#pdf">PDF</a></li>
- <li><a href="#eps">EPS</a></li>
+ <li><a href="#images-intro">Inserting images and graphics</a>
+ <ul>
+ <li><a href="#converting">Image conversion and file processing</a>
+ <ul style="margin-left: -1.25em">
+ <li><a href="#pdf">PDF</a></li>
+ <li><a href="#eps">EPS</a></li>
+ </ul></li>
+ <li><a href="#pdf-image">The PDF_IMAGE macro</a>
+ <ul style="margin-left: -1.25em">
+ <li><a href="#pdf-image-frame">PDF_IMAGE_FRAME</a>—set parameters
for image frames</li>
+ </ul></li>
+ <li><a href="#pspic">The PSPIC macro</a></li>
+ </ul>
+ <li><a href="#floats-intro">Floats</a>
+ <ul>
+ <li><a href="#float">The FLOAT macro</a></li>
</ul></li>
- <li><a href="#pdf-image">The PDF_IMAGE macro</a></li>
- <li><a href="#pspic">The PSPIC macro</a></li>
- <li><a href="#preprocessor-support">Preprocessor support</a>
- <ul style="margin-left: -.5em; list-style-type: disc;">
- <li><a href="#tbl">tbl</a>
- <ul style="margin-left: -1.25em;"><li><a href="#ts-te">.TS /
.TH / .TE macros and arguments</a></li>
- </ul></li>
- <li><a href="#pic">pic</a></li>
- <li><a href="#eqn">eqn</a></li>
- <li><a href="#refer">refer</a></li>
+ <li><a href="#preprocessor-support">Preprocessor support</a>
+ <ul>
+ <li><a href="#tbl">tbl</a>
+ <ul style="margin-left: -1.25em;">
+ <li><a href="#ts-te">.TS / .TH / .TE macros and arguments</a></li>
+ </ul></li>
+ <li><a href="#eqn">eqn</a>
+ <ul style="margin-left: -1.25em;">
+ <li><a href="#eq-en">.EQ / .EN macros and arguments</a></li>
+ </ul></li>
+ <li><a href="#pic">pic</a>
+ <ul style="margin-left: -1.25em;">
+ <li><a href="#ps-pe">.PS / .PE macros and arguments</a></li>
+ <li><a href="#pic-text-style">PIC_TEXT_STYLE</a>—set parameters
for text used in diagrams</li>
+ </ul></li>
+ <li><a href="#refer">refer</a></li>
+ </ul>
+ <li><a href="#captions-and-labels">Captions and labels</a>
+ <ul>
+ <li><a href="#autolabel">AUTOLABEL</a></li>
+ <li><a href="#caption-after-label">CAPTION_AFTER_LABEL</a></li>
+ <li><a href="#captions-labels-sources">CAPTIONS / LABELS /
SOURCES</a>—set style parameters for each</li>
+ <li><a href="#mla">MLA</a></li>
+ </ul></li>
+ <li><a href="#lists-of">Lists of Figures, Tables, and Equations</a>
+ <ul>
+ <li><a href="#lists-placement">Placement of Lists</a></li>
+ <li><a href="#lists-macros">Macros to generate Lists</a></li>
+ <li><a href="#formatting-lists">Formatting and style parameters for
Lists</a>
+ <ul style="margin-left: -1.25em">
+ <li><a href="#lists-style">LISTS_STYLE</a></li>
+ </ul></li>
</ul></li>
- <li><a href="#floats-intro">Introduction to floats</a></li>
- <li><a href="#float">The FLOAT macro</a></li>
</ul>
</div>
<div class="rule-medium"><hr/></div>
-<h2 id="images-intro" class="docs">Introduction to inserting images and
graphics</h2>
+<h2 id="images-intro" class="docs">Inserting images and graphics</h2>
<p>
In order to include images in mom documents, the images must be in
@@ -139,7 +170,7 @@ recommended.
</span>
</p>
-<!-- -PDF_IMAGE- -->
+<!---PDF_IMAGE--->
<div class="macro-id-overline">
<h3 id="pdf-image" class= "macro-id">PDF_IMAGE</h3>
@@ -148,9 +179,15 @@ recommended.
<div class="box-macro-args">
Macro: <b>PDF_IMAGE</b> <kbd class="macro-args">[ -L | -C | -R | -I
<indent> ] \
<br/>
-<pdf image> <width> <height> \
+<image-file.pdf> <width> <height> [ SCALE <factor> ] \
<br/>
-[ SCALE <factor> ] [ ADJUST +|-<vertical adjustment> ]</kbd>
+[ ADJUST +|-<vertical adjustment> ] [ NO_SHIM ] \
+<br/>
+[ FRAME ] \
+<br/>
+[ CAPTION "<caption>" ] [ SHORT_CAPTION "<short caption>" ] \
+<br/>
+[ LABEL "<label>" ]</kbd>
</div>
<p class="requires">
• <span style="font-style: normal">
@@ -164,6 +201,14 @@ require a
<a href="definitions.html#unitofmeasure">unit of measure</a>
</p>
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Arguments may be broken into several lines using the
+“line-continued” backslash (<b>\</b>), as shown above.
+</p>
+</div>
+
<p>
Unlike
<a href="#pspic">PSPIC</a>,
@@ -190,9 +235,9 @@ If you omit the first argument, the image will be centred.
<p>
<kbd><pdf image></kbd> must be in PDF format, with a .pdf
-extension. If it is not, mom will abort with a message. See <a
-href="#pdf">here</a> for instructions on converting image formats to
-PDF.
+extension. If it is not, mom will abort with a message. See
+<a href="#pdf">here</a>
+for instructions on converting image formats to PDF.
</p>
<p id="bounding-box">
@@ -215,23 +260,86 @@ and <kbd><height></kbd> must be <kbd>p</kbd>.
</p>
<p>
-The optional <kbd>SCALE</kbd> argument allows you to scale the image
-by <kbd><factor></kbd>. The factor is a percentage of the
-image’s original dimensions, thus
-<br/>
-<span class="pre-in-pp">
- SCALE 50
-</span>
+The remaining arguments are optional and may be entered in any
+order, although it’s best to put <kbd>CAPTION</kbd>,
+<kbd>SHORT_CAPTION</kbd>, and <kbd>LABEL</kbd> last.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'SCALE'</h5>
+
+<p>
+<kbd>SCALE</kbd> allows you to scale the image by
+<kbd><factor></kbd>. The factor is a percentage of the
+image’s original dimensions, thus <kbd>SCALE 50</kbd>
scales the image to 50 percent of its original size. No percent
sign or unit of measure should be appended.
</p>
+<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.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_SHIM'</h5>
+
+<p>
+<kbd>NO_SHIM</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim">shimming</a>
+after the image, which she does by default. Shimming ensures that
+running text after the image falls properly on the page’s baseline
+grid, but usually results in slightly unequal spacing above and
+below, which must be corrected with the <kbd>ADJUST</kbd> argument.
+Mom’s default shimming is generally a good idea since it ensures
+properly aligned bottom margins for running text, however if you
+have several images on the page, there may be visible differences in
+the spacing beneath images. <kbd>NO_SHIM</kbd> corrects the
+problem, but will result in running text that does not completely
+fill the page unless shimming is applied manually elsewhere on the
+same page.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'FRAME'</h5>
+
+<p>
+<kbd>FRAME</kbd> instructs mom to put a frame around the image.
+Parameters for the frame are set with
+<a href="#pdf-image-frame">PDF_IMAGE_FRAME</a>.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'CAPTION'</h5>
+
+<p>
+<kbd>CAPTION</kbd> allows you to give the image a caption. By
+default, the caption appears above the image, but may be attached to
+the label that appears beneath the image. See
+<a href="#caption-after-label">CAPTION_AFTER_LABEL</a>
+in
+<a href="#captions-and-labels">Captions and labels</a>.
+The text of the caption must be surrounded by double-quotes.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform:
none">'SHORT_CAPTION'</h5>
+
+<p>
+<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
+inclusion in the List of Figures. The text you supply, surrounded
+by double-quotes, is what will appear in the List.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'LABEL'</h5>
+
<p>
-The final optional argument is the vertical adjustment to apply to
-the image. A plus value raises the image
-<span style="font-style: italic">within the space allotted for it</span>;
-a negative value lowers it. The value must have a unit of measure
-appended.
+<kbd>LABEL</kbd>, if given, appears beneath the image. The text you
+supply, surrounded by double-quotes, is how the image is labelled
+in both the document proper and the List of Figures. Mom provides
+an auto-labelling facility for images (see
+<a href="#autolabel">AUTOLABEL</a>),
+which, if enabled, overrides the <kbd>LABEL</kbd> argument.
</p>
<p>
@@ -245,35 +353,71 @@ with
<div class="box-tip">
<p class="tip-top">
-<span class="note">Note:</span>
-Mom automatically applies shimming after PDF_IMAGE. See
-<a href="docprocessing.html#shim">SHIM</a>
-for a discussion of shimming, and how to disable it.
-<p>
-
-<p>
-<span class="note">Additional note:</span>
-Mom treats single, discrete images inserted into a document with
-PDF_IMAGE somewhat like
+<span class="note">Note: Version 2.0-c change</span>
+<br/>
+Mom now treats all pdf images identically to
<a href="#floats-intro">floats</a>,
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, and a
-message is printed to stderr advising you where the deferment has
-taken place.
+<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.
</p>
<p class="tip-bottom">
-However, if more than one image does not fit on the output page,
-mom defers only the first; the remainder are silently ignored.
-Therefore, if you insert several images close together in the text,
-it is highly recommended that you wrap the images in floats, which
-do not have this restriction.
+Prior to 2.0-c, it was recommended that images be wrapped inside
+<a href="#float">FLOAT</a>,
+but this is now no longer required, and should, in fact, be avoided.
</p>
</div>
+<!---PDF_IMAGE_FRAME--->
+
+<div class="macro-id-overline">
+<h3 id="pdf-image-frame" class= "macro-id">PDF_IMAGE_FRAME</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PDF_IMAGE_FRAME</b> <kbd class="macro-args"><inset amount>
<rule weight> <color></kbd>
+</div>
+<p class="requires">
+• <span style="font-style: normal"><kbd><inset
amount></kbd></span>
+requires a
+<a href="definitions.html#unitofmeasure">unit of measure</a>;
+conversely,
+<span style="font-style: normal"><kbd><rule weight></kbd></span>
+must not have a unit of measure appended
+</p>
+
+<p>
+PDF_IMAGE_FRAME establishes the parameters for subsequent invocations of
+<a href="#pdf-image">PDF_IMAGE</a>
+when the <kbd>FRAME</kbd> argument is given. Arguments must appear
+in order, and any you wish left at the current value should be
+entered as two adjacent double-quotes. So, for example,
+<span class="pre-in-pp">
+ .PDF_IMAGE_FRAME "" "" blue
+</span>
+leaves the inset value and rule weight at their current value and
+changes the frame colour to blue.
+<p>
+Frames are drawn <span class="italic">outside</span> the image at
+its requested dimensions inclusive of scaling. Colours must be
+pre-initialized with
+<a href="color.html#xcolor">XCOLOR</a>
+or
+<a href="color.html#newcolor">NEWCOLOR</a>.
+</p>
+
+<p>
+The default inset is 6 <a
+href="definitions.html#picaspoints">points</a>, the default rule
+weight is .5 (points), and the default colour is black.
+</p>
+
<!-- -PSPIC- -->
<div class="macro-id-overline">
@@ -286,14 +430,9 @@ Macro: <b>PSPIC</b> <kbd class="macro-args">[ -L | -R | -I
<n> ] <file&
<p>
PSPIC is not actually part of mom, but rather a macro included with
-every groff installation. Although its arguments are identical to
-PDF_IMAGE (except for <kbd>SCALE</kbd> and <kbd>ADJUST</kbd>, which
-are missing), its behaviour is slightly different.
-</p>
-
-<p>
-<kbd>man groff_tmac</kbd> contains the documentation for PSPIC, but
-I’ll repeat it here with a few modifications for clarity.
+every groff installation. <kbd>man groff_tmac</kbd> contains the
+documentation for PSPIC, but I’ll repeat it here with a few
+modifications for clarity.
</p>
<div class="examples-container">
@@ -341,18 +480,21 @@ image will probably be required, typically by using the
<a href="typesetting.html#ald">ALD</a>
and
<a href="typesetting.html#rld">RLD</a>
-macros.
+macros. Wrapping the image in a
+<a href="#float">float</a>
+and using FLOAT’s <kbd>ADJUST</kbd> option can also be used to
+correct optical centering.
</p>
<p>
-Additionally, EPS images inserted into
+Additionally, non-floated EPS images inserted into
<a href="definitions.html#running">running text</a>
will almost certainly disrupt the baseline placement of running
-text. In order to get mom back on track after invoking
-<kbd>.PSPIC</kbd>, I strongly recommend using the
+text. In order to get mom back on track after inserting a
+non-floated <kbd>.PSPIC</kbd> image, I strongly recommend using the
<a href="docprocessing.html#shim">SHIM</a>
macro so that the bottom margin of running text falls where it
-should. Please note that with PDF_IMAGE, this is not necessary.
+should.
</p>
<p>
@@ -364,25 +506,253 @@ with
</span>
</p>
+<div class="box-tip">
+<p class="tip">
+<span class="note">Please note:</span>
+<kbd>PSPIC</kbd> does not support
+<a href="autolabel">autolabelling</a>,
+labels, captions, or inclusion in the List of Figures. If you wish
+this functionality,
+<a href="#converting">convert your images to pdf</a>
+and use
+<a href="#pdf-image">PDF_IMAGE</a>
+instead, then process the file with
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
+(without the <kbd>-Tps</kbd> option).
+</p>
+</div>
+<div class="rule-medium"><hr/></div>
+
+<h2 id="floats-intro" class="docs">Introduction to floats</h2>
+
+<p>
+Non-textual insertions in a document (tables, for example) sometimes
+do not fit on the output page of a PDF or PostScript document at
+the place they’re inserted in the input file. It’s
+necessary, therefore, to defer them to the next page while carrying
+on with
+<a href="definitions.html#running">running text</a>.
+</p>
+
+<p>
+Whenever you need this functionality, mom provides the FLOAT macro.
+</p>
+
+<p>
+Floats are usually used for images and graphics, but can contain
+anything you like, including text. Whatever’s in the
+float will be kept together as a block, output immediately if
+there’s room, or deferred to the top of the next output page
+when there isn’t; running text continues to the bottom of the
+previous page without interruption.
+</p>
+
+<p>
+In the case of a float that doesn’t fit being followed by
+one that does, the second is output in position and the first is
+deferred. In the case of two or more that don’t fit, they are
+output in order on the next page.
+</p>
+
+<p>
+A key distinction between a float and a
+<a href="docelement.html#quote">QUOTE</a>
+or
+<a href="docelement.html#blockquote">BLOCKQUOTE</a>
+is that while a float keeps everything together and defers output if
+necessary, quotes and blockquotes are output immediately, and may
+start on one page and finish on the next.
+</p>
+
+<p>
+Floats always deposit a break before they begin, which means the
+line beforehand will not be
+<a href="definitions.html#filled">filled</a>.
+Floats, therefore, cannot be inserted in the middle of a paragraph
+without studying the output file and determining where to break or
+<a href="typesetting.html#spread">spread</a>
+the line before the float. Furthermore, if you want a float between
+paragraphs, the float should come before <kbd>.PP</kbd>, like this:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ ...
+ .FLOAT OFF
+ .PP
+</span>
+not
+<br/>
+<span class="pre-in-pp">
+ .PP
+ .FLOAT
+ ...
+ .FLOAT OFF
+</span>
+</p>
+
+<p id="float-spacing">
+Floats begin on the baseline immediately below the running text
+preceding them. No additional whitespace surrounds them, above or
+below. Running text below a float is, however,
+<a href="docprocessing.html#shim">shimmed</a>,
+unless shimming has been disabled with <kbd>.NO_SHIM</kbd> or the
+<kbd>NO_SHIM</kbd> argument is given to <kbd>FLOAT</kbd>. Shimming
+generally results in a small amount of extra whitespace after the
+float, which can be equalized with the whitespace beforehand using
+the <kbd>ADJUST</kbd> argument to FLOAT.
+</p>
+
+<p>
+If you’d like more space around a float, you must add it
+manually, for example with
+<a href="typesetting.html#ald">ALD</a>
+or
+<a href="typesetting.html#space">SPACE</a>.
+</p>
+
+<!-- -FLOAT- -->
+
+<div class="macro-id-overline">
+<h3 id="float" class= "macro-id">FLOAT</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>FLOAT</b> <kbd class="macro-args">[ ADJUST +|-<amount> ] [
FORCE ] [ SPAN ] [ NO_SHIM] | <anything></kbd>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+FLOAT is intended for use with the document processing macros only.
+</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>
+
+<p>
+The optional <kbd>ADJUST</kbd> argument tells mom to raise
+(<kbd>+</kbd>) or lower (<kbd>-</kbd>) the float <i>within
+the space allotted to it</i> by the specified amount.
+<kbd><amount></kbd> must have a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+appended. <kbd>ADJUST</kbd> gives you precise control over
+the vertical centering of floats, allowing you to compensate for
+unequal spacing that may result of from the automatic shimming of
+floats (or the absence thereof). See
+<a href="docprocessing.html#shim">SHIM</a>
+for a discussion of automatic shimming.
+</p>
+
+<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
+not fit on the current page. While this is somewhat contrary to the
+notion of floats (ie that running text should continue to fill the
+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.
+</p>
+
+<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
+not be used for floats containing a boxed table; mom will abort with
+a warning should this occur. Unboxed tables, on the other hand, are
+acceptable within floats that are given the <kbd>SPAN</kbd> argument.
+</p>
+
+<p>
+<kbd>NO_SHIM</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim">shimming</a>
+after the float, which she does by default. Shimming ensures that
+running text after the float falls properly on the page’s baseline
+grid, but usually results in slightly unequal spacing above and
+below, which must be corrected with the <kbd>ADJUST</kbd> argument.
+Mom’s default shimming is generally a good idea since it ensures
+properly aligned bottom margins for running text, however if you
+have several floats on the page, there may be visible differences in
+the spacing beneath them. <kbd>NO_SHIM</kbd> corrects the
+problem, but will result in running text that does not completely
+fill the page unless shimming is applied manually elsewhere on the
+same page.
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+Floats use
+<a href="definitions.html#filled">no-fill mode</a>,
+with each input line beginning at the left margin. If this is not
+what you want, you must specify the preferred horizontal alignment
+<i>within the float</i> (eg
+<a href="typesetting.html#lrc">CENTER</a>
+or
+<a href="typesetting.html#lrc">RIGHT</a>).
+</p>
+
+<p class="tip-bottom">
+Furthermore, if you want text
+<a href="definitions.html#filled">filled</a>,
+you must specify
+<a href="typesetting.html#quad"><kbd>.QUAD L|R|C</kbd></a>
+or
+<a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a>—again,
+within the float.
+</p>
+</div>
+
<div class="rule-medium"><hr/></div>
<h2 id="preprocessor-support" class="docs">Preprocessor support</h2>
+<p>
+Mom offers full support for the <b>eqn</b> (equations),
+<b>pic</b> (diagrams), <b>tbl</b> (tables), and <b>refer</b>
+(bibliographies/citations) preprocessors, including captions,
+labelling, autolabelling, and inclusion in the Lists of Equations,
+Figures, and Tables.
+</p>
+
+<p>
+Other than <b>refer</b>, which is discussed at length in the <a
+href="refer.html">Bibliographies and references</a> section, it is
+beyond the scope of this documentation to cover full preprocessor
+usage. Consult the manpages <b>eqn(1)</b>, <b>pic(1)</b>, and
+<b>tbl(1)</b> for instructions.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Version 2.0-c changes</span>
+<br/>
+Preprocessor support has been revised and expanded as of version 2.0-c.
+Please read the following sections thoroughly and update any
+documents created with versions prior to 2.0.c as necessary.
+</p>
+</div>
+
<h3 id="tbl" class="docs">tbl support</h3>
<p>
Mom documents can include tables generated with the groff
-pre-processor, <kbd>tbl</kbd>. <kbd>tbl</kbd> usage itself is beyond
-the scope of this documentation, but is covered in the manpage
-<kbd>tbl(1)</kbd>. You can also download a copy of
+preprocessor, <b>tbl</b>. If you are unfamiliar with <b>tbl</b>, I
+recommend downloading a copy of
<a href="http://plan9.bell-labs.com/10thEdMan/tbl.pdf";>Tbl - A Program to
Format Tables</a>,
-which, in addition to providing a thorough introduction to <kbd>tbl</kbd>,
-contains some fine examples.
+which, in addition to providing a thorough introduction, contains
+some fine examples.
</p>
<p>
Tables formatted with <kbd>tbl</kbd> begin with the macro
-<kbd>.TS</kbd> (<b>T</b>able <b>S</b>art) and end with
+<kbd>.TS</kbd> (<b>T</b>able <b>S</b>tart) and end with
<kbd>.TE</kbd> (<b>T</b>able <b>E</b>nd). Depending on where you
want your tables output in a document, you may need to wrap
your <kbd>tbl</kbd> code inside a
@@ -397,7 +767,8 @@ of the next page if it doesn’t. If you prefer a
table to
begin where you say and span over to the next page, or if you know
for certain a boxed table will run to multiple pages, simply pass the
<kbd>H</kbd> argument to <kbd>.TS</kbd>, along with a corresponding
-<a href="#th"><kbd>TH</kbd></a>.
+<a href="#th"><kbd>TH</kbd></a>
+and do not wrap the table inside a float.
</p>
<div class="box-tip">
@@ -419,7 +790,9 @@ If you use <kbd>.TS</kbd> without the <kbd>H</kbd> argument
(and
therefore no <kbd>.TH</kbd>), tables that fit on the page are output
in position. If there is not enough room to output the table,
<kbd>tbl</kbd> will abort with message instructing you to use
-<kbd>.TS H/.TH</kbd>.
+<kbd>.TS H/.TH</kbd>. Given that <kbd>.TS</kbd> without <kbd>TH</kbd>
+may sometimes fail, it is advisable to begin all <b>tbl</b> blocks
+with <kbd>.TS H</kbd>.
</p>
<p>
@@ -459,14 +832,12 @@ is a result of
<a href="docprocessing.html#shim">shimming</a>
that mom applies automatically after each table. You may
disable shimming with <kbd>.NO_SHIM</kbd>, or by giving the
-<kbd>NO_SHIM</kbd> argument to <kbd>.TE</kbd>. In either case, you
+<kbd>NO_SHIM</kbd> argument to <kbd>.TS</kbd>. In either case, you
will still likely want to adjust the spacing around with table with
-<a href="typesetting.html#ald">ALD</a>
-or
-<a href="typesetting.html#rld">RLD</a>.
-Tables inside floats are more easily adjusted with the
-<kbd>ADJUST</kbd> argument to
-<a href="#float">FLOAT</a>.
+the <kbd>AJUST</kbd> argument to <kbd>.TS</kbd>. Tables inside
+floats should be adjusted with the <kbd>ADJUST</kbd> argument to
+<a href="#float">FLOAT</a>,
+not the <kbd>ADJUST</kbd> argument to <kbd>.TS</kbd>.
</p>
</div>
@@ -475,11 +846,36 @@ Tables inside floats are more easily adjusted with the
</div>
<div class="box-macro-args">
-Macro: <a href="#ts"><b>TS</b></a> <kbd class="macro-args">[ H ] [ BOXED ] [
CENTER ] [ NEEDS ]</kbd>
+Macro: <a href="#ts"><b>TS</b></a>
+<kbd class="macro-args"><br/>
+Arguments:
+<br/>
+ [ H ]
+<br/>
+ [ BOXED ]
+<br/>
+ [ CENTER ]
+<br/>
+ [ NEEDS ]
+<br/>
+ [ ADJUST +|-<vertical adjustment>]</kbd>
+<span style="font-size: 95%">
+(<a href="definitions.html#unitofmeasure">unit of measure</a>
+required)
+</span>
+<kbd class="macro-args"><br/>
+ [ NO_SHIM ]
+<br/>
+ [ CAPTION "<caption>" ]
+<br/>
+ [ SHORT_CAPTION "<short caption>" ]
+<br/>
+ [ LABEL "<label>" ]
+</kbd>
<br/>
Macro: <a href="#th"><b>TH</b></a> <kbd class="macro-args">(optional, only if
.TS H)</kbd>
<br/>
-Macro: <a href="#te"><b>TE</b></a> <kbd class="macro-args">[ "caption" ] [
<distance> ] [ LEFT | CENTER | RIGHT ] [ NO_SHIM ]</kbd>
+Macro: <a href="#te"><b>TE</b></a> <kbd class="macro-args">[ SOURCE "<text
of table source>" ]
</div>
<p>
@@ -511,10 +907,35 @@ if it fits, or deferred to the next page if it
doesn’t.
<h4 id="ts" class="docs" style="font-size: 100%; margin-top: .5em">The .TS
macro</h4>
</div>
-<p>
-The <b>TS</b> macro must be invoked before entering a <kbd>tbl</kbd>
-block. You may give as many or as few of its arguments as required,
-in any order.
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note: Version 2.0-c change</span>
+<br/>
+2.0-c introduces revisions to the handling of labels and/or
+captions, which, along with <kbd>NO_SHIM</kbd>, must now be given
+as arguments to <kbd>.TS</kbd> rather than <kbd>.TE</kbd>, as was
+the case formerly. Please read this section carefully if you have
+documents containing tables as they may need to be updated.
+</p>
+</div>
+
+<div class="box-important" style="margin-top: 1em">
+<p class="tip">
+<span class="important">IMPORTANT:</span>
+All arguments to <b>TS</b> must appear on the same line as
+<kbd>.TS</kbd>. Do not attempt to break them up with the
+“line-continued” backslash. You may want to set your
+text editor to “wrap” mode in order to see all your
+arguments. This annoyance stems from the preprocessor mechanism
+itself, not groff or mom.
+</p>
+</div>
+
+<p>
+The <b>TS</b> macro must be invoked before entering a <kbd>tbl</kbd>
+block. You may give as many or as few of its arguments as required,
+in any order, although it is advisable to put <kbd>CAPTION</kbd>,
+<kbd>SHORT_CAPTION</kbd>, and/or <kbd>LABEL</kbd> last.
</p>
<h5 class="docs" style="margin-top: 1em; text-transform: none">'H'</h5>
@@ -619,8 +1040,66 @@ number with the <kbd>NEEDS</kbd> argument, followed by
the desired
number of rows.
</p>
+<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.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_SHIM'</h5>
+
+<p>
+<kbd>NO_SHIM</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim">shimming</a>
+after the image, which she does by default. Shimming ensures that
+running text after the image falls properly on the page’s baseline
+grid, but usually results in slightly unequal spacing above and
+below, which must be corrected with the <kbd>ADJUST</kbd> argument.
+Mom’s default shimming is generally a good idea since it ensures
+properly aligned bottom margins for running text, however if you
+have several images on the page, there may be visible differences in
+the spacing beneath images. <kbd>NO_SHIM</kbd> corrects the
+problem, but will result in running text that does not completely
+fill the page unless shimming is applied manually elsewhere on the
+same page.
+</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'CAPTION'</h5>
+
+<p>
+<kbd>CAPTION</kbd> allows you to give the table a caption. By
+default, the caption appears above the table, but may be attached to
+the label that appears beneath the table. See
+<a href="#caption-after-label">CAPTION_AFTER_LABEL</a>
+in
+<a href="#captions-and-labels">Captions and labels</a>.
+The text of the caption must be surrounded by double-quotes.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform:
none">'SHORT_CAPTION'</h5>
+
+<p>
+<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
+inclusion in the List of Tables. The text you supply, surrounded
+by double-quotes, is what will appear in the List.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'LABEL'</h5>
+
+<p>
+<kbd>LABEL</kbd>, if given, appears beneath the table. The text you
+supply, surrounded by double-quotes, is how the table is labelled
+in both the document proper and the List of Tables. Mom provides
+an auto-labelling facility for tables (see
+<a href="#autolabel">AUTOLABEL</a>),
+which, if enabled, overrides the <kbd>LABEL</kbd> argument.
+</p>
+
<div class="macro-id-overline">
-<h4 id="ts" class="docs" style="font-size: 100%; margin-top: .5em">The .TH
macro</h4>
+<h4 id="th" class="docs" style="font-size: 100%; margin-top: .5em">The .TH
macro</h4>
</div>
<p>
@@ -636,82 +1115,433 @@ second row, the first and second rows form the header,
and so on.
</p>
<div class="macro-id-overline">
-<h4 id="ts" class="docs" style="font-size: 100%; margin-top: .5em">The .TE
macro</h4>
+<h4 id="te" class="docs" style="font-size: 100%; margin-top: .5em">The .TE
macro</h4>
</div>
<p>
-<kbd>tbl</kbd> blocks must be terminated with <kbd>.TE</kbd>.
-Arguments to <b>TE</b> are optional. If
<kbd>“<caption>”</kbd>
-is given, you may use as many or as few of the subsequent arguments
-as you wish, in any order.
+<kbd>tbl</kbd> blocks must be terminated with <kbd>.TE</kbd>,
+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
+<a href="#mla">MLA</a>
+(Modern Language Association) is enabled, immediately below the
+table.
</p>
-<h5 class="docs" style="margin-top: 1em; text-transform:
none">“<caption>”</h5>
+<div class="rule-medium"><hr/></div>
+
+<h3 id="pic" class="docs">pic support</h3>
<p>
-If you wish a table to have a caption, or label, underneath, surround the
-caption in double-quotes after <kbd>.TE</kbd>, like this:
-<span class="pre-in-pp">
- .TE "Table 1"
-</span>
+Mom documents can include diagrams generated with the groff
+preprocessor, <b>pic</b>. If you are unfamiliar with <b>pic</b>, I
+recommend downloading a copy of
+<a href="http://www.kohala.com/start/troff/gpic.raymond.ps";>Making Pictures
with GNU PIC</a>
+which provides a thorough introduction and contains many examples.
</p>
-<h5 class="docs" style="margin-top: 1em; text-transform:
none"><distance></h5>
+<p>
+Diagrams created with <kbd>pic</kbd> begin with the macro
+<kbd>.PS</kbd> (<b>P</b>ic <b>S</b>tart) and end with
+<kbd>.PE</kbd> (<b>P</b>ic <b>E</b>nd). Everything between them is
+intrepreted by the preprocessor as pic instructions.
+</p>
<p>
-If you would like to increase the space between the bottom of a
-table and its caption, enter the increase with a digit to which is
-appended a
-<a href="definitions.html#unitofmeasure">unit of measure</a>:
-<span class="pre-in-pp">
- .TE "Table 1" 3p
+Pic diagrams are always centered. Note that this represents a
+change from version 2.0-b of mom, where centering diagrams required
+passing <kbd>-mpic</kbd> to <b>groff</b> or
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
+on the command line.
+</p>
+
+<p>
+In addition, mom treats <b>pic</b> diagrams identically to
+<a href="#floats-intro">floats</a>,
+which is to say that if a diagram 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 a diagram is deferred, except
+when moving from column to column on the same page, when the diagram
+may need to be optically adjusted. Subsequent diagrams that do not
+fit, if any, are output in order immediately after the first.
+</p>
+
+<p>
+Lastly, if your diagrams contain text, you may set all the type
+parameters for the text (family, font, size, leading) separately
+from the <b>pic</b> block with the macro,
+<a href="#pic-text-style">PIC_TEXT_STYLE</a>.
+If you need to change the type parameters within the block
+on-the-fly, you must use <b>pic</b>’s native facilities for
+doing so.
+</p>
+
+<div class="macro-id-overline">
+<h3 id="ps-pe" class= "macro-id">.PS / .PE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PS</b>
+<kbd class="macro-args">
+<br/>
+Arguments:
+<br/>
+ [ width ]</kbd> <span style="font-size: 95%">(in inches; no unit
of measure required)</span>
+<kbd class="macro-args"><br/>
+ [ height ]</kbd> <span style="font-size: 95%">(in
+inches; no unit of measure required)</span>
+<kbd class="macro-args"><br/>
+ [ ADJUST +|-<vertical adjustment>]</kbd>
+<span style="font-size: 95%">
+(<a href="definitions.html#unitofmeasure">unit of measure</a>
+required)
</span>
+<kbd class="macro-args"><br/>
+ [ NO_SHIM ]
+<br/>
+ [ CAPTION "<caption>" ]
+<br/>
+ [ SHORT_CAPTION "<short caption>" ]
+<br/>
+ [ LABEL "<label>" ]
+</kbd>
+<br/>
+Macro: <b>PE</b> <span style="font-size: 95%">(no arguments; ends
+the <b>pic</b> block)</span>
+</div>
+
+<div class="box-important" style="margin-top: 1.5em">
+<p class="tip">
+<span class="important">IMPORTANT:</span>
+All arguments to <b>PS</b> must appear on the same line as
+<kbd>.PS</kbd>. Do not attempt to break them up with the
+“line-continued” backslash. You may want to set your
+text editor to “wrap” mode in order to see all your
+arguments. This annoyance stems from the preprocessor mechanism
+itself, not groff or mom.
</p>
+</div>
-<h5 class="docs" style="margin-top: 1em; text-transform: none">LEFT | CENTER |
RIGHT</h5>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'width' and
'height'</h5>
<p>
-By default, mom aligns captions with the left side of tables. If
-this is what you want, you may enter <kbd>LEFT</kbd>, or simply skip
-stating where you want the caption. If you would prefer centered or
-right placement, use <kbd>CENTER</kbd> or <kbd>RIGHT</kbd>.
+The <kbd>width</kbd> and <kbd>height</kbd> arguments to
+<kbd>.PS</kbd> are idiosyncratic owing to the preprocessor itself.
+If a width argument is supplied, the diagram, but not any text it
+contains, is scaled to the given width. If a literal width argument
+of <kbd>0</kbd> (zero) is given and a height argument is supplied,
+the diagram, but not any text it contains, will be scaled to the
+requested height. In the case of two non-zero arguments being
+given, only the height scaling is applied.
</p>
-<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'ADJUST'</h5>
<p>
-By default, mom adds
+<kbd>ADJUST</kbd> lets you raise (<kbd>+</kbd>) or lower
+(<kbd>-</kbd>) a diagram
+<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>
+
+<p>
+<kbd>NO_SHIM</kbd> instructs mom not to apply
<a href="docprocessing.html#shim">shimming</a>
-underneath tables. This behaviour may be disabled with the
-<kbd>NO_SHIM</kbd> argument, which, moreover, can be used for tables
-without a caption, like this:
-<span class="pre-in-pp">
- .TE NO_SHIM
-</span>
+after the diagram, which she does by default. Shimming ensures that
+running text after the diagram falls properly on the page’s baseline
+grid, but usually results in slightly unequal spacing above and
+below, which must be corrected with the <kbd>ADJUST</kbd> argument.
+Mom’s default shimming is generally a good idea since it ensures
+properly aligned bottom margins for running text, however if you
+have several diagrams on the page, there may be visible differences in
+the spacing beneath them. <kbd>NO_SHIM</kbd> corrects the
+problem, but will result in running text that does not completely
+fill the page unless shimming is applied manually elsewhere on the
+same page.
</p>
-<div class="rule-medium"><hr/></div>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'CAPTION'</h5>
-<h3 id="pic" class="docs">pic support</h3>
+<p>
+<kbd>CAPTION</kbd> allows you to give the diagram a caption. By
+default, the caption appears above the diagram, but may be attached to
+the label that appears beneath it. See
+<a href="#caption-after-label">CAPTION_AFTER_LABEL</a>
+in
+<a href="#captions-and-labels">Captions and labels</a>.
+The text of the caption must be surrounded by double-quotes.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform:
none">'SHORT_CAPTION'</h5>
+
+<p>
+<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
+inclusion in the List of Figures. The text you supply, surrounded
+by double-quotes, is what will appear in the List.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'LABEL'</h5>
<p>
-At present, mom has no integrated support or special features
-for the <b>pic</b> preprocessor, however <b>pic</b> may be used
-successfully within a mom document. Generally, it’s best to
-wrap <b>pic</b> blocks within a float (see below). If you want
-your <b>pic</b>s centred, you must include <kbd>-mpic</kbd> in the
-options passed to <kbd>pdfmom</kbd> or <kbd>groff</kbd>.
+<kbd>LABEL</kbd>, if given, appears beneath the diagram. The text you
+supply, surrounded by double-quotes, is how the diagram is labelled
+in both the document proper and the List of Figures. Mom provides
+an auto-labelling facility for diagrams (see
+<a href="#autolabel">AUTOLABEL</a>),
+which, if enabled, overrides the <kbd>LABEL</kbd> argument.
</p>
+<!---PIC_TEXT_STYLE--->
+
+<div class="macro-id-overline">
+<h3 id="pic-text-style" class= "macro-id">PIC_TEXT_STYLE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PIC_TEXT_STYLE</b> \
+<br/>
+<kbd class="macro-args">
+ [ FAMILY ] "<family>" \
+<br/>
+ [ FONT ] "<font>" \
+<br/>
+ [ SIZE ] "+|-<size>" \
+<br/>
+ [ AUTOLEAD ] "<value>"
+</kbd>
+</div>
+
+<p>
+Diagrams drawn with <b>pic</b> may contain text, and groff
+<a href="inlines.html#intro-inlines">inline escapes</a>
+may be used to alter the text parameters. A problem that arises
+from so doing is that, in many cases, it clutters up the <b>pic</b>
+code unnecessarily.
+</p>
+
+<p>
+PIC_TEXT_STYLE lets you establish the type parameters for text
+inside a <b>pic</b> block all at once in cases where so doing
+improves the readability of your mom source files.
+</p>
+
+<p>
+The arguments to PIC_TEXT_STYLE behave identically to the arguments
+to other control macros, explained
+<a href="docelement.html#control-macro-args">here</a>.
+They may be given in any order, and you may use as many or as few as
+you like.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Text within <b>pic</b> diagrams does not scale when you provide a
+scaling argument to <kbd>.PS</kbd>. This is a limitation of the
+preprocessor itself, not groff or mom.
+</p>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
<h3 id="eqn" class="docs">eqn support</h3>
<p>
-At present, mom has no integrated support or special features
-for the <b>eqn</b> preprocessor, however <b>eqn</b> may be used
-successfully within a mom document. Generally, it’s best to
-wrap <b>eqn</b> blocks within a float (see below).
+Support for <b>eqn</b> is provided via extensions to the standard
+<kbd>.EQ/.EN</kbd> macros. <kbd>eqn</kbd> usage itself is beyond
+the scope of this documentation, but is covered in the manpage
+<kbd>eqn(1)</kbd>. You can also download a copy of Ted
+Harding’s
+<!--- edit me -->
+<a href="http://www.zen89632.zen.co.uk/Groff/Eqn/eqnguide.pdf";>A Guide to
Typesetting Mathematics Using GNU eqn</a>,
+which contains useful examples.
+</p>
+
+<div class="macro-id-overline">
+<h3 id="eq-en" class= "macro-id">.EQ / .EN</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <a href="#eq"><b>EQ</b></a>
+<br/>
+<kbd class="macro-args">Arguments:
+<br/>
+ [ -L | -C | -I <ident> ]</kbd>
+<span style="font-size: 95%">
+(<a href="definitions.html#unitofmeasure">unit of measure</a>
+required)
+</span>
+<kbd class="macro-args"><br/>
+ [ ADJUST +|-<vertical adjustment>]</kbd>
+<span style="font-size: 95%">
+(<a href="definitions.html#unitofmeasure">unit of measure</a>
+required)
+</span>
+<kbd class="macro-args"><br/>
+ [ CAPTION "<caption>" ]
+<br/>
+ [ LABEL "<label>" ]
+<br/>
+ [ LABEL_ADJUST +|-<vertical adjustment> ]
+<br/>
+ [ SHORT_CAPTION "<short caption>" ]
+<br/>
+Macro: <a href="#en"><b>EN</b></a> <kbd class="macro-args"> [ CONTINUED | CONT
| ... ]</kbd>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note: Version 2.0-c change</span>
+<br/>
+2.0-c introduces revisions to <b>EQ</b>, including the addition
+of a dash (<kbd>-</kbd>) to the positioning arguments
+(<kbd>-L</kbd>, <kbd>-C</kbd>, and <kbd>-I</kbd>) and the removal of a
+default value for <kbd>-I</kbd>. Other changes include passing all
+options to <kbd>.EQ</kbd> (including the label) such that
+<kbd>.EN</kbd> takes only a single, optional argument saying whether
+the equation is to be continued at the next invocation of
+<kbd>.EQ</kbd>. Please read this section carefully if you have
+documents containing equations as they may need to be updated.
+</p>
+</div>
+
+<div class="box-important" style="margin-top: 1em">
+<p class="tip">
+<span class="important">IMPORTANT:</span>
+All arguments to <b>EQ</b> must appear on the same line as
+<kbd>.EQ</kbd>. Do not attempt to break them up with the
+“line-continued” backslash. You may want to set your
+text editor to “wrap” mode in order to see all your
+arguments. This annoyance stems from the preprocessor mechanism
+itself, not groff or mom.
+</p>
+</div>
+
+<div class="macro-id-overline" style="margin-top: .5em">
+<h4 id="eq" class="docs" style="font-size: 100%; margin-top: .5em">The .EQ
macro</h4>
+</div>
+
+<p>
+Equations to be set with <b>eqn</b> begin with <kbd>.EQ</kbd>,
+followed by <b>eqn</b> code. Equations are centered by default,
+but may be set flush left or indented from the left margin
+if <kbd>-L</kbd> or <kbd>-I</kbd> are passed as arguments to
+<kbd>.EQ</kbd>.
+</p>
+
+<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>) an equation
+<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>
+
+<p>
+<kbd>NO_SHIM</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim">shimming</a>
+after the equation, which she does by default. Shimming ensures that
+running text after the equation falls properly on the page’s baseline
+grid, but usually results in slightly unequal spacing above and
+below, which must be corrected with the <kbd>ADJUST</kbd> argument.
+Mom’s default shimming is generally a good idea since it ensures
+properly aligned bottom margins for running text, however if you
+have several equations on the page, there may be visible differences in
+the spacing beneath them. <kbd>NO_SHIM</kbd> corrects the
+problem, but will result in running text that does not completely
+fill the page unless shimming is applied manually elsewhere on the
+same page.
+</p>
+
+</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'CAPTION'</h5>
+
+<p>
+<kbd>CAPTION</kbd> allows you to give the equation a caption.
+Equation captions always appear beneath the equation.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform:
none">'SHORT_CAPTION'</h5>
+
+<p>
+<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
+inclusion in the List of Equations. The text you supply, surrounded
+by double-quotes, is what will appear in the List.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'LABEL'</h5>
+
+<p>
+<kbd>LABEL</kbd>, if given, appears on the same baseline as the last line of
the
+equation, flush with the left or right margin, depending on the
+equation’s horizontal position. The text you supply, surrounded by
+double-quotes, is how
+the equation is labelled in both the document proper and the List of
+Equations. Mom provides an auto-labelling facility for equations (see
+<a href="#autolabel">AUTOLABEL</a>),
+which, if enabled, overrides the <kbd>LABEL</kbd> argument.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform:
none">'LABEL_ADJUST'</h5>
+
+<p>
+<kbd>LABEL_ADJUST</kbd> allows you to raise (<kbd>-</kbd>) or lower
+(<kbd>+</kbd>) the equation label. It’s primary use is to
+center equation labels vertically on the equation rather than flush
+with the last line. Assuming a three-line equation,
+<kbd>.EQ LABEL_ADJUST -1v</kbd> would raise the label by
+one line, thus centering it vertically on the equation.
+</p>
+
+<div class="macro-id-overline" style="margin-top: .5em">
+<h4 id="en" class="docs" style="font-size: 100%; margin-top: .5em">The .EN
macro</h4>
+</div>
+
+<p>
+A block of <b>eqn</b> code is terminated with <kbd>.EN</kbd>.
+</p>
+
+<p>
+If an equation needs to span multiple lines, possibly aligned
+with <b>eqn</b>’s <kbd>'mark'</kbd> and <kbd>'lineup'</kbd>
+directives, separate invocations of <kbd>.EQ/.EN</kbd> are required
+for each line, and the optional argument, <kbd>CONTINUED</kbd> (or
+<kbd>CONT</kbd>, or <kbd>...</kbd> [three dots, an ellipsis]), must
+be passed to <kbd>.EN</kbd>.
+</p>
+
+<p>
+If <kbd>-L</kbd> or <kbd>-I</kbd> is given to the first
+<kbd>.EQ</kbd> of a multi-line equation, they remain in effect
+until the final <kbd>.EN</kbd>, which does not have the
+<kbd>CONTINUED</kbd> argument.
+</p>
+
+<p>
+Mom does not treat equations as floats, therefore it is possible to
+begin an equation on one page and terminate it on the next. If you
+wish to keep all lines of an equation together, you must wrap the
+equation, including all invocations of <kbd>.EQ/.EN</kbd>, inside
+a
+<a href="#floats-intro">float</a>.
</p>
+<div class="rule-medium"><hr/></div>
+
<h3 id="refer" class="docs">refer support</h3>
<p>
@@ -721,162 +1551,616 @@ wrap <b>eqn</b> blocks within a float (see below).
<div class="rule-medium"><hr/></div>
-<h2 id="floats-intro" class="docs">Introduction to floats</h2>
+<h2 id="captions-and-labels" class="docs">Captions and labels</h2>
+
+<ul>
+ <li><a href="#autolabel">AUTOLABEL</a></li>
+ <li><a href="#caption-after-label">CAPTION_AFTER_LABEL</a></li>
+ <li><a href="#mla">MLA</a>—MLA-style captioning and labelling</li>
+ <li><a href="#caption-label-style">Set style parameters for captions,
labels, and sources</a></li>
+</ul>
<p>
-Images and graphics (including those created with
-<strong>tbl</strong> and <strong>pic</strong>) sometimes do not
-fit on the output page of a PDF or PostScript document at the
-place they’re inserted in the input file. It’s
-necessary, therefore, to defer them to the next page while carrying
-on with
-<a href="definitions.html#running">running text</a>.
+Mom includes facilities for adding captions and labels to figures,
+tables, equations, and pdf images, including auto-labelling. If
+Lists of Figures, Tables, and Equations are desired, captions (if
+any) and labels (if any) are collected and output in the Lists with
+the appropriate page number.
</p>
<p>
-Whenever you need this functionality (tables, for example, generally
-need only appear near related text, not at a precise location), mom
-provides the FLOAT macro.
+The distinction between a caption and a label is that labels are
+identifiers, e.g. “Fig. 1” or “Table 3”,
+while captions are descriptive or informative. For most types of
+writing, it is usual to provide both.
</p>
<p>
-Floats are usually used for images and graphics, but can contain
-anything you like, including text. Whatever’s in the
-float will be kept together as a block, output immediately if
-there’s room, or deferred to the top of the next output page
-when there isn’t; running text continues to the bottom of the
-previous page without interruption.
+By default, mom sets captions above figures (i.e. <b>pic</b> output and
+pdf images) and tables. This behaviour may be modified with the
+macro
+<a href="#caption-after-label">CAPTION_AFTER_LABEL</a>.
+Equations always have their captions set underneath. All aspects of
+the text style for captions may be set with the macro,
+<a href="#captions-labels-sources">CAPTIONS</a>.
</p>
<p>
-In the case of a float that doesn’t fit being followed by
-one that does, the second is output in position and the first is
-deferred. In the case of two or more that don’t fit, they are
-output in order on the next page.
+Labels for tables are set underneath the table unless the
+<a href="#mla">MLA</a>
+macro has been invoked, in which case the label and caption appear
+above the table, per MLA style, and the source for the table, if
+any, appears underneath. Labels for figures are set underneath.
+Equation labels, by default, are set on the same baseline as the
+last line of the equation. Like captions, all aspects of text style
+for labels may be established with a single macro,
+<a href="#labels">LABELS</a>. Furthermore, mom can autolabel
+figures, tables, and equations, with or without a prefixed chapter
+number.
</p>
+<div class="macro-id-overline">
+<h3 id="autolabel" class="macro-id">Autolabel</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>AUTOLABEL_EQUATIONS</b>
+<br/>
+Macro: <b>AUTOLABEL_IMAGES</b>
+<br/>
+Macro: <b>AUTOLABEL_PIC</b>
+<br/>
+Macro: <b>AUTOLABEL_TABLES</b>
+<br/>
+<kbd class="macro-args">Arguments:
+<br/>
+[ PREFIX "<string>"] [ SUFFIX "<string>"] [ PREFIX_CHAPTER [
<n> ] ]
+</kbd>
+</div>
+
<p>
-A key distinction between a float and a
-<a href="docelement.html#quote">QUOTE</a>
-or
-<a href="docelement.html#blockquote">BLOCKQUOTE</a>
-is that while a float keeps everything together and defers output if
-necessary, quotes and blockquotes are output immediately, and may
-start on one page and finish on the next.
+<b>AUTOLABEL_<type></b> takes care of labelling <type> by
+identifying each with a separate, incrementing numeric scheme, which
+is also collected for output in Lists of Figures, Equations, and
+Tables. By default, the label numbers are prefixed, and, in the
+case of equations, suffixed, with strings such that they appear for
+tables as “Table <n>”, for <b>pic</b> diagrams and
+pdf images as “Fig. <n>”, and for equations as
+“(<n>)”.
</p>
<p>
-Floats always deposit a break before they begin, which means the
-line beforehand will not be
-<a href="definitions.html#filled">filled</a>.
-Floats, therefore, cannot be inserted in the middle of a paragraph
-without studying the output file and determining where to break or
-<a href="typesetting.html#spread">spread</a>
-the line before the float.
+If you wish to change the prefix string, pass <i>both</i>
+the <kbd>PREFIX</kbd> and <kbd>SUFFIX</kbd> arguments to
+<kbd>.AUTOLABEL_<type></kbd> and enter the string you wish,
+including any spaces, surrounded by double-quotes. If no suffix is
+needed, give <kbd>SUFFIX</kbd> an empty string with two adjacent
+double-quotes.
</p>
-<p id="float-spacing">
-Floats begin on the baseline immediately below the running text
-preceding them. No additional whitespace surrounds them, above or
-below. Running text below a float is, however,
-<a href="docprocessing.html#shim">shimmed</a>,
-unless shimming has been disabled with <kbd>.NO_SHIM</kbd>. This
-usually results in a small amount of extra whitespace after the
-float. The <kbd>ADJUST</kbd> argument to FLOAT allows you to
-fine-tune the vertical centering.
+<p>
+For example, if you are including musical excerpts
+in your document, MLA style requires that they be labelled
+“Ex. <n>”. Since musical excerpts are likely to
+be scanned images (in pdf format, don’t forget), you must
+change the prefix string for pdf images:
+<br/>
+<span class="pre-in-pp">
+ .AUTOLABEL_IMAGES PREFIX "Ex. " SUFFIX ""
+</span>
</p>
+<h4 class="docs" style="margin-top: -1em">Prefixing chapter numbers</h4>
+
<p>
-If you’d like more space around a float, you must add it
-manually, for example with
-<a href="typesetting.html#ald">ALD</a>
-or
-<a href="typesetting.html#space">SPACE</a>.
+If you would like mom to prefix chapter numbers to the label,
+pass <kbd>AUTOLABEL_<type></kbd> the argument
+<kbd>PREFIX_CHAPTER</kbd>.
</p>
-<!-- -FLOAT- -->
+<p>
+If you have not given mom a <kbd>CHAPTER <n></kbd> prior
+to invoking <kbd>AUTOLABEL_<type> PREFIX_CHAPTER</kbd>,
+you must give the chapter number after <kbd>PREFIX_CHAPTER</kbd>.
+Once done, all subsequent chapters or collated document sections
+will increment the chapter number by one automatically. Failure to
+provide a chapter number after <kbd>PREFIX</kbd> when it is required
+will result in mom aborting with a reminder to do so.
+</p>
<div class="macro-id-overline">
-<h3 id="float" class= "macro-id">FLOAT</h3>
+<h3 id="caption-after-label" class="macro-id">Captions after labels</h3>
</div>
-<div class="box-macro-args">
-Macro: <b>FLOAT</b> <kbd class="macro-args">[ FORCE ] [ ADJUST
+|-<amount> ] [ SPAN ] | <anything></kbd>
+<div class="box-macro-args" style="margin-top: .5em">
+Macro: <b>CAPTION_AFTER_LABEL</b> <kbd class="macro-args">IMG | PIC | TBL |
ALL [ <anything></kbd> ]
+</kbd>
</div>
+<p>
+By default, mom sets captions above figures (<b>pic</b> output
+and pdf images) and tables; labels are always underneath.
+</p>
+
+<p>
+<kbd>.CAPTION_AFTER_LABEL</kbd>, with one of the required arguments,
+instructs mom to attach captions directly to the appropriate
+labels, beginning on the same line. Any argument after the first
+disables this behaviour, restoring caption placement to mom’s
+default. For example,
+<br/>
+<span class="pre-in-pp">
+ .CAPTION_AFTER_LABEL ALL
+</span>
+would enable captions after labels globally, while a subsequent
+<br/>
+<span class="pre-in-pp">
+ .CAPTION_AFTER_LABEL IMG OFF
+</span>
+would disable captions after labels for pdf images only.
+<kbd>OFF</kbd> can be anything you like (<kbd>X</kbd>,
+<kbd>NO</kbd>, etc).
+</p>
+
+<p>
+If
+<a href="#mla">MLA</a>
+is enabled, there's no need to invoke <kbd>CAPTION_AFTER_LABEL</kbd>
+as this is implied.
+</p>
+
<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
-FLOAT is intended for use with the document processing macros only.
+A separate invocation of <kbd>.CAPTION_AFTER_LABEL</kbd> is required
+for each one of the required first arguments. You cannot, for
+example, do
+<br/>
+<span class="pre-in-pp">
+ .CAPTION_AFTER_LABEL IMG TBL
+</span>
+Rather, you must do
+<br/>
+<span class="pre-in-pp">
+ .CAPTION_AFTER_LABEL IMG
+ .CAPTION_AFTER_LABEL TBL
+</span>
</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).
+<div class="macro-id-overline">
+<h3 id="mla" class="macro-id">MLA-style captioning and labelling</h3>
+</div>
+
+<div class="box-macro-args" style="margin-top: .5em">
+Macro: <b>MLA</b> <kbd class="macro-args"> [ <anything></kbd> ]
+</kbd>
+</div>
+
+<p>
+Modern Language Association style dictates that captions should
+always go after labels. Furthermore, labels and captions for tables
+should go <i>above</i> the tables, with the source for the table, if
+any, underneath.
+</p>
+
+<p>
+Invoking <kbd>.MLA</kbd> by itself takes care of these details. If
+you need to disable MLA-style captioning and labelling mid-document,
+<kbd>.MLA OFF</kbd> does the trick. <kbd>OFF</kbd> can be
+anything you like (<kbd>X</kbd>, <kbd>NO</kbd>, etc).
+</p>
+
+<div class="macro-id-overline" style="margin-top: 1em">
+<h3 id="captions-labels-sources" class="macro-id">Style parameters for
captions, labels and sources</h3>
+</div>
+
+<div class="box-macro-args" style="margin-top: .5em">
+Macro: <b>CAPTIONS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL |
ALL</kbd>
+<br/>
+Macro: <b>LABELS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL | ALL</kbd>
+<br/>
+Macro: <b>SOURCES</b> <kbd class="macro-args">TBL</kbd>
+<br/>
+<kbd class="macro-args">Style arguments:
+<br/>
+ FAMILY <family> \
+<br/>
+ FONT <font> \
+<br/>
+ SIZE "+|-<size>" \
+<br/>
+ AUTOLEAD "<value>" \
+<br/>
+ COLOR "<color>" \
+<br/>
+ QUAD LEFT | CENTER | RIGHT [ ON_LL ] \
+<br/>
+ ADJUST +|-<vertical adjustment>
+</kbd>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Arguments may be broken into several lines using the
+“line-continued” backslash (<b>\</b>), as shown above.
</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Additional note:</span>
+Mom’s default style for labels, captions, and sources is
+the same as the style used for running text, with two exceptions:
+labels are set in bold, except for eqn which is roman medium, and
+the autolead value for all three is “2”, effectively
+tightening the lead. Furthermore, they are quadded left (except
+eqn, which is quadded right.)
+</p>
+</div>
<p>
-The optional <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 not fit on the current page. While this is
-somewhat contrary to the notion of floats (ie that running text
-should continue to fill the page), there are circumstances where it
-may be desirable.
+With the exception of <kbd>ADJUST</kbd> and <kbd>QUAD</kbd> (which
+requires a bit of explanation), the style arguments to <kbd>CAPTIONS</kbd>,
+<kbd>LABELS</kbd>, and <kbd>SOURCES</kbd> (which is only available
+for tables) behave identically to the
+<a href="docelement.html#control-macro-args">arguments to control macros</a>.
</p>
<p>
-The <kbd>ADJUST</kbd> argument tells mom to raise
-(<kbd>+</kbd>) or lower (<kbd>-</kbd>) the float <i>within the space
-allotted to it</i> by the specified amount.
-<kbd><amount></kbd> must have a
-<a href="definitions.html#unitofmeasure">unit of measure</a>
-appended. <kbd>ADJUST</kbd> gives you precise control over
-the vertical centering of floats, allowing you to compensate for
-unequal spacing that may result of from the automatic shimming of
-floats (or the absence thereof). See
-<a href="docprocessing.html#shim">SHIM</a>
-for a discussion of automatic shimming.
+The first, required argument after <kbd>CAPTIONS</kbd>,
+<kbd>LABELS</kbd>, and <kbd>SOURCES</kbd> indicates the preprocessor
+type for which you are setting the parameters. (For convenience
+PDF_IMAGE—argument <kbd>IMG</kbd>—is here treated as a
+preprocessor.) An argument of <kbd>ALL</kbd> sets a unified
+style for every preprocessor. If the <kbd>ALL</kbd> argument is
+given, arguments to subsequent invocations of <kbd>CAPTIONS</kbd>,
+<kbd>LABELS</kbd>, or <kbd>SOURCES</kbd> overwrite only the
+explicitly named style parameters.
</p>
+<h4 class="docs">QUAD — quadding of labels, captions, and sources</h4>
+
<p>
-<kbd>ADJUST</kbd> is ignored whenever a float is deferred to
-the following page.
+By default, figures (<b>pic</b> output and pdf images) and tables
+have their captions and labels set quad left. Sources (for tables)
+are also set quad left. Equations have their labels set quad right,
+and their captions centered.
</p>
<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
-not be used for floats containing a boxed table; mom will abort with
-a warning should this occur. Unboxed tables, on the other hand, are
-acceptable within floats that are given the <kbd>SPAN</kbd> argument.
+The meaning of left, center, and right is fluid, depending on a
+number of factors. Know, however, that if you pass the optional
+<kbd>ON_LL</kbd> argument to <kbd>QUAD <direction></kbd>, mom
+will use the entire line length, from left to right margin, as the
+basis for quadding.
+</p>
+
+<p>
+For figures and tables, without the <kbd>ON_LL</kbd> argument,
+<kbd>LEFT</kbd>, <kbd>CENTER</kbd>, and <kbd>RIGHT</kbd> mean flush
+left, center, or right on the figure or table.
+</p>
+
+<p>
+If the figure or table is positioned left and the quad direction is
+<kbd>LEFT</kbd>, text will flow past the figure or table and break
+only when the right margin of the page is reached. If the quad
+direction is <kbd>CENTER</kbd>, text will be centered on the figure
+or table. If the quad direction is <kbd>RIGHT</kbd>, text will be
+quadded flush with the right margin of the figure or table.
+</p>
+
+<p>
+If the figure or table is positioned center and the quad direction
+is <kbd>CENTER</kbd>, text will be centered on the full line length.
+If the quad direction is <kbd>LEFT</kbd> or <kbd>RIGHT</kbd>, text
+will be set flush left or right on the figure or table, with the
+width of the figure or table determining the line length (unless
+<kbd>ON_LL</kbd> is given).
+</p>
+
+<p>
+If the figure or table is positioned right and the quad direction
+is <kbd>RIGHT</kbd>, text will be set flush right with the figure or
+table (which is also the right margin of the page) and will extend
+<i>to the right</i> of the figure or table over the full line length.
+If the quad direction is <kbd>LEFT</kbd>, text
+will be set flush left on the figure or table, with the
+width of the figure or table determining the line length (unless
+<kbd>ON_LL</kbd> is given). If the quad direction is
+<kbd>CENTER</kbd>, text is centered on the figure or table.
+</p>
+
+<p>
+Equations behave differently. By default, equation labels are
+set flush right with the page’s right margin regardless of
+equation positioning, which is, again by default, centered. If the
+equation is positioned left, the label will appear at the right
+margin regardless of the direction you give to <kbd>QUAD</kbd>. If
+the equation is indented with the <kbd>-I <indent></kbd>
+option, a quad direction of <kbd>LEFT</kbd> is observed, but may
+overprint the last line of the equation. Note that there is no
+<kbd>CENTER</kbd> option for equation labels, and that captions are
+always quadded over the full line length.
+</p>
+
+<h4 class="docs">ADJUST</h4>
+
+<p>
+The <kbd>ADJUST</kbd> argument allows you to add(<kbd>+</kbd>) or
+subtract (<kbd>-</kbd>) vertical space between labels and captions
+and the output to which they are attached. The argument requires a
+<a href="definitions.html#unitofmeasure">unit of measure</a>. For
+example, if you find that table labels are a bit too close to the
+table itself,
+<br/>
+<span class="pre-in-pp">
+ .LABELS TBL ADJUST +3p
+</span>
+would put three extra points of space between the bottoms of tables
+and the labels that appear beneath them.
+</p>
+
+<h2 id="lists-of" class="docs">Lists of Figures, Tables, and Equations</h2>
+
+<p>
+Besides a
+<a href="tables-of-contents.html">Table of Contents</a>,
+mom can generate Lists of Figures, Tables, and Equations. Labels
+and captions are collected and concatenated, and output in lists
+with the appropriate page number, just like a Table of Contents.
+Including such lists in a document is as simple as adding whichever
+you need of
+<br/>
+<span class="pre-in-pp">
+ .LIST_OF_FIGURES
+ .LIST_OF_EQUATIONS
+ .LIST_OF_TABLES
+</span>
+to the end of your input file.
+</p>
+
+<p>
+Also like the Table of Contents, entries in the Lists' output are
+clickable PDF links when a document is viewed at the screen.
+</p>
+
+<h3 id="lists-placement" class="docs">Placement of Lists</h3>
+
+<p>
+Lists normally appear after the Table of Contents, and continue
+the page numbering scheme used for it. By default, the Table of
+Contents begins on roman-numeral page “i”.
</p>
+<p>
+If you are using mom’s
+<a href="tables-of-contents.html#auto-relocate-toc">AUTO_RELOCATE_TOC</a>
+feature, you have two options for placement of the Lists within the
+document. If you want the Lists shifted to the top of the document
+along with the Table of Contents, invoke the Lists macros <i>after</i>
+<a href="tables-of-contents.html#toc"><kbd>.TOC</kbd></a>.
+If you prefer to have the Lists at the end of the document, invoke
+the Lists macros <i>before</i> <kbd>.TOC</kbd>.
+</p>
+
+<p>
+Lists shifted with the Table of Contents do not appear in the Table
+of Contents itself, but do appear as clickable links in the PDF
+outline typically available in the left panel of most PDF viewers.
+Lists that are not shifted with the Table of Contents appear in both
+the Table of Contents itself and the PDF outline.
+</p>
+
+<div class="macro-id-overline" style="margin-top: 1em">
+<h3 id="lists-macros" class="macro-id">Macros to generate Lists</h3>
+</div>
+
+<div class="box-macro-args" style="margin-top: .5em">
+Macro: <b>LIST_OF_EQUATIONS</b>
+<br/>
+Macro: <b>LIST_OF_FIGURES</b>
+<br/>
+Macro: <b>LIST_OF_TABLES</b>
+<br/>
+<kbd class="macro-args">Arguments:
+<br/>
+ [ TITLE_STRING "<string>" ] [ START_PAGENUM <page
number> ]
+</div>
+
+<p>
+The first optional argument to the <kbd>LIST_OF_<type></kbd>
+macros allows you to change the title that appears at the top of the
+page. This is useful not only for internationalization, or to meet
+the requirements of various style guides, but is also useful
+for, say, documents containing musical examples, which, per
+MLA-style, should be labelled “Example ” or
+“Ex. ”. When it comes time to output the List of
+Figures (to which musical examples, usually scanned pdf images, belong),
+<br/>
+<span class="pre-in-pp">
+ LIST_OF_FIGURES TITLE_STRING "List of Examples"
+</span>
+ensures that the title of the List is correct.
+</p>
+
+<p>
+The second optional argument allows you to give a starting page
+number for a list in cases where mom’s pagination scheme does
+not provide the List with the starting page number you want.
+</p>
+<h3 id="formatting-lists" class="docs">Formatting and style parameters for
Lists</h3>
+
+<p>
+Like the Table of Contents, nearly every aspect of Lists can be
+designed independently of a document’s overall style. By
+default, Lists follow the formatting and style parameters of the
+Table of Contents, both mom’s defaults and any changes you may
+have made to the Table of Contents.
+</p>
+
+<p>
+If you wish to make changes to any aspect of Lists formatting
+or styling, the macro <kbd>LISTS_STYLE</kbd> provides all the
+tools necessary. It is unlikely that you’ll want the
+formatting of the various list types to differ one from the other,
+so <kbd>LISTS_STYLE</kbd> applies to all Lists. In the event that
+you do need to change some aspect of the formatting for different
+list types, simply invoke <kbd>LISTS_STYLE</kbd> immediately prior
+to each list whose formatting needs to be changed.
+</p>
+
+<div class="macro-id-overline" style="margin-top: 1em">
+<h3 id="lists-style" class="macro-id">Lists style</h3>
+</div>
+
+<div class="box-macro-args" style="margin-top: .5em">
+Macro: <b>LISTS_STYLE</b> <kbd class="macro-args">
+<br/>
+Arguments:
+<br/>
+ FAMILY <family> \
+<br/>
+ FONT <font> \
+<br/>
+ PT_SIZE <size> \
+<br/>
+ LEAD <leading> \
+<br/>
+ TITLE_FAMILY <family> \
+<br/>
+ TITLE_FONT <font> \
+<br/>
+ TITLE_SIZE +|-<size> \
+<br/>
+ TITLE_QUAD LEFT | CENTER | RIGHT \
+<br/>
+ TITLE_COLOR <color> \
+<br/>
+ PN_FAMILY <family> \
+<br/>
+ PN_FONT <font> \
+<br/>
+ PN_SIZE +|-<size> \
+<br/>
+ EQN_PN_PADDING <placeholders> \
+<br/>
+ FIG_PN_PADDING <placeholders> \
+<br/>
+ TBL_PN_PADDING <placeholders> \
+<br/>
+ PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha \
+<br/>
+ NO_PAGINATION
+</kbd>
+</div>
+
<div class="box-tip">
-<p class="tip-top">
+<p class="tip">
<span class="note">Note:</span>
-Floats use
-<a href="definitions.html#filled">no-fill mode</a>,
-with each input line beginning at the left margin. If this is not
-what you want, you must specify the preferred horizontal alignment
-<i>within the float</i> (eg
-<a href="typesetting.html#lrc">CENTER</a>
-or
-<a href="typesetting.html#lrc">RIGHT</a>).
+Arguments may be broken into several lines using the
+“line-continued” backslash (<b>\</b>), as shown above.
</p>
+</div>
-<p class="tip-bottom">
-Furthermore, if you want text
-<a href="definitions.html#filled">filled</a>,
-you must specify
-<a href="typesetting.html#quad"><kbd>.QUAD L|R|C</kbd></a>
+<p>
+<kbd>FAMILY</kbd> is the family for the entirety of Lists pages.
+</p>
+
+<p>
+<kbd>FONT</kbd> is the font for the entirety of Lists pages.
+</p>
+
+<p>
+<kbd>PT_SIZE</kbd> is the base point size for the entirety of Lists
+pages.
+</p>
+
+<p>
+<kbd>LEAD</kbd> is the base leading for the entirety of Lists pages.
+</p>
+
+<p>
+<kbd>TITLE_FAMILY</kbd> is the family for the Lists titles if you
+want it different from the family otherwise used for the Lists
+pages.
+</p>
+
+<p>
+<kbd>TITLE_FONT</kbd> is the font for the Lists titles if you want
+it different from the font otherwise used for the Lists pages.
+</p>
+
+<p>
+<kbd>TITLE_SIZE</kbd> tells mom by how much to increase
+(<kbd>+</kbd>) or decrease (<kbd>-</kbd>) the point size of the
+titles relative to the overall point size of Lists pages.
+</p>
+
+<p>
+<kbd>TITLE_QUAD</kbd> tells mom how to position the title
+horizontally.
+</p>
+
+<p>
+<kbd>TITLE_COLOR</kbd> sets the colour for the titles. The colour
+must be pre-initialized with
+<a href="color.html#newcolor">NEWCOLOR</a>
or
-<a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a>—again,
-within the float.
+<a href="color.html#xcolor">XCOLOR</a>.
+</p>
+
+<p>
+<kbd>PN_FAMILY</kbd> sets the family for entry pagenumbers.
+</p>
+
+<p>
+<kbd>PN_FONT</kbd> sets the font for entry pagenumbers.
+</p>
+
+<p>
+<kbd>PN_SIZE</kbd> tells mom by how much to increase (<kbd>+</kbd>)
+or decrease (<kbd>-</kbd>) the point size of entry pagenumbers
+relative to the overall point size of Lists pages.
+</p>
+
+<p>
+<kbd>EQN_PN_PADDING</kbd>, <kbd>FIG_PN_PADDING</kbd>, and
+<kbd>TBL_PN_PADDING</kbd> tells mom how many placeholders to reserve
+for the entry pagenumbers in their respective Lists. If, for example,
+a document with both tables and figures runs to over a hundred
+pages, but there are no tables after page 99,
+<br/>
+<span class="pre-in-pp">
+ LISTS_STYLE FIG_PN_PADDING 3
+ LISTS_STYLE TBL_PN_PADDING 2
+</span>
+would prevent an unneeded, reserved placeholder from putting too
+much space between the leader and the entry pagenumber in the List of
+Tables.
+</p>
+
+<p>
+The padding in effect, unless you change it, is whatever was set for
+the Tables of Contents; mom’s default is “3”.
+</p>
+
+<p>
+<kbd>PAGENUM_STYLE</kbd> tells mom which pagination format to use
+for the page numbers of the Lists pages themselves. By default,
+since Lists observe what is in effect for the Table of Contents, the
+pagination format is “roman”. Please note that the
+starting page number for any of the Lists is given as an argument to
+the
+<a href="#lists-of">LISTS_0F_<type></a>
+macro.
+</p>
+
+<p>
+<kbd>NO_PAGINATION</kbd> disables pagination of Lists pages.
</p>
-</div>
<div class="rule-long"><hr/></div>
diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html
index eb128f2..7574dd2 100644
--- a/contrib/mom/momdoc/inlines.html
+++ b/contrib/mom/momdoc/inlines.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html
index 205b24a..445bf1c 100644
--- a/contrib/mom/momdoc/intro.html
+++ b/contrib/mom/momdoc/intro.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009,
-2010, 2011, 2012, 2013 Free Software Foundation, Inc.
+2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/letters.html b/contrib/mom/momdoc/letters.html
index 1d109ba..840a8e2 100644
--- a/contrib/mom/momdoc/letters.html
+++ b/contrib/mom/momdoc/letters.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/macrolist.html
b/contrib/mom/momdoc/macrolist.html
index 0cb16ca..274e8e1 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -74,37 +74,42 @@ elsewhere in the documentation.
</ul>
<h3 class="docs" style="margin-top: -.5em;">DOCUMENT PROCESSING MACROS</h3>
<ul style="margin-top: .5em; margin-left: 0; padding-left: 0; list-style-type:
none;">
- <li><a href="#qr-19">Reference macros</a></li>
- <li><a href="#qr-20">General document formatting directives</a></li>
- <li><a href="#qr-21">Line numbering</a></li>
- <li><a href="#qr-22">Set documents in columns</a></li>
+ <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-23">TYPEWRITE control macros</a></li>
+ <li><a href="#qr-47">Document and section cover (title) pages</a></li>
+ <li><a href="#qr-22">Set documents in columns</a></li>
+ <li><a href="#qr-21">Line numbering</a></li>
<li><a href="#qr-24">Initiate document processing</a></li>
+ <li><a href="#qr-42">Global print style changes after START</a></li>
</ul>
</div>
<ul style="margin-top: 1.75em; margin-left: 0; padding-left: 0;
list-style-type: none;">
+ <li><a href="#qr-43">Managing a document’s first-page header<br/><span
style="margin-left: 1.25em;">(the “docheader”)</span></a></li>
<li><a href="#qr-25">Epigraphs</a></li>
<li><a href="#qr-26">Headings</a></li>
<li><a href="#qr-30">Paragraphs</a></li>
<li><a href="#qr-31">Quotes (line for line quotes)</a> </li>
<li><a href="#qr-32">Blockquotes (cited passages of text)</a></li>
- <li><a href="#qr-49">Floats</a></li>
- <li><a href="#qr-50">tbl support</a></li>
<li><a href="#qr-33">Code snippets (inserting bits of programming
code)</a></li>
<li><a href="#qr-34">Author linebreaks (section breaks)</a></li>
<li><a href="#qr-35">Document termination string</a></li>
<li><a href="#qr-36">Footnotes</a></li>
<li><a href="#qr-37">Endnotes</a></li>
<li><a href="#qr-38">Margin notes</a></li>
+ <li><a href="#qr-49">Floats</a></li>
+ <li><a href="#qr-53">Images and graphics</a></li>
+ <li><a href="#qr-51">eqn support</a></li>
+ <li><a href="#qr-52">pic support</a></li>
+ <li><a href="#qr-50">tbl support</a></li>
+ <li><a href="#qr-54">Captions and labels</a></li>
<li><a href="#qr-39">Bibliographic references</a></li>
<li><a href="#qr-40">Tables of contents</a></li>
+ <li><a href="#qr-55">Lists of Figures, Tables, and Equations</a></li>
<li><a href="#qr-41">Letter (correspondence) macros</a></li>
- <li><a href="#qr-42">Changing global print style parameters after<br/><span
style="margin-left: 1.25em;">START</span></a></li>
- <li><a href="#qr-43">Managing a document’s first-page header<br/><span
style="margin-left: 1.25em;">(the “docheader”)</span></a></li>
<li><a href="#qr-44">Managing page headers and footers</a></li>
<li><a href="#qr-45">Recto/verso page headers and footers</a></li>
<li><a href="#qr-46">Pagination</a></li>
- <li><a href="#qr-47">Document and section cover (title) pages</a></li>
<li><a href="#qr-48">Utilities</a></li>
</ul>
<br/>
@@ -795,6 +800,7 @@ elsewhere in the documentation.
<tr>
<th id="qr-49" class="quick-ref" colspan="2" >+++Floats </th>
</tr>
+<tr>
<td style="vertical-align: top"><a
href="images.html#float">FLOAT</a></td><td>-- keep blocks of input together,
output on next page
<br/>
if necessary</td>
@@ -803,16 +809,100 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-50" class="quick-ref" colspan="2" >+++tbl support </th>
+<th id="qr-53" class="quick-ref" colspan="2" >+++Images and graphics </th>
+</tr>
+<tr>
+<td style="vertical-align: top"><a
href="images.html#pdf">PDF_IMAGE</a></td><td>-- inserting pdf images
+</tr>
+<tr>
+<td style="vertical-align: top"><a
href="images.html#pdf-image-frame"> PDF_IMAGE_FRAME</a></td><td>-- set
parameters for pdf image frames
+</tr>
+<tr>
+<td style="vertical-align: top"><a
href="images.html#pspic">PSPIC</a></td><td>-- inserting PostScript images
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-51" class="quick-ref" colspan="2" >+++eqn support </th>
+</tr>
+<tr>
+<td><a href="images.html#eq-en">EQ</a></td><td>-- begin an eqn block</td>
+</tr>
+<tr>
+<td><a href="images.html#eq-en">EN</a></td><td>-- end an eqn block</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-52" class="quick-ref" colspan="2" >+++pic support </th>
+</tr>
+<tr>
+<td><a href="images.html#ps-pe">PS</a></td><td>-- begin a pic block</td>
+</tr>
+<tr>
+<td><a href="images.html#ps-pe">PE</a></td><td>-- end a pic block</td>
+</tr>
+<tr>
+<td><a href="images.html#pic-text-style">PIC_TEXT_STYLE</a></td><td>-- set
style for pic text</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-50" class="quick-ref" colspan="2" >+++tbl support</th>
+</tr>
+<tr>
+<td><a href="images.html#ts-te">TS</a></td><td>-- begin a tbl block</td>
+</tr>
+<tr>
+<td><a href="images.html#ts-te">TH</a></td><td>-- running table header (after
TS H)</td>
+</tr>
+<tr>
+<td><a href="images.html#ts-te">TE</a></td><td>-- end tbl block</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-54" class="quick-ref" colspan="2" >+++ Captions and labels</th>
+</tr>
+<tr>
+<td><a href="images.html#autolabel">AUTOLABEL</a></td><td>-- auto-label
figures, tables, equations</td>
+</tr>
+<tr>
+<td><a
href="images.html#caption-after-label">CAPTION_AFTER_LABEL</a></td><td>-- place
captions after labels</td>
+</tr>
+<tr>
+<td><a href="images.html#mla">MLA</a></td><td>-- MLA-style labelling and
captioning</td>
+</tr>
+<tr>
+<td><a href="images.html#captions-labels-sources">CAPTIONS</a></td><td>-- set
style for captions</td>
+</tr>
+<tr>
+<td><a href="images.html#captions-labels-sources">LABELS</a></td><td>-- set
style for labels</td>
+</tr>
+<tr>
+<td><a href="images.html#captions-labels-sources">SOURCES</a></td><td>-- set
style for sources (tbl only)</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-55" class="quick-ref" colspan="2" >+++Lists of Figures, Tables, and
Equations</th>
+</tr>
+<tr>
+<td><a href="images.html#lists-macros">LIST_OF_FIGURES</a></td><td>-- generate
a List of Figures</td>
</tr>
<tr>
-<td><a href="docelement.html#blockquote">TS</a></td><td>-- begin a tbl
block</td>
+<td><a href="images.html#lists-macros">LIST_OF_TABLES</a></td><td>-- generate
a List of Tables</td>
</tr>
<tr>
-<td><a href="docelement.html#blockquote-general">TH</a></td><td>-- running
table header (after TS H)</td>
+<td><a href="images.html#lists-macros">LIST_OF_EQUATIONS</a></td><td>--
generate a List of Equations</td>
</tr>
<tr>
-<td><a href="docelement.html#always-fullspace-quotes">TE</a></td><td>-- end
tbl block</td>
+<td><a href="images.html#lists-style">LISTS_STYLE</a></td><td>-- set style
parameters for Lists</td>
</tr>
</table>
diff --git a/contrib/mom/momdoc/rectoverso.html
b/contrib/mom/momdoc/rectoverso.html
index b725e9e..bacd089 100644
--- a/contrib/mom/momdoc/rectoverso.html
+++ b/contrib/mom/momdoc/rectoverso.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html
index 6d77875..aae2554 100644
--- a/contrib/mom/momdoc/refer.html
+++ b/contrib/mom/momdoc/refer.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/reserved.html b/contrib/mom/momdoc/reserved.html
index 4f5e547..b5d0fc2 100644
--- a/contrib/mom/momdoc/reserved.html
+++ b/contrib/mom/momdoc/reserved.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -57,8 +57,9 @@ mom uses, along with brief descriptions of their functions.
</p>
<p>
-Please note that PDF-related macros, strings, and registers are not
-included.
+The list is not exhaustive. PDF-related macros, strings, registers,
+and diversions, as well as those associated with preprocessor
+support and “Lists of” are not included.
</p>
<div class="rule-medium"><hr/></div>
@@ -618,7 +619,10 @@ included.
ENDNOTE_REFS Send REFs to endnotes
ENDNOTES Output endnotes
EPIGRAPH Epigraph before 1st para
+ EQ/EN eqn block
FINIS Prints --END--
+ FLOAT Keep material together as a block; defer output
+ to following page if not enough room to print
FOOTNOTE Collects footnotes in text for printing at bottom
of page
FOOTNOTE_REFS Send REFs to footnotes
@@ -653,6 +657,8 @@ included.
with doc info macros
SUBHEAD Subheads
SUBSUBHEAD Subsubheads
+ TH Running tbl header
+ TS/TE Begin/end a tbl block
<span style="display: block; margin-top: -.75em; margin-bottom:
-1em;">*Headers/footers</span>
BREAK_QUOTE Manually break a footnoted quote that crosses
@@ -715,6 +721,9 @@ included.
FINIS_STRING What to print when FINIS is invoked
FINIS_STRING_CAPS Whether to capitalize the finis string
+-eqn-
+ EQ_INDENT Indent value if 'EQ I'
+
-Footnotes-
FOOTNOTE_AUTOLEAD Autolead to use in footnotes
FOOTNOTE_LINENUMBER_BRACKETS Brackets for footnote linenumbers
@@ -1033,10 +1042,10 @@ included.
to fill page to #B_MARGIN
TYPEWRITER Sets family (C), font (R) and point size (12)
for PRINTSTYLE TYPEWRITE
- VFP_CHECK Trap-sprung macro 1 valid baseline higher than
+ VFP_CHECK Trap-sprung macro, 1 valid baseline higher than
where FOOTER will be sprung; checks whether
there is, in fact, just enough room for
- another line of running text to be added to
+ another line of running text to be added to
the page without jamming footnotes too close
to running text.
@@ -1186,9 +1195,7 @@ included.
#DATE_FIRST Was .DATE invoked as first letter
header after .START? (boolean)
dc "mark" register for document columns
- #DIVER_FN Register that tells FOOTNOTE whether to
- "move" or "defer" a footnote collected
- inside a diversion
+ DD Vert. space before and after eqn blocks
defer / new-defer Appended to FLOAT*DIV: if float deferred
#DEFER_BIB_SPACING Tells DEFAULTS to do BIBLIOGRAPHY_SPACING
if it was called before START
@@ -1206,6 +1213,10 @@ included.
#DEPTH_TO_B_MARGIN Page length minus #B_MARGIN
D-float Depth of float containing/ending with
DRH, DRV, DBX, or DCL
+ DI eqn indent if EQ I
+ #DIVER_FN Register that tells FOOTNOTE whether to
+ "move" or "defer" a footnote collected
+ inside a diversion
#DIVERSIONS_HY_MARGIN A reasonable value for .hym applied to
QUOTE, BLOCKQUOTE and EPIGRAPH to
avoid excessive hyphenation if these are
@@ -1533,6 +1544,7 @@ included.
with EPIGRAPH when columns are on
#L_MARGIN_DIFF Difference between DOC_L_MARGIN and
L_MARGIN
+ #LB_CHAR_ITERATIONS Number of linebreak character iterations
#LEFT_CAP_HEIGHT Cap height of left string in headers/footers
#VALID_BASELINE Calculates vert. position of next valid
baseline in SHIM
@@ -2357,6 +2369,7 @@ included.
$RL_WEIGHT Rule weight (DRH/DRV)
$SAVED_COPYRIGHT Temporarily holds string in $COPYRIGHT
$SAVED_RULE_GAP Temporarily holds string in $RULE_GAP
+ $SAVED_DOC_FAM Document family in effect before COLLATE
$SAVED_PP_FT $PP_FT in effect at start of
.COLLATE; tested for and removed
in .PP
diff --git a/contrib/mom/momdoc/tables-of-contents.html
b/contrib/mom/momdoc/tables-of-contents.html
index c9a8ffa..7f2d475 100644
--- a/contrib/mom/momdoc/tables-of-contents.html
+++ b/contrib/mom/momdoc/tables-of-contents.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index efdf15b..273a818 100644
--- a/contrib/mom/momdoc/toc.html
+++ b/contrib/mom/momdoc/toc.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -21,7 +21,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-b -- Table of Contents</title>
+ <title>Mom, version 2.1-c -- Table of Contents</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
</head>
@@ -32,7 +32,7 @@ FDL in the main directory of the groff source package.
<div class="page">
<div class="version">
- mom, version 2.1-b
+ mom, version 2.1-c
</div>
<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
@@ -350,12 +350,42 @@ FDL in the main directory of the groff source package.
<ul>
<li><a href="images.html#images-intro">5.5.1 Inserting images and
graphics</a></li>
<li><a href="images.html#converting">5.5.2 Image conversion and file
processing</a></li>
- <li><a href="images.html#pdf-image">5.5.3 PDF_IMAGE</a></li>
+ <li><a href="images.html#pdf-image">5.5.3 PDF_IMAGE</a>
+ <ul>
+ <li><a href="images.html#pdf-image-frame">5.5.3.1
PDF_IMAGE_FRAME</a></li>
+ </ul></li>
<li><a href="images.html#pspic">5.5.4 PSPIC</a></li>
- <li><a href="images.html#tbl">5.5.5 tbl support</a></li>
- <li><a href="images.html#floats-intro">5.5.6 Floats</a></li>
- </ul>
- </li>
+ <li><a href="images.html#floats-intro">5.5.5 Floats</a>
+ <ul>
+ <li><a href="images.html#float">5.5.5.1 FLOAT</a></li>
+ </ul></li>
+ <li><a href="images.html#preprocessor-support">5.5.6 Preprocessor
support</a>
+ <ul>
+ <li><a href="images.html#tbl">5.5.6.1 tbl support</a></li>
+ <li><a href="images.html#eqn">5.5.6.2 eqn support</a></li>
+ <li><a href="images.html#pic">5.5.6.3 pic support</a>
+ <ul style="list-style-type: disc">
+ <li><a href="images.html#pic-text-style">5.5.6.3.1
PIC_TEXT_STYLE</a></li>
+ </ul></li>
+ <li><a href="images.html#refer">5.5.6.4 refer support</a></li>
+ </ul></li>
+ <li><a href="#captions-and-labels">5.5.7 Captions and labels</a>
+ <ul>
+ <li><a href="#autolabel">5.5.7.1 AUTOLABEL</a></li>
+ <li><a href="#caption-after-label">5.5.7.2
CAPTION_AFTER_LABEL</a></li>
+ <li><a href="#captions-labels-sources">5.5.7.3 CAPTIONS / LABELS /
SOURCES—set style parameters</a></li>
+ <li><a href="#mla">5.5.7.4 MLA</a></li>
+ </ul></li>
+ <li><a href="#lists-of">5.5.8 Lists of Figures, Tables, and
Equations</a>
+ <ul>
+ <li><a href="#lists-placement">5.5.8.1 Placement of Lists</a></li>
+ <li><a href="#lists-macros">5.5.8.2 Macros to generate Lists</a></li>
+ <li><a href="#formatting-lists">5.5.8.3 Formatting and style
parameters for Lists</a>
+ <ul>
+ <li><a href="#lists-style">5.5.8.3.1 LISTS_STYLE</a></li>
+ </ul></li>
+ </ul></li>
+ </ul></li>
<li><a id="hdrftr" class="highlight" href="headfootpage.html#top">5.6
PAGE HEADERS AND FOOTERS</a>
<ul>
<li><a href="headfootpage.html#headfootpage-intro">5.6.1
Introduction</a></li>
diff --git a/contrib/mom/momdoc/typesetting.html
b/contrib/mom/momdoc/typesetting.html
index 800842a..3ca5d6a 100644
--- a/contrib/mom/momdoc/typesetting.html
+++ b/contrib/mom/momdoc/typesetting.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -1209,7 +1209,7 @@ Macro: <b>AUTOLEAD</b> <kbd class="macro-args"><amount
of automatic leading&g
• Does not require a <a href="definitions.html#unitofmeasure">unit
of measure</a>
<br/>
(Please see
-<a href=""></a>
+<a href="docprocessing.html#autolead">here</a>
for information on using
<span style="font-style: normal">AUTOLEAD</span> during document
processing.)
@@ -2118,6 +2118,11 @@ or
<span class="pre-in-pp">
.HY END
</span>
+A subsequent call to HY restores hyphenation with the parameters for
+LINES, MARGIN, or SPACE that were formerly in effect (see below).
+</p>
+
+<p>
HY observes the following default hyphenation rules:
</p>
<ul style="margin-top: -.5em; margin-left: 18px;">
@@ -3263,7 +3268,7 @@ than respecting organizational hierarchy.
Try setting this up and processing it it with
<br/>
<span class="pre-in-pp">
- pdfmom filename.mom | ps2pdf - filename.pdf
+ pdfmom filename.mom > filename.pdf
</span>
then previewing the .pdf file. Notice how <kbd>.TN</kbd>
simply moves over to the next tab, while the combination
@@ -3498,7 +3503,7 @@ than respecting organizational hierarchy.
Try setting this up and processing it with
<br/>
<span class="pre-in-pp">
- pdfmom filename | ps2pdf - filename.pdf
+ pdfmom filename.mom > filename.pdf
</span>
and previewing the .pdf file.
</p>
@@ -4732,7 +4737,7 @@ require a measure to be given.
Paste the example above into a file and preview it with
<br/>
<span class="pre-in-pp">
- pdfmom filename.mom | ps2pdf - filename.pdf
+ pdfmom filename.mom > filename.pdf
</span>
to see hanging indents in action.
</p>
diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html
index 7006761..2377415 100644
--- a/contrib/mom/momdoc/using.html
+++ b/contrib/mom/momdoc/using.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/version-2.html
b/contrib/mom/momdoc/version-2.html
index 15b38b1..ee51d8a 100644
--- a/contrib/mom/momdoc/version-2.html
+++ b/contrib/mom/momdoc/version-2.html
@@ -3,7 +3,7 @@
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
-2011, 2012, 2013 Free Software Foundation, Inc.
+2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -58,7 +58,7 @@ FDL in the main directory of the groff source package.
<li><a href="#table-of-contents">2.5 Table of contents</a></li>
</ul></li>
<li><a href="#pdfmom">The <strong>pdfmom</strong> wrapper around
groff</a></li>
- <li><a href="#install-font">The <strong>install-font</strong> script</a></li>
+ <li><a href="#install-font">The <strong>install-font.sh</strong>
script</a></li>
</ol>
</div>
@@ -122,7 +122,7 @@ papersize within the source file without the corresponding
need for
<p>
Lastly, while not strictly part of mom, a bash script,
-<strong>install-font</strong>, has been posted at the
+<strong>install-font.sh</strong>, has been posted at the
<a href="http://www.schaffter.ca/mom/";>mom site</a>.
The script significantly eases the installation of new
groff families and fonts, with conversion to .pfa
@@ -340,10 +340,10 @@ recognizes PDF images that have been embedded with
<a href="images.html#pdf-image"><kbd>PDF_IMAGE</kbd></a>.
</p>
-<h2 id="install-font" class="docs">4. install-font</h2>
+<h2 id="install-font" class="docs">4. install-font.sh</h2>
<p>
-A bash script, <strong>install-font</strong>, has been posted at the
+A bash script, <strong>install-font.sh</strong>, has been posted at the
<a href="http://www.schaffter.ca/mom/mom-01.html";>mom site</a>.
There’s nothing mom-specific about the script, and it is not
an official part of groff.
@@ -351,7 +351,7 @@ an official part of groff.
<p>
Installing groff fonts is a multi-step procedure, which, while not
-difficult, can be a nuisance. <strong>install-font</strong> takes
+difficult, can be a nuisance. <strong>install-font.sh</strong> takes
care of all the details, including converting fonts to formats
acceptable to <strong>grops</strong> and <strong>gropdf</strong>,
creating and installing the groff fonts in the appropriate
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: Version 2.0 doc updates,
Peter Schaffter <=