contrib/mom/momdoc/images.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004, 2005, 2006, 2009, 2010,
   6 2011, 2012, 2013 Free Software Foundation, Inc.
   7 Written by Peter Schaffter (peter@schaffter.ca).
   8
   9 Permission is granted to copy, distribute and/or modify this document
  10 under the terms of the GNU Free Documentation License, Version 1.3 or
  11 any later version published by the Free Software Foundation; with the
  12 Invariant Sections being this comment section, with no Front-Cover
  13 Texts, and with no Back-Cover Texts.
  14
  15 A copy of the Free Documentation License is included as a file called
  16 FDL in the main directory of the groff source package.
  17 -->
  18
  19 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  20 <html xmlns="http://www.w3.org/1999/xhtml">
  21
  22 <head>
  23   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  24   <title>Mom -- Graphics and floats</title>
  25   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  26 </head>
  27
  28 <body style="background-color: #f5faff;">
  29
  30 <!-- ==================================================================== -->
  31
  32 <div id="top" class="page">
  33
  34 <!-- Navigation links -->
  35 <table style="width: 100%;">
  36 <tr>
  37   <td><a href="toc.html">Back to Table of Contents</a></td>
  38   <td style="text-align: right;"><a href="headfootpage.html#top">Next: Page headers/footers, pagination</a></td>
  39 </tr>
  40 </table>
  41
  42 <h1 class="docs">Graphics and floats</h1>
  43
  44 <div style="width: 55%; margin: auto;">
  45 <ul class="no-enumerator" style="margin-left: -1em;">
  46   <li><a href="#images-intro">Introduction to inserting images and graphics</a>
  47   <li><a href="#converting">Image conversion and file processing</a>
  48   <ul style="margin-left: -.5em; list-style-type: disc;">
  49     <li><a href="#pdf">PDF</a></li>
  50     <li><a href="#eps">EPS</a></li>
  51   </ul></li>
  52   <li><a href="#pdf-image">The PDF_IMAGE macro</a></li>
  53   <li><a href="#pspic">The PSPIC macro</a></li>
  54   <li><a href="#floats-intro">Introduction to floats</a></li>
  55   <li><a href="#float">The FLOAT macro</a>
  56   <ul style="margin-left: -.5em; list-style-type: disc;">
  57                 <li><a href="#tbl-with-float">Using tbl with FLOAT</a></li>
  58         </ul></li>
  59 </ul>
  60 </div>
  61
  62 <div class="rule-medium"><hr/></div>
  63
  64 <h2 id="images-intro" class="docs">Introduction to inserting images and graphics</h2>
  65
  66 <p>
  67 In order to include images in mom documents, the images must be in
  68 either PDF (.pdf) or EPS (.eps) format.  Each format requires its own
  69 macro, but both take the same arguments, and in the same order.
  70 </p>
  71
  72 <p>
  73 Please note that there are differences in the way the files
  74 containing PDF and EPS images must be processed, hence documents may
  75 not contain a mix.
  76 </p>
  77
  78 <h3 id=converting class="docs">Image conversion and file processing</h3>
  79
  80 <p>
  81 When your image files are not in PDF or EPS format&mdash;jpgs,
  82 for example&mdash;you must convert them before including them in
  83 a mom document.  Any utility for converting images may used.  The
  84 ImageMagick suite of programmes, present on most GNU/Linux
  85 systems, contains <b>convert</b>, which is simple and effective.
  86 </p>
  87
  88 <h4 id="pdf" class="docs">PDF</h4>
  89
  90 <p>
  91 Assuming a jpg image, conversion to PDF is done like this:
  92 <br/>
  93 <span class="pre-in-pp">
  94   convert &lt;image&gt;.jpg &lt;image&gt;.pdf
  95 </span>
  96 Any image type supported by <b>convert</b> may be converted this
  97 way.
  98 </p>
  99
 100 <p>
 101 Mom files containing PDF images must be processed using
 102 groff&#8217;s pdf driver.  Use of
 103 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
 104 is strongly recommended, which natively invokes the pdf driver.
 105 <br/>
 106 <span class="pre-in-pp">
 107   pdfmom doc.mom &gt; doc.pdf
 108 </span>
 109 </p>
 110
 111 <h4 id="eps" class="docs">EPS</h4>
 112
 113 <p>
 114 Assuming a jpg image, conversion to EPS is done like this:
 115 <br/>
 116 <span class="pre-in-pp">
 117   convert &lt;image&gt;.jpg &lt;image&gt;.eps
 118 </span>
 119 Any image type supported by <b>convert</b> may be converted this
 120 way.  There have been reports of trouble with PostScript level 2
 121 images, so don&#8217;t save your images in this format.
 122 </p>
 123
 124 <p>
 125 Mom files containing EPS images must be processed using
 126 groff&#8217;s postscript driver.  Use of
 127 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
 128 which can be told to use the postscript driver, is strongly
 129 recommended.
 130 <br/>
 131 <span class="pre-in-pp">
 132   pdfmom -Tps doc.mom &gt; doc.pdf
 133 </span>
 134 </p>
 135
 136 <!-- -PDF_IMAGE- -->
 137
 138 <div class="macro-id-overline">
 139 <h3 id="pdf-image" class= "macro-id">PDF_IMAGE</h3>
 140 </div>
 141
 142 <div class="box-macro-args">
 143 Macro: <b>PDF_IMAGE</b> <kbd class="macro-args">[ -L | -C | -R | -I &lt;indent&gt; ] \
 144 <br/>
 145 &lt;pdf image&gt; &lt;width&gt; &lt;height&gt; \
 146 <br/>
 147 [ SCALE &lt;factor&gt; ] [ ADJUST +|-&lt;vertical adjustment&gt; ]</kbd>
 148 </div>
 149 <p class="requires">
 150 &bull;&nbsp;<span style="font-style: normal">
 151 <kbd>&lt;indent&gt;</kbd>,
 152 <kbd>&lt;width&gt;</kbd>,
 153 <kbd>&lt;height&gt;</kbd></span>
 154 and
 155 <span style="font-style: normal">
 156 <kbd>&lt;vertical adjustment&gt;</kbd></span>
 157 require a
 158 <a href="definitions.html#unitofmeasure">unit of measure</a>
 159 </p>
 160
 161 <p>
 162 Unlike
 163 <a href="#pspic">PSPIC</a>,
 164 which it resembles, PDF_IMAGE requires that the pdf image&#8217;s
 165 dimensions (the bounding box,
 166 <a href="#bounding-box">see below</a>)
 167 be supplied each time it&#8217;s called.
 168 </p>
 169
 170 <p>
 171 The first optional argument tells mom how to align the image
 172 horizontally, with <kbd>-L</kbd>, <kbd>-C</kbd>, and <kbd>-R</kbd>
 173 standing for left, centre and right respectively.  If you need more
 174 precise placement, the <kbd>-I</kbd> argument allows you to give an
 175 indent from the left margin.  Thus, to indent a PDF image 6
 176 <a href="definitions.html#picaspoints">picas</a>
 177 from the left margin
 178 <br/>
 179 <span class="pre-in-pp">
 180   .PDF_IMAGE -I 6P &lt;remaining arguments&gt;
 181 </span>
 182 If you omit the first argument, the image will be centred.
 183 </p>
 184
 185 <p>
 186 <kbd>&lt;pdf image&gt;</kbd> must be in PDF format, with a .pdf
 187 extension.  If it is not, mom will abort with a message.  See <a
 188 href="#pdf">here</a> for instructions on converting image formats to
 189 PDF.
 190 </p>
 191
 192 <p id="bounding-box">
 193 <kbd>&lt;width&gt;</kbd> and <kbd>&lt;height&gt;</kbd> are the
 194 dimensions of the image&#8217;s bounding box.  The most reliable way
 195 of getting the bounding box is with the utility, <strong>pdfinfo</strong>:
 196 <br/>
 197 <span class="pre-in-pp">
 198   pdfinfo &lt;image.pdf&gt; | grep "Page *size"
 199 </span>
 200 This will spit out a line that looks like this:
 201 <br/>
 202 <span class="pre-in-pp">
 203   Page size:      width x height pts
 204 </span>
 205 <kbd>pts</kbd> means
 206 <a href="definitions.html#picaspoints">points</a>,
 207 therefore the unit of measure appended to <kbd>&lt;width&gt;</kbd>
 208 and <kbd>&lt;height&gt;</kbd> must be <kbd>p</kbd>.
 209 </p>
 210
 211 <p>
 212 The optional <kbd>SCALE</kbd> argument allows you to scale the image
 213 by <kbd>&lt;factor&gt;</kbd>.  The factor is a percentage of the
 214 image&#8217;s original dimensions, thus
 215 <br/>
 216 <span class="pre-in-pp">
 217  SCALE 50
 218 </span>
 219 scales the image to 50 percent of its original size.  No percent
 220 sign or unit of measure should be appended.
 221 </p>
 222
 223 <p>
 224 The final optional argument is the vertical adjustment to apply to
 225 the image.  A plus value raises the image
 226 <span style="font-style: italic">within the space allotted for it</span>;
 227 a negative value lowers it.  The value must have a unit of measure
 228 appended.
 229 </p>
 230
 231 <p>
 232 Remember that mom files with embedded PDF images must be processed
 233 with
 234 <br/>
 235 <span class="pre-in-pp">
 236  pdfmom doc.mom &gt; doc.pdf
 237 </span>
 238 </p>
 239
 240 <div class="box-tip">
 241 <p class="tip-top">
 242 <span class="note">Note:</span>
 243 Mom automatically applies shimming after PDF_IMAGE.  See
 244 <a href="docprocessing.html#shim">SHIM</a>
 245 for a discussion of shimming, and how to disable it.
 246 <p>
 247
 248 <p>
 249 <span class="note">Additional note:</span>
 250 Mom treats single, discrete images inserted into a document with
 251 PDF_IMAGE somewhat like
 252 <a href="#floats-intro">floats</a>,
 253 which is to say that if an image doesn&#8217;t fit on the output
 254 page, she will defer it to the top of the next page while continuing
 255 to process
 256 <a href="definitions.html#running">running text</a>.
 257 <kbd>ADJUST</kbd> is ignored whenever an image is deferred, and a
 258 message is printed to stderr advising you where the deferment has
 259 taken place.
 260 </p>
 261
 262 <p class="tip-bottom">
 263 However, if more than one image does not fit on the output page,
 264 mom defers only the first; the remainder are silently ignored.
 265 Therefore, if you insert several images close together in the text,
 266 it is highly recommended that you wrap the images in floats, which
 267 do not have this restriction.
 268 </p>
 269 </div>
 270
 271 <!-- -PSPIC- -->
 272
 273 <div class="macro-id-overline">
 274 <h3 id="pspic" class= "macro-id">PSPIC</h3>
 275 </div>
 276
 277 <div class="box-macro-args">
 278 Macro: <b>PSPIC</b> <kbd class="macro-args">[ -L | -R | -I &lt;n&gt; ] &lt;file&gt; [ width [ height ] ]</kbd>
 279 </div>
 280
 281 <p>
 282 PSPIC is not actually part of mom, but rather a macro included with
 283 every groff installation.  Although its arguments are identical to
 284 PDF_IMAGE (except for <kbd>SCALE</kbd> and <kbd>ADJUST</kbd>, which
 285 are missing), its behaviour is slightly different.
 286 </p>
 287
 288 <p>
 289 <kbd>man groff_tmac</kbd> contains the documentation for PSPIC, but
 290 I&#8217;ll repeat it here with a few modifications for clarity.
 291 </p>
 292
 293 <div class="examples-container">
 294 <h3 id="groff-tmac" class="docs" style="margin-top: .5em;">From <span style="text-transform: none">groff_tmac</span></h3>
 295 <p style="margin-top: .5em; margin-bottom: .5em;">
 296 <kbd>&lt;file&gt;</kbd> is the name of the file containing the
 297 image; <kbd>width</kbd> and <kbd>height</kbd> give the desired
 298 width and height of the image as you wish it to appear within the
 299 document.  The width and height arguments may have
 300 <a href="definitions.html#unitofmeasure">units of measure</a>
 301 attached; the default unit of measure is
 302 <kbd>i</kbd>.  PSPIC will scale the graphic
 303 uniformly in the x and y directions so that it is no more than
 304 <kbd>width</kbd> wide and <kbd>height</kbd> high.  By default, the
 305 graphic will be horizontally centred.  The <kbd>-L</kbd> and
 306 <kbd>-R</kbd> options cause the graphic to be left-aligned and
 307 right-aligned, respectively.  The <kbd>-I</kbd> option causes
 308 the graphic to be indented by <kbd>&lt;n&gt;</kbd>;  the default unit of
 309 measure is <kbd>m</kbd>
 310 (<a href="definitions.html#em">ems</a>).
 311 </p>
 312 </div>
 313
 314 <p>
 315 It is not necessary to pass PSPIC the
 316 <kbd>&lt;width&gt;</kbd> and <kbd>&lt;height&gt;</kbd> arguments unless
 317 you are scaling the image, in which case you will most likely need
 318 the original dimensions of the EPS image&#8217;s bounding box.
 319 These can be found with
 320 <span class="pre-in-pp">
 321  gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox &lt;image file&gt;.pdf 2&gt;&amp;1 \
 322  | grep "%%BoundingBox" | cut -d " " -f4,5
 323 </span>
 324 The two digits returned are in
 325 <a href="definitions.html#picaspoints">points</a>,
 326 therefore the
 327 <a href="definitions.html#unitofmeasure">unit of measure</a>
 328 <kbd>p</kbd> must be appended to them.
 329 </p>
 330
 331 <p>
 332 Because PSPIC lacks the <kbd>ADJUST</kbd> option offered by
 333 <a href="#pdf-image">PDF_IMAGE</a>
 334 a certain amount of manual tweaking of the vertical placement of the
 335 image will probably be required, typically by using the
 336 <a href="typesetting.html#ald">ALD</a>
 337 and
 338 <a href="typesetting.html#rld">RLD</a>
 339 macros.
 340 </p>
 341
 342 <p>
 343 Additionally, EPS images inserted into
 344 <a href="definitions.html#running">running text</a>
 345 will almost certainly disrupt the baseline placement of running
 346 text.  In order to get mom back on track after
 347 invoking <kbd>.PSPIC</kbd>, I strongly recommend using the
 348 <a href="docprocessing.html#shim">SHIM</a>
 349 macro so that the bottom margin of running text falls where it
 350 should.  Please note that with PDF_IMAGE, this is not necessary.
 351 </p>
 352
 353 <p>
 354 Remember that mom files with embedded EPS images must be processed
 355 with
 356 <br/>
 357 <span class="pre-in-pp">
 358  pdfmom -Tps doc.mom &gt; doc.pdf
 359 </span>
 360 </p>
 361
 362 <div class="rule-medium"><hr/></div>
 363
 364 <h2 id="floats-intro" class="docs">Introduction to floats</h2>
 365
 366 <p>
 367 Images and graphics (including those created with
 368 <strong>tbl</strong> and <strong>pic</strong>) sometimes do not
 369 fit on the output page of a PDF or PostScript document at the
 370 place they&#8217;re inserted in the input file.  It&#8217;s
 371 necessary, therefore, to defer them to the next page while carrying
 372 on with
 373 <a href="definitions.html#running">running text</a>.
 374 </p>
 375
 376 <p>
 377 Whenever you need this functionality (tables, for example, generally
 378 need only appear near related text, not at a precise location), mom
 379 provides the FLOAT macro.
 380 </p>
 381
 382 <p>
 383 Floats are usually used for images and graphics, but can contain
 384 anything you like, including text.  Whatever&#8217;s in the
 385 float will be kept together as a block, output immediately if
 386 there&#8217;s room, or deferred to the top of the next output page
 387 when there isn&#8217;t; running text continues to the bottom of the
 388 previous page without interruption.
 389 </p>
 390
 391 <p>
 392 In the case of a float that doesn&#8217;t fit being followed by
 393 one that does, the second is output in position and the first is
 394 deferred.  In the case of two or more that don&#8217;t fit, they are
 395 output in order on the next page.
 396 </p>
 397
 398 <p>
 399 A key distinction between a float and a
 400 <a href="docelement.html#quote">QUOTE</a>
 401 or
 402 <a href="docelement.html#blockquote">BLOCKQUOTE</a>
 403 is that while a float keeps everything together and defers output if
 404 necessary, quotes and blockquotes are output immediately, and may
 405 start on one page and finish on the next.
 406 </p>
 407
 408 <p>
 409 Floats always deposit a break before they begin, which means the
 410 line beforehand will not be
 411 <a href="definitions.html#filled">filled</a>.
 412 Floats, therefore, cannot be inserted in the middle of a paragraph
 413 without studying the output file and determining where to break or
 414 <a href="typesetting.html#spread">spread</a>
 415 the line before the float.
 416 </p>
 417
 418 <p id="float-spacing">
 419 Floats begin on the baseline immediately below the running text
 420 preceding them.  No additional whitespace surrounds them, above or
 421 below.  Running text below a float is, however,
 422 <a href="docprocessing.html#shim">shimmed</a>,
 423 unless shimming has been disabled with <kbd>.NO_SHIM</kbd>.  This
 424 usually results in a small amount of extra whitespace after the
 425 float.  The <kbd>ADJUST</kbd> argument to FLOAT allows you to
 426 fine-tune the vertical centering.
 427 </p>
 428
 429 <p>
 430 If you&#8217;d like more space around a float, you must add it
 431 manually, for example with
 432 <a href="typesetting.html#ald">ALD</a>
 433 or
 434 <a href="typesetting.html#space">SPACE</a>.
 435 </p>
 436
 437 <!-- -FLOAT- -->
 438
 439 <div class="macro-id-overline">
 440 <h3 id="float" class= "macro-id">FLOAT</h3>
 441 </div>
 442
 443 <div class="box-macro-args">
 444 Macro: <b>FLOAT</b> <kbd class="macro-args">[ FORCE ] [ ADJUST +|-&lt;amount&gt; ] | &lt;anything&gt;</kbd>
 445 </div>
 446
 447 <div class="box-tip">
 448 <p class="tip">
 449 <span class="note">Note:</span>
 450 FLOAT is intended for use with the document processing macros only.
 451 </p>
 452 </div>
 453
 454 <p style="margin-top: -.5em">
 455 To begin a float, simply invoke <kbd>.FLOAT</kbd> and follow it with
 456 whatever you want the float to contain.  When you&#8217;re done,
 457 invoke <kbd>.FLOAT&nbsp;OFF</kbd> (or <kbd>QUIT, END, X</kbd>, etc).
 458 </p>
 459
 460 <p>
 461 The optional <kbd>FORCE</kbd> argument instructs mom to output
 462 the float exactly where it occurs in the input file.  With
 463 <kbd>FORCE</kbd>, mom immediately breaks to a new page to output
 464 the float if it does not fit on the current page.  While this is
 465 somewhat contrary to the notion of floats (ie that running text
 466 should continue to fill the page), there are circumstances where it
 467 may be desirable.
 468 </p>
 469
 470 <p>
 471 The <kbd>ADJUST</kbd> argument tells mom to raise
 472 (<kbd>+</kbd>) or lower (<kbd>-</kbd>) the float <i>within the space
 473 allotted to it</i> by the specified amount.
 474 <kbd>&lt;amount&gt;</kbd> must have a
 475 <a href="definitions.html#unitofmeasure">unit of measure</a>
 476 appended.  <kbd>ADJUST</kbd> gives you precise control over
 477 the vertical centering of floats, allowing you to compensate for
 478 unequal spacing that may result of from the automatic shimming of
 479 floats (or the absence thereof).  See
 480 <a href="docprocessing.html#shim">SHIM</a>
 481 for a discussion of automatic shimming.
 482 </p>
 483
 484 <p>
 485 <kbd>ADJUST</kbd> is ignored whenever a float is deferred to
 486 the following page.
 487 </p>
 488
 489 <div class="box-tip">
 490 <p class="tip-top">
 491 <span class="note">Note:</span>
 492 Floats use
 493 <a href="definitions.html#filled">no-fill mode</a>,
 494 with each input line beginning at the left margin.  If this is not
 495 what you want, you must specify the preferred horizontal alignment
 496 <i>within the float</i> (eg
 497 <a href="typesetting.html#lrc">CENTER</a>
 498 or
 499 <a href="typesetting.html#lrc">RIGHT</a>).
 500 </p>
 501
 502 <p class="tip-bottom">
 503 Furthermore, if you want text
 504 <a href="definitions.html#filled">filled</a>,
 505 you must specify
 506 <a href="typesetting.html#quad"><kbd>.QUAD&nbsp;L|R|C</kbd></a>
 507 or
 508 <a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a>&mdash;again,
 509 within the float.
 510 </p>
 511 </div>
 512
 513 <h4 id="tbl-with-float" class="docs">Using tbl with FLOAT</h4>
 514
 515 <p>
 516 Unboxed tables created with <strong>tbl</strong> (see <kbd>man
 517 tbl(1)</kbd>) may be put in a float with the usual start and end
 518 macros, <kbd>.TS</kbd> and <kbd>.TE</kbd>.
 519 </p>
 520
 521 <p>
 522 Boxed tables don&#8217;t play nice with FLOAT, and require that you
 523 pass the argument <kbd>BOXED</kbd> to <kbd>.TS</kbd>, otherwise mom
 524 cannot guarantee the vertical spacing of the float will be
 525 <a href="#float-spacing">as described</a>.
 526 <br/>
 527 <span class="pre-in-pp">
 528   .FLOAT
 529   .TS BOXED
 530   &lt;tbl commands&gt;
 531   .TE
 532   .FLOAT OFF
 533 </span>
 534 You may put text (or anything else you like) above or below the
 535 table; mom will ensure the float is spaced correctly.
 536 </p>
 537
 538 <div class="rule-long"><hr/></div>
 539
 540 <!-- Navigation links -->
 541 <table style="width: 100%; margin-top: 12px;">
 542 <tr>
 543   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 544   <td style="width: 20%; text-align: center;"><a href="#top">Top</a></td>
 545   <td style="width: 46%; text-align: right;"><a href="headfootpage.html">Next: Page headers/footers, pagination</a></td>
 546 </tr>
 547 </table>
 548
 549 </div>
 550
 551 <div class="bottom-spacer"><br/></div>
 552
 553 </body>
 554 </html>
 555 <!-- vim: fileencoding=utf-8: nomodified: -->