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