Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 153 lines (124 sloc) 6.861 kb
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
1 <html><head>
2fe6e177 »
2011-12-10 Import Elvis 2.2_1 (written by Steve Kirkendall)
2 <title>Elvis-2.2_1 Messages</title>
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
3 </head><body>
4
5 <h1>12. MESSAGES</h1>
6
7 Elvis has an extremely versatile method for handling messages.
8d1ac0c1 »
2011-12-10 Import Elvis 2.1 (written by Steve Kirkendall)
8 You can change the wording, or even the language, of any message.
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
9 You can make any message ring the terminal's bell.
10 You can hide certain messages.
11
12 <p>This section of the manual describes how messages are generated,
13 and how you can customize them.
14 A list of the individual messages can be found in <a href="elvistrs.msg">
15 Appendix A.</a>
16
17 <h2>12.1 The msg() function.</h2>
18
19 Every message begins with a call to the msg() function.
20 The message function is passed at least two arguments:
21 the message's importance, and the text of the message.
22 Some messages also have other arguments.
23
24 <p>The importance of a message is a symbol which describes what type of message
25 it is.
26 The symbol can be any of the following:
27 MSG_STATUS, MSG_INFO, MSG_WARNING, MSG_ERROR, or MSG_FATAL.
28 This affects the way that the message is displayed.
29 For example, MSG_STATUS messages are always displayed immediately,
30 and can be overwritten by later messages; this is used for messages like
31 "Reading foo.c..."
32 MSG_ERROR messages cause the <a href="elvisopt.html#exitcode">exitcode</a>
33 option to be set to 1.
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
34 MSG_FATAL messages cause Elvis to exit immediately after displaying the message.
35 You can't alter a message's importance without editing Elvis' source code
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
36 and recompiling; each message's importance is hardcoded.
37
38 <p>The text of the message is a string.
39 If there are other arguments, then the text of the message will be preceded
40 by a bracketed list of letters which help the msg() function convert
41 the arguments to strings.
42 Although this bracketed list is part of the string, it is not considered
43 to be part of the message's text.
44
45 <p>Each letter in the bracketed list describes how one argument is to be
46 displayed.
47 <strong>d</strong> indicates that a long int argument is to be converted into
48 a decimal number string.
49 <strong>c</strong> and <strong>C</strong> indicate that a char or CHAR is to
50 be converted into a string of length 1.
51 <strong>s</strong> and <strong>S</strong> indicate that the argument is
52 already a string of chars or CHARs.
53 (The CHAR data type could be either an 8-bit character or a 16-bit character,
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
54 depending on the compile-time configuration of Elvis.
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
55 The <a href="elvisopt.html#bitsperchar">bitsperchar</a> option indicates which.)
56
57 <h2>12.2 Translation</h2>
58
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
59 All of the messages built into Elvis are terse.
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
60 If the <a href="elvisopt.html#terse">terse</a> option is turned off,
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
61 then Elvis will attempt to translate each terse message into a verbose one.
8d1ac0c1 »
2011-12-10 Import Elvis 2.1 (written by Steve Kirkendall)
62 Although the terse messages are written in English, the verbose messages
63 can be in any language.
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
64
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
65 <p>When Elvis first creates a new edit session, it attempts to locate a
8d1ac0c1 »
2011-12-10 Import Elvis 2.1 (written by Steve Kirkendall)
66 file named "<a name="elvis.msg">elvis.msg</a>" and load it into a buffer named
67 "Elvis messages".
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
68 To find the "elvis.msg" file, Elvis searches through all of the directories
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
69 named in the <a href="elvisopt.html#elvispath">elvispath</a> option.
70
71 <p>Each line of the "Elvis messages" buffer describes how a single message
72 should be translated.
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
73 To translate a message, Elvis scans through the "Elvis messages" buffer
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
74 for a line which begins with the terse message text followed immediately
75 by a ':' character.
76 If it finds one, then it skips any whitespace after the ':' and uses the
77 remainder of the line as the message text.
78 If it doesn't find any matching line, then the terse text is used.
79
80 <p>This is primarily intended to be used for translating the messages into
81 your native language.
82
83 <p>The file that contains <a href="elvistrs.msg">Appendix A</a>
84 (initially "lib/elvistrs.msg")
85 is a handy resource when you're constructing your "elvis.msg" file.
86 It contains the terse forms of almost all messages.
87 You can yank a line from Appendix A, paste it into your "elvis.msg" file,
88 and add a colon and verbose message to the end of the message.
89
90 <p>By the way, Appendix A is created automatically via the command
8d1ac0c1 »
2011-12-10 Import Elvis 2.1 (written by Steve Kirkendall)
91 <code>"make&nbsp;lib/elvistrs.msg".</code>
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
92 This just searches for all messages in any source file, sorts them, and
93 discards any duplicates.
94 I intend to add another appendix some day which describes some of the
95 more subtle messages in detail.
96
97 <h2>12.3 Argument substitution</h2>
98
99 After translation, the message text is evaluated using the
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
100 <a href="elvisexp.html#SIMPLER">simpler syntax of the built-in calculator.</a>
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
101 This basically means that you can use <strong>$1</strong> in the message text
102 to indicate where the first argument should appear, <strong>$2</strong> for
103 the second argument, and so on.
104
105 <p>It also means that anything inside of parentheses is evaluated using the
106 full power of the calculator, which has a C-like syntax.
107 The message output by the <a href="elvisex.html#file">:file</a> command
108 uses this to calculate the percentage of the way through the file.
109
110 <p>If you want to output a literal '$', '(', ')', or '\' character as part of
111 the message, you'll need to precede it with a '\' character.
112
113 <h2>12.4 Bell control</h2>
114
115 You can force any individual messages to ring the bell by using the
116 "Elvis messages" buffer to translate them into a message which begins with
117 a <kbd>^G</kbd> character.
118
119 <p>There are also two options which allow you to force the bell to ring for
120 certain message types.
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
121 If Elvis is outputting a MSG_ERROR message, and the
122 <a href="elvisopt.html#errorbells">errorbells</a> option is set, then Elvis
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
123 will ring the terminal's bell.
124 It will also ring the bell for MSG_WARNING messages if the
125 <a href="elvisopt.html#warningbells">warningbells</a> option is set.
126
127 <p>Note that there is also a <a href="elvisopt.html#flash">flash</a> option which
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
128 instructs Elvis to use a visible alternative to the bell, if one is available.
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
129
130 <h2>12.5 Displaying the message</h2>
131
132 Messages are normally displayed at the bottom of the current window.
133 Usually this is exactly what you would expect, but it can be a little
134 counterintuitive when you're creating or closing windows.
135
136 <p>When you're creating a window, the "current window" is the window where
137 you gave the command which caused the window to be created.
138 So if you're editing "foo.c" and give the command
139 <a href="elvisopt.html#split">:split bar.c</a> then the information about
140 the "bar.c" file will show up in the window where you're editing "foo.c".
141 The bottom line of the "bar.c" window will be blank.
142
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
143 <p>When you're closing a window, Elvis chooses some other window to become
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
144 the new "current window" so that it'll have a place where it can display
145 the messages.
146 You can't always predict which window it will choose.
147
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
148 <p>When you close the last window and exit Elvis, any messages that Elvis
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
149 wants to output will simply be written to stdout or stderr.
9f1c6f0f »
2011-12-10 Import Elvis 2.2_0 (written by Steve Kirkendall)
150 Typically, the only message that Elvis wants to output when closing will be
cf92e3be »
2011-12-10 Import Elvis 2.0 (written by Steve Kirkendall)
151 "wrote foo.c, 1234 lines, 56789 characters".
152
153 </body></html>
Something went wrong with that request. Please try again.