[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff-commit] groff/contrib/mom/momdoc images.html toc.html
From: |
Peter Schaffter |
Subject: |
[Groff-commit] groff/contrib/mom/momdoc images.html toc.html |
Date: |
Tue, 17 Sep 2013 16:20:18 +0000 |
CVSROOT: /sources/groff
Module name: groff
Changes by: Peter Schaffter <PTPi> 13/09/17 16:20:18
Modified files:
contrib/mom/momdoc: images.html toc.html
Log message:
Doc updates for tbl support.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/images.html?cvsroot=groff&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/toc.html?cvsroot=groff&r1=1.45&r2=1.46
Patches:
Index: images.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/images.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- images.html 29 Jan 2013 05:02:46 -0000 1.4
+++ images.html 17 Sep 2013 16:20:17 -0000 1.5
@@ -21,7 +21,7 @@
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8"/>
- <title>Mom -- Graphics and floats</title>
+ <title>Mom -- Graphics, tbl support, and floats</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
</head>
@@ -39,7 +39,7 @@
</tr>
</table>
-<h1 class="docs">Graphics and floats</h1>
+<h1 class="docs">Graphics, tbl support, and floats</h1>
<div style="width: 55%; margin: auto;">
<ul class="no-enumerator" style="margin-left: -1em;">
@@ -51,11 +51,9 @@
</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="#tbl">tbl support</a></li>
<li><a href="#floats-intro">Introduction to floats</a></li>
- <li><a href="#float">The FLOAT macro</a>
- <ul style="margin-left: -.5em; list-style-type: disc;">
- <li><a href="#tbl-with-float">Using tbl with FLOAT</a></li>
- </ul></li>
+ <li><a href="#float">The FLOAT macro</a></li>
</ul>
</div>
@@ -361,6 +359,124 @@
<div class="rule-medium"><hr/></div>
+<h2 id="tbl" class="docs">tbl support</h2>
+
+<p>
+Mom documents can include tables generated with the groff
+pre-processor, <kbd>tbl</kbd>. <kbd>tbl</kbd> usage is beyond the
+scope of this documentation, but is covered fully in <kbd>man(1)
+tbl</kbd>.
+</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>.TE</kbd>
+(<b>T</b>able <b>E</b>nd).
+Depending on where you want your tables output in a document, you will likely
+need to wrap your <kbd>tbl</kbd> code inside a
+<a href="#floats-intro">float</a>,
+or use the <kbd>H</kbd> extension to <kbd>.TS</kbd>. If you put
+<kbd>tbl</kbd> code inside a float, the table will be output
+immediately if it fits on the page, or defered to the top 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
+your table will run to multiple pages, use <kbd>.TS H</kbd>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If you use <kbd>.TS H</kbd> to create a table that spans multiple
+pages, do not attempt to wrap the table inside a float. <kbd>.TS
+H</kbd> and <kbd>.FLOAT</kbd> are mutually exclusive. <b>FLOAT</b>
+“collects” the table and outputs it where convenient,
+whereas <kbd>.TS H</kbd> begins the table immediately and spans
+multiple pages, with a table header, if necessary.
+</p>
+</div>
+
+<div class="macro-id-overline">
+<h3 id="ts-te" class= "macro-id">.TS/.TE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>TS</b> <kbd class="macro-args">[ BOXED | H ]</kbd>
+<br/>
+Macro: <b>TH</b>
+<br/>
+Macro: <b>TE</b>
+</div>
+
+<p>
+Tables to be formatted with <kbd>tbl</kbd> begin with the macro
+<kbd>.TS</kbd> and end with <kbd>.TE</kbd>. Formatting
+instructions, per <kbd>man tbl</kbd> come between the two macros.
+<br/>
+<span class="pre-in-pp">
+ .TS
+ <tbl commands and data>
+ .TE
+</span>
+Tables may be wrapped inside a
+<a href="#float-intro">float</a>,
+in which case, the entire table will be output on the current page
+if it fits, or defered to the next page if it doesn’t.
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ .TS
+ <tbl commands and data>
+ .TE
+ .FLOAT OFF
+</span>
+If a table inside a float is to be boxed (ie have a frame or border
+around it), you must give the optional argument <kbd>BOXED</kbd> to
+<kbd>.TS</kbd>, as in this example:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ .TS BOXED
+ allbox center;
+ c s s
+ c c c
+ n n n.
+ <tbl commands and data>
+ .TE
+ .FLOAT OFF
+</span>
+Unboxed tables inside a float require no special argument to
+<kbd>.TS</kbd>.
+</p>
+
+<p>
+If you prefer a table to start where you say and span multiple
+pages, or if you know for certain the table will run to several
+pages, do not use the <b>FLOAT</b> macro. Instead, invoke
+<kbd>.TS</kbd> with the <kbd>H</kbd> argument, enter any
+<kbd>tbl</kbd> global options (per <kbd>man(1) tbl</kbd>), and
+follow the last line of the global options, which terminates with
+a period, with text for the table header. Afterwards, invoke the
+macro, <kbd>.TH</kbd>, then begin entering table data, as in the
+following:
+<br/>
+<span class="pre-in-pp">
+ .TS H
+ allbox center;
+ c s s
+ c c c
+ n n n.
+ AT&T Common Stock
+ .TH
+ <tbl commands and data>
+ .TE
+</span>
+In the example, “AT&T Common Stock” will be the
+table’s header, printed at the start of the table and at the
+top of the table on all subsequent pages.
+</p>
+
<h2 id="floats-intro" class="docs">Introduction to floats</h2>
<p>
@@ -510,31 +626,6 @@
</p>
</div>
-<h4 id="tbl-with-float" class="docs">Using tbl with FLOAT</h4>
-
-<p>
-Unboxed tables created with <strong>tbl</strong> (see <kbd>man
-tbl(1)</kbd>) may be put in a float with the usual start and end
-macros, <kbd>.TS</kbd> and <kbd>.TE</kbd>.
-</p>
-
-<p>
-Boxed tables don’t play nice with FLOAT, and require that you
-pass the argument <kbd>BOXED</kbd> to <kbd>.TS</kbd>, otherwise mom
-cannot guarantee the vertical spacing of the float will be
-<a href="#float-spacing">as described</a>.
-<br/>
-<span class="pre-in-pp">
- .FLOAT
- .TS BOXED
- <tbl commands>
- .TE
- .FLOAT OFF
-</span>
-You may put text (or anything else you like) above or below the
-table; mom will ensure the float is spaced correctly.
-</p>
-
<div class="rule-long"><hr/></div>
<!-- Navigation links -->
Index: toc.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/toc.html,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -b -r1.45 -r1.46
--- toc.html 24 Aug 2013 22:27:59 -0000 1.45
+++ toc.html 17 Sep 2013 16:20:18 -0000 1.46
@@ -98,7 +98,7 @@
<li><a href="#prelim">Preliminary document setup</a></li>
<li><a href="#typemacdoc">Behaviour of the typesetting macros during
document processing</a></li>
<li><a href="#tags">The document element tags</a> – headings,
paragraphs, quotes, footnotes, etc.</li>
- <li><a href="#images">Graphics and floats</a></li>
+ <li><a href="#images">Graphics, tbl support, and floats</a></li>
<li><a href="#hdrftr">Page headers and footers</a></li>
<li><a href="#paginate">Pagination</a></li>
<li><a href="#rv">Recto/verso printing and collating</a></li>
@@ -346,7 +346,16 @@
<li><a href="docelement.html#margin-notes-intro">5.4.13 Margin
notes</a></li>
<li><a href="docelement.html#finis-intro">5.4.14 Document
termination string</a> – FINIS</li>
</ul></li>
- <li><a id="images" class="highlight" href="images.html#top">5.5 GRAPHICS
AND FLOATS</a></li>
+ <li><a id="images" class="highlight" href="images.html#top">5.5
GRAPHICS, tbl SUPPORT, AND FLOATS</a>
+ <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#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 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>
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Groff-commit] groff/contrib/mom/momdoc images.html toc.html,
Peter Schaffter <=