From 3ba71bae1806d1b02f7d0d0e49d53523bb501c70 Mon Sep 17 00:00:00 2001 From: PTPi Date: Wed, 18 Aug 2010 22:40:25 +0000 Subject: Complete doc overhaul; removed old files --- contrib/mom/momdoc/graphical.html | 593 -------------------------------------- 1 file changed, 593 deletions(-) delete mode 100644 contrib/mom/momdoc/graphical.html (limited to 'contrib/mom/momdoc/graphical.html') 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 @@ - - - - - - -Mom -- Graphical Objects - - - - - - - -

-Next -Prev -Back to Table of Contents -

- -

Graphical objects

- -

-Introduction to graphical objects - -

Graphical object behaviour
Order of arguments

- -Index of graphical object macros -

- -

Introduction to graphical objects

- -

-Groff has a number of -inline escapes -for drawing rules, polygons, ellipses and splines. All begin with -\D (presumably for "Draw") and are documented -in the groff info manual: - -

-    info groff => Escape index => \D
-

- -

-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 consistent manner, they don't -always perform in an expected manner. -

- -

-Experience shows that the most common graphical elements typesetters -need are rules (horizontal and vertical), boxes, and circles (or -ellipses). For this reason, mom provides macros -to draw these objects in an easy-to-understand way; the results are -predictable, and mom's syntax makes fixes or tweaks -painless. -

- - - -

-For example, if you want to draw a 2-inch square outline box at the left -margin using groff's \D escapes, it looks like this: - -

-              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
-

- -Obviously, this isn't very efficient for something as simple as a -box. -

- -

-Here's the same box, drawn with mom's box drawing -macro, -DBX: - -

-left margin indent-+  +-box width
-                   |  |
-          .DBX .5  0  2i  2i
-                |         |
-   rule weight--+         +-box depth
-   (in points)
-

- -

-Mom'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. -

- -

-There are no defaults for the arguments to mom'a -graphical object macros, which means you must supply the arguments -every time you invoke them. -

- -

-NOTE: As stated above, mom only -provides macros for commonly-used graphical objects (rules, boxes, -circles) only. More complex objects (polygons, non-straight lines, -splines) must be drawn using groff's \D -escapes. -

- -

Graphical object behaviour

- -

-Mom's graphical object macros all behave in the -following, carved-in-stone ways: - -

Objects are drawn from the - baseline - down, including horizontal rules.
Objects begin precisely at the left indent supplied as - an argument to the macro.
Objects are drawn from left to right.
Enclosed objects (boxes, circles) are drawn from the - perimeter inward.
Objects return to their horizontal/vertical point of origin.

- -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. -

- -

Order of arguments

- -

-The order of arguments to the graphical object macros is the same -for every macro: - -

the Weight of the rule

if the object is enclosed (i.e. is a box or circle), the - weight of the rule if you want the object outlined
the single word SOLID may be used in place - of the weight argument if you want the - object filled

the Indent from the current left margin at - which to begin the object
the Length of the object, if applicable
the Depth of the object, if applicable
the Colour of the object (optional)

- -

-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, -DRH, -with only the arguments (from the mnemonic) that apply: W-I-L (and -possibly C). -

- -

Index of graphical object macros

- -

DRH - — horizontal rule
DRV - — vertical rule
DBX - — box
DCL - — circle or ellipse

- - - -

- -

Drawing horizontal rules

- -

-Macro: DRH <none> | <rule weight> <indent> <length> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent> and -<length>, require a unit of measure. -

- -

