'''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>