wiki:MessageStandardization

Version 17 (modified by martinl, 15 years ago) ( diff )

--

In progress, see http://grass.osgeo.org/wiki/Development_Specs

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
    (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
    ("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
    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().
    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

Note: See TracWiki for help on using the wiki.