.-
help for ^addtex^ and ^hlTex^ 
.-

A very simple utility to display texts on a graph
-------------------------------------------------
	^addtex^  [filename] 

	^hlTex^   workhorse called by addtex, 
		analyzes magnifications and locates texts on plot.



Description
-----------

It is tedious and sometimes difficult to add texts on a graph. 

The little ^addtex^ program listed below will put stored texts in 
preassigned positions on an existing graph. 
 
The texts to be displayed must be stored in global macros (see below). 

The program obeys desired magnification (also stored, default 100) 
and saves the resulting plot when a (new) filename is provided.

^addtex^ should not require modifications, ^hlTex^ may be enriched.

*--------------
prog def addtex
*--------------
	if "`1'"=="" { gph open }
	else         { gph open , saving(`1') } 
	gr		/* reproduces last graph */
	hlTex		/* adds the stored texts */
	gph close
end
*


Example
-------

. use auto
. graph mpg price
. ^addtex^ mpg


Plot something and let ^addtex^ put some stored texts in fixed places on 
the graph. The modified graph is saved in file mpg.gph. That's all, no 
programming, all you need to do is prepare your texts.

Things might look a bit messy though, and it will usually be better to 
use Stata's ^bounding box^ in order to leave some free space where the 
texts can be displayed. Declaring, for instance,

. global bb bbox(3000,3000,20000,29000,923,444,0)

will permit 3000 all around (about 10% of the graphing area) and request 
a text size of 923 by 444 (the standard in @gph@), oriented horizontally. 

So, the second attempt would look like: 

. erase mpg.gph
. graph mpg price, $bb [ other graph options ]
. ^addtex^ mpg

If you dont like the size of your added texts, you may change their
overall magnification which is stored in the global macro hlMag 


Running addtex again after

. glob hlMag 90 

redraws the original graph where the added texts are reduced (90%), while 
default texts remain unchanged because they are controlled by the bbox. 


Remarks:

 - it is not required to rerun graph, just addtex.
 - all Stata graph options and, in particular, the 8 standard textlines 
   remain available. They won't overlap if bbox-margins are adequate.
 - the default of 100 for hlMag corresponds to the gph standard textsize

Stored texts
------------

^addtex^ calls ^hlTex^ to display the following texts in the indicated
positions. They are in global macros whose names all start with hlTex.


 ^hlText1^	(t1) top line, left justified 
 ^hlText2^	(t2) second line from top, also left justified 

 ^hlTexb1^	(b1) bottom line, left justified
 ^hlTexb2^	(b2) second line from bottom, also left justified


 ^hlTexr^	(r)  right: parsed, one word per line,
 ^hlTexl^	(l)  left: also one word per line, 

 ^hlTexc^	(c)  lower right corner, typically for signature or date.



Enhancements
------------

Four conventions allow modification of the default presentation of
added texts (see examples):

   the first convention applies to all added texts, the second to top 
   and bottom texts and the last two to right and left texts.


1. Overall text magnification is saved in global hlMag, but individual 
   text magnification may be requested as part of each stored text and 
   will be stripped away. 
   The convention is to start the text with ^mag(^#^)^, where the number # 
   is the desired magnification.

2. Top and bottom texts are left-aligned. You may want to shift these 
   texts to the right. 
   The convention is to put ^shr(^#^)^ immediately after the mag() request
   (if present) or at the start of the text otherwise. The # corresponds 
   roughly to the percent (of the total width) shifted to the right. 

3. Left and right texts are parsed and displayed from the top line down. 
   However, an isolated period is interpreted as meaning "write nothing 
   on this line", so you can start writing lower than the top line. The 
   height of a line is always 150% of the character height, and small
   characters will therefore need more skipping to get to a specific
   level on the graph. 

4. It is possible to use left or right texts as a legend.
   The convention is to put ^sym(^ ^)^ immediately after the mag() request
   (if present) or at the start of the text otherwise. The parens contain
   the symbols you want to associate with each word of the legend. A
   special character (the ~) is used to mean "no sym": eg ^sym(~AB)^ means
   no symbol associated with first word, A with the second, B with the third. 




Examples 
--------

Suppose the following globals have been declared before the call to graph in 
the automobile example above (these declarations might have been grouped in 
a do file):

glo hlText1 ^mag(110)^A BEAUTIFUL TITLE, LEFT ALIGNED (mag 110%) 
glo hlText2 ^shr(8)^and a sub-title, shifted to the right 
glo hlTexb1 mag(60)^shr(15)^footnote: $bb 
glo hlTexr  mag(70) . . $S_DATE . . . . . just to show the current date !
glo hlTexl  mag(80) . . . . . . . . . . . . . guess what, we're using auto
data
glo hlTexc  mag(70)GvM 

Then ^addtex^ will apply the following rules:  

top1  : magnify 110%; show title
top2  : standard mag (as stored in hlMag) move about 8% to the right
bot1  : mag 60; move about 15% to the right, display global bb
right : mag 70; skip 2 lines, show parsed date, skip 5 lines, remainder
left  : mag 80; skip 13 lines, start showing
corner: mag 70; hi there


Suppose you replace some declarations as follows:

glo repair REPAIR poor so-so ave ok good
glo hlTexl  mag(73)sym(~12345) . . . . . . . . . . . . . . . $repair
glo bb bbox(4000,3000,21000,27000,900,450,0) 


and you run
. gr mpg pri , $bb border xla(5000,10000,15000) yla s([rep78])

then the legend for the 5 symbols is shown in the left margin with the word 
LEGEND on top, no symbol in front.

If you think this looks awfully overcrowded, just think you could display 
the standard t1,t2,b1,b2,l1,l2,r1,r2 texts as well!



Author 
------
	Guy D. van Melle, university of Lausanne, Switzerland
	email: guy.van-melle@@inst.hospvd.ch


Also see
--------
	gphdt (STB-34) H.J.Newton & J.W.Hardin
	manual: [R] gph
	on-line: @gph@
	
