| 1 | .NH |
| 2 | Introduction to Macros |
| 3 | .PP |
| 4 | Before we can go much further in |
| 5 | .UL troff , |
| 6 | we need to learn a bit about the |
| 7 | macro |
| 8 | facility. |
| 9 | In its simplest form, a macro is just a shorthand notation |
| 10 | quite similar to a string. |
| 11 | Suppose we want every paragraph to start |
| 12 | in exactly the same way _ |
| 13 | with a space and a temporary indent of two ems: |
| 14 | .P1 |
| 15 | ^sp |
| 16 | ^ti +2m |
| 17 | .P2 |
| 18 | Then to save typing, we would like to collapse these into |
| 19 | one shorthand line, |
| 20 | a |
| 21 | .UL troff |
| 22 | `command' like |
| 23 | .P1 |
| 24 | ^PP |
| 25 | .P2 |
| 26 | that would be treated by |
| 27 | .UL troff |
| 28 | exactly as |
| 29 | .P1 |
| 30 | ^sp |
| 31 | ^ti +2m |
| 32 | .P2 |
| 33 | .BD .PP |
| 34 | is called a |
| 35 | .ul |
| 36 | macro. |
| 37 | The way we tell |
| 38 | .UL troff |
| 39 | what |
| 40 | .BD .PP |
| 41 | means is to |
| 42 | .ul |
| 43 | define |
| 44 | it with the |
| 45 | .BD .de |
| 46 | command: |
| 47 | .P1 |
| 48 | ^de PP |
| 49 | ^sp |
| 50 | ^ti +2m |
| 51 | ^^ |
| 52 | .P2 |
| 53 | The first line names the macro |
| 54 | (we used |
| 55 | .BD .PP ' ` |
| 56 | for `paragraph', |
| 57 | and upper case so it wouldn't conflict with |
| 58 | any name that |
| 59 | .UL troff |
| 60 | might |
| 61 | already know about). |
| 62 | The last line |
| 63 | .BD .. |
| 64 | marks the end of the definition. |
| 65 | In between is the text, |
| 66 | which is simply inserted whenever |
| 67 | .UL troff |
| 68 | sees the `command' |
| 69 | or macro call |
| 70 | .P1 |
| 71 | ^PP |
| 72 | .P2 |
| 73 | A macro |
| 74 | can contain any mixture of text and formatting commands. |
| 75 | .PP |
| 76 | The definition of |
| 77 | .BD .PP |
| 78 | has to precede its first use; |
| 79 | undefined macros are simply ignored. |
| 80 | Names are restricted to one or two characters. |
| 81 | .PP |
| 82 | Using macros for commonly occurring sequences of commands |
| 83 | is critically important. |
| 84 | Not only does it save typing, |
| 85 | but it makes later changes much easier. |
| 86 | Suppose we decide that the paragraph indent is too small, |
| 87 | the vertical space is much too big, |
| 88 | and roman font should be forced. |
| 89 | Instead of changing the whole document, |
| 90 | we need only change the definition of |
| 91 | .BD .PP |
| 92 | to |
| 93 | something like |
| 94 | .P1 |
| 95 | ^de PP \e" paragraph macro |
| 96 | ^sp 2p |
| 97 | ^ti +3m |
| 98 | ^ft R |
| 99 | ^^ |
| 100 | .P2 |
| 101 | and the change takes |
| 102 | effect everywhere we used |
| 103 | .BD .PP . |
| 104 | .PP |
| 105 | .BD \e" |
| 106 | is a |
| 107 | .UL troff |
| 108 | command that causes the rest of the line to be ignored. |
| 109 | We use it here to add comments to the macro |
| 110 | definition |
| 111 | (a wise idea once definitions get complicated). |
| 112 | .PP |
| 113 | As another example of macros, |
| 114 | consider these two which start and end a block of offset, |
| 115 | unfilled text, like most of the examples in this paper: |
| 116 | .P1 |
| 117 | ^de BS \e" start indented block |
| 118 | ^sp |
| 119 | ^nf |
| 120 | ^in +0.3i |
| 121 | ^^ |
| 122 | ^de BE \e" end indented block |
| 123 | ^sp |
| 124 | ^fi |
| 125 | ^in \(mi0.3i |
| 126 | ^^ |
| 127 | .P2 |
| 128 | Now we can surround text like |
| 129 | .P1 |
| 130 | Copy to |
| 131 | John Doe |
| 132 | Richard Roberts |
| 133 | Stanley Smith |
| 134 | .P2 |
| 135 | by the commands |
| 136 | .BD .BS |
| 137 | and |
| 138 | .BD .BE , |
| 139 | and it will come out as it did above. |
| 140 | Notice that we indented by |
| 141 | .BD .in\ +0.3i |
| 142 | instead of |
| 143 | .BD .in\ 0.3i . |
| 144 | This way we can nest our uses of |
| 145 | .BD .BS |
| 146 | and |
| 147 | .BD BE |
| 148 | to get blocks within blocks. |
| 149 | .PP |
| 150 | If later on we decide that the indent |
| 151 | should be 0.5i, then it is only necessary to |
| 152 | change the definitions of |
| 153 | .BD .BS |
| 154 | and |
| 155 | .BD .BE , |
| 156 | not the whole paper. |