-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 .DRH without any -arguments. (Note that DRH 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, -RULE_WEIGHT. -DRH, used this way, is exactly equivalent to -entering the -inline escape, -\*[RULE]. -

- -

-To draw horizontal rules of a specified length, you must, at a -minimum, supply -DRH with the arguments -rule weight, indent (measured from the -current left margin) and length. -

- -

-Optionally, you may give a colour argument. -The colour may be either one defined with -NEWCOLOR, -or a named X-colour inititialized with -XCOLOR, -or an X-colour alias (again, initialized with -XCOLOR). -

- -

-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 .DRH like this: - -

-         weight length
-           |      |
-    .DRH 1.125 2P 3i
-               |
-             indent
-

- -(Note that the rule weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -

-If, in addition, you want the rule blue: - -

-    .DRH 1.125 2P 3i blue
-

- -

How mom handles the positioning of horizontal rules

- -

-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. -

- -

-Furthermore, after the rule is drawn, mom returns -you to the current left margin, at the same vertical position on -the page as when DRH was invoked. In other words, -DRH causes no movement on the page, either -horizontal or vertical. -

- - - -

- -

Drawing vertical rules

- -

-Macro: DRV <rule weight> <indent> <depth> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent> and -<depth>, require a unit of measure. -

- -

-To draw vertical rules of a specified length, you must, at a -minimum, supply -DRV with the arguments -rule weight, indent (measured from the -current left margin) and depth. -

- -

-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 .DRV like this: - -

-         weight   depth
-           |        |
-    .DRV .75 19P+6p 6c
-               |
-             indent
-

- -(Note that the rule weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -

-If, in addition, you want the rule red: - -

-    .DRV .75 19P+6p 6c red
-

- -

How mom handles the positioning of vertical rules

- -

-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 DRV. -

- -

-Furthermore, after the rule is drawn, mom returns -you to the current left margin, at the same vertical position -on the page as when DRV was invoked. In other -words, DRV causes no movement on the page, either -horizontal or vertical. -

- - - -

- -

Drawing boxes

- -

-Macro: DBX < <rule weight> | SOLID > <indent> <length> <depth> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent>, -<length> and <depth> -require a unit of measure. -

- -

-To draw boxes of specified dimensions, you must, at a minimum, -supply DBX with the arguments rule -weight or SOLID, indent -(measured from the current left margin), length and -depth. -

- -

-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 .DBX like this: - -

-           indent   depth
-             |        |
-    .DBX .5  1i  12P  6P
-          |       |
-       weight   length
-

- -(Note that the box weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -If you want the same box, but solid ("filled") rather -than drawn as an outline: - -

-    .DBX SOLID 1i 12P 6P
-

- -

-Additionally, if you want the box green: - -

-    .DBX .5 1i 12P 6P green
-     or
-    .DBX SOLID 1i 12P 6P green
-

- -

How mom handles the positioning of boxes

- -

-Boxes are drawn from the baseline down, from left to right, and -from the perimeter inward. "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 -within the dimensions of the box. -

- -

-Furthermore, after the box is drawn, mom returns -you to the current left margin, at the same vertical position -on the page as when DBX was invoked. In other -words, DBX causes no movement on the page, either -horizontal or vertical. -

- - - -

- -

Drawing circles (ellipses)

- -

-Macro: DCL < <rule weight> | SOLID > <indent> <length> <depth> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent>, -<length> and <depth> -require a unit of measure. -

- -

-To draw circles of specified dimensions, you must, at a minimum, -supply DCL with the arguments rule -weight or SOLID, indent -(measured from the current left margin), length and -depth. -

- -

-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 .DCL like this: - -

-           indent  depth
-             |       |
-    .DCL .5  1i  6c  3c
-          |      |
-       weight   ength
-

- -(Note that the box weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -If you want the same box, but solid ("filled") rather -than drawn as an outline: - -

-    .DCL SOLID 1i 6c 3c
-

- -

-Additionally, if you want the circle yellow: - -

-    .DCL .5 1i 6c 3c yellow
-     or
-    .DCL SOLID 1i 6c 3c yellow
-

- -

How mom handles the positioning of circles (ellipses)

- -

-Circles (ellipses) are drawn from the baseline down, from left -to right, and from the perimeter inward. "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 within the dimensions of the -circle or ellipse. -

- -

-Furthermore, after the circle is drawn, mom returns -you to the current left margin, at the same vertical position -on the page as when DCL was invoked. In other -words, DCL causes no movement on the page, either -horizontal or vertical. -

- -

-Next -Prev -Top -Back to Table of Contents -

- - - - - -- cgit v1.2.1