.\" 
.TH d.labels 1
.nh
.SH NAME
d.labels \- Create/Edit GRASS label files 
.SH SYNOPSIS
.B d.labels 
.br
.I (Not Available through
.B grass3
.I menu)
.SH DESCRIPTION
The \fId.labels\fR program allows you to interactively create and modify 
paint-label files for use with the \fIpaint map\fR, \fIPmap[2P]\fR, and
\fIDpaint.labels[2D]\fR programs.  Paint-label files that you create 
will be stored in your mapset.  \fId.labels\fR requires the use 
of the graphics display.  Before running \fId.labels\fR, you should 
plot a cell-file and/or a vector-file on the graphics display for use as
a visual reference as the labels are placed.  Once you have started 
d.labels and have chosen a label file name you will then be asked to
indicate label positions on the map display with the mouse-pointer, and
to edit label parameters that define the label's size, color, and other
characteristics through use of a visual-ask (VASK) data entry screen.

.SH USER PROMPTS

You will first be prompted to enter the name of either an old paint-labels
file that you wish to modify, or a new paint-labels file that you wish
to create.  The following is the file name prompt:

.in +5
.nf
Enter the name of an existing labels file
Enter \fBlist\fR for a list of existing labels files
Hit \fBRETURN\fR to cancel request
>
.fi
.in -5


For a new paint-label file, you will be prompted to indicate a
location on the graphics display for the first label.  Once you have

.in +5
.nf
Mouse Buttons
 Left:    Place Label Here
 Middle:  Where Am I ?
 Right:   Quit
.fi
.in -5

indicated a position, you will be presented with a data-entry screen
(also known as a VASK screen) so that you can enter the paint-label
parameters that define how the label will appear on the display or
on the color printer.  Once you finish entering the label-parameters,
and you hit the <ESC> key to proceed, the label will be displayed on
the screen.  If you like the appearance of the label, enter "y" to the
"Look OK?" prompt, if not, enter "n" and you will be presented with the
data entry screen again.  Once you approve the label's appearance
you will be asked to indicate the position of the next label.

For an old paint-label file, you will be shown the labels in the file
one at a time.  For each label, you will be asked "Look OK?"  If you
answer "n" to the "Look OK?" prompt, you will be presented with the
data entry screen so that you may modify the appearance of the label
to your liking.

On-Line help is available.  If you are puzzled about what should go 
in a data entry field, just enter "help" in that field, hit the <ESC>
key, and you will be presented with a short description of the field 
and what you may enter.

The Following is a list of the different fields in the data entry screen
and and a short description of each one.

.in +5
\fBTEXT\fR:
The user can enter up to four lines of text.

\fBSKIP\fR:
yes/no. If \fIno\fR, label will be printed.
If \fIyes\fR, the label will be retained in the file but not printed.

\fBLOCATION\fR:
Determines where the text will be located on the image.
The user specifies the easting and northing, and (optionally) specifies
a vertical and horizontal offset (in printer pixels) from the
specified easting/northing. (The vertical offset will shift the location
to the south if positive, north if negative. The horizontal offset
will shift the location east if positive, west if negative.) These
offsets are provided to allow finer placement of labels.

\fBRESET LOCATION\fR:
yes/no.  If \fIyes\fR, the user will be allowed to use the mouse to 
select a new location for the label.  The mouse buttons will function
as follows:

.in +5
.nf
Mouse Buttons
 Left:    Place Label Here
 Middle:  Where Am I ?
 Right:   Quit
.fi
.in -5

\fBPLACEMENT\fR:
Determines which part of the label to which the location refers.
This may be specified as:

.in -5
.nf
	lower left	(lower left corner of the text)
	lower right	(lower right corner of the text)
	lower center	(bottom center of the text)

	upper left	(upper left corner of the text)
	upper right	(upper right corner of the text)
	upper center	(top center of the text)

	center	(center of the text)
.fi
.in +5

\fBTEXT SIZE\fR:
This determines the size of the letters. The size specifies
the vertical height of the letters in meters
on the ground. Thus text will
grow or shrink depending on the scale at which the map is drawn.

\fBTEXT COLOR\fR:
This selects the text color.
This color can be specified in one of four ways:

.in +3
.ti -3
1) By color name:
.br
aqua
black
blue
brown
cyan
gray
green
grey
indigo
magenta
orange
purple
red
violet
white
yellow

.ti -3
2) As red, green, blue percentages.
for example: .5 .4 .7
.br
(This form is not supported by \fIDpaint.labels[2D]\fR.)

.ti -3
3) By printer color number to get the exact printer color.
.br
(This form is not supported by \fIDpaint.labels[2D]\fR.)

.ti -3
4) Specify
\fInone\fR
to suppress the lettering.
.in

\fBWIDTH\fR:
This determines the line thickness of the letters.
The normal text width should be set to 1.  Larger numbers
can be used to simulate bold face. (\fIDpaint.labels[2D]\fR ignores
this value and always uses 1.)

\fBHIGHLIGHT COLOR\fR:
The text can be highlighted in another color so that it appears to be
in two colors. The text is drawn first in this color at a wider line
width, and then redrawn in the text color at the regular line width.
Highlight colors are not shown on the graphics display, they are
only shown in the output out paint and Pmap.

\fBHIGHLIGHT WIDTH\fR:
Specifies how far from the text lines (in pixels) the highlight
color should extend.
Highlight colors are not shown on the graphics display, they are
only shown in the output out paint and Pmap.

\fBBACKGROUND COLOR\fR:
Text may be boxed in
a solid color by specifying a background
color (see TEXT COLOR above to specify a color).
Specify
\fInone\fR
for no background.

\fBOPAQUE TO VECTORS\fR:
\fIyes/no\fR. This field only has meaning if a background color is selected.
\fIyes\fR will prevent vector lines from entering the background.
\fIno\fR will allow vector lines to enter the background.

\fBBORDER COLOR\fR:
Select a color for the border around the background.
Specify
\fInone\fR
to suppress the border.
.in -5

.RE
.SH "SEE ALSO"
.nf
Dpaint.labels
Pmap
paint
.fi 

.SH AUTHOR
.nf 
Dave Johnson
DBA Systems, Inc.
10560 Arrowhead Drive
Fairfax, Virginia 22030
