diff options
Diffstat (limited to 'contrib/mom/momdoc/graphical.html')
| -rw-r--r-- | contrib/mom/momdoc/graphical.html | 593 |
1 files changed, 0 insertions, 593 deletions
diff --git a/contrib/mom/momdoc/graphical.html b/contrib/mom/momdoc/graphical.html deleted file mode 100644 index 1f57b1c5..00000000 --- a/contrib/mom/momdoc/graphical.html +++ /dev/null @@ -1,593 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- -This file is part of groff, the GNU roff type-setting system. - -Copyright (C) 2004, 2005, 2006, 2009 Free Software Foundation, Inc. -Written by Peter Schaffter. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being this comment section, with no Front-Cover -Texts, and with no Back-Cover Texts. - -A copy of the Free Documentation License is included as a file called -FDL in the main directory of the groff source package. ---> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> -<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"/> -<title>Mom -- Graphical Objects</title> -</head> -<body bgcolor="#dfdfdf"> - -<!-- ==================================================================== --> - -<a name="TOP"></a> - -<p> -<a href="docprocessing.html#TOP">Next</a> -<a href="color.html#TOP">Prev</a> -<a href="toc.html">Back to Table of Contents</a> -</p> - -<h1 align="center"><a name="COLOR_INTRO"><u>Graphical objects</u></a></h1> - -<p> -<a href="#INTRO_GRAPHICAL">Introduction to graphical objects</a> - -<ul> - <li><a href="#BEHAVIOUR">Graphical object behaviour</a></li> - <li><a href="#ORDER">Order of arguments</a></li> -</ul> - -<a href="#MACROS_GRAPHICAL">Index of graphical object macros</a> -</p> - -<a name="INTRO_GRAPHICAL"><h2><u>Introduction to graphical objects</u></h2></a> - -<p> -<strong>Groff</strong> has a number of -<a href="definitions.html#TERMS_INLINES">inline escapes</a> -for drawing rules, polygons, ellipses and splines. All begin with -<kbd>\D</kbd> (presumably for "Draw") and are documented -in the <strong>groff</strong> info manual: - -<pre> - info groff => Escape index => \D -</pre> -</p> - -<p> -The escapes allow you to draw just about any simple graphical object -you can think of, but owing to their syntax, they're not always easy -to read, which can make tweaking them difficult. Additionally, -while they perform in a <em>consistent</em> manner, they don't -always perform in an <em>expected</em> manner. -</p> - -<p> -Experience shows that the most common graphical elements typesetters -need are rules (horizontal and vertical), boxes, and circles (or -ellipses). For this reason, <strong>mom</strong> provides macros -to draw these objects in an easy-to-understand way; the results are -predictable, and <strong>mom</strong>'s syntax makes fixes or tweaks -painless. -</p> - -<a name="GRAPHICAL_EXAMPLE"></a> - -<p> -For example, if you want to draw a 2-inch square outline box at the left -margin using <strong>groff</strong>'s <kbd>\D</kbd> escapes, it looks like this: - -<pre> - back up - by - weight - +-------+ - | | - \D't 500'\h'-500u'\D'p 2i 0 0 2i -2i 0 0 -2i' - | | | | - +-------+ +------------------------+ - set rule draw box, 1 line at a time - weight -</pre> - -Obviously, this isn't very efficient for something as simple as a -box. -</p> - -<p> -Here's the same box, drawn with <strong>mom</strong>'s box drawing -macro, -<a href="#DBX">DBX</a>: - -<pre> -left margin indent-+ +-box width - | | - .DBX .5 0 2i 2i - | | - rule weight--+ +-box depth - (in points) -</pre> -</p> - -<p> -<strong>Mom</strong>'s graphical object macros allow — in fact, -require — giving the rule weight ("thickness") for the -object (or saying that you want it filled), an indent from the left -margin where the object begins, the dimensions of the object, and -optionally a colour for the object. -</p> - -<p> -There are no defaults for the arguments to <strong>mom</strong>'a -graphical object macros, which means you must supply the arguments -every time you invoke them. -</p> - -<p> -<strong>NOTE:</strong> As stated above, <strong>mom</strong> only -provides macros for commonly-used graphical objects (rules, boxes, -circles) only. More complex objects (polygons, non-straight lines, -splines) must be drawn using <strong>groff</strong>'s <kbd>\D</kbd> -escapes. -</p> - -<a name="BEHAVIOUR"><h3><u>Graphical object behaviour</u></h3></a> - -<p> -<strong>Mom</strong>'s graphical object macros all behave in the -following, carved-in-stone ways: - -<ol> - <li>Objects are drawn from the - <a href="definitions.html#TERMS_BASELINE">baseline</a> - down, including horizontal rules.</li> - <li>Objects begin precisely at the left indent supplied as - an argument to the macro.</li> - <li>Objects are drawn from left to right.</li> - <li>Enclosed objects (boxes, circles) are drawn from the - perimeter <em>inward</em>.</li> - <li>Objects return to their horizontal/vertical point of origin.</li> -</ol> - -The consistency means that once you've mastered the very simple -order of arguments that applies to invoking graphical object -macros, you can draw objects with full confidence that you know -exactly where they're placed and how much room they occupy. -Furthermore, because all return to their point of origin, you'll -know exactly where you are on the page. -</p> - -<a name="ORDER"><h3><u>Order of arguments</u></h3></a> - -<p> -The order of arguments to the graphical object macros is the same -for every macro: - -<ul> - <li>the <strong>Weight</strong> of the rule</li> - <ul> - <li>if the object is enclosed (i.e. is a box or circle), the - weight of the rule if you want the object outlined</li> - <li>the single word <kbd>SOLID</kbd> may be used in place - of the <strong>weight</strong> argument if you want the - object filled</li> - </ul> - <li>the <strong>Indent</strong> from the current left margin at - which to begin the object</li> - <li>the <strong>Length</strong> of the object, if applicable</li> - <li>the <strong>Depth</strong> of the object, if applicable</li> - <li>the <strong>Colour</strong> of the object (optional)</li> -</ul> -</p> - -<p> -A simple mnemonic for the order of arguments is "WILD C". -If you fix the mnemonic in your brain and apply a little judicious -reasoning, you'll always remember how to draw graphical objects. -The "judicious reasoning" means that, for example, -horizontal rules don't require a depth and vertical rules don't -require a length. Thus, in the case of drawing a horizontal rule, -you supply the macro, -<a href="#DRH">DRH</a>, -with only the arguments (from the mnemonic) that apply: W-I-L (and -possibly C). -</p> - -<a name="MACROS_GRAPHICAL"><h3><u>Index of graphical object macros</u></h3></a> - -<ul> - <li><a href="#DRH">DRH</a> - — horizontal rule</li> - <li><a href="#DRV">DRV</a> - — vertical rule</li> - <li><a href="#DBX">DBX</a> - — box</li> - <li><a href="#DCL">DCL</a> - — circle or ellipse</li> -</ul> - -<!-- -DRH- --> - -<hr width="66%" align="left"/> - -<a name="DRH"><h3><u>Drawing horizontal rules</u></h3></a> - -<p> -<nobr>Macro: <strong>DRH</strong> <kbd><none> | <rule weight> <indent> <length> [<colour>]</kbd></nobr> -<br/> - -<em>*The argument to</em> <kbd><rule weight></kbd> <em>is -in</em> -<a href="definitions.html#TERMS_PICASPOINTS">points</a>, -<em>but do </em> NOT <em>append the</em> -<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of -measure</a>, <kbd>p</kbd>. -<br/> - -<em>*The arguments,</em> <kbd><indent></kbd> <em>and</em> -<kbd><length></kbd>, <em>require a unit of measure.</em> -</p> - -<p> -If all you want is to draw a rule from your current left -margin to your current right margin (in other words, a "full -measure" rule), you may invoke <kbd>.DRH</kbd> without any -arguments. (Note that <strong>DRH</strong> is the only graphical -object macro that may be invoked without arguments.) The weight of -the rule is determined by the argument you last gave the macro, -<a href="inlines.html#RULE_WEIGHT">RULE_WEIGHT</a>. -<strong>DRH</strong>, used this way, is exactly equivalent to -entering the -<a href="definitions.html#TERMS_INLINES">inline escape</a>, -<a href="inlines.html#INLINE_RULE_MOM"><kbd>\*[RULE]</kbd></a>. -</p> - -<p> -To draw horizontal rules of a specified length, you must, at a -minimum, supply -<strong>DRH</strong> with the arguments -<kbd><nobr>rule weight,</nobr> indent</kbd> (measured from the -current left margin) and <kbd>length</kbd>. -</p> - -<p> -Optionally, you may give a <kbd>colour</kbd> argument. -The colour may be either one defined with -<a href="color.html#NEWCOLOR">NEWCOLOR</a>, -or a named X-colour inititialized with -<a href="color.html#XCOLOR">XCOLOR</a>, -or an X-colour alias (again, initialized with -<strong>XCOLOR</strong>). -</p> - -<p> -Say, for example, you want to draw a 1-1/4 point horizontal rule -that starts 2 picas from the current left margin and runs for 3 -inches. To do so, you'd invoke <kbd>.DRH</kbd> like this: - -<pre> - weight length - | | - .DRH 1.125 2P 3i - | - indent -</pre> - -(Note that the rule weight argument, which is expressed in points, -must NOT have the unit of measure <kbd>p</kbd> appended to it.) -</p> - -<p> -If, in addition, you want the rule blue: - -<pre> - .DRH 1.125 2P 3i blue -</pre> -</p> - -<h3><u>How mom handles the positioning of horizontal rules</u></h3> - -<p> -Horizontal rules are drawn from left to right, and from the baseline -down. "From the baseline down" means that if you request -a rule with a weight of four points, the four points of rule fall -entirely below the baseline. -</p> - -<p> -Furthermore, after the rule is drawn, <strong>mom</strong> returns -you to the current left margin, at the same vertical position on -the page as when <strong>DRH</strong> was invoked. In other words, -<strong>DRH</strong> causes no movement on the page, either -horizontal or vertical. -</p> - -<!-- -DRV- --> - -<hr width="33%" align="left"/> - -<a name="DRV"><h3><u>Drawing vertical rules</u></h3></a> - -<p> -<nobr>Macro: <strong>DRV</strong> <kbd><rule weight> <indent> <depth> [<colour>]</kbd></nobr> -<br/> - -<em>*The argument to</em> <kbd><rule weight></kbd> <em>is -in</em> -<a href="definitions.html#TERMS_PICASPOINTS">points</a>, -<em>but do </em> NOT <em>append the</em> -<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of -measure</a>, <kbd>p</kbd>. -<br/> - -<em>*The arguments,</em> <kbd><indent></kbd> <em>and</em> -<kbd><depth></kbd>, <em>require a unit of measure.</em> -</p> - -<p> -To draw vertical rules of a specified length, you must, at a -minimum, supply -<strong>DRV</strong> with the arguments -<kbd><nobr>rule weight,</nobr> indent</kbd> (measured from the -current left margin) and <kbd>depth</kbd>. -</p> - -<p> -Optionally, you may give a <kbd>colour</kbd> argument. -The colour may be either one defined with -<a href="color.html#NEWCOLOR">NEWCOLOR</a>, -or a named X-colour inititialized with -<a href="color.html#XCOLOR">XCOLOR</a>, -or an X-colour alias (again, initialized with -<strong>XCOLOR</strong>). -</p> - -<p> -Say, for example, you want to draw a 3/4-point vertical rule that -starts 19-1/2 picas from the current left margin and has a depth of -6 centimeters. To do so, you'd invoke <kbd>.DRV</kbd> like this: - -<pre> - weight depth - | | - .DRV .75 19P+6p 6c - | - indent -</pre> - -(Note that the rule weight argument, which is expressed in points, -must NOT have the unit of measure <kbd>p</kbd> appended to it.) -</p> - -<p> -If, in addition, you want the rule red: - -<pre> - .DRV .75 19P+6p 6c red -</pre> -</p> - -<h3><u>How mom handles the positioning of vertical rules</u></h3> - -<p> -Vertical rules are drawn from the baseline down, and from left to -right. "Left to right" means that if you request a rule -with a weight of four points, the four points of rule fall entirely -to the left of the indent given to <strong>DRV</strong>. -</p> - -<p> -Furthermore, after the rule is drawn, <strong>mom</strong> returns -you to the current left margin, at the same vertical position -on the page as when <strong>DRV</strong> was invoked. In other -words, <strong>DRV</strong> causes no movement on the page, either -horizontal or vertical. -</p> - -<!-- -DBX- --> - -<hr width="33%" align="left"/> - -<a name="DBX"><h3><u>Drawing boxes</u></h3></a> - -<p> -<nobr>Macro: <strong>DBX</strong> <kbd>< <rule weight> | SOLID > <indent> <length> <depth> [<colour>]</kbd></nobr> -<br/> - -<em>*The argument to</em> <kbd><rule weight></kbd> <em>is -in</em> -<a href="definitions.html#TERMS_PICASPOINTS">points</a>, -<em>but do </em> NOT <em>append the</em> -<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of -measure</a>, <kbd>p</kbd>. -<br/> - -<em>*The arguments,</em> <kbd><indent></kbd><em>,</em> -<kbd><length></kbd> <em>and</em> <kbd><depth></kbd> -<em>require a unit of measure.</em> -</p> - -<p> -To draw boxes of specified dimensions, you must, at a minimum, -supply <strong>DBX</strong> with the arguments <kbd><nobr>rule -weight</nobr></kbd> or <kbd>SOLID</kbd>, <kbd>indent</kbd> -(measured from the current left margin), <kbd>length</kbd> and -<kbd>depth</kbd>. -</p> - -<p> -Optionally, you may give a <kbd>colour</kbd> argument. -The colour may be either one defined with -<a href="color.html#NEWCOLOR">NEWCOLOR</a>, -or a named X-colour inititialized with -<a href="color.html#XCOLOR">XCOLOR</a>, -or an X-colour alias (again, initialized with -<strong>XCOLOR</strong>). -</p> - -<p> -Say, for example, you want to draw a 1/2 point outline box that -starts one inch from the current left margin and has the dimensions -12 picas x 6 picas. To do so, you'd invoke <kbd>.DBX</kbd> like this: - -<pre> - indent depth - | | - .DBX .5 1i 12P 6P - | | - weight length -</pre> - -(Note that the box weight argument, which is expressed in points, -must NOT have the unit of measure <kbd>p</kbd> appended to it.) -</p> - -If you want the same box, but solid ("filled") rather -than drawn as an outline: - -<pre> - .DBX SOLID 1i 12P 6P -</pre> - -<p> -Additionally, if you want the box green: - -<pre> - .DBX .5 1i 12P 6P green - or - .DBX SOLID 1i 12P 6P green -</pre> -</p> - -<h3><u>How mom handles the positioning of boxes</u></h3> - -<p> -Boxes are drawn from the baseline down, from left to right, and -from the perimeter <em>inward</em>. "From the perimeter -inward" means that if you request a box weight of six points, -the 6-point rules used to draw the outline of the box fall entirely -<em>within</em> the dimensions of the box. -</p> - -<p> -Furthermore, after the box is drawn, <strong>mom</strong> returns -you to the current left margin, at the same vertical position -on the page as when <strong>DBX</strong> was invoked. In other -words, <strong>DBX</strong> causes no movement on the page, either -horizontal or vertical. -</p> - -<!-- -DCL- --> - -<hr width="33%" align="left"/> - -<a name="DCL"><h3><u>Drawing circles (ellipses)</u></h3></a> - -<p> -<nobr>Macro: <strong>DCL</strong> <kbd>< <rule weight> | SOLID > <indent> <length> <depth> [<colour>]</kbd></nobr> -<br/> - -<em>*The argument to</em> <kbd><rule weight></kbd> <em>is -in</em> -<a href="definitions.html#TERMS_PICASPOINTS">points</a>, -<em>but do </em> NOT <em>append the</em> -<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of -measure</a>, <kbd>p</kbd>. -<br/> - -<em>*The arguments,</em> <kbd><indent></kbd><em>,</em> -<kbd><length></kbd> <em>and</em> <kbd><depth></kbd> -<em>require a unit of measure.</em> -</p> - -<p> -To draw circles of specified dimensions, you must, at a minimum, -supply <strong>DCL</strong> with the arguments <kbd><nobr>rule -weight</nobr></kbd> or <kbd>SOLID</kbd>, <kbd>indent</kbd> -(measured from the current left margin), <kbd>length</kbd> and -<kbd>depth</kbd>. -</p> - -<p> -Optionally, you may give a <kbd>colour</kbd> argument. -The colour may be either one defined with -<a href="color.html#NEWCOLOR">NEWCOLOR</a>, -or a named X-colour inititialized with -<a href="color.html#XCOLOR">XCOLOR</a>, -or an X-colour alias (again, initialized with -<strong>XCOLOR</strong>). -</p> - -<p> -Say, for example, you want to draw a 1/2 point outline circle -(ellipse, actually, in this case) that starts one inch from the -current left margin and has the dimensions 6 centimeters x 3 -centimeters. To do so, you'd invoke <kbd>.DCL</kbd> like this: - -<pre> - indent depth - | | - .DCL .5 1i 6c 3c - | | - weight ength -</pre> - -(Note that the box weight argument, which is expressed in points, -must NOT have the unit of measure <kbd>p</kbd> appended to it.) -</p> - -If you want the same box, but solid ("filled") rather -than drawn as an outline: - -<pre> - .DCL SOLID 1i 6c 3c -</pre> - -<p> -Additionally, if you want the circle yellow: - -<pre> - .DCL .5 1i 6c 3c yellow - or - .DCL SOLID 1i 6c 3c yellow -</pre> -</p> - -<h3><u>How mom handles the positioning of circles (ellipses)</u></h3> - -<p> -Circles (ellipses) are drawn from the baseline down, from left -to right, and from the perimeter <em>inward</em>. "From the -perimeter inward" means that if you request a circle weight of -six points, the 6-point rule used to draw the outline of the circle -or ellipse falls entirely <em>within</em> the dimensions of the -circle or ellipse. -</p> - -<p> -Furthermore, after the circle is drawn, <strong>mom</strong> returns -you to the current left margin, at the same vertical position -on the page as when <strong>DCL</strong> was invoked. In other -words, <strong>DCL</strong> causes no movement on the page, either -horizontal or vertical. -</p> - -<hr/> - -<p> -<a href="docprocessing.html#TOP">Next</a> -<a href="color.html#TOP">Prev</a> -<a href="#TOP">Top</a> -<a href="toc.html">Back to Table of Contents</a> -</p> - -</body> -</html> - -<!-- vim: fileencoding=latin1: nomodified: ---> |