'''In progress''', see http://grass.osgeo.org/wiki/Development_Specs
[[TOC]]
= Message Standardization =

== How should Errors/Warnings/Messages be formatted ==

 * Only user derived variables should be bracketed, not GRASS derived variables, for example:
{{{
 Yes: Creating raster map <%s>.  Pass 1 of 7 ...
 No:  Creating <raster> map <%s>.  Pass [1] of [7] ...
}}}

 * strings '''< >''' - raster, vector maps, group names, etc., e.g.
  * Raster map <%s> not found
 * strings ''' ' ' ''' - paths, SQL queries, etc., e.g.
  * File '%s' not found
  * Unable to create table: '%s'

=== Discussion ===

 * The [bracketed] parenthetical disrupts the flow of the phrase and doesn't help enhance clarity of meaning. IMHO, this reads better without [] brackets: "''Line %d deleted.''" [] Brackets should be used when value is outside of the phrase: ''"Unknown line [%d]"''. --HB

=== Statistics ===

|| symbol || number of code lines (2007-04-11) || 2008-02-14 (6.3svn) || 2009-08-02 (7.0svn)
|| <%s> || 637 || 1406 || 1935
|| [%s] || 690 || 427 || 222
||'%s'  || 354 || 370 || 537
|| <%d> || 12  || 7 || 11
|| [%d] || 207 || 13 || 137
||'%d'  || 3   || 1 || 1

{{{
TYPES="<%s> \[%s\] '%s' <%d> \[%d\] '%d'"

for TYPE in $TYPES ; do
  NUM_HITS=`grep -rI "$TYPE" * | grep -v '/.svn/\|^dist.i686-\|locale/po/' | wc -l`
  echo "$TYPE  $NUM_HITS"
done
}}}

== Macros to be defined for C library ==

 * MSG_RASTER_NOT_FOUND_IN_MAPSET - "Raster map <%s> not found in <%s>"
 * MSG_CANNOT_OPEN_RASTER - "Unable to open raster map <%s>"
 * MSG_CANNOT_OPEN_FILE - Unable to open file <%s>

Note: Problem with xgettext package. How to use macros to work with xgettext?

== Standard messages sandbox ==

 * First letter should be capitalized
 * Use the present tense[[BR]]
 (cannot instead of could not; '''better: unable to'''; even better: avoid the issue altogether by rewording like "File not found.")
 * Avoid contractions (cannot instead of can't)
 * Good sentence construction[[BR]]
 ("Cannot find input map <%s>" instead of "It could not be find input map <%s>"; possibly better: "Input map <%s> not found.")
 * Be consistent with periods. Either end all phrases with a period or none. Without periods the translators save also some time[[BR]]
 Complete sentences or all parts of a message with multiple sentences should end with periods. Short phrases should not. Punctuated events, such as errors, deserve a period. e.g. ''"Operation complete."'' Phrases which imply ongoing action look odd if missing an ellipse or any other form of punctuation.  Phrase != Sentence. --HB
 * Either all '''module''' descriptions should end with periods or not. As some are multi-sentence, and thus should end in a period for consistency within the message, so probably they all should end in one. Currently by my count 237 end with '.', 139 do not. In the multi-sentence case it may be posible to put the simple description in the module->label field and additional explanitory text into the ->description field.
 * '''option''' and '''flag''' descriptions generally should not end in a period (more likely to be phrases than sentences). But they can suffer the same multi-sentence period problem as module descriptions. In this case splitting out additional text into a ->label, ->description split may help.
 * Suspension points used to indicate some process is being done should be placed next to last word, without space. e.g. 
{{{
Reading raster map...
}}}
 instead of
{{{
Reading raster map ...
}}}
 HB: FWIW & my 2c, 1) to me keeping the space before the ellipse looks better, is this a purely cosmetic choice or is there some style logic? [wikipedia article on the ellipse was cited on grass-dev, I would argue that refers to printed typeset text not monospace terminal text, strangely suggests punctuation+3 dots (....), is just one other guy's opinion, and I'm still not swayed]  2) these messages may be good candidates for G_verbose_message().[[BR]]
 HB 2c more: (i.landsat.rgb example)
{{{
  Processing <$i>...
 
  Processing <$i> ...
}}}
  The version with the space just looks better. The version without just looks wrong.
  But when the line ends with a word, no-space doesn't look that bad: (v.in.ascii)
{{{
  Importing points...
 
  Importing points ...
}}}
 * Module descriptions should use all the same verbal tense. Currently some of them can be found in infinitive and others in present.

