diff options
Diffstat (limited to 'share/doc/usd/22.trofftut/tt11')
| -rw-r--r-- | share/doc/usd/22.trofftut/tt11 | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/share/doc/usd/22.trofftut/tt11 b/share/doc/usd/22.trofftut/tt11 new file mode 100644 index 000000000000..538fac77920d --- /dev/null +++ b/share/doc/usd/22.trofftut/tt11 @@ -0,0 +1,233 @@ +.\" This module is believed to contain source code proprietary to AT&T. +.\" Use and redistribution is subject to the Berkeley Software License +.\" Agreement and your Software Agreement with AT&T (Western Electric). +.\" +.\" @(#)tt11 8.1 (Berkeley) 6/8/93 +.\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are +.\" met: +.\" +.\" Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" +.\" This product includes software developed or owned by Caldera +.\" International, Inc. Neither the name of Caldera International, Inc. +.\" nor the names of other contributors may be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA +.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE +.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.NH +Macros with arguments +.PP +The next step is to define macros that can change from one +use to the next +according to parameters supplied as arguments. +To make this work, we need two things: +first, when we define the macro, we have to indicate that some +parts of it will be provided as arguments when the macro is called. +Then when the macro is +called +we have to provide actual arguments +to be plugged into the definition. +.PP +Let us illustrate by defining a macro +.BD .SM +that will print its argument two points +smaller than the surrounding text. +That is, the macro call +.P1 +^SM TROFF +.P2 +will produce +.UC TROFF . +.PP +The definition of +.BD .SM +is +.P1 +^de SM +\es\-2\e\e$1\es+2 +^^ +.P2 +Within a macro definition, +the symbol +.BD \e\e$n +refers to the +.BD n th +argument +that the macro was called with. +Thus +.BD \e\e$1 +is the string to be placed in a smaller point +size when +.BD .SM +is called. +.PP +As a slightly more complicated version, the following definition of +.BD .SM +permits optional second and third arguments +that will be printed in the normal size: +.P1 +^de SM +\e\e$3\es\-2\e\e$1\es+2\e\e$2 +^^ +.P2 +Arguments not provided when the macro is called are treated +as empty, +so +.P1 +^SM TROFF ), +.P2 +produces +.UC TROFF ), +while +.P1 +^SM TROFF ). ( +.P2 +produces +.UC TROFF ). ( +It is convenient to reverse +the order of arguments because trailing punctuation +is much more common than leading. +.PP +By the way, the number of arguments that a macro was called with +is available in number register +.BD .$ . +.PP +The following macro +.BD ^BD +is the one used to make the +`bold roman' we have been using for +.UL troff +command names in text. +It combines horizontal motions, width computations, +and argument rearrangement. +.P1 2 +\&.de BD +\e&\e\e$3\ef1\e\e$1\eh'\-\ew'\e\e$1'u+1u'\e\e$1\efP\e\e$2 +\&.. +.P2 +The +.BD \eh +and +.BD \ew +commands need no extra backslash, as we discussed above. +The +.BD \e& +is there in case the argument begins with a period. +.WS +.PP +Two backslashes are needed with the +.BD \e\e$n +commands, though, +to protect one of them when the macro is +being defined. +Perhaps a second example will make this clearer. +Consider a macro called +.BD .SH +which +produces section headings rather like those in this paper, +with the sections numbered automatically, +and the title in bold in a smaller size. +The use is +.P1 +^SH "Section title ..." +.P2 +(If the argument to a macro is to contain blanks, +then it must be +.ul +surrounded +by double quotes, +unlike a string, where only one leading quote is permitted.) +.PP +Here is the definition of the +.BD .SH +macro: +.P1 +.ta .75i 1.15i +^nr SH 0 \e" initialize section number +^de SH +^sp 0.3i +^ft B +^nr SH \e\en(SH+1 \e" increment number +^ps \e\en(PS\-1 \e" decrease PS +\e\en(SH. \e\e$1 \e" number. title +^ps \e\en(PS \e" restore PS +^sp 0.3i +^ft R +^^ +.P2 +The section number is kept in number register SH, which is incremented each +time just before it is used. +(A number register may have the same name as a macro +without conflict but a string may not.) +.PP +We used +.BD \e\en(SH +instead of +.BD \en(SH +and +.BD \e\en(PS +instead of +.BD \en(PS . +If we had used +.BD \en(SH , +we would get the value of the register at the time the macro was +.ul +defined, +not at the time it was +.ul +used. +If that's what you want, fine, +but not here. +Similarly, +by using +.BD \e\en(PS , +we get the point size at the time the macro is called. +.WS +.PP +As an example that does not involve numbers, +recall our +.BD .NP +macro which had a +.P1 +^tl 'left'center'right' +.P2 +We could make these into parameters by using instead +.P1 +^tl '\e\e*(LT'\e\e*(CT'\e\e*(RT' +.P2 +so the title comes from three strings called LT, CT and RT. +If these are empty, then the title will be a blank line. +Normally CT would be set with something like +.P1 +\&^ds CT - % - +.P2 +to give just the page number between hyphens (as on the top of this page), +but a user could supply private definitions for +any of the strings. |