home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V7 / usr / doc / trofftut / tt08 < prev    next >
Encoding:
Text File  |  1979-01-10  |  2.6 KB  |  157 lines
  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.
  157.