p.map.new(1)	       Grass User's Manual	     p.map.new(1)



NNAAMMEE
       _p_._m_a_p_._n_e_w - Color map output utility.

       _(_G_R_A_S_S _H_a_r_d_c_o_p_y _O_u_t_p_u_t _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       pp..mmaapp..nneeww

       pp..mmaapp..nneeww [iinnppuutt= _n_a_m_e] [ssccaallee= _m_a_p_s_c_a_l_e]

DDEESSCCRRIIPPTTIIOONN
       The  _p_._m_a_p_._n_e_w command produces color maps for output on a
       color hardcopy device or a graphics  monitor.  Output  can
       include	a raster map, any number of vector overlays, site
       data, text labels, and other map elements.

       This command has three modes of	operation.  The  command-
       line  mode  requires a previously prepared file of mapping
       instructions describing the map elements  to  be  printed.
       The  interactive  mode  (i.e.,  no command-line arguments)
       will prompt the user for items to be mapped and	does  not
       require	the  user  to prepare a file of instructions. The
       keyboard mode is started by entering a hyphen (	-  )  for
       the iinnppuutt parameter. The _p_._m_a_p_._n_e_w instructions would then
       be entered via the keyboard.

       The command-line parameters are:

       iinnppuutt=_n_a_m_e
	   File containing mapping instructions (or enter iinnppuutt=--
	   to	enter  instructions  from  the	keyboard).  These
	   instructions are described in detail below.

       ssccaallee=_m_a_p_s_c_a_l_e
	   Scale of the output map, e.g. 1:25000

	   Default: 1 panel

	   The options for this parameter are  identical  to  the
	   _s_c_a_l_e  mapping instruction described below. If a _s_c_a_l_e
	   instruction is present in an input file, it is  super-
	   seded by the command-line ssccaallee parameter.


       An  output  device  can	be selected using _p_._s_e_l_e_c_t before
       running _p_._m_a_p_._n_e_w. Valid devices include on-line  hardcopy
       devices, plus _p_r_e_v_i_e_w_, _p_r_e_v_i_e_w_2, and _p_p_m. See manual entry
       for _p_._s_e_l_e_c_t.

       The current geographic region determines the area that  is
       mapped using _p_._m_a_p_._n_e_w

NNOONN--IINNTTEERRAACCTTIIVVEE MMAAPPPPIINNGG IINNSSTTRRUUCCTTIIOONNSS
       Mapping instructions allow the user to specify various map
       elements to be plotted. These  instructions  are  normally
       prepared  in an ASCII text file using a system editor. All
       of the listed mapping instructions are usable  in  a  pre-
       pared  file  in the command-line mode. Not all of them are
       available in the interactive and keyboard modes.

       Some instructions are single line instructions while  oth-
       ers  are multiple line. Multiple-line instructions consist
       of the main instruction followed by a subsection of one or
       more  additional  instructions. All multiple-line instruc-
       tions must be completed by the eenndd terminator.

       Some instructions, such as those using data layers, icons,
       or  labels,  access  files  via	the current mapset search
       path.

bbaarrssccaallee
       Places a barscale on the output map.

	       bbaarrssccaallee  x_% y_%
	       uunniitt  _f_t| _m_i| _m| _k_m
	       lleennggtthh  #
	       iinntteerrvvaall  #
	       ssttyyllee  _d_a_s_h| _t_i_c_k
	       wwiiddtthh  #
	       ccoolloorr  color
	       tteexxttssiizzee  #
	       tteexxttccoolloorr  color| _n_o_n_e
	       tteexxttffoonntt  font
	       bbaacckkggrroouunndd  color| _n_o_n_e
	       bboorrddeerr  color| _n_o_n_e
	       eenndd


       The location of the zero point of the scale bar is entered
       on the first instruction line. The location can be defined
       either by map coordinates or by	percentages  of  the  map
       area, where 0% 0% is the lower left corner of the map.

       The  user  specifies the barscale uunniitt of measurement, the
       total lleennggtthh using that unit, and the length of one iinntteerr--
       vvaall  (a	smaller  length  evenly  divisible into the total
       length).

       The ssttyyllee of the scale bar  can	be  specified.	The  _d_a_s_h
       style  has  solid  lines representing each interval, sepa-
       rated by gaps. The _t_i_c_k style has  a  solid  total  length
       with vertical ticks marking each interval.

       The  user can also specify the wwiiddtthh of the bar in pixels,
       its ccoolloorr (see VALID COLORS NAMES), the	tteexxttccoolloorr,  tteexxtt--
       ssiizzee in geographic units, tteexxttffoonntt (see VALID FONT NAMES),
       bbaacckkggrroouunndd color, and bboorrddeerr color.

       The bbaarrssccaallee instruction set must be  completed	with  the
       eenndd terminator.

       This  example would result in a scale bar representing two
       kilometers.  Vertical ticks would be placed at  the  scale
       origin,	the  mid-point, and at the end. The black bar and
       its accompanying black text  would  overlay  a  white  box
       trimmed be a red border.

	       bbaarrssccaallee  605000 4915000
	       uunniitt  km
	       lleennggtthh  2
	       iinntteerrvvaall  1
	       ssttyyllee  tick
	       wwiiddtthh  2
	       ccoolloorr  black
	       tteexxttccoolloorr  black
	       tteexxttssiizzee  150
	       bbaacckkggrroouunndd  white
	       bboorrddeerr  red
	       eenndd


ccoolloorrmmooddee
       Selects the method to portray the colors of the raster map
       layer or image.

       There are two options for ccoolloorrmmooddee: _a_p_p_r_o_x and _b_e_s_t.
       The
       _a_p_p_r_o_x option should be used for raster	map  layers  with
       few
       categories, and
       _b_e_s_t should be used for images like LANDSAT images
       or NHAP photos, or maps with very many categories. The
       _a_p_p_r_o_x mode
       treats  each  pixel  independently,  giving it the printer
       color that best
       approximates the true color. The
       _b_e_s_t mode "blends" colors from
       pixel to pixel using a  dithering  technique  to  simulate
       more colors than
       the  printer  can  actually  print.  If	unspecified,  the
       default is
       _b_e_s_t_.

       This example would select the
       _a_p_p_r_o_x colormode. The assumption
       is that the raster map layer being printed has few  colors
       or that the colors
       would not look good dithered.

	       ccoolloorrmmooddee  approx


ccoolloorrttaabbllee
       Includes  the  color table for the raster map layer in the
       area below the
       map on hardcopy output.

       The color table will display the colors	for  each  raster
       map layer category
       and the category value. The ccoolloorrttaabbllee instruction can not
       precede
       the rraasstteerr instruction in the
       _p_._m_a_p_._n_e_w input. The color
       table is not shown when the output  device  is  the  color
       monitor.

       The  user  should be careful about asking for color tables
       for raster
       map layers that have very many categories, such as an ele-
       vation layer.
       This could result in the printing of an extremely long and
       generally useless
       color table!

       This example would print a color table below the data area
       of the map.

	       ccoolloorrttaabbllee  y


ccoommmmeennttss
       Prints comments beneath the map on hardcopy output.

	       comments
	       eenndd
       Comment text can be entered in the
       _p_._m_a_p_._n_e_w file or from a separate,
       previously  prepared file. Comments are not shown when the
       output device
       is the color monitor. The ccoommmmeennttss instruction set must be
       completed
       by the eenndd terminator.

       This  example prints the comment "This is a comment" below
       the data area
       on the the map.

	       ccoommmmeennttss
	       This is a comment.
	       eenndd
       This example prints the text in a  file	called	"veg.com-
       ments" in the current
       directory.

	       rraasstteerr  vegetation
	       ccoommmmeennttss  veg.comments
	       eenndd


ddeeffppaatt
       Defines an area fill pattern to be used in sseettppaatt instruc-
       tions.

	       pattern
	       ccoolloorr  #  color
	       eenndd
       An area fill  pattern  is  given  a  name  on  the  ddeeffppaatt
       instruction line.
       This  name  can then be used in subsequent _s_e_t_p_a_t instruc-
       tions. The
       ddeeffppaatt instruction can be used more than once  to  specify
       multiple
       patterns.

       The specified pattern is composed of a sequence of numbers
       (0-9, and
       blanks, which are equivalent to 0) on one or  more  lines.
       The zeros and
       blanks indicate areas in the pattern where the normal cat-
       egory colors are
       visible. The other digits, 1-9,	indicate  pattern  pixels
       and can be assigned
       any valid color.

       The  ccoolloorr  option  specifies a non-zero digit in the pat-
       tern, followed
       by a valid color name. It can be repeated for each of  the
       non-zero digits
       in  the pattern. The default color for all non-zero digits
       is black unless
       specified with the ccoolloorr option.

       The ddeeffppaatt instruction set must be completed by the eenndd
       terminator.

       In the _p_._m_a_p_._n_e_w input, the ddeeffppaatt instruction  must  pre-
       cede
       any sseettppaatt instruction using the specified pattern.

       NNoottee::  Indented pattern specifications will be interpreted
       as
       having leading blanks.

       This example  creates  a  black	horizontal  line  pattern
       called "horiz".
       Each black line in the pattern would be one pixel wide and
       would be three
       pixels from neighboring lines.

	       ddeeffppaatt  horiz
	       1
	       0
	       0
	       0
	       ccoolloorr  1 black
	       eenndd
       This example creates a green vertical line pattern.

	       ddeeffppaatt  vert
	       1000
	       ccoolloorr  1 green
	       eenndd
       The following example creates a red diagonal line pattern.

	       ddeeffppaatt  diag
	       00001
	       0001
	       001
	       01
	       1
	       ccoolloorr  1 red
	       eenndd
       This  example creates a two-toned tree pattern with orange
       "trunks" and
       green "leaves".

	       ddeeffppaatt  tree
		    2
		   222
		  22122
		 22 1 22
		     1


			      2
			     222
			    22122
			   22 1 22
			       1
	       ccoolloorr  1 orange
	       ccoolloorr  2 black
	       eenndd


eenndd
       Terminates input and begins the painting of the map to the
       output device.

       An   eenndd   instruction	completes  the	entire	input  to
       _p_._m_a_p_._n_e_w.
       It is normally the last line in an input file, but it  can
       be moved forward
       to eliminate any instructions following its position.

       The  eenndd  instruction  for  the entire input should not be
       confused
       with eenndd terminators that are required with all	multiple-
       line instruction
       sets.

eennddppaanneell
       Specifies  which panel number to end printing. The default
       is 0, and will
       print all panels from the startpanel to the last panel.

	       eennddppaanneell 4
       This example would end output at panel 4.

ggrriidd
       Overlays a coordinate grid on the output map.

	       ppaatttteerrnn	_n_o_t_i_c_k| _t_i_c_k # #
	       mmaasskkeedd  [_d_a_t_a| _n_o_d_a_t_a| _a_l_l]
	       ssttyyllee  sequence
	       wwiiddtthh  #
	       ccoolloorr  color
	       nnuummbbeerrss	#  [color] [_i_n| _o_u_t]
	       nnuummbbeerrssbbgg  color| _n_o_n_e
	       nnuummbbeerrssiizzee  #
	       eenndd
       The spacing of the grid in  geographic  coordinate  system
       units must be be
       specified  on  the  first  instruction  line. The user can
       specify the overall
       look of the grid using the ppaatttteerrnn parameter. The
       _n_o_t_i_c_k
       option is for a complete net of	intersecting  lines.  The
       _t_i_c_k option
       is  for smaller tick marks where grid intervals intersect.
       The horizontal
       and vertical lengths, in pixels, must  be  specified  with
       the _t_i_c_k
       option.

       The  user  can  control	the  areas covered by the grid by
       using the
       mmaasskkeedd
       parameter. With the _d_a_t_a option of mmaasskkeedd, the grid will
       be seen over all areas of the map's  raster  layer  except
       the no-data (category
       0)  areas.  With  the _n_o_d_a_t_a option, the grid will be seen
       only over
       the no-data areas. The entire grid is seen  with  the  _a_l_l
       option to
       mmaasskkeedd.

       The grid line ssttyyllee can be specified using a series of 1's
       and
       0's. The 1's represent the visible dashes and the 0's rep-
       resent gaps between
       the dashes. The default is solid lines. The wwiiddtthh (in pix-
       els) and
       ccoolloorr of the grid lines can also be specified.

       The user can control the placement and look of grid  label
       numbers using
       the nnuummbbeerrss, nnuummbbeerrssbbgg, and nnuummbbeerrssiizzee parameters.
       The  nnuummbbeerrss  parameter is used to include grid labels, to
       specify
       which labels should be shown (where 1 is every grid label,
       2 is every other
       grid  label,  etc.), and to specify the label color. It is
       also used to place
       the labels inside or outside the current region. The back-
       ground color behind
       each  label  is	specified by the nnuummbbeerrssbbgg parameter. The
       user controls
       the grid label size using  the  nnuummbbeerrssiizzee  parameter,  in
       geographic
       units.

       The ggrriidd instruction set must be concluded by the eenndd
       parameter.

       When used in a metric location, this example would produce
       grid ticks
       every 5000 meters. The purple ticks would have "arms"  ten
       pixels long and
       would be visible over the entire map area. The purple grid
       numbers would
       be 350 meters high (to scale), inside the  current  region
       map area, and
       have  no background color. A grid label would appear every
       5000 meters.

	       ggrriidd  5000
	       ppaatttteerrnn	tick 10 10
	       mmaasskkeedd  all
	       wwiiddtthh  1
	       ccoolloorr  purple
	       nnuummbbeerrss	1 purple in
	       nnuummbbeerrssbbgg  none
	       nnuummbbeerrssiizzee  350
	       eenndd
       The following example would produce black grid lines every
       1000 meters.
       The  lines  would be visible only in the areas of category
       0, and they would
       be dashed, with one long dash for every short  gap.  Every
       other grid label
       would be shown, each with a white background.

	       ggrriidd  1000
	       ppaatttteerrnn	notick
	       mmaasskkeedd  nodata
	       ssttyyllee  11111100
	       wwiiddtthh  1
	       ccoolloorr  black
	       nnuummbbeerrss	2 black in
	       nnuummbbeerrssbbgg  white
	       nnuummbbeerrssiizzee  200
	       eenndd


llaabbeellss
       Selects a labels file for output.

       The  llaabbeellss instruction includes previously prepared label
       specifications.
       See manual entry for
       _p_._l_a_b_e_l_sfor correct
       format of the labels file. The labels file must be  acces-
       sible via the current
       mapset  search  path. The _l_i_s_t option is available in key-
       board mode.

       This example would paint labels from a labels file called
       _t_o_w_n_._n_a_m_e_s.

	       llaabbeellss  town.names


lleeggeenndd
       Places a user-designed map legend on the output.

	       lleeggeenndd  x_% y_%
	       hheeiigghhtt  #
	       wwiiddtthh  #
	       vvlleenn  #
	       tteexxttccoolloorr  color
	       tteexxttssiizzee  #
	       tteexxttwwiiddtthh  #
	       xxssppaaccee  #
	       yyssppaaccee  #
	       bbaacckkggrroouunndd  color
	       bboorrddeerr  color
	       bbeeggiinnrraasstt
	       rraammpp  _v_a_l_u_e| _l_a_b_e_l _v_e_r_t_i_c_a_l| _h_o_r_i_z_o_n_t_a_l
	       ccaattnnuumm  cat description
	       eenndd
	       bbeeggiinnvveecctt
	       vveeccttnnaammee  vectormap description
	       vveeccttTTIITTLLEE  vectormap
	       eenndd
	       bbeeggiinnssiittee
	       ssiitteennaammee  sitemap description
	       eenndd
	       eenndd
       The location of the upper left corner of the  legend  must
       be entered on
       the  first  instruction	line. The location can be defined
       either by map coordinates
       or by percentages of the map area,  where  0%  0%  is  the
       lower left corner
       of the map.

       The user specifies the hheeiigghhtt and wwiiddtthh of the boxes that
       will  show  raster  category  colors  and/or patterns. The
       length of line segments
       that will show vector line colors and patterns  is  speci-
       fied with the vvlleenn
       parameter.  The	user  controls horizontal spacing between
       legend symbols
       and legend text using xxssppaaccee. The yyssppaaccee parameter is used
       to control vertical spacing between legend symbols. All of
       these measurements
       are in pixels.

       The user designs the  legend  text  using  the  tteexxttccoolloorr,
       tteexxttssiizzee,
       and
       tteexxttwwiiddtthh parameters. Colors are listed in the VALID COLOR
       NAMES
       section of this manual entry. The tteexxttssiizzee is specified in
       pixels.
       The tteexxttwwiiddtthh is also specified in pixels.

       The user can specify the color for the bbaacckkggrroouunndd box con-
       taining
       the entire legend. If a color is  chosen,  underlying  map
       elements are opaqued.
       The  user  can  also specify a bboorrddeerr color for the legend
       box.

       The user specifies the symbols to be included in the  leg-
       end using the
       bbeeggiinnrraasstt,
       bbeeggiinnvveecctt, and bbeeggiinnssiittee parameters. Each of these parame-
       ters
       starts a subsection of the lleeggeenndd instruction that must be
       completed
       by  an  eenndd  terminator. These should not be confused with
       the eenndd
       terminator for the entire lleeggeenndd instruction set.

       If the user simply uses the bbeeggiinnrraasstt  parameter  followed
       by eenndd,
       all  categories of the map's raster layer will be shown in
       individual boxes,
       and the legend labels will be the  corresponding  category
       names in the layer's
       _c_a_t_s  file.  The  user can include specific categories and
       optional
       labels by using one or more ccaattnnuumm lines, each including a
       category
       number  and  the  accompanying  legend  text. If the map's
       raster layer portrays
       a continuous range of data, a rraammpp in the legend might  be
       appropriate.
       The  rraammpp can be vertical or horizontal, and it's accompa-
       nying text
       can be either the smallest and largest category values, or
       the _c_a_t_s
       labels  associated  with  the  smallest	and largest cate-
       gories. The bbeeggiinnrraasstt
       subsection must be completed with an eenndd terminator.

       Symbols for vector data on the map can be included in  the
       legend by
       using  the bbeeggiinnvveecctt parameter. If the user simply follows
       bbeeggiinnvveecctt
       with eenndd, all vector layers in the map will be included in
       the legend.
       The  user can include specific vector layers in the legend
       by using the
       vveeccttnnaammee
       line one or more times, each including a vector layer name
       and an accompanying
       description. The vector layer TITLEs as written in
       _d_i_g___c_a_t_s files
       can  be included as the legend text by using the vveeccttTTIITTLLEE
       line one
       or more times. The bbeeggiinnvveecctt subsection must be	completed
       with an
       eenndd terminator.

       Site  symbols  are  included in the legend by using one or
       more ssiitteennaammee
       lines in the bbeeggiinnssiittee subsection. Each line includes  the
       name of
       the  site list and an accompanying description. The bbeeggiinn--
       ssiittee subsection
       must be completed with an eenndd terminator.

       The entire lleeggeenndd instruction set must be completed by  an
       eenndd
       terminator.

       In the _p_s_._m_a_p_._n_e_w input, the lleeggeenndd instruction can not
       precede	the instructions for any of the map elements that
       are to be shown
       in the legend.

       This example would produce a legend with five  symbols:	a
       point symbol,
       the colors and patterns for three raster categories, and a
       line representing
       one vector layer, in that order.  The  background  of  the
       legend would be
       white and surrounded by a red border. All text in the leg-
       end would be black.

	       lleeggeenndd  589000 4921200
	       hheeiigghhtt  10
	       wwiiddtthh  20
	       vvlleenn  20
	       xxssppaaccee  10
	       yyssppaaccee  7
	       tteexxttccoolloorr  black
	       tteexxttssiizzee  250
	       tteexxttwwiiddtthh  1
	       bbaacckkggrroouunndd  white
	       bboorrddeerr  red
	       bbeeggiinnssiittee
	       ssiitteennaammee  archsites Arch. site
	       eenndd
	       bbeeggiinnrraasstt
	       ccaattnnuumm  4 Sandstone
	       ccaattnnuumm  5 Limestone
	       ccaattnnuumm  6 Shale
	       eenndd
	       bbeeggiinnvveecctt
	       vveeccttnnaammee  roads Road
	       eenndd
	       eenndd
       The following example would produce a legend with a verti-
       cal ramp showing
       all  the  colors  in the map's raster layer. The labels of
       the first and last
       categories would be included.

	       lleeggeenndd  589000 4921200
	       hheeiigghhtt  10
	       wwiiddtthh  20
	       xxssppaaccee  10
	       tteexxttccoolloorr  black
	       tteexxttssiizzee  250
	       tteexxttwwiiddtthh  1
	       bbaacckkggrroouunndd  gray
	       bboorrddeerr  black
	       bbeeggiinnrraasstt
	       rraammpp  label vertical
	       eenndd
	       eenndd


lliinnee
       Draws a line that is independent of any vector  map  layer
       on the output
       map.

	       lliinnee  x_% y_% x_% y_%
	       ssttyyllee  sequence
	       ccoolloorr  [# ] color
	       wwiiddtthh  #
	       hhccoolloorr  color
	       hhwwiiddtthh  #
	       mmaasskkeedd  [_y| _n]
	       eenndd
       The beginning and ending points of the line are entered on
       the main instruction
       line. These points can be defined either  by  map  coordi-
       nates or by using
       percentages  of	the geographic region, where 0% 0% is the
       lower left corner
       of the map.

       The default line style is a continuous,	solid  line,  but
       the user can
       specify a dashed line using the ssttyyllee parameter. The ssttyyllee
       parameter can contain a sequence of digits (0-9) that rep-
       resent a colored
       pattern	on  the  desired  line. Colors can be assigned to
       each non-zero digit
       by using the ccoolloorr parameter multiple times. If the ccoolloorr
       parameter is used without a  specified  digit,  the  named
       color will be assigned
       to  the	entire line. Colors are listed in the VALID COLOR
       NAMES section
       in this manual entry.

       The user can specify line wwiiddtthh	in  pixels.  A	highlight
       color
       can  be assigned with hhccoolloorr, and the highlight's width in
       pixels
       can be assigned with hhwwiiddtthh. The user can also specify  if
       the line
       is to be
       mmaasskkeedd  by the current mask. (See manual entry for _r_._m_a_s_k_-
       for
       more information on the mask.)

       The lliinnee instruction set must be completed by an eenndd  ter-
       minator.

       The  lliinnee instruction can be used more than once to create
       multiple
       lines.

       This example would draw a blue line from the point x=  10%
       y= 80% to
       the point x= 30% y= 70%. The line would be two pixels wide
       and would appear
       even if there is a mask.

	       lliinnee  10% 80% 30% 70%
	       ccoolloorr  blue
	       wwiiddtthh  2
	       mmaasskkeedd  n
	       eenndd
       The following example would draw a line with yellow dashes
       on a black background.

	       lliinnee  605000 4915000 595300 4918200
	       ssttyyllee  1111100
	       ccoolloorr  1 yellow
	       wwiiddtthh  1
	       hhccoolloorr  black
	       hhwwiiddtthh  1
	       eenndd


oouuttlliinnee
       Outlines  areas	of  a  raster  map layer with a specified
       color.

	       ccoolloorr  color
	       eenndd
       The oouuttlliinnee instruction can be  used  to  place	a  border
       around all
       contiguous  groups  of  same-value  cells  in a raster map
       layer. A valid color
       name can be specified with the optional	ccoolloorr  parameter.
       The default
       color is black.

       The oouuttlliinnee instruction set must be completed by the
       eenndd
       terminator, even if the ccoolloorr parameter is not used.

       The  oouuttlliinnee instruction can not precede a rraasstteerr instruc-
       tion
       in a _p_._m_a_p_._n_e_w input file.

       The instruction sequence in this example would outline  in
       grey the category
       areas of a raster map layer called "soils".

	       rraasstteerr  soils
	       oouuttlliinnee
	       ccoolloorr  grey
	       eenndd


ppooiinntt
       Places a point symbol on the output map.

	       ppooiinntt  x_% y_%
	       iiccoonn  iconfile| _l_i_s_t
	       ccoolloorr  color
	       ssiizzee  #
	       mmaasskkeedd  [_y| _n]
	       eenndd
       The  user  enters  a  point  symbol  location  on the main
       instruction line. The
       location can be defined either by map  coordinates  or  by
       percentages of
       the  map area, where 0% 0% is the lower left corner of the
       map.

       The icon to be used can be specified with the iiccoonn parame-
       ter.
       The user can use any icon in an _i_c_o_n_s directory within the
       current
       mapset search path. Icons can be created using _p_._i_c_o_n_sor
       by simply using a system editor. The  default  icon  is	a
       diamond. The _l_i_s_t
       option for iiccoonn is available in keyboard mode.

       The  user  can specify the symbol ccoolloorr. Colors are listed
       in the
       VALID COLOR NAMES section of this manual entry.

       The icon ssiizzee is a positive, floating-point scaling factor
       of
       the pattern in the icon file. A size of 1 produces an icon
       with the same
       number of pixels (at the output	device's  resolution)  as
       ASCII characters
       in the icon file.

       The  user  can also specify whether the point symbol is to
       be mmaasskkeedd
       by the current mask. (See manual entry for _r_._m_a_s_kfor
       more information on the mask.)

       The ppooiinntt instruction set must be completed be an eenndd
       terminator. Multiple points may be drawn with multiple
       ppooiinntt instructions.

       This example would access an icon file called "box" within
       the current
       mapset  search path. The red box symbol would be placed at
       the point E603000,
       N4921750. The box would have the same number of pixels  as
       characters in
       the icon file. It would not be masked by the current mask.

	       ppooiinntt  603000 4921750
	       iiccoonn  box
	       ccoolloorr  red
	       ssiizzee  1
	       mmaasskkeedd  n
	       eenndd


rraasstteerr
       Selects a raster map layer for output.

       Only one GRASS raster map layer	can  be  specified  in	a
       _p_._m_a_p_._n_e_w
       input  file.  If no raster map layer is requested, a white
       background will
       be produced. The _l_i_s_t  option  is  available  in  keyboard
       mode.

       The  raster  layer  must  be accessible within the current
       mapset search
       path. In a _p_._m_a_p_._n_e_w input file,  the  rraasstteerr  instruction
       must
       precede these instructions: ccoolloorrttaabbllee,
       oouuttlliinnee, sseettccoolloorr,
       and  sseettppaatt.  It  also must precede any lleeggeenndd instruction
       set
       that applies to the raster map layer.

       This example would paint a map of  the  raster  map  layer
       _s_o_i_l_s.

	       rraasstteerr  soils


rreeaadd
       Provides  input	to  _p_._m_a_p_._n_e_w  from a previously prepared
       instruction
       file.

       Mapping instructions can be placed in a file and  read  as
       input to
       _p_._m_a_p_._n_e_w_.
       If  a certain set of mapping instructions are used in many
       different maps,
       they can be placed in one separate  file  and  efficiently
       accessed by each
       map's instructions using the rreeaadd instruction.

       Note:  _p_._m_a_p_._n_e_w  will not search for the file to be read.
       The
       file must be in the current directory or a full path needs
       to be specified
       on the rreeaadd instruction line. (Note to /bin/csh users: the
       tilde
       [ ~ ] path alias will not work with this instruction).

       This  example  reads  the  ASCII  file  "pmap.roads"  into
       _p_._m_a_p_._n_e_w.

	       rreeaadd  pmap.roads


rreeggiioonn
       Places  the  outline  of a geographic region on the output
       map.

	       ssttyyllee  sequence
	       ccoolloorr  [# ] color
	       wwiiddtthh  #
	       hhccoolloorr  color
	       hhwwiiddtthh  #
	       mmaasskkeedd  [_y| _n]
	       eenndd
       The user can place  the	outline  of  a	saved  geographic
       region on the map
       using rreeggiioonn. The named region file must be in a
       _w_i_n_d_o_w_s
       directory  within  the  current	mapset	search path. Geo-
       graphic region settings
       can be created and saved using _g_._r_e_g_i_o_n.
       The _l_i_s_t option is available in keyboard mode.

       The default region outline style is  a  continuous,  solid
       line, but the
       user  can specify a dashed line using the ssttyyllee parameter.
       The ssttyyllee
       parameter can contain a sequence of digits (0-9) that rep-
       resent a colored
       pattern	on  the  desired  line. Colors can be assigned to
       each non-zero digit
       by using the ccoolloorr parameter multiple times. If the ccoolloorr
       parameter is used without a  specified  digit,  the  named
       color will be assigned
       to  the	entire	region	outline. Colors are listed in the
       VALID COLOR NAMES
       section in this manual entry.

       The user can specify the region outline wwiiddtthh in pixels. A
       highlight
       color  can  be  assigned  with hhccoolloorr, and the highlight's
       width can
       be assigned with hhwwiiddtthh. The user can also specify if  the
       outline
       is to be
       mmaasskkeedd  by the current mask. (See manual entry for _r_._m_a_s_k_-
       for
       more information on the mask.)

       The rreeggiioonn instruction set must be completed by an eenndd
       terminator.

       The rreeggiioonn instruction can be used more than once to  show
       multiple
       regions.

       This  example  would  produce  a white outline, two pixels
       wide, showing
       the geographic region called "fire.zones".

	       rreeggiioonn  fire.zones
	       ccoolloorr  white
	       wwiiddtthh  2
	       eenndd


ssccaallee
       Specifies the scale of the hardcopy output map.

       The scale of the output map can be  specified  in  one  of
       several different
       forms:

       relative ratio e.g. 1:25000

       number of geographic units per map unit e.g. 1 inch equals
       4 miles

       absolute width of the printed map e.g. 10 inches

       width in number of printed panels e.g. 3 panels




       Map inches can be equated  with	these  geographic  units:
       miles, kilometers,
       and meters. Valid width units are inches, centimeters, and
       panels. One
       panel is the single-sheet maximum width available  on  the
       hardcopy medium.

       The final size of the hardcopy map output is determined by
       the combination
       of the specified scale and the current geographic  region.

       The  ssccaallee  instruction does not affect output to the _p_r_e_-
       _v_i_e_w
       device. If used, the command-line  _s_c_a_l_e  parameter  over-
       rides the
       ssccaallee instruction.

       This  example  would  set  the scale of the map to one map
       unit represents
       25,000 geographic units.

	       ssccaallee  1:25000
       The following example would specify  an	output	map  that
       would be fifteen
       centimeters wide.

	       ssccaallee  15 centimeters


sseettccoolloorr
       Overrides  the color assigned to one or more categories of
       the raster map
       layer.

       The user can assign a desired color  to	categories  in	a
       raster map layer
       by using sseettccoolloorr. Categories are specified on the parame-
       ter line
       before a valid color name. One or  more	category  numbers
       can appear on the
       parameter  line,  separated by commas (with no spaces), or
       in ranges using
       hyphens.

       The sseettccoolloorr instruction can be used more  than	once  for
       assignment
       of multiple colors.

       In the input _p_._m_a_p_._n_e_w file, the sseettccoolloorr instruction
       must follow the rraasstteerr instruction.

       Colors are listed in the VALID COLOR NAMES section of this
       manual entry.

       In this example, the color for  raster  map  categories	1
       through 3, plus
       category  5, would be set to green, categories 4, 6, and 8
       would be set
       to blue, and category 7 would be set to red, regardless of
       their assigned
       colors in the database.

	       rraasstteerr  watersheds
	       sseettccoolloorr  1-3,5 green
	       sseettccoolloorr  4,6,8 blue
	       sseettccoolloorr  7 red



sseettppaatt
       Assigns a previously defined pattern to one or more raster
       map layer categories.

	       sseettppaatt  cat(s) _#number
	       sseettppaatt  _a_l_l| _b_u_i_l_t_i_n
       The user can assign a pattern to categories  in	a  raster
       map layer by using
       sseettppaatt.	Categories  are  specified  on the parameter line
       before the
       name of a pattern defined earlier using ddeeffppaatt, or  before
       the number
       signifying a built-in
       _p_._m_a_p_._n_e_w pattern. One or more category numbers
       can  appear  on	the  parameter	line, separated by commas
       (with no spaces),
       or in ranges using hyphens.

       The built-in patterns are defined in etc/paint/patterns in
       the compiled
       GRASS   code  directory.  Each  built-in  pattern  has  an
       assigned number. These
       numbers can be used following a pound sign ( # ) on a sseett--
       ppaatt instruction
       line.  By  using  the  _b_u_i_l_t_i_n  option, each category in a
       raster map
       layer can be assigned the correspondingly numbered builtin
       pattern.

       All raster map categories can be assigned the same defined
       pattern if
       the _a_l_l option is used. In this	case,  only  one  pattern
       should be
       defined within the _p_._m_a_p_._n_e_w mapping instruction file.

       The  sseettppaatt  instruction  can  be  used more than once for
       assignment
       of multiple patterns.

       In the input _p_._m_a_p_._n_e_w file, the sseettppaatt instruction must
       follow the rraasstteerr instruction, as well as the
       ddeeffppaatt instruction
       defining the pattern that is used.

       This example assigns a pattern called "vert" to categories
       3 and 4 of
       the  raster  map  layer	"vegetation" and a pattern called
       "tree" to category
       10.

	       rraasstteerr  veg
	       sseettppaatt  3-4 vert
	       sseettppaatt  10 tree
       This example reads a previously prepared ASCII file called
       _h_o_r_i_z_._p_a_t
       containing
       ddeeffppaatt instructions for creating a black, horizontal
       pattern	called "horiz", and assigns that pattern to cate-
       gory 5 of the raster
       map layer "soils".

	       rraasstteerr  soils
	       rreeaadd  horiz.pat
	       sseettppaatt  5 horiz
       This example assigns built-in pattern 1 to category  1  of
       the "soils" raster
       layer, pattern 2 to category 2, and so on.

	       rraasstteerr  soils
	       sseettppaatt  builtin
       This  example  assigns  built-in pattern 1 to categories 5
       through 7 in the
       "soils" raster map layer, and built-in pattern 2 to  cate-
       gories 10 and 12.

	       rraasstteerr  soils
	       sseettppaatt  5-7 # 1
	       sseettppaatt  10,12 # 2


ssiitteess
       Selects sites data to be placed on the output map.

	       iiccoonn  iconfile| _l_i_s_t
	       ccoolloorr color
	       ssiizzee  #
	       ddeesscc  [_y| _n]
	       tteexxttccoolloorr  color
	       tteexxttssiizzee  #
	       eenndd
       GRASS sites data can be portrayed on the map using the
       ssiitteess instruction.
       The  user  can  specify	the  point symbol to be used, and
       whether labels are
       to appear next to the symbols.  The  sites  data  must  be
       accessible via the
       current	mapset	search path. The _l_i_s_t option is available
       in keyboard
       mode.

       An icon can be specified with the iiccoonn parameter. The user
       can
       use  any  icon  in  an  _i_c_o_n_s directory within the current
       mapset search
       path. Icons can be created using _p_._i_c_o_n_sor
       by simply using a system editor. The  default  icon  is	a
       diamond. The _l_i_s_t
       option for iiccoonn is available in keyboard mode.

       The  user  can specify the symbol ccoolloorr. Colors are listed
       in the
       VALID COLOR NAMES section of this manual entry.

       The icon ssiizzee is a positive, floating-point scaling factor
       of
       the pattern in the icon file. A size of 1 produces an icon
       with the same
       number of pixels (at the output	device's  resolution)  as
       ASCII characters
       in the icon file.

       The  ddeesscc  parameter is used to specify whether or not the
       description
       of each site in the _s_i_t_e___l_i_s_t_s file is also to be printed.
       These
       labels will appear directly to the right of each site sym-
       bol. The user
       controls the color  of  the  labels  using  the	tteexxttccoolloorr
       parameters.
       Valid  colors  are  listed  in the named colors section of
       this manual entry.
       The label size is  specified  in  geographic  units  using
       tteexxttssiizzee.

       The ssiitteess instruction set must be completed by the
       eenndd
       terminator.

       This  instruction  can  be  used more than once to portray
       multiple site
       lists.

       This example would produce point symbols representing  the
       data in a
       _s_i_t_e___l_i_s_t_s  file called "windmills". An icon called "wind-
       mill" would
       be placed at each site location. These  symbols	would  be
       two times larger
       than  the size of the icon in the icon file (twice as many
       pixels as there
       are characters in the icon file).  Descriptions	from  the
       sites list file
       would not be produced in this example.

	       ssiitteess  windmills
	       iiccoonn  windmill
	       ccoolloorr  blue
	       ssiizzee  2
	       ddeesscc  n
	       eenndd


ssttaarrttppaanneell
       Specifies at which panel number to begin printing. Default
       is 0 and would
       start printing from the first panel.

	       ssttaarrttppaanneell 2
       This example would begin printing at panel 2.

tteexxtt
       Places text at a user-specified location on the map.

	       tteexxtt  x_% y_%  text
	       tteexxttffoonntt  font
	       ssiizzee  #
	       ccoolloorr  color| _n_o_n_e
	       wwiiddtthh  #
	       hhccoolloorr  color| _n_o_n_e
	       hhwwiiddtthh  #
	       rreeff  reference_point
	       rroottaattiioonn  #
	       xxooffffsseett	#
	       yyooffffsseett	#
	       bbaacckkggrroouunndd  color| _n_o_n_e
	       ooppaaqquuee  [_y| _n]
	       bboorrddeerr  color| _n_o_n_e
	       eenndd
       The user specifies where text will be placed by	providing
       map coordinates
       or  percentages	of the map area, where 0% 0% is the lower
       left corner of
       the map. The text follows the  locational  information  on
       the same instruction
       line.  Multiple lines of text can be specified by notating
       the end of a
       line with
       \\nn (e.g., USA\nCERL). Leading blanks an be inserted
       by preceding the text string  with  a  backslash  and  the
       blanks (e.g., text
       600000 4920500\ See\nWall Drug ).

       The user can control the appearance of the text, its loca-
       tion, and the
       appearance of its background box.

       The user can specify tteexxttffoonntt (see  VALID  FONT	NAMES  in
       this manual
       entry), ssiizzee in geographic units,
       ccoolloorr (see VALID COLOR
       NAMES),	and wwiiddtthh in pixels. The user can further control
       the text
       appearance by specifying a highlight  color  (hhccoolloorr)  and
       the width
       of the highlight color (hhwwiiddtthh).

       The  text  is  located at the specified coordinate or per-
       centage pair in
       relation to a reference point on  the  text  string.  This
       point, specified
       with the
       rreeff parameter, has two parts. The first part refers to
       a  vertical location on the text string. Valid choices are
       _l_o_w_e_r,
       _c_e_n_t_e_r, and
       _u_p_p_e_r. The second part refers to a horizontal
       location: _l_e_f_t, _c_e_n_t_e_r, and _r_i_g_h_t.

       The text string can be rotated at the reference	point  by
       using the rroottaattiioonn
       parameter.  The value specified will be the counter-clock-
       wise rotation in
       degrees from the horizontal.

       The
       xxooffffsseett parameter provides  finer  placement  of  text  by
       shifting
       the  text  a horizontal distance in pixels from the speci-
       fied easting. The
       xxooffffsseett will shift the text location east if positive  and
       west if
       negative. The
       yyooffffsseett parameter shifts the text a vertical distance
       in pixels from the specified northing. The
       yyooffffsseett will shift the
       location to the south if positive, north if negative.

       The  user  can specify if a bbaacckkggrroouunndd box is present, and
       what
       color it should be. The user can also specify  whether  or
       not the background
       box is
       ooppaaqquuee to other map elements. The color of the bboorrddeerr
       of this box can be specified.

       This  example  would place the text "SPEARFISH LAND COVER"
       at the coordinates
       E650000, N7365000. The text would be a total of three pix-
       els wide (one
       pixel  of  red  text and one pixel of black on each side),
       have a white background
       enclosed in a red box, and  be  500  meters  in	size  (to
       scale). The lower
       left corner of the text would be placed at the coordinates
       provided. All
       other map elements would not be seen under the text.

	       tteexxtt  650000 7365000 SPEARFISH LAND COVER
	       tteexxttffoonntt  romand
	       ccoolloorr  red
	       wwiiddtthh  1
	       ssiizzee  500
	       rreeff  lower left
	       hhccoolloorr  black
	       hhwwiiddtthh  1
	       bbaacckkggrroouunndd  white
	       bboorrddeerr  red
	       ooppaaqquuee  y
	       eenndd


vveeccttoorr
       Selects a vector map layer for output.

	       ssttyyllee  sequence
	       ccoolloorr  [# ] color
	       wwiiddtthh  #
	       hhccoolloorr  color
	       hhwwiiddtthh  #
	       mmaasskkeedd  [_y| _n]
	       eenndd
       GRASS vector data can be portrayed on the map using the
       vveeccttoorr instruction.
       The name of the vector layer is	specified  on  the  first
       instruction line.
       The  named vector layer must be accessible via the current
       mapset search
       path. The
       _l_i_s_t option is available in keyboard mode.

       The default vector line style is a continuous, solid line,
       but the user
       can  specify  a dashed line using the ssttyyllee parameter. The
       ssttyyllee
       parameter can contain a sequence of digits (0-9) that rep-
       resent a colored
       pattern	on  the  vectors.  Colors can be assigned to each
       non-zero digit by
       using the ccoolloorr parameter multiple  times.  If  the  ccoolloorr
       parameter
       is used without a specified digit, the named color will be
       assigned to
       the entire lengths of the vectors. Colors  are  listed  in
       the VALID COLOR
       NAMES section in this manual entry.

       The  user  can  specify the vector line wwiiddtthh in pixels. A
       highlight
       color can be assigned with  hhccoolloorr,  and  the  highlight's
       width in
       pixels  can  be	assigned  with	hhwwiiddtthh. The user can also
       specify if
       the vectors are to be
       mmaasskkeedd by the current mask. (See manual entry
       for _r_._m_a_s_kfor more information on the
       mask.)

       The vveeccttoorr instruction set must be completed by an eenndd
       terminator.

       The vveeccttoorr instruction can be used more than once to  por-
       tray
       multiple vector data layers.

       This  example  would  include  a  vector  map  layer named
       "streams" in the
       output map. These streams would be a total of four  pixels
       wide (two blue
       pixels with a white outer highlight one pixel wide on each
       side). The map
       would not show streams outside of the current mask.

	       vveeccttoorr  streams
	       ccoolloorr  blue
	       wwiiddtthh  2
	       hhccoolloorr  white
	       hhwwiiddtthh  1
	       mmaasskkeedd  y
	       eenndd
       The following example would portray  a  vector  map  layer
       named "roads". These
       roads  would be two pixels wide and would be dashed blank-
       black-red (the
       blank areas  would  show  other	map  elements  under  the
       roads). The roads would
       be visible inside and outside of the current mask.

	       vveeccttoorr  roads
	       wwiiddtthh  2
	       ssttyyllee  001122
	       ccoolloorr  1 black
	       ccoolloorr  2 red
	       mmaasskkeedd  n
	       eenndd


vveerrbboossee
       Sets the amount of feedback sent out by _p_._m_a_p_._n_e_w.

       A higher value set using vveerrbboossee results in more feedback.
       The default
       is 2.

       This example sets the amount of feedback to a minimum.

	       vveerrbboossee	0


VVAALLIIDD CCOOLLOORR NNAAMMEESS
       The following are the valid color names in _p_._m_a_p_._n_e_w:

       black   gray    magenta violet
       blue    green   orange  white
       brown   grey    purple  yellow
       any integer from 0 through 124, representing printer color
       numbers (see
       _p_._c_o_l_o_r_smanual entry)

VVAALLIIDD FFOONNTT NNAAMMEESS
       The following are the valid font names in _p_._m_a_p_._n_e_w:

       gothgbt greekp  romanc  scriptc
       gothgrt greeks  romancs scripts
       gothitt italicc romand
       greekc  italiccs        romans (default)


IICCOONNSS VVSS.. PPAATTTTEERRNNSS
       Icons  and  patterns as used in _p_._m_a_p_._n_e_w are not the same
       things.
       Patterns can only be used to cover the extended areas of a
       raster map layer
       category.  A pattern will repeat above, below and adjacent
       to itself. Icons
       are used to represent single points.

       Patterns can be defined directly within
       _p_._m_a_p_._n_e_w using the
       ddeeffppaatt
       instruction, while icons are created outside of	_p_._m_a_p_._n_e_w
       using
       the
       _p_._i_c_o_n_scommand or a system editor.

EEXXAAMMPPLLEE pp..mmaapp..nneeww IINNPPUUTT FFIILLEE
       The  following  is  an example of a _p_._m_a_p_._n_e_w script file.
       The file
       has been named "spear.soils". For the purposes  of  illus-
       tration only, the
       file  is  shown	in  two  columns. This script file can be
       entered at the command
       line.

       pp..mmaapp..nneeww iinnppuutt==_s_p_e_a_r_._s_o_i_l_s

       rraasstteerr soils	       ddeeffppaatt diag
       vveeccttoorr streams	       000001
	  ccoolloorr blue	       00001
	  wwiiddtthh 2	       0001
	  hhccoolloorr white	       001
	  hhwwiiddtthh 1	       01
	  mmaasskkeedd y	       1
	  eenndd			  ccoolloorr 1 red
       vveeccttoorr roads		  eenndd
	  wwiiddtthh 2	       sseettppaatt 4 diag
	  ssttyyllee  001122 	 tteexxtt  608000  3476004	SPEARFISH
       SOILS MAP
	  ccoolloorr 1 black 	  ccoolloorr red
	  ccoolloorr 2 red		  wwiiddtthh 2
	  mmaasskkeedd n		  hhccoolloorr black
	  eenndd			  hhwwiiddtthh 1
       llaabbeellss town.names	  bbaacckkggrroouunndd white
       rreeggiioonn subregion 	  bboorrddeerr red
	  ccoolloorr white		  ssiizzee 500
	  wwiiddtthh 2		  rreeff lower left
	  eenndd			  ooppaaqquuee y
       ggrriidd 10000		  eenndd
	  ccoolloorr green	       lliinnee 606969 3423092 616969 3423092
	  nnuummbbeerrss 2 red 	 ccoolloorr yellow
	  eenndd			  wwiiddtthh 2
       oouuttlliinnee			  ooppaaqquuee yes
	  ccoolloorr black		  eenndd
	  eenndd		       ppooiinntt 40% 60%
       ccoolloorrttaabbllee y		 ccoolloorr purple
       ccoommmmeennttss 		  iiccoonn diamond
	  This is a comment	  ssiizzee 2
	  eenndd			  mmaasskkeedd n
       ssccaallee 1:25000		  eenndd
       sseettccoolloorr 6,8,9 white    eenndd
       sseettccoolloorr 10 green


IINNTTEERRAACCTTIIVVEE MMOODDEE
       If the user enters _p_._m_a_p_._n_e_w on the  command-line  without
       arguments,
       a prompting session occurs. Some, but not all, of the non-
       interactive requests
       are available in this mode.

SSEEEE AALLSSOO
       _g_._m_a_p_s_e_t_s

       _g_._r_e_g_i_o_n

       _p_._c_h_a_r_t

       _p_._c_o_l_o_r_s

       _p_._i_c_o_n_s

       _p_._l_a_b_e_l_s

       _p_._p_p_m

       _p_._s_e_l_e_c_t

       _r_._m_a_s_k

AAUUTTHHOORR
       Michael	 Shapiro,   U.S.Army   Construction   Engineering
       Research Laboratory

       Joo  Joo Chia, U.S. Army Construction Engineering Research
       Laboratories

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_3 _$



GRASS 5.0					     p.map.new(1)
