*! 4.4.0  26Apr1999  jw/ics   STB-50 gr38
*  3.1.3  09Nov1994  (StataCorp)
program define hilite2
	version 6.0

	syntax varlist(min=2 max=2 numeric) [if] [in] [, /*
		*/ HILite(str) HIVar(varlist) Overlay MATrix MARgin(passthru) /*
		*/ miss noLAbel By(str) SAving(passthru) SYmbol(str) TItle(passthru) /*
		*/ T1title(passthru) BSize(int 0) * ]

	local opts `options'

	* scratch
	tempvar grp notfrst

	* select sample
	marksample touse

	/*
		generate and verify expressions
	*/

	if (`"`hilite'"' == "" & "`hivar'" == "") | /*
		*/ (`"`hilite'"' ~= "" & "`hivar'" ~= "") {
		di in re "either hilite() or hivar() should be specified"
		exit 198
	}

	if "`hivar'" ~= "" {

		**  generate the hilite list from a varlist

		local nhivar : word count `hivar'
		quietly egen `grp' = group(`hivar') if `touse', `miss'
 		quietly summ `grp' if `touse', meanonly
		local nh = r(max) /* number of groups */
		if `nh' > 49 {
			di in re "`nh' groups. Maximum = 49"
			exit 498
		}
		else if `nh' == 1 {
			di in re "`hivar' is constant; no expressions to hilite"
			exit 498
		}

		sort `grp'
		quietly by `grp': gen byte `notfrst' = _n>1
		sort `notfrst' `grp'

		tokenize `hivar'
		local ih 1
		while `ih' <= `nh' {
			local exp`ih' `"`grp'==`ih'"'

			local iv 1
			while `iv' <= `nhivar' {
				local vvi = ``iv''[`ih']
				if "`label'" == "" {
					* capture ensures that string vars are permitted!
					capt local vvi : label (``iv'') `vvi'
				}
				local label`ih' `"`label`ih''``iv''==`vvi'  "'
				local iv = `iv'+1
			}

			*di `"exp`ih'  : `exp`ih''"'
			*di `"label`ih': `label`ih''"'
			local ih = `ih'+1
		}
	}
	else {

		**  parse the hilite list into expressions **on spaces**
		tokenize `hilite'
		local nh 0
		while `"`1'"' ~= "" {
			local nh = `nh'+1
			local exp`nh' `"`1'"'
			expr_ok  if `exp`nh''
			local label`nh' `exp`nh''
			mac shift
		}
	}

	/*
		create plots
	*/

	if "`overlay'" ~= "" & "`matrix'" ~= "" {
		di in re "overlay and matrix cannot be specified simultaneously"
		exit 198
	}

	local tsize : set textsize
	if `"`t1title'"' == "" & `nh' == 1 {
		local t1title `"highlighted: `exp1'"'
	}

	local y : word 1 of `varlist'
	local x : word 2 of `varlist'

	local labely : variable label `y'
	if `"`labely'"' == "" {
		local labely `"`y'"'
	}

	local labelx : variable label `x'
	if `"`labelx'"' == "" {
		local labelx `"`x'"'
	}

	if "`by'" ~= "" {
		sort `by'
		local by "by(`by')"
	}

	if "`overlay'" ~= "" | `nh' == 1 {

		/*
			overlay plot
		*/

		if `nh' > 6 {
			di in re "max 6 overlay plots allowed"
			exit 198
		}
		if `nh' > 4 {
			di in bl "only 4 overlay plots are labeled"
		}
		if `"`symbol'"' == "" {
			local symbol = substr("odpTSO", 1, `nh')
		}
		else if length(`"`symbol'"') ~= `nh' {
			di in re "symbol() should contain `nh' symbol-characters"
			exit 198
		}

		local ih 1
		while `ih' <= `nh' {
			tempvar Temp`ih'
			qui gen `Temp`ih'' = `y' if (`exp`ih'') & (`touse')
			label var `Temp`ih'' `"hilite: `label`ih''"'
			local tvar `"`tvar' `Temp`ih''"'
			local ih = `ih'+1
		}

		graph `y' `tvar' `x' if `touse', twoway `by' `saving' `opts' /*
			*/ symbol(`".`symbol'"') t1(`"`t1title'"') l1(`"`labely'"')
	}

	else {
		/*
			matrix plot
		*/

		set graphics off
		local symbol = substr(`"`symbol'o"', 1, 1)
		local msize = 1 + int(sqrt(`nh') - 0.0001)
		if `bsize' == 0 {
			local bsize = int(`tsize' * (1.30^(`msize')))
		}
		set textsize `bsize'

		tempvar Temp
		local ih 1
		while `ih' <= `nh' {
			qui gen `Temp' = `y' if (`exp`ih'') & (`touse')
			tempfile File`ih'
			local Files "`Files' `File`ih''"

			* label only the left/bottom sides
			local l1
			local b2
			if mod(`ih',`msize') == 1 {
				local l1 `"`labely'"'
			}
			if int(`ih'/`msize' - 1E-4) == int(`nh'/`msize' - 1E-4) {
				local b2 `"`labelx'"'
			}

			graph `y' `Temp' `x' if `touse' , twoway `by'   /*
				*/ symbol(`".`symbol'"') t1(`"hilite: `label`ih''"') /*
				*/ l1(`"`l1' "') b2(`"`b2' "') ti(" ") /*
				*/ `opts' saving(`File`ih'')

			local ih = `ih'+1
			drop `Temp'
		}

		set graphics on
		set textsize `tsize'
		graph using `Files', `margin' `saving' t1(`"`t1title'"') `title'
	}
end

* syntax: expr_ok <expression>
* usage:  verifies that an expression is well-defined
program define expr_ok
	syntax if /* produces error message automatically */
end