=== DB messages ===

db_open_database(), db_start_driver_open_database()
 Unable to open database <%s> by driver <%s>
db_execute_immediate()
 Unable to insert new record: '%s'

 Unable to create table: '%s'

 Unable to drop table: '%s'
db_grant_on_table()
 Unable to grant privileges on table <%s>
db_start_driver()
 Unable to start driver <%s>
db_describe_table()
 Unable to describe table <%s>
db_select_value()
 Unable to select record from table <%s> (key %s, column %s)

 No records selected from table <%s>
db_fetch()
 Unable to fetch data from table <%s>
db_create_index(), db_create_index2()
 Unable to create index for table <%s>, key <%s>
db_copy_table(), db_copy_table_by_ints()
 Unable to copy table <%s>
db_delete_table()
 Unable to delete table <%s>
db_table_exists()
 Unable to find table <%s> linked to vector map <%s>
db_get_column()
 Column <%s> not found in table <%s>
db_list_tables()
 Unable to get list tables in database <%s>
db_open_select_cursor()
 Unable to open select cursor: '%s'
db_create_table()
 Unable to create table <%s>
db_get_num_rows()
 Unable select records from table <%s>

=== General messages ===
G_legal_filename()
 <%s> is an illegal file name
G_set_window()
 Invalid graphics coordinates
 
 Unable to set region
D_do_conversions()
 Error calculating graphics-region conversions
G_tempfile()
 Unable to open temporary file <%s>
G_get_projinfo()
 Unable to get projection info of raster map
G_get_projunits()
 Unable to get projection units of raster map

=== Raster messages ===
G_find_cell2()
 Raster map <%s> not found
 
 Raster map <%s> not found in the current mapset

 Raster map <%s> not found in mapset <%s>
G_open_cell_old()
 Unable to open raster map <%s>
G_open_cell_new()
 Unable to create raster map <%s>
G_close_cell()
 Unable to close raster map <%s>
G_get_cellhd()
 Unable to read header of raster map <%s>
G_get_raster_row()
 Unable to read raster map <%s> row %d
G_put_raster_row()
 Failed writing raster map <%s> row %d
G_write_cats()
 Unable to write category file for raster map <%s>
G_read_colors()
 Unable to read color file of raster map <%s>
G_read_cats()
 Unable to read category file of raster map <%s>
G_read_fp_range()
 Unable to read fp range of raster map <%s>
G_read_range()
 Unable to read range of raster map <%s>

=== 3D raster messages ===

G_find_grid3()
 3D Raster map <%s> not found
 
 3D Raster map <%s> not found in the current mapset
 
 3D Raster map <%s> not found in mapset <%s>
G3d_openCellOld()
 Unable to open 3D raster map <%s>
G3d_range_load()
 Unable to read range of 3D raster map <%s>
G3d_closeCell()
 Unable to close raster map <%s>

=== Vector messages ===
G_find_vector2()
 Vector map <%s> not found

 Vector map <%s> not found in the current mapset
 
 Vector map <%s> not found in mapset <%s>
Vect_open_old()
 Unable to open vector map <%s>
 
 Unable to open vector map <%s> at topology level %d
Vect_open_new()
 Unable to create vector map <%s>
Vect_get_field(), Vect_get_dblink()
 Database connection not defined for layer %d
Vect_get_area_centroid()
 Area %d without centroid or Skipping area %d without centroid
Vect_open_old_head()
 Unable to open header file of vector map <%s>
Vect_map_add_dblink()
 Unable to add database link for vector map <%s>
Vect_read_next_line
 Unable to read vector map <%s> feature id %d