troff.d/tmac.d/vgrind

 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

 ident "%Z%%M% %I% %E% SMI"
 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.
..
----------------
 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.
..
'ds _ \d-\u
'ds - -
'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
..
----------------
 no: no-op
 This macro does nothing. It's defined as a place-holder to
 immediately precede \} constructs, to make editing easier.
..
..
----------------
 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...
..
 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
..
----------------
 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.
..
'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!
' 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
..
----------------
 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.
..
'ss 12
'ps
'vs
'bd B
'bd S
..
----------------
 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
..
----------------
 v<: Output page header
 Called from vH.
..
'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\s0'\\*(=H'\f3\s14\\*(=F\s0'
'\" Emit the ellipsis string for the current function.
'sp .25i
'ft 1
\f2\s12\h'\\n(.lu-\w'\\*(=f'u'\\*(=f\s0\h'|0u'
.sp .05i
'ev
 Save current file name for use in footer.
'ds =G \\*(=F
..
----------------
 v.: Output function ellipsis string as part of column header.
 Called from vH.
..
'ev 2
'sp .25i
'ft 1
\f2\s12\h'\\n(vKu-\w'\\*(=f'u'\\*(=f\s0\h'|0u'
'ev
'ns \" Suppress additional spacing.
..
----------------
 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.
..
'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>
..
----------------
 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 %'
'el 'tl '\f2\\*(=M''Page % of \\*(=G'
'bp
'ev
'ft \\*(tP
'if \\n(vC=1 'ft \\*(tC
..
----------------
 (): Inter-file macro
 Only invoked when not in filter mode. Called between input files,
 to reset page numbering for each.
..
'de ()
'pn 1
..
----------------
 +C: Start comment
..
'de +C
'nr vC 1
'ft \\*(tC
'ds +K
'ds -K
..
----------------
 -C: end comment
..
'de -C
'nr vC 0
'ft \\*(tP
'ds +K \\f\\*(fK
'ds -K
..
----------------
 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\s0\h'|0u'\c
'ds =f ...\\$1
..
----------------
 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
'ds =f ...\\$1
..
----------------
 -F: function end
 Removes definition of =f string so that the marginal entry for
 function continuation will no longer appear.
..
'de -F
'rm =f
..
----------------