small corrections / a forgived string ...
[midnight-commander.git] / doc / mcedit.1.in
blobc499b3b99482254077cdbcaedf8bf9528238a9b1
1 .TH mcedit 1 "30 January 1997"
2 .\"SKIP_SECTION"
3 .SH NAME
4 mcedit \- Full featured terminal text editor for Unix-like systems.
5 .\"SKIP_SECTION"
6 .SH USAGE
7 .B mcedit
8 [[+number] file [\-bcCdfhstVx?]]
9 .SH DESCRIPTION
10 .LP
11 Mcedit is a link to 
12 .B mc,
13 the Midnight Commander, forcing it 
14 to immediately start its internal editor. The editor is a terminal 
15 version of the 
16 .B cooledit 
17 standalone X Window editor.
18 .\".\"DONT_SPLIT"
19 .SH OPTIONS
20 .TP
21 .I "+number"
22 Go  to the line specified by number (do not insert
23 a space between the "+" sign and the number).
24 .TP
25 .I "\-b"
26 Forces black and white display.
27 .TP
28 .I "\-c"
29 Force color mode on terminals where 
30 .B mcedit 
31 defaults to black and white.
32 .TP
33 .I "\-C <keyword>=<FGcolor>,<BGcolor>:<keyword>= ..."
34 Used to specify a different color set, where 
35 .I keyword 
36 is one of normal, selected, marked, markselect, errors,
37 reverse menu, menusel, menuhot, menuhotsel and gauge. The colors
38 are optional and are one of black, gray, red, brightred, green,
39 brightgreen, brown, yellow, blue, brightblue, magenta,
40 brightmagenta, cyan, brightcyan, lightgray and white.
41 See the 
42 .B Colors 
43 section in 
44 .B mc.1 
45 for more information.
46 .TP
47 .I "\-d"
48 Disables mouse support.
49 .TP
50 .I "\-f"
51 Displays the compiled-in search paths for Midnight Commander files.
52 .TP
53 .I "\-t"
54 Used only if the code was compiled with Slang and terminfo: it makes
55 the Midnight Commander use the value of the 
56 .B TERMCAP
57 variable for the terminal information instead of the information on
58 the system wide terminal database
59 .TP
60 .I "\-V"
61 Displays the version of the program.
62 .TP
63 .I "\-x"
64 Forces xterm mode.  Used when running on xterm-capable terminals (two
65 screen modes, and able to send mouse escape sequences).
66 .PP
67 .SH Features
68 The internal file editor provides most of the features of common full
69 screen editors.  It has an extendable file size limit of sixteen megabytes
70 and edits binary files flawlessly.  The features it presently supports
71 are: Block copy, move, delete, cut, paste;
72 .I "key for key undo"; 
73 pull-down
74 menus; file insertion; macro definition; regular expression
75 search and replace (and our own scanf-printf search and
76 replace); shift-arrow MSW-MAC text highlighting (for the
77 linux console only); insert-overwrite toggle; word-wrap;
78 a variety of tabbing options; syntax highlighting for
79 various file types; and an option
80 to pipe text blocks through shell commands like indent and
81 ispell.
82 .PP
83 .SH Keys
84 The editor is very easy to use and requires no tutoring.
85 To see what keys do what, just consult the appropriate
86 pull-down menu. Other keys are: Shift movement
87 keys do text highlighting (Linux console only). 
88 .B Ctrl-Ins 
89 copies to the file 
90 .BR ~/.mc/cedit/cooledit.clip,
91 and 
92 .B Shift-Ins 
93 pastes from 
94 .BR ~/.mc/cedit/cooledit.clip. 
95 .B Shift-Del 
96 cuts to 
97 .BR ~/.mc/cedit/cooledit.clip, 
98 and 
99 .B Ctrl-Del 
100 deletes highlighted text - all linux console only.  Mouse highlighting
101 also works, and you can override the mouse as usual by holding down
102 the shift key while dragging the mouse to let normal terminal mouse
103 highlighting work.
105 The completion key (usually
106 .B "Alt-Tab"
108 .BR "Espace-Tab")
109 completes the word under the cursor using the words used earlier in the
110 file.
112 To define a macro, press 
113 .B Ctrl-R 
114 and then type out the key
115 strokes you want to be executed. Press 
116 .B Ctrl-R 
117 again when finished. You can then assign the macro to any key you
118 like by pressing that key. The macro is executed when you press
119 .B Ctrl-A 
120 and then the assigned key. The macro is also executed if
121 you press Meta, Ctrl, or Esc and the assigned key, provided that the
122 key is not used for any other function. Once defined, the macro
123 commands go into the file 
124 .BR ~/.mc/cedit/cooledit.macros. 
125 Do NOT edit this file if you are going to use macros again in the same
126 editing session, because
127 .B Mcedit 
128 caches macro key defines in memory. 
129 .B Mcedit 
130 now overwrites a macro if a macro with the same key already exists,
131 so you won't have to edit this file. You will also have to restart
132 other running editors for macros to take effect.
134 .B F19 
135 will format C code when it is highlighted.  An executable file called 
136 .B ~/.mc/cedit/edit.indent.rc 
137 will be created for you from the default template.  Feel free to edit it
138 if you need.
140 .B C-p 
141 will run ispell on a block of text in a similar way.  The script file
142 will be called
143 .B ~/.mc/cedit/edit.spell.rc
146 .SH Redefining Keys
147 Keys may be redefined from the Midnight Commander options
148 menu.
150 .SH SYNTAX HIGHLIGHTING
151 As of version 3.6.0, \fBcooledit\fP has syntax highlighting.  This means
152 that keywords and contexts (like C comments, string constants, etc)
153 are highlighted in different colors.  The following section explains
154 the format of the file \fB~/.mc/cedit/Syntax\fP.
156 The file \fB~/.mc/cedit/Syntax\fP is rescanned on opening of a any new
157 editor file. The file contains rules for highlighting, each of which is
158 given on a separate line, and define which keywords will be highlighted
159 to what color. The file is also divided into sections, each beginning
160 with a line with the \fBfile\fP command, followed by a regular
161 expression. The regular expression dictates the file name that that set
162 of rules applies to. Following this is a description to be printed on the
163 left of the editor window explaining the file type to the user. A third
164 optional argument is a regular expression to match the first line of
165 text of the file. If either the file name matches, or the first line of text,
166 then those rules will be loaded.
168 A section ends with the start of a new section. Each section is divided
169 into contexts, and each context contains rules. A context is a scope
170 within the text that a particular set of rules belongs to. For instance,
171 the region within a C style comment (i.e. between \fB/*\fP and \fB*/\fP)
172 has its own color. This is a context, although it will have no further
173 rules inside it because there is probably nothing that we want
174 highlighted within a C comment.
176 A trivial C programming section might look like this:
179 file .\\*\\\\.c C\\sProgram\\sFile (#include|/\\\\\\*)
181 wholechars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_
183 # default colors
184 context default
185   keyword  whole  if       24
186   keyword  whole  else     24
187   keyword  whole  for      24
188   keyword  whole  while    24
189   keyword  whole  do       24
190   keyword  whole  switch   24
191   keyword  whole  case     24
192   keyword  whole  static   24
193   keyword  whole  extern   24
194   keyword         {        14
195   keyword         }        14
196   keyword         '*'      6 
198 # C comments
199 context /\\* \\*/ 22
201 # C preprocessor directives
202 context linestart # \\n 18
203   keyword  \\\\\\n  24
205 # C string constants
206 context " " 6
207   keyword  %d    24
208   keyword  %s    24
209   keyword  %c    24
210   keyword  \\\\"   24
213 Each context starts with a line of the form:
215 \fBcontext\fP [\fBexclusive\fP] [\fBwhole\fP|\fBwholeright\fP|\fBwholeleft\fP] 
216 [\fBlinestart\fP] \fIdelim\fP [\fBlinestart\fP] \fIdelim\fP [\fIforeground\fP] [\fIbackground\fP]
219 One exception is the first context. It must start with the command
221 \fBcontext\fP \fBdefault\fP [\fIforeground\fP] [\fIbackground\fP]
223 or else \fBcooledit\fP will return an error.
225 The \fBlinestart\fP option dictates that \fIdelim\fP must start at
226 the beginning of a line.
228 The \fBwhole\fP option tells that delim must be a whole word. What
229 constitutes a whole word are a set of characters that can be
230 changed at any point in the file with the \fBwholechars\fP
231 command. The \fBwholechars\fP command at the top just sets the
232 set exactly to its default and could therefore have been omitted. To
233 specify that a word must be whole on the left only, you can use
234 the \fBwholeleft\fP option, and similarly on the right. The left and
235 right set of characters can be set separately with,
237 \fBwholechars\fP [\fBleft\fP|\fBright\fP] \fIcharacters\fP
239 The \fBexclusive\fP option causes the text between the delimiters to be
240 highlighted, but not the delimiters themselves.
242 Each rule is a line of the form:
244 \fBkeyword\fP [\fBwhole\fP|\fBwholeright\fP|\fBwholeleft\fP] [\fBlinestart\fP] 
245 \fIstring\fP \fIforeground\fP [\fIbackground\fP]
248 Context or keyword strings are interpreted, so that you can include
249 tabs and spaces with the sequences \\t and \\s.  Newlines and the \\ are
250 specified with \\n and \\\\ respectively.  Since whitespace is used as a
251 separator, it may not be used as is.  Also, \\* must be used to specify
252 a *.  The * itself is a wildcard that matches any length of characters.
253 For example,
255   keyword         '*'      6 
257 colors all C single character constants green. You could also have
258 used
260   keyword         "*"      6 
262 to color string constants, except that the matched string may not cross
263 newlines. \fIThe wildcard may be used within context delimiters as
264 well\fP, but you \fBcannot have a wildcard as the last or first character\fP.
266 Important to note is the line
268   keyword  \\\\\\n  24
270 This line defines a keyword containing the \\ and newline characters.
271 Because keywords have a higher precedence than context delimiters, this
272 keyword prevents the context from ending at the end of a line if the
273 line ends in a \\ thus allowing C preprocessor directive to continue
274 across multiple lines.
276 The colors themselves are numbered 0 to 26 and are explained below in
277 \fBFURTHER BEHAVIORAL OPTIONS\fP. You can also use \fBany\fP of the named
278 colors specified in \fB/usr/lib/X11/rgb.txt\fP, though only one word
279 versions of them. It is better to stick to the numerical colors
280 to limit use of the color palette.
282 Comments may be included on a line of there own and begin with
283 a #.
285 Because of the simplicity of the implementation, there are a few
286 intricacies that will not be coped with correctly but these are a minor
287 irritation. On the whole, a broad spectrum of quite complicated
288 situations are handled with these simple rules. It is a good idea to
289 take a look at the syntax file to see some of the nifty tricks you can
290 do with a little imagination. If you can't get by with the rules I have
291 coded, and you think you have a rule that would be useful, please email
292 me with your request. However, do not ask for regular expression
293 support, because this is flatly impossible.
295 A useful hint is to work with as much as possible with the things
296 you \fIcan\fP do rather than try to do things that this
297 implementation can't cope with. Also remember that the aim of
298 syntax highlighting is to make programming less prone to error,
299 \fInot\fP to make code look pretty.
301 .SH COLORS
302 The default colors may be changed by appending to the
303 \fBMC_COLOR_TABLE\fP environment variable. Foreground and
304 background colors pairs may be specified for example with:
307 MC_COLOR_TABLE="$MC_COLOR_TABLE:\\
308 editnormal=lightgray,black:\\
309 editbold=yellow,black:\\
310 editmarked=black,cyan"
313 .SH OPTIONS
314 Most options can now be set from the editors options dialog
315 box. See the \fBOptions\fP menu. The following options are defined in 
316 \fB~/.mc/ini\fP and have obvious counterparts in the dialog box.
317 You can modify them to change the editor behavior, by editing the file. 
318 Unless specified, a 1 sets the option to on, and a 0 sets it to
319 off, as is usual.
321 .I use_internal_edit
322 This option is ignored when invoking 
323 .B mcedit.
325 .I editor_key_emulation
326 1 for 
327 .B Emacs 
328 keys, and 0 for normal 
329 .B Cooledit 
330 keys.
332 .I editor_tab_spacing
333 Interpret the tab character as being of this length.
334 Default is 8. You should avoid using
335 other than 8 since most other editors and text viewers
336 assume a tab spacing of 8. Use 
337 .B editor_fake_half_tabs 
338 to simulate a smaller tab spacing.
340 .I editor_fill_tabs_with_spaces
341 Never insert a tab space. Rather insert spaces (ascii 20h) to fill to the
342 desired tab size.
344 .I editor_return_does_auto_indent
345 Pressing return will tab across to match the indentation
346 of the first line above that has text on it.
348 .I editor_backspace_through_tabs
349 Make a single backspace delete all the space to the left
350 margin if there is no text between the cursor and the left
351 margin.
353 .I editor_fake_half_tabs
354 This will emulate a half tab for those who want to program
355 with a tab spacing of 4, but do not want the tab size changed
356 from 8 (so that the code will be formatted the same when displayed
357 by other programs). When editing between text and the left 
358 margin, moving and tabbing will be as though a tab space were
359 4, while actually using spaces and normal tabs for an optimal fill.
360 When editing anywhere else, a normal tab is inserted.
362 .I editor_option_save_mode
363 (0, 1 or 2.) The save mode (see the options menu also)
364 allows you to change the method
365 of saving a file. Quick save (0) saves the file by immediately,
366 truncating the disk file to zero length (i.e. erasing it)
367 and the writing the editor contents to the file. This method
368 is fast, but dangerous, since a system error during a file
369 save will leave the file only partially written, possibly
370 rendering the data irretrievable. When saving, the safe save (1)
371 option enables creation of a temporary file into which the
372 file contents are first written. In the event of an problem,
373 the original file is untouched. When the temporary file is
374 successfully written, it is renamed to the name of the original
375 file, thus replacing it. The safest method is create
376 backups (2). Where a backup file is created before any changes
377 are made. You can specify your own backup file extension in
378 the dialog. Note that saving twice will replace your backup
379 as well as your original file.
381 .SH Miscellaneous
383 (Scanf search and replace have previously not worked properly.
384 With this release, problems with search and replace have been
385 fixed.)
387 You can use scanf search and replace to search and replace
388 a C format string. First take a look at the 
389 .B sscanf 
390 and 
391 .B sprintf 
392 man pages to see what a format string
393 is and how it works. An example is as follows: Suppose you want
394 to replace all occurrences of say, an open bracket, three
395 comma separated numbers, and a close bracket, with the
396 word 
397 .I apples, 
398 the third number, the word 
399 .I oranges
400 and then the second number, you would fill in the Replace dialog
401 box as follows:
404 .B Enter search string
405 (%d,%d,%d)
406 .B Enter replace string
407 apples %d oranges %d
408 .B Enter replacement argument order
412 The last line specifies that the third and then the second
413 number are to be used in place of the first and second.
415 It is advisable to use this feature with Prompt On Replace on, because
416 a match is thought to be found whenever the number of arguments found
417 matches the number given, which is not always a real match. Scanf also
418 treats whitespace as being elastic.  Note that the scanf format %[ is
419 very useful for scanning strings, and whitespace.
421 The editor also displays non-us characters (160+). When editing
422 binary files, you should set 
423 .B display bits 
424 to 7 bits in the Midnight Commander options menu to keep the
425 spacing clean.
428 .SH FILES
429 @prefix@/share/mc.hlp
431 The help file for the program.
433 @prefix@/share/mc/mc.ini
435 The default system-wide setup for the Midnight Commander, used only if
436 the user lacks his own ~/.mc/ini file.
438 @prefix@/share/mc/mc.lib
440 Global settings for the Midnight Commander.  Settings in this file are
441 global to any Midnight Commander, it is useful to define site-global
442 .\"LINK2
443 terminal settings.
444 .\"Terminal databases"
446 $HOME/.mc/ini
448 User's own setup. If this file is present then the setup is loaded
449 from here instead of the system-wide startup file.
451 $HOME/.mc/cedit/
453 User's own temporary directory where block commands are processed
454 and saved.
456 .\"SKIP_SECTION"
457 .SH LICENSE
458 This program is distributed under the terms of the GNU General Public
459 License as published by the Free Software Foundation. See the built-in
460 help of the Midnight Commander for details on the License and the lack
461 of warranty.
462 .SH AVAILABILITY
463 The latest version of this program can be found at 
464 ftp://ftp.gnome.org/mirror/gnome.org/stable/sources/mc/ and on the
465 mirrors listed on the GNOME site http://www.gnome.org/.
466 .SH SEE ALSO
467 cooledit(1), mc(1), gpm(1), terminfo(1), scanf(3).
469 .SH AUTHORS
470 Paul Sheer (psheer@obsidian.co.za) is the developer of
471 the Midnight Commander's internal editor.
473 .SH BUGS
474 Bugs should be reported to mc-devel@gnome.org