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