|Version 15 (modified by martinl, 4 years ago)|
In progress, see http://grass.osgeo.org/wiki/Development_Specs
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  of  ...
- 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'
- 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
|symbol||number of code lines (2007-04-11)||2008-02-14 (6.3svn)||2009-08-02 (7.0svn)|
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.
Unable to open database <%s> by driver <%s>
Unable to insert new record: '%s'
Unable to create table: '%s'
Unable to drop table: '%s'
Unable to grant privileges on table <%s>
Unable to start driver <%s>
Unable to describe table <%s>
Unable to select record from table <%s> (key %s, column %s)
No records selected from table <%s>
Unable to fetch data from table <%s>
Unable to create index for table <%s>, key <%s>
Unable to copy table <%s>
Unable to delete table <%s>
Unable to find table <%s> linked to vector map <%s>
Column <%s> not found in table <%s>
Unable to get list tables in database <%s>
Unable to open select cursor: '%s'
Unable to create table <%s>
Unable select records from table <%s>