HP OpenVMS Systems Documentation

Appendix A
Message Guidelines

File-Naming Conventions

Cause and Recovery Information

Comment Lines for Translators

Programming Format

Writing Style

Usage Statements

Standard Messages

Regular Expression Standard Messages

Sample Messages

File-Naming Conventions

• It is X/Open-compliant.
• It becomes a *.cat file through the use of the gencat command.

Cause and Recovery Information

The message Bad arg is not very helpful. However, the following message tells users exactly what to do to make the command work:

Do not specify more than 2 files on the command line

Line cannot exceed 20 characters

See "Sample Messages" for samples of original and rewritten messages.

Comment Lines for Translators

$ This is a comment

Place the comment line directly beneath the message to which it refers, rather than at the bottom of the message catalog. Global comments for an entire set can be placed directly below the $set directive in the source file.

Specify in a comment line any messages within the message catalog that are obsolete.

Programming Format

• Do not construct messages from clauses. Use flags or other means within the program to pass information so that a complete message can be issued at the proper time.

• Do not use hardcoded English text as a variable for a %s string in an existing message. This is also the construction of messages and is not translatable.

• Capitalize the first word of the sentence, and use a period at the end of the sentence or phrase.

• End the last line of the message with \n (backslash followed by a lowercase n, indicating a new line). This also applies to one-line messages.

• Begin the second and remaining lines of a message with \t (backslash followed by a lowercase t, indicating a tab).

• End all other lines with \n\ (backslash followed by a lowercase n, followed by another backslash, indicating a new line).

• If, for some reason, the message should not end with a new line, use a comment to tell the writers.

• Precede each message with the name of the command that called the message, followed by a colon. The command name should precede the component number in error messages. The command name is shown in the following example as it should appear in a message:

  OPIE "foo: Opening the file."
  

Writing Style

• Use sentence format. One-line and one-sentence messages are preferable.

• Add articles (a, an, the) when necessary to eliminate ambiguity.

• Capitalize the first word of the sentence and use a period at the end.

• Use the present tense. Do not allow future tense in a message. For example, use the sentence:

  The foo command displays a calendar.
  

  Instead of:

  The foo command will display a calendar.
  

• Do not use the first person (I or we) anywhere in messages.

• Avoid using the second person.

  Do not use the word you except in help and interactive text.

• Use active voice. The first line is the original message. The second line is the preferred wording.

  MYNUM "Month and year must be entered as numbers."
  MYNUM "foo: 7777-222 Enter month and year as numbers.\n"
  

  7777-222 is the message ID.

• Use the imperative mood (command phrase) and active verbs: specify, use, check, choose, and wait are examples.

• State messages in a positive tone. The first line is the original message. The second line is the preferred wording.

  BADL "Don't use the f option more than once."
  BADL "foo: 7777-009 Use the -f flag only once.\n"
  

• Do not use nouns as verbs. Use words only in the grammatical categories shown in the dictionary. If a word is shown only as a noun, do not use it as a verb. For example, do not solution a problem (or, for that matter, architect a system).

• Do not use prefixes or suffixes. Translators may not understand words beginning with re-, un-, in-, or non-, and the translations of messages that use these prefixes or suffixes may not have the meaning you intended. Exceptions to this rule occur when the prefix is an integral part of a commonly used word. The words previous and premature are acceptable; the word nonexistent, is not.

• Do not use plurals. Do not use parentheses to show singular or plural, as in error(s), which cannot be translated. If you must show singular and plural, write error or errors. A better way is to condition the code so that two different messages are issued depending on whether the singular or plural of a word is required.

• Do not use contractions. Use the single word cannot to denote something the system is unable to do.

• Do not use quotation marks. This includes both single and double quotation marks. For example, do not use quotation marks around variables such as %s, %c, and %d or around commands. Users may take the quotation marks literally.

• Do not hyphenate words at the end of lines.

• Do not use the standard highlighting guidelines in messages, and do not substitute initial or all caps for other highlighting practices.

• Do not use and/or. This construction does not exist in other languages. Usually it is better to say or to indicate that it is not necessary to do both.

• Use the 24-hour clock. Do not use a.m. or p.m. to specify time. For example, write 1:00 p.m. as 1300.

• Avoid acronyms. Only use acronyms that are better known to your audience than their spelled-out versions. To make a plural of an acronym, add a lowercase s, without an apostrophe. Verify that it is not a trademark before using it.

• Avoid the "no-no" words. Examples are abort, argument, and execute. See the project glossary.

• Retain meaningful terminology. Keep as much of the original message text as possible while ensuring that the message is meaningful and translatable.

Usage Statements

• Show the command syntax in the usage statement. For example, a possible usage statement for the del command reads:

  Usage: del {File ...|-}
  

• Clauses defining the purpose of a command are to be removed.

• Capitalize the first letter of such words (parameters) as File, Directory, String, Number, and so on only when used in a usage statement.

• Do not abbreviate parameters on the command line. It may be perfectly obvious to experienced users that Num means Number, but spell it out to ensure correct translation.

• Use only the following delimiters in usage statements:

  Delimiter

  Description

  []

  Parameter is optional.

  { }

  There is more than one parameter choice, but one of the parameters is required. (See the following text.)

  |

  Choose one parameter only. [a|b] indicates that you can choose a or b or neither a nor b. {a|b} indicates that you must choose either a or b.

  ..

  Parameter can be repeated on the command line. (Note that there is a space before the ellipsis.)

  -

  Standard input.

• A usage statement parameter does not require square brackets or braces if it is required and is the only choice, as in the following:

  banner String
  

• In usage statements, put a space between flags that must be separated on the command line. For example:

  unget [-n] [-rSID] [-s] {File|-}
  

• If flags can be used together without a separating space, do not separate them with a space on the command line. For example:

  wc [-cwl] {File ...|-}
  

• When the order of flags on the command line does not make a difference, put them in alphabetical order. If the case is mixed, put lowercase versions first:

  get -aAijlmM
  

• Some usage statements can be long and involved. Use your best judgment to determine where you should end lines in the usage statement. The following example shows an old-style usage statement for the get command:

  Usage: get [-e|-k] [-cCutoff] [-iList] [-rSID] [-wString] [xList] [-b] [-gmnpst] [-l[p]] File ...
  Retrieves a specified version of a Source Code Control System (SCCS) file.
  

Standard Messages

• Tell the user to Press the ------ key to select a key on the keyboard, including the specific key to press (such as, Press Ctrl-D).

• Unless the system is overloaded, there is no need to tell the user to Try again later. That should be obvious from the message.

• When writing message text, use the word parameter to describe text on the command line; use the word value to indicate numeric data.

• Use the word flag rather than the words command option.

• Do not use commas to set off the one-thousandth place in values.

• Do not use 1,000. Use 1000.

• If a message must be set off with an asterisk, use two asterisks at the beginning of the message and two asterisks at the end of the message.

  ** Total **
  

• Use log in and log off as verbs.

  Log in to the system; enter the data; then log off.
  

• Use user name, group name, and login as nouns.

  The user name is sam.
  The group name is staff.
  The login directory is /u/sam.
  

• User number and group number refer to the number associated with the user's name and group.

• Do not use the term superuser. The root user may not have all privileges.

• Use the words command string to describe the command with its parameters.

• Many of the same messages occur frequently. Table A-1 lists the new standard message that replaces the old message.

  Table A-1 New Standard Messages
  
  

Regular Expression Standard Messages

Table A-2 Regular Expression Standard Messages

Sample Messages

AFLGKEYLTRS "Too Many -a Keyletters (Ad9)"
AFLGKEYLTRS "foo: 7777-007 Use the -a flag less than 11 times.\n"

FLGTWICE "Flag %c Twice  (Ad4)"
FLGTWICE "foo: 7777-004 Use the %c header flag once.\n"

ESTAT "can't access %s.\n"
ESTAT "foo: 7777-031 Cannot find or access %s.\n"

EMODE "foo: invalid mode\n"
EMODE "foo: 7777-033 A mode flag or value is not correct.\n"

DNORG "-d has no argument  (ad1)"
DNORG "foo: 7777-001 Specify a parameter after the -d flag.\n"

FLOORRNG "floor out of range  (ad23)"
FLOORRNG "foo: 7777-021 Specify a floor value greater than 0\n\
\tand less than 10000.\n"

AFLGARG "bad -a argument  (ad8)"
AFLGARG "foo: 7777-006 Specify a user name, group name, or\n\
\tgroup number after the -a flag.\n"

BADLISTFMT "bad list format  (ad27)"
BADLISTFMT "foo: 7777-025 Use numeric version and release\ \tnumbers.\n"