home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V7 / usr / doc / trofftut / tt11 < prev    next >
Encoding:
Text File  |  1979-01-10  |  3.8 KB  |  191 lines
  1. .NH
  2. Macros with arguments
  3. .PP
  4. The next step is to define macros that can change from one
  5. use to the next
  6. according to parameters supplied as arguments.
  7. To make this work, we need two things:
  8. first, when we define the macro, we have to indicate that some
  9. parts of it will be provided as arguments when the macro is called.
  10. Then when the macro is 
  11. called
  12. we have to provide actual arguments
  13. to be plugged into the definition.
  14. .PP
  15. Let us illustrate by defining a macro
  16. .BD .SM
  17. that will print its argument two points
  18. smaller than the surrounding text.
  19. That is, the macro call
  20. .P1
  21. ^SM TROFF
  22. .P2
  23. will produce
  24. .UC TROFF .
  25. .PP
  26. The definition of
  27. .BD .SM
  28. is
  29. .P1
  30. ^de SM
  31. \es\-2\e\e$1\es+2
  32. ^^
  33. .P2
  34. Within a macro definition,
  35. the symbol
  36. .BD \e\e$n
  37. refers to the
  38. .BD n th
  39. argument
  40. that the macro was called with.
  41. Thus
  42. .BD \e\e$1
  43. is the string to be placed in a smaller point
  44. size when
  45. .BD .SM
  46. is called.
  47. .PP
  48. As a slightly more complicated version, the following definition of
  49. .BD .SM
  50. permits optional second and third arguments
  51. that will be printed in the normal size:
  52. .P1
  53. ^de SM
  54. \e\e$3\es\-2\e\e$1\es+2\e\e$2
  55. ^^
  56. .P2
  57. Arguments not provided when the macro is called are treated
  58. as empty,
  59. so
  60. .P1
  61. ^SM  TROFF  ),
  62. .P2
  63. produces
  64. .UC TROFF ),
  65. while
  66. .P1
  67. ^SM  TROFF  ).  (
  68. .P2
  69. produces
  70. .UC TROFF ). (
  71. It is convenient to reverse 
  72. the order of arguments because trailing punctuation
  73. is much more common than leading.
  74. .PP
  75. By the way, the number of arguments that a macro was called with
  76. is available in number register
  77. .BD .$ .
  78. .PP
  79. The following macro
  80. .BD ^BD
  81. is the one used to make the
  82. `bold roman' we have been using for
  83. .UL troff
  84. command names in text.
  85. It combines horizontal motions, width computations,
  86. and argument rearrangement.
  87. .P1 2
  88. \&.de BD
  89. \e&\e\e$3\ef1\e\e$1\eh'\-\ew'\e\e$1'u+1u'\e\e$1\efP\e\e$2
  90. \&..
  91. .P2
  92. The
  93. .BD \eh
  94. and
  95. .BD \ew
  96. commands need no extra backslash, as we discussed above.
  97. The
  98. .BD \e&
  99. is there in case the argument begins with a period.
  100. .WS
  101. .PP
  102. Two backslashes are needed with the
  103. .BD \e\e$n
  104. commands, though,
  105. to protect one of them when the macro is
  106. being defined.
  107. Perhaps a second example will make this clearer.
  108. Consider a macro called
  109. .BD .SH
  110. which
  111. produces section headings rather like those in this paper,
  112. with the sections numbered automatically,
  113. and the title in bold in a smaller size.
  114. The use is
  115. .P1
  116. ^SH  "Section title ..."
  117. .P2
  118. (If the argument to a macro is to contain blanks,
  119. then it must be
  120. .ul
  121. surrounded
  122. by double quotes,
  123. unlike a string, where only one leading quote is permitted.)
  124. .PP
  125. Here is the definition of the
  126. .BD .SH
  127. macro:
  128. .P1
  129. .ta .75i 1.15i
  130. ^nr SH 0    \e" initialize section number
  131. ^de SH
  132. ^sp 0.3i
  133. ^ft B
  134. ^nr SH \e\en(SH+1    \e" increment number
  135. ^ps \e\en(PS\-1    \e" decrease PS
  136. \e\en(SH.  \e\e$1    \e" number. title
  137. ^ps \e\en(PS        \e" restore PS
  138. ^sp 0.3i
  139. ^ft R
  140. ^^
  141. .P2
  142. The section number is kept in number register SH, which is incremented each
  143. time just before it is used.
  144. (A number register may have the same name as a macro
  145. without conflict but a string may not.)
  146. .PP
  147. We used
  148. .BD \e\en(SH
  149. instead of
  150. .BD \en(SH
  151. and
  152. .BD \e\en(PS
  153. instead of
  154. .BD \en(PS .
  155. If we had used
  156. .BD \en(SH ,
  157. we would get the value of the register at the time the macro was
  158. .ul
  159. defined,
  160. not at the time it was
  161. .ul
  162. used.
  163. If that's what you want, fine,
  164. but not here.
  165. Similarly,
  166. by using
  167. .BD \e\en(PS ,
  168. we get the point size at the time the macro is called.
  169. .WS
  170. .PP
  171. As an example that does not involve numbers,
  172. recall our
  173. .BD .NP
  174. macro which had a
  175. .P1
  176. ^tl 'left'center'right'
  177. .P2
  178. We could make these into parameters by using instead
  179. .P1
  180. ^tl '\e\e*(LT'\e\e*(CT'\e\e*(RT'
  181. .P2
  182. so the title comes from three strings called LT, CT and RT.
  183. If these are empty, then the title will be a blank line.
  184. Normally CT would be set with something like
  185. .P1
  186. \&^ds  CT  - % -
  187. .P2
  188. to give just the page number between hyphens (as on the top of this page),
  189. but a user could supply private definitions for
  190. any of the strings.
  191.