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 hard-
       copy device or a graphics monitor. Output can include a raster map, any
       number  of  vector overlays, site data, text labels, and other map ele-
       ments.

       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 superseded by the command-line	ssccaallee  parame-
	   ter.


       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 prepared 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 others are	multi-
       ple  line.  Multiple-line  instructions consist of the main instruction
       followed by a subsection of one or more	additional  instructions.  All
       multiple-line instructions 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 coor-
       dinates 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  iinntteerrvvaall  (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, separated 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, tteexxttssiizzee 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 cate-
       gory
       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 elevation	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.comments" in the
       current
       directory.

	       rraasstteerr  vegetation
	       ccoommmmeennttss  veg.comments
	       eenndd



       ddeeffppaatt
       Defines an area fill pattern to be used in sseettppaatt instructions.

	       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 instructions. 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  category	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 pattern, followed
       by a valid color name. It can be repeated for each of the non-zero dig-
       its
       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 precede
       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 for-
       ward
       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 instruc-
       tion
       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 over-
       all
       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 horizon-
       tal
       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 represent gaps
       between
       the dashes. The default is solid lines. The wwiiddtthh (in pixels) 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 background 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  specifica-
       tions.
       See manual entry for
       _p_._l_a_b_e_l_sfor correct
       format  of  the labels file. The labels file must be accessible via the
       current
       mapset search path. The _l_i_s_t option is available in keyboard 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 specified 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  mea-
       surements
       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 containing
       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 legend using the
       bbeeggiinnrraasstt,
       bbeeggiinnvveecctt, and bbeeggiinnssiittee parameters. Each of these parameters
       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 por-
       trays
       a  continuous range of data, a rraammpp in the legend might be appropriate.
       The rraammpp can be vertical or horizontal, and it's accompanying text
       can be either the smallest and largest category values, or the _c_a_t_s
       labels associated with the smallest and largest categories. The	bbeeggiinn--
       rraasstt
       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 bbeeggiinnssiittee 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 repre-
       senting
       one vector layer, in that order. The background of the legend would be
       white and surrounded by a red border. All text in the legend  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 vertical ramp show-
       ing
       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 coordinates 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 represent a  col-
       ored
       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_kfor
       more information on the mask.)

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

       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 instruction
       in a _p_._m_a_p_._n_e_w input file.

       The instruction sequence in this example would outline in grey the cat-
       egory
       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 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  charac-
       ters
       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 speci-
       fied
       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. Geographic region set-
       tings
       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 represent a  col-
       ored
       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_kfor
       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  differ-
       ent
       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, kilome-
       ters,
       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 combina-
       tion
       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 overrides 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 parameter 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  sseettppaatt  instruc-
       tion
       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 cate-
       gory
       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 category 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 categories 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  charac-
       ters
       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 symbol. 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 "windmill" 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  coordi-
       nates
       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 location, 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 percentage 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-clockwise  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 specified 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  back-
       ground
       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 coordi-
       nates
       E650000, N7365000. The text would be a total of three pixels 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 represent a col-
       ored
       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 portray
       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  illustration  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)
