OpenSolaris_b135/cmd/vgrind/tmac.vgrind
.\" ident "%Z%%M% %I% %E% SMI"
.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License, Version 1.0 only
.\" (the "License"). You may not use this file except in compliance
.\" with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.ig
This version of tmac.vgrind is intended to interface more
gracefully to other macro packages than the previous version.
Rather than defining things irrevocably, with no way to alter
the definitions, this version encapsulates definitions and
changes in the operating environment into macros whose
definitions can be overriden as needed.
Guide to strings that vfontedpr generates code to define:
=F current file name
=H operand of vfontedpr's -h flag
=M time and date info for current file
Guide to number registers that vfontedpr generates code to define:
vP point size (in points) to use for main text. Pre-defined
only if the -s option was supplied to vfontedpr.
N.B.: does not affect headers or margin entries.
Internal strings
=f ellipsis string for current function
=G local copy of =F used to keep header and footer consistent
with each other
+K string used to start keyword; value depends on whether
or not a comment is active
-K string used to end keyword; value depends on whether
or not a comment is active
Internal number registers
v nonzero prevents cut marks (in theory, at least)
vC nonzero when in comment
To do: convert hard-wired point sizes, etc. to parameterized values.
XXX: vfontedpr has font 2 wired into it for comments; change to use
tC and fC as below.
*** This version is also augmented with support for two column output.
N.B.: I haven't thought at all about how to make this work in
filter mode. Things will have to be redefined, as I rely on adding
hooks to the header and footer macros to flip from one column to
the next.
Additional register that vfontedpr defines:
=2 if nonzero, generate two column output.
Additional internal number registers.
v2 corrent column number: 0 == left, 1 == right
vH saved vertical position of top of left column; calculated
in vH when switching to left column and used in vF when
switching to the right column.
vO page offset in effect for left column (the original offset).
vR page offset in effect for right column.
vL saved line length in effect at beginning of new page.
vK line length in effect for each column.
vX scratch register.
..
'\"----------------
.ig
sI: Initialize configurable strings
XXX: need better name for this macro.
This macro is called from the vI macro at initialization time.
It must define the following:
_ string representation for underscore
- string representation for minus
/ string representation for slash, shifted horizontally so
that C-style comments will line up
/* string representation for /*, shifted horizontally so
that C-style comments will line up.
tC string comment font in .ft form (e.g., `BI')
fC string comment font in \f form (e.g., `(BI')
tK string keyword font in .ft form
fK string keyword font in \f form
tP string program font in .ft form
fP string program font in \f form
By redefining this macro, one can alter the appearance of vgrind's
output.
..
.de sI
'ds _ \d\(mi\u
'ds - \(mi
'ds / \\h'\\w' 'u-\\w'/'u'/
'ds /* \\h'\\w' 'u-\\w'/'u'/*
'\"
'ds tC 2
'ds fC 2
'ds tK 3
'ds fK 3
'ds tP 1
'ds fP 1
'\"
.nr v 1
..
'\"----------------
.ig
no: no-op
This macro does nothing. It's defined as a place-holder to
'\" immediately precede \} constructs, to make editing easier.
..
.de no
..
'\"----------------
.ig
vI: Initial definitions.
This macro is called once only, before any .vS -- .vE program
inclusions are processed (or before all input files, if they consist
solely of program text).
XXX: We assume that 2-column mode imples landscape output. Ideally, there
should be a separate -T<device> entry for the landscape version of the
output device, but that hasn't happened. Instead, all there is is a
"-L" flag to troff that does nothing more than rotate the resulting
PostScript 90 degrees. In particular, page lengths and widths are
unaffected. Thus, we hack altered values into place here. This is
pretty disgusting...
..
.de vI
'\" Deal with page length and width -- see above.
'if \\n(=2 \{\
' ll 9.5i
' lt 9.5i
' ev 2
' ll 9.5i
' lt 9.5i
' ev
' pl 8i
'no\}
'sI
'\" If point size values haven't already been established, set them
'\" to suitable default values. The defaults are smaller for two column
'\" mode.
'if \\n(vP=0 \{\
' ie \\n(=2 \{\
' nr vP 8
' no\}
' el \{\
' nr vP 9
' no\}
'no\}
'\" Force comment state indicators into the correct
'\" initial state. Convert the comment start macro
'\" to its final form.
'+C
'-C
'am +C
'ne 3
\\..
'ft \\*(tP
'lg 0
..
'\"----------------
.ig
vS: Start program text
This macro must be called at the start of a chunk of interpolated
program text. The version given here is a default version suitable
for standalone use -- that is, not in conjunction with some other
macro package. It should be redefined as necessary to coexist
gracefully with the macro package of your choice. Of course, the
redefined version should do the same things this version does.
It may be necessary to move the emboldening commands to the vI
macro, or remove them altogether. If they remain here, they will
probably have to be supplemented with copies of themselves that
are protected with the transparent throughput indicator.
..
.de vS
'ss 23
'\" Set text point size and vertical spacing.
'\" XXX: All point size stuff should be parameterized, not just the
'\" primary text sizes.
'ps \\n(vPp
'nr vX \\n(vP+1
'vs \\n(vXp
'\" If in two column mode, reduce page offset to first column a bit
'\" and bump line length correspondingly.
'\" XXX: Aargh! More hard-wiring!
.if \\n(=2 \{\
' po -0.4i
' ll +0.4i
' lt +0.4i
' ev 2
' ll +0.4i
' lt +0.4i
' ev
'no\}
'\"'bd B 3
'\"'bd S B 3
'nf \" When not run standalone, the host macro package
' \" may well do this for us.
'nr vC 0 \" We're not in a comment.
'nr v2 0 \" start in left column
'nr vO \\n(.ou \" save page offset
'nr vL \\n(.lu \" save line length
'nr vR \\n(.ou+(\\n(.lu/2u)+(0.25i)u \" get right column offset
'ie \\n(=2 'nr vK (\\n(.lu/2u)-(0.25i)u \" get column width
'el 'nr vK \\n(.lu
..
'\"----------------
.ig
vE: End program text
This macro closes the chunk of program text started by vS. The
same comments apply to it that do for vS.
..
.de vE
'ss 12
'ps
'vs
'\"'bd B
'\"'bd S
..
'\"----------------
.ig
vH: Header macro
Only invoked when not in filter mode.
N.B.: This macro hard-wires the inter-column gap to 0.25i.
..
'de vH
'v< \" Put out the header itself.
'if \\n(=2 \{\
'\" In two column mode: we've trapped because we've moved to a new
'\" page. Save position information for later use. Squash down line
'\" length.
' nr v2 0 1 \" reset column counter
' mk vH \" save vertical position for later restoration
' ll \\n(vKu
'.no\}
'v. \" Put out the column header
..
'\"----------------
.ig
v<: Output page header
Called from vH.
..
.de v<
'ev 2
'if t 'if !\nv 'tl '\-\-''\-\-'
'\" Emit page header (file name at right and left page margins).
'ft 1
'sp .35i
'tl '\s14\f3\\*(=F\fP\s0'\\*(=H'\f3\s14\\*(=F\fP\s0'
'\"'\" Emit the ellipsis string for the current function.
'\"'sp .25i
'\"'ft 1
'\"\f2\s12\h'\\n(.lu-\w'\\*(=f'u'\\*(=f\fP\s0\h'|0u'
'\".sp .05i
'ev
'\" Save current file name for use in footer.
'ds =G \\*(=F
..
'\"----------------
.ig
v.: Output function ellipsis string as part of column header.
Called from vH.
..
.de v.
'ev 2
'sp .25i
'ft 1
\f2\s12\h'\\n(vKu-\w'\\*(=f'u'\\*(=f\fP\s0\h'|0u'
.sp .05i
'ev
'ns \" Suppress additional spacing.
..
'\"----------------
.ig
vF: Footer macro
Only invoked when not in filter mode.
If in two column mode, handles switching between columns.
N.B.: This macro hard-wires the inter-column gap to 0.25i.
..
.de vF
'ie \\n(=2 \{\
'\" in two column mode
' ie \\n+(v2=1 \{\
'\" Transition from left column to right.
'\" Construct a vertical line running down the center of the
'\" gutter.
' ev 2
' nr vX (\\n(vLu/2u-(0.125i))u \" Horiz off to gutter center
\h'|\\n(vXu'\c
\L'|\\n(vHu'\c
\h'|0u'\c
'\" Move back to top of column and bump page offset to move
'\" into it.
. sp |\\n(vHu
' po \\n(vRu
'\" Put out the current function ellipsis string.
' ev
' v.
' no\}
' el \{\
'\" Transition from right column to left of next page: restore
'\" saved values and then output the footer.
' po \\n(vOu
' ll \\n(vLu
' v>
' no\}
'no\}
'el 'v>
..
'\"----------------
.ig
v>: Output page footer
Called from vF when in single column mode or when it hits the
bottom of the left column.
..
'de v>
'ev 2
'sp .35i
'ie '\\*(=G'' 'tl '\f2\\*(=M''Page %\fP'
'el 'tl '\f2\\*(=M''Page % of \\*(=G\fP'
'bp
'ev
'ft \\*(tP
'if \\n(vC=1 'ft \\*(tC
..
'\"----------------
.ig
(): Inter-file macro
Only invoked when not in filter mode. Called between input files,
to reset page numbering for each.
..
'de ()
'pn 1
..
'\"----------------
.ig
+C: Start comment
..
'de +C
'nr vC 1
'ft \\*(tC
'ds +K
'ds -K
..
'\"----------------
.ig
-C: end comment
..
'de -C
'nr vC 0
'ft \\*(tP
'ds +K \\f\\*(fK
'ds -K \fP
..
'\"----------------
.ig
FN: function definition
Issues marginal notation giving function's name.
Issues the primary index entry for it.
Sets the =f string to record a continuation entry for it
(e.g., " ...func-name").
..
'de FN
\f2\s14\h'\\n(vKu-\w'\\$1'u'\\$1\fP\s0\h'|0u'\c
.if \\nx .tm \\$1 \\*(=F \\n%
'ds =f \&...\\$1
..
'\"----------------
.ig
FC: function continuation
Issues index entry for where the function definition picks up again.
Sets the =f string to record a continuation entry for it
(e.g., " ...func-name").
..
'de FC
.if \\nx .tm \\$1 \\*(=F \\n%
'ds =f \&...\\$1
..
'\"----------------
.ig
-F: function end
Removes definition of =f string so that the marginal entry for
function continuation will no longer appear.
..
'de -F
'rm =f
..
'\"----------------