[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: Doc updates to reflect changes in 2.0-c_1.
From: |
Peter Schaffter |
Subject: |
[groff] 01/01: Doc updates to reflect changes in 2.0-c_1. |
Date: |
Mon, 20 Oct 2014 17:02:29 +0000 |
PTPi pushed a commit to branch master
in repository groff.
commit 83b356011af6aebdde77b2bf0568f8e107afb216
Author: Peter Schaffter <address@hidden>
Date: Mon Oct 20 12:55:20 2014 -0400
Doc updates to reflect changes in 2.0-c_1.
---
contrib/mom/momdoc/docelement.html | 27 +++++++
contrib/mom/momdoc/images.html | 128 +++++++++++++++--------------------
contrib/mom/momdoc/toc.html | 22 +++---
contrib/mom/momdoc/typesetting.html | 6 ++-
4 files changed, 97 insertions(+), 86 deletions(-)
diff --git a/contrib/mom/momdoc/docelement.html
b/contrib/mom/momdoc/docelement.html
index 4e79421..090352e 100644
--- a/contrib/mom/momdoc/docelement.html
+++ b/contrib/mom/momdoc/docelement.html
@@ -1981,6 +1981,33 @@ quotes on the same page are all spaced identically.
</p>
</div>
+<h3 id="float-quote" class="docs">Keeping QUOTEs and BLOCKQUOTEs together as a
block</h3>
+
+<p>
+The text of quotes and blockquotes is output immediately, and may therefore
+start on one page and finish on the next. If you wish to keep the
+text together as a block, deferred to the following page if the
+block doesn’t all fit on one page, wrap
+(BLOCK)QUOTE / (BLOCK)QUOTE OFF
+inside a
+<a href="images.html#floats-intro">float</a>. If you further wish to
+force a page break before the floated quote or blockquote (leaving
+whitespace at the bottom of the page, pass
+<a href="images.html#float">FLOAT</a>
+the <kbd>FORCE</kbd> argument.
+<span class="pre-in-pp">
+ .FLOAT FORCE
+ .QUOTE
+ Fly me to the moon
+ And let me play among the stars
+ Let me see what life is like
+ On Jupiter and Mars
+ .QUOTE END
+ .FLOAT OFF
+</span>
+
+</p>
+
<!-- -QUOTE- -->
<div class="macro-id-overline">
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index 0b3a9cb..fdff0c0 100644
--- a/contrib/mom/momdoc/images.html
+++ b/contrib/mom/momdoc/images.html
@@ -937,7 +937,7 @@ 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>
+<h5 id="h" class="docs" style="margin-top: 1em; text-transform: none">'H'</h5>
<p>
With the <b>H</b> argument, a table will span as many pages as
@@ -1078,6 +1078,13 @@ in
The text of the caption must be surrounded by double-quotes.
</p>
+<p>
+Please note that if your table has a caption, you must invoke
+<kbd>TS</kbd> with the <kbd>H</kbd> flag, which also entails the use
+of
+<a href="#th">TH</a>.
+</p>
+
<h5 class="docs" style="margin-top: 1em; text-transform:
none">'SHORT_CAPTION'</h5>
<p>
@@ -1105,12 +1112,26 @@ which, if enabled, overrides the <kbd>LABEL</kbd>
argument.
The <b>TH</b> macro (<b>T</b>able <b>H</b>eader), which is required
when you begin a table with <kbd>.TS H</kbd>, allows you to
determine what goes in a table’s running header if it spans
-multiple pages. If you place it immediately underneath your
-<kbd>tbl</kbd> formatting specifications, the last line of which
-always ends with a period (see <kbd>tbl(1)</kbd>), there will
-be no running header. If you place it under the first row of
-<kbd>tbl</kbd> data, the first row will form the header; under the
-second row, the first and second rows form the header, and so on.
+multiple pages. Placing <kbd>.TH</kbd> under the first row of
+<kbd>tbl</kbd> data makes the first row the header. If placed under
+the second row, the first and second rows form the header, and so
+on.
+</p>
+
+<p>
+As there are sometimes reasons to run <kbd>.TS H</kbd> when
+you don’t, in fact, want a running header (e.g. when
+your table has a caption), you can suppress it by placing
+<kbd>.TH</kbd> immediately underneath your <kbd>tbl</kbd> formatting
+specifications, the last line of which always ends with a period
+(see <kbd>tbl(1)</kbd>).</p>
+</p>
+
+<p>
+See the
+<kbd><a href="#h">H</a></kbd>
+argument to <kbd>.TS</kbd> for examples demonstrating <kbd>.TH</kbd>
+placement.
</p>
<div class="macro-id-overline">
@@ -1390,7 +1411,7 @@ required)
<br/>
[ LABEL "<label>" ]
<br/>
- [ LABEL_ADJUST +|-<vertical adjustment> ]
+ [ SHIFT_LABEL +|-<vertical adjustment> ]
<br/>
[ SHORT_CAPTION "<short caption>" ]
<br/>
@@ -1495,14 +1516,14 @@ Equations. Mom provides an auto-labelling facility for
equations (see
which, if enabled, overrides the <kbd>LABEL</kbd> argument.
</p>
-<h5 class="docs" style="margin-top: 1em; text-transform:
none">'LABEL_ADJUST'</h5>
+<h5 class="docs" style="margin-top: 1em; text-transform:
none">'SHIFT_LABEL'</h5>
<p>
-<kbd>LABEL_ADJUST</kbd> allows you to raise (<kbd>-</kbd>) or lower
+<kbd>SHIFT_LABEL</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
+<kbd>.EQ SHIFT_LABEL -1v</kbd> would raise the label by
one line, thus centering it vertically on the equation.
</p>
@@ -1629,27 +1650,27 @@ pdf images as “Fig. <n>”, and for
equations as
</p>
<p>
-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>
-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:
+Use <kbd>PREFIX <"string"></kbd> to change what comes
+before the automatic numbering. 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 have to change the prefix string for pdf images:
+<br/>
+<span class="pre-in-pp">
+ .AUTOLABEL_IMAGES PREFIX "Ex. "
+</span>
+If you need a suffix after the automatic numbering, use
+<kbd>SUFFIX <"string"></kbd>, like this:
<br/>
<span class="pre-in-pp">
- .AUTOLABEL_IMAGES PREFIX "Ex. " SUFFIX ""
+ .AUTOLABEL_IMAGES PREFIX "(Fig. " SUFFIX ")"
</span>
+Note that the double-quotes around the single-character SUFFIX
+string are optional.
</p>
-<h4 class="docs" style="margin-top: -1em">Prefixing chapter numbers</h4>
+<h4 class="docs" style="margin-top: -.5em">Prefixing chapter numbers</h4>
<p>
If you would like mom to prefix chapter numbers to the label,
@@ -1663,8 +1684,8 @@ 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.
+provide a chapter number after <kbd>PREFIX_CHAPTER</kbd> when it is
+required will result in mom aborting with a reminder to do so.
</p>
<div class="macro-id-overline">
@@ -1825,51 +1846,10 @@ explicitly named style parameters.
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 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.
+and their captions centered. Regardless of the quad direction,
+captions, labels, and sources are quadded over the width of figures
+and tables unless you pass the optional <kbd>ON_LL</kbd> argument to
+<kbd>QUAD <direction></kbd>.
</p>
<p>
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index b7f72af..da3b6b0 100644
--- a/contrib/mom/momdoc/toc.html
+++ b/contrib/mom/momdoc/toc.html
@@ -20,7 +20,7 @@ FDL in the main directory of the groff source package.
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8"/>
- <title>Mom, version 2.1-c -- Table of Contents</title>
+ <title>Mom, version 2.1-c_1 -- Table of Contents</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
</head>
@@ -31,7 +31,7 @@ FDL in the main directory of the groff source package.
<div class="page">
<div class="version">
- mom, version 2.1-c
+ mom, version 2.1-c_1
</div>
<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
@@ -368,18 +368,18 @@ FDL in the main directory of the groff source package.
</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>
+ <li><a href="images.html#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>
+ <li><a href="images.html#autolabel">5.5.7.1 AUTOLABEL</a></li>
+ <li><a href="images.html#caption-after-label">5.5.7.2
CAPTION_AFTER_LABEL</a></li>
+ <li><a href="images.html#captions-labels-sources">5.5.7.3 CAPTIONS /
LABELS / SOURCES—set style parameters</a></li>
+ <li><a href="images.html#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>
+ <li><a href="images.html#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>
+ <li><a href="images.html#lists-placement">5.5.8.1 Placement of
Lists</a></li>
+ <li><a href="images.html#lists-macros">5.5.8.2 Macros to generate
Lists</a></li>
+ <li><a href="images.html#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>
diff --git a/contrib/mom/momdoc/typesetting.html
b/contrib/mom/momdoc/typesetting.html
index 0bda6ea..3a8722a 100644
--- a/contrib/mom/momdoc/typesetting.html
+++ b/contrib/mom/momdoc/typesetting.html
@@ -305,6 +305,7 @@ PAGEWIDTH.
when you need it, should be placed at the top of your files.
</p>
</div>
+
<!-- -PAGELENGTH- -->
<div class="macro-id-overline">
@@ -345,7 +346,7 @@ when you need it, should be placed at the top of your files.
</div>
<div class="box-macro-args">
-Macro: <b>PAPER</b> <kbd class="macro-args"><paper type></kbd>
+Macro: <b>PAPER</b> <kbd class="macro-args"><paper type> [ LANDSCAPE
]</kbd>
</div>
<p>
@@ -374,6 +375,9 @@ than to remember the correct dimensions and enter
.PAGEWIDTH 595p
.PAGELENGTH 842p
</span>
+If you’d like landscape orientation for your paper type,
+pass PAPER the <kbd>LANDSCAPE</kbd> argument.
+<p>
Please read the
<a href="#page-setup-note">Important note on page dimensions and papersize</a>
for information on ensuring groff respects your PAPER size.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: Doc updates to reflect changes in 2.0-c_1.,
Peter Schaffter <=