Development Specs

From GRASS-Wiki
Revision as of 05:48, 2 June 2007 by ⚠️HamishBowman (talk | contribs) (→‎Messages Discussion: G_put_raster_row() try2)
Jump to navigation Jump to search

Message standardization

How should Errors/Warnings/Messages be formatted

  • strings < >
    • e.g. Raster map <%s> not found
  • numbers [ ]
    • e.g. Line [%d] deleted
? 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

Discussion:

Statistics [2007-04-11]:

symbol number of code lines
<%s> 637
[%s] 690
'%s' 354
<%d> 12
[%d] 207
'%d' 3

Macros to be defined for C library

  • MSG_RASTER_NOT_FOUND_IN_MAPSET - "Raster map <%s> not found in <%s>"
  • MSG_CANNOT_OPEN_RASTER - "Failed opening raster map <%s>"
  • MSG_CANNOT_OPEN_FILE - Cannot 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)
  • 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>")
  • 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.


DB messages

db_open_database()
Cannot open database <%s> by driver <%s>
db_execute_immediate()
Cannot insert new record: %s
Cannot create table <%s>
db_grant_on_table()
Cannot grant privileges on table <%s>
db_start_driver_open_database()
G_fatal_error(_("Cannot open database <%s> by driver <%s>"), Fi->database, Fi->driver);

General messages

G_legal_filename()
<%s> illegal file name
G_set_window()
Invalid graphics coordinates
Cannot set window
D_do_conversions()
Error calculating graphics-region conversions

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 <%s>
G_get_cellhd()
Cannot read header of raster map <%s>
G_open_cell_old()
Cannot open raster map <%s>
G_open_cell_new()
Cannot create raster map <%s>
G_get_raster_row()
Cannot read raster row [%d] from raster map <%s>
G_put_raster_row()
Cannot write raster row [%d] to 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 <%s>
Vect_open_old()
Cannot open vector map <%s>
Cannot open vector map <%s> at topo level [%d]
Vect_get_field()
"Database connection not defined for layer <%d>"

Messages Discussion

  • "Map <roads> in <user1>" or "Map <roads@user1>"
  • G_get_raster_row
"Unable to read raster map <%s> row %d"
Cannot get raster raster of input map
Cannot raster raster of input map
Cannot read raster row [%d]
Can't get row %d from raster map %s
can't read row in input elevation map
Could not read from <%s>
Could not read from <%s>, row=%d
Error getting input null cells
error reading hue data
Error reading 'hue' map
Error reading input
error reading intensity data
Error reading 'intensity' map
Error reading map %s
Error reading row of data
error reading saturation data
Error reading 'saturation' map
G_get_raster_row failed
reading map
Reading map
Reading row %d
read_row: error reading data
%s: Unable to read raster map [%s]
Unable to get row %d from raster map
Unable to get row %d from <%s>
Unable to read map raster row %d
Unable to read raster row.
Unable to read raster row %d
Unable to read row %i\n
  • G_put_raster_row
"Failed writing raster map <%s> row %d"
Cannot write row to raster map
Cannot write to <%s>
el
Error while writing new cell map.
Error writing cell map during transform.
error writing data
Error writing output map
G_put_raster_row failed (file system full?)
%s - ERROR writing %s
Unable to properly write output raster map
unable to write map row %d
  • G_open_cell_new
"Unable to create raster map <%s>"
Cannot open output raster map <%s>
can't open %s
el
Error in opening output file <%s>
Unable to create output <%s>
Unable to create raster map <%s>
Unable to create raster map [%s]
Unable to open cell map <%s> for output.\n
Unable to open output file.
Unable to open the cell map MASK.
  • G_open_cell_old
"Unable to open raster map <%s>"
Cannot find map %s
Cannot find mapset for %s
Cannot open File %s
Cannot open input raster map <%s>
Cannot open map %s
Cannot open raster map
Cannot open raster map <%s>
Cannot open raster map [%s]
Cannot open raster map [%s]!
Cannot open %s
Cannot open seed map <%s@%s>!
Cannot open terrain raster map <%s@%s>!
Can't open input map
can't open raster map [%s]
can't open raster map <%s> in mapset %s
can't open %s
Could not open raster <%s>
Could not open raster '%s'
el
Error in opening input file <%s>
Not able to open cellfile for [%s]
Problem opening input file [%s]
Raster file <%s> not found
Raster map [%s] not found
%s - can't open raster map
<%s> cellfile not found
%s: Couldn't open raster <%s@%s>
%s: o_open_file: could not open raster map %s in %s
%s - raster map not found
Unable to open band files.
unable to open cellfile for [%s]
Unable to open cellfile for [%s]
Unable to open map <%s>
 unable to open MASK
unable to open MASK
Unable to open MASK
unable to open raster map [%s]
Unable to open raster map [%s]
Unable to open raster <%s>
unable to open [%s] in [%s]
Unable to proceed
  • G_find_cell
"Raster map <%s> not found"
albedo raster map <%s> not found
aspin raster map <%s> not found
Cannot find map %s
Cannot find mapset for %s
Cannot find raster map
Cannot find %s
cell file [%s] not found
code
coefbh raster map <%s> not found
coefdh raster map <%s> not found
el
elevin raster map <%s> not found
Input map [%s] in location [%s] in mapset [%s] not found.
latin raster map <%s> not found
linkein raster map <%s> not found
No clump map specified and MASK not set.
Raster file [%s] not found. Exiting.
Raster map [%s] already exists.\nPlease try another.
Raster map <%s> not found
Raster map [%s] not found
Raster <%s> already exist.
Raster <%s> not found
Raster '%s' not found
Requested raster map <%s> not found
[%s] cannot be found!
%s - exits in Mapset <%s>, select another name
slopein raster map <%s> not found
%s: more than %d files not allowed
%s - not found
%s: o_open_file: raster map %s not found
%s: <%s> raster map not found
%s: %s - raster map not found
%s: %s - Unable to find the imaginary-image.
%s: %s - Unable to find the real-image map.
stringliteral
Training map [%s] not found.
Unable to find base map <%s>
Unable to find cell map <%s>
Unable to find cover map <%s>
Unable to find file [%s].
Unable to find input cell map <%s>
Unable to find raster [%s].
  • G_find_vector
"Vector map <%s> not found"
Cannot find input map <%s>
Cannot find vector map
Cannot not find input vector map <%s>
could not find input map <%s>
Could not find input map <%s>
Could not find input map <%s>.
Could not find input map '%s'.
Could not find input map <%s> in current mapset.
Could not find input map <%s>\n
Could not find input %s
Could not find input %s\n
Could not find input vector map <%s>
Could not find input vector map %s
Could not find network input map '%s'.
Could not find vector map %s
Could not find vector map <%s> in current mapset
Could not find vector '%s'
el
It could not be find input map <%s>
It could not be found input map <%s>
Vector file [%s] not available
vector map <%s> not found
Vector map '%s' not found

Systematic Approach

  • Collect all possible error states from functions
  • assign error codes for macros?
  • G_option() parameters (like output->description = ("Path to resulting ASCII file");)

Note: Would be possible to conctretize your ideas? (MartinL)

Parameters and flags

Fix the parameters and flags. Make it a concept. See proposal in GRASS 5 documents/parameter_proposal.txt

Verbosity levels

Current abstract concept

verbose 3 MAX_LEVEL print progress and all messages messages
standard 2 STD_LEVEL print progress and selected messages
brief 1 print only progress information
silent but not mute 0 MIN_LEVEL print nothing (but ERR and WAR)
mute 2>&1 > /dev/null
Proposal
  • module output (should be "parsable") is not controlled by GRASS_VERBOSE [use fprintf (stdout, ...)]
  • silent
    • only warnings and fatal errors are printed
  • brief
    • all G_percent() and selected G_message() (especially connected to progress information, up to the programmer ??)
  • standard
    • all G_percent() and selected G_message()
  • verbose
    • all G_percent() + G_message()
Modification
  • remove verbose level → standard == all G_percent () + G_messages()
  • move some messages to G_debug()
  • change level numbers to 1, 3, 5
  • Add new G_msg(int level, "%format", ...); lib function. Existing G_message() could stay and would be the same as G_msg(LEVEL_STD,...).
Discussion
  • HB: I'm quite happy to leave the current system as it is, but use GRASS_MESSAGE_FORMAT=silent to switch off G_percent(),G_clicker() output.
Mixing a sliding verbosity scale plus a binary switch or >= rule for when G_percent() happens in the same variable is very messy IMO.

Alternative Abstract concept

standard 3 PERMSG_MODE print progress and messages
standard 2 MESSAGE_MODE print only messages
brief 1 PERCENT_MODE print only progress information
silent but not mute 0 QUIET_MODE print nothing (but ERR and WAR)
mute 2>&1 > /dev/null
Retrieved from "https://grasswiki.osgeo.org/w/index.php?title=Development_Specs&oldid=4294"