diff options
Diffstat (limited to 'doc/man/mcedit.1.in')
| -rw-r--r-- | doc/man/mcedit.1.in | 661 |
1 files changed, 661 insertions, 0 deletions
diff --git a/doc/man/mcedit.1.in b/doc/man/mcedit.1.in new file mode 100644 index 0000000..2869af7 --- /dev/null +++ b/doc/man/mcedit.1.in @@ -0,0 +1,661 @@ +.TH MCEDIT 1 "%DATE_OF_MAN_PAGE%" "MC Version %MAN_VERSION%" "GNU Midnight Commander" +.SH NAME +mcedit \- Internal file editor of GNU Midnight Commander. +.SH SYNOPSIS +.B mcedit +[\-bcCdfhstVx?] [+lineno] [file1] [file2] ... +.PP +.B mcedit +[\-bcCdfhstVx?] file1:lineno[:] file2:lineno[:] ... +.SH DESCRIPTION +.LP +mcedit is a link to +.BR mc , +the main GNU Midnight Commander executable. Executing GNU Midnight Commander +under this name runs the internal editor and opens files +specified on the command line. The editor is based on the terminal version of +.B cooledit +\- standalone editor for X Window System. +.SH OPTIONS +.TP +.I "+lineno" +Go to the line specified by number (do not put a space between the +.I "+" +sign and the number). Several line numbers are allowed but only the last one +will be used, and it will be applied to the first file only. +.TP +.I "\-b" +Force black and white display. +.TP +.I "\-c" +Force ANSI color mode on terminals that don't seem to have color +support. +.TP +.I "\-C <keyword>=<fgcolor>,<bgcolor>,<attributes>:<keyword>= ..." +Specify a different color set. See the +.B Colors +section in mc(1) for more information. +.TP +.I "\-d" +Disable mouse support. +.TP +.I "\-f" +Display the compiled\-in search path for GNU Midnight Commander data +files. +.TP +.I "\-t" +Force using termcap database instead of terminfo. This option is only +applicable if GNU Midnight Commander was compiled with S\-Lang library +with terminfo support. +.TP +.I "\-V" +Display the version of the program. +.TP +.I "\-x" +Force xterm mode. Used when running on xterm\-capable terminals (two +screen modes, and able to send mouse escape sequences). +.SH FEATURES +The internal file editor is a full\-featured windowed editor. It can +edit several files at the same time. Maximum size of each file is 64 +megabytes. It is possible to edit binary files. The features it presently +supports are: block copy, move, delete, cut, paste; key for key undo; +pull\-down menus; file insertion; macro commands; regular expression +search and replace; shift\-arrow text highlighting (if supported by +the terminal); insert\-overwrite toggle; autoindent; tunable tab size; +syntax highlighting for various file types; and an option to pipe text +blocks through shell commands like indent and ispell. +.PP +Each file is opened in its own window in full\-screen mode. Window control +in mcedit is similar to the window control in other multi\-window program: +double click on window title maximizes the window to full\-screen or restores +window size and position; left\-click on window title and mouse drag moves +the window in editor area; left\-click on low\-right frame corner and mouse drag +resizes the window. These actions can be made using "Window" menu. +.SH KEYS +The editor is easy to use and can be used without learning. The +pull\-down menu is invoked by pressing F9. You can learn other keys from +the menu and from the button bar labels. +.PP +In addition to that, Shift combined with arrows does text highlighting +(if supported by the terminal): +.B Ctrl\-Ins +copies to the file +.BR ~/.cache/mc/mcedit/mcedit.clip , +.B Shift\-Ins +pastes from +.BR ~/.cache/mc/mcedit/mcedit.clip , +.B Shift\-Del +cuts to +.BR ~/.cache/mc/mcedit/mcedit.clip , +and +.B Ctrl\-Del +deletes highlighted text. Mouse highlighting also works on some +terminals. To use the standard mouse support provided by your terminal, +hold the Shift key. Please note that the mouse support in the terminal +doesn't share the clipboard with +.BR mcedit . +.PP +The completion key (usually +.B "Meta\-Tab" +or +.BR "Escape Tab" ) +completes the word under the cursor using the words used in the file. +.SH MACRO +.PP +To define a macro, press +.B Ctrl\-R +and then type out the keys you want to be executed. Press +.B Ctrl\-R +again when finished. The macro can be assigned to any key by pressing that key. +The macro is executed when you press the assigned key. +.PP +The macro commands are stored in section +.B [editor] +it the file +.BR ~/.local/share/mc/mc.macros . +.PP +External scripts (filters) can be assigned into the any hotkey by edit +.B mc.macros +like following: +.PP +.nf +[editor] +ctrl\-W=ExecuteScript:25; +.fi +.PP +This means that ctrl\-W hotkey initiates the +.I ExecuteScript(25) +action, then editor handler translates this into execution of +.B ~/.local/share/mc/mcedit/macros.d/macro.25.sh +shell script. +.PP +External scripts are stored in +.B ~/.local/share/mc/mcedit/macros.d/ +directory and must be named as +.B macro.XXXX.sh +where +.B XXXX +is the number from 0 to 9999. +See +.B Edit Menu File +for more detail about format of the script. +.PP +Following macro definition and directives can be used: +.TP +.I #silent +If this directive is set, then script starts without interactive subshell. +.TP +.I %c +The cursor column position number. +.TP +.I %i +The indent of blank space, equal the cursor column. +.TP +.I %y +The syntax type of current file. +.TP +.I %b +The block file name. +.TP +.I %f +The current file name. +.TP +.I %n +Only the current file name without extension. +.TP +.I %x +The extension of current file name. +.TP +.I %d +The current directory name. +.TP +.I %F +The current file in the unselected panel. +.TP +.I %D +The directory name of the unselected panel. +.TP +.I %t +The currently tagged files. +.TP +.I %T +The tagged files in the unselected panel. +.TP +.IR %u " and " %U +Similar to the +.I %t +and +.I %T +macros, but in addition the files are untagged. You can use this macro +only once per menu file entry or extension file entry, because next time +there will be no tagged files. +.TP +.IR %s " and " %S +The selected files: The tagged files if there are any. Otherwise the +current file. +.PP +Feel free to edit this files, if you need. +Here is a sample external script: +.PP +.nf +l comment selection + TMPFILE=`mktemp ${MC_TMPDIR:\-/tmp}/up.XXXXXX` || exit 1 + echo #if 0 > $TMPFILE + cat %b >> $TMPFILE + echo #endif >> $TMPFILE + cat $TMPFILE > %b + rm \-f $TMPFILE +.fi +.PP +If some keys don't work, you can use +.B Learn Keys +in the +.B Options +menu. +.SH CODE NAVIGATION +.B mcedit +can be used for navigation through code with tags files created by etags +or ctags commands. If there is no TAGS file code navigation will not work. +For example, in case of exuberant\-ctags for C language command will be: +.PP +ctags \-e \-\-language\-force=C \-R ./ +.PP +.B Meta\-Enter +shows list box to select item under cursor (cursor should stand at the end +of the word). +.PP +.B Meta\-Minus +where minus is symbol "\-" goes to previous function in navigation list +(like browser's Back button). +.PP +.B Meta\-Equal +where equal is symbol "=" goes to next function in navigation list +(like browser's Forward button). +.PP +.SH SYNTAX HIGHLIGHTING +.B mcedit +supports syntax highlighting. This means that keywords and contexts +(like C comments, string constants, etc) are highlighted in different +colors. The following section explains the format of the file +.BR ~/.local/share/mc/syntax/Syntax . +If this file is missing, system\-wide +.B %pkgdatadir%/syntax/Syntax +is used. +The file +.B ~/.local/share/mc/syntax/Syntax +is rescanned on opening of every new editor file. The file contains +rules for highlighting, each of which is given on a separate line, and +define which keywords will be highlighted with what color. +.PP +The file is divided into sections, each beginning with a line with the +.B file +command. The sections are normally put into separate files using the +.B include +command. +.PP +The +.B file +command has three arguments. The first argument is a regular expression +that is applied to the file name to determine if the following section +applies to the file. The second argument is the description of the file +type. It is used in +.BR cooledit ; +future versions of +.B mcedit +may use it as well. The third optional argument is a regular expression +to match the first line of text of the file. The rules in the following +section apply if either the file name or the first line of text matches. +.PP +A section ends with the start of another section. Each section is +divided into contexts, and each context contains rules. A context is a +scope within the text that a particular set of rules belongs to. For +instance, the text within a C style comment (i.e. between +.B /* +and +.BR */ ) +has its own color. This is a context, although it has no further rules +inside it because there is probably nothing that we want highlighted +within a C comment. +.PP +A trivial C programming section might look like this: +.PP +.nf +file .\\*\\\\.c C\\sProgram\\sFile (#include|/\\\\\\*) + +wholechars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_ + +# default colors +define comment brown +context default + keyword whole if yellow + keyword whole else yellow + keyword whole for yellow + keyword whole while yellow + keyword whole do yellow + keyword whole switch yellow + keyword whole case yellow + keyword whole static yellow + keyword whole extern yellow + keyword { brightcyan + keyword } brightcyan + keyword '*' green + +# C comments +context /\\* \\*/ comment + +# C preprocessor directives +context linestart # \\n red + keyword \\\\\\n brightred + +# C string constants +context " " green + keyword %d brightgreen + keyword %s brightgreen + keyword %c brightgreen + keyword \\\\" brightgreen +.fi +.PP +Each context starts with a line of the form: +.PP +.B context +.RB [ exclusive ] +.RB [ whole | wholeright | wholeleft ] +.RB [ linestart ] +.I delim +.RB [ linestart ] +.I delim +.RI [ foreground ] +.RI [ background ] +.RI [ attributes ] +.PP +The first context is an exception. It must start with the command +.PP +.B context default +.RI [ foreground ] +.RI [ background ] +.RI [ attributes ] +.PP +otherwise +.B mcedit +will report an error. The +.B linestart +option specifies that +.I delim +must start at the beginning of a line. The +.B whole +option tells that +.I delim +must be a whole word. To specify that a word must begin on the word +boundary only on the left side, you can use the +.B wholeleft +option, and similarly a word that must end on the word boundary is specified by +.BR wholeright . +.PP +The set of characters that constitute a whole word can be changed at any +point in the file with the +.B wholechars +command. The left and right set of characters can be set separately +with +.PP +.B wholechars +.RB [ left | right ] +.I characters +.PP +The +.B exclusive +option causes the text between the delimiters to be highlighted, but not +the delimiters themselves. +.PP +Each rule is a line of the form: +.PP +.B keyword +.RB [ whole | wholeright | wholeleft ] +.RB [ linestart ] +.I string foreground +.RI [ background ] +.RI [ attributes ] +.PP +Context or keyword strings are interpreted, so that you can include tabs +and spaces with the sequences \\t and \\s. Newlines and backslashes are +specified with \\n and \\\\ respectively. Since whitespace is used as a +separator, it may not be used as is. Also, \\* must be used to specify +an asterisk. The * itself is a wildcard that matches any length of +characters. For example, +.PP +.nf + keyword '*' green +.fi +.PP +colors all C single character constants green. You also could use +.PP +.nf + keyword "*" green +.fi +.PP +to color string constants, but the matched string would not be allowed +to span across multiple newlines. The wildcard may be used within +context delimiters as well, but you cannot have a wildcard as the last +or first character. +.PP +Important to note is the line +.PP +.nf + keyword \\\\\\n brightgreen +.fi +.PP +This line defines a keyword containing the backslash and newline +characters. Since the keywords are matched before the context +delimiters, this keyword prevents the context from ending at the end of +the lines that end in a backslash, thus allowing C preprocessor +directive to continue across multiple lines. +.PP +The possible colors are: black, gray, red, brightred, green, +brightgreen, brown, yellow, blue, brightblue, magenta, brightmagenta, +cyan, brightcyan, lightgray and white. The special keyword "default" means +the terminal's default. Another special keyword "base" means mc's main +colors, it is useful as a placeholder if you want to specify attributes +without modifying the background color. When 256 colors are available, +they can be specified either as color16 to color255, or as rgb000 to rgb555 +and gray0 to gray23. +.PP +If the syntax file is shared with +.BR cooledit , +it is possible to specify different colors for +.B mcedit +and +.B cooledit +by separating them with a slash, e.g. +.PP +.nf +keyword #include red/Orange +.fi +.PP +.B mcedit +uses the color before the slash. See cooledit(1) for supported +.B cooledit +colors. +.PP +Attributes can be any of bold, italic, underline, reverse and blink, appended by a +plus sign if more than one are desired. +.PP +Comments may be put on a separate line starting with the hash sign (#). +.PP +If you are describing case insensitive language you need to use +.B caseinsensitive +directive. It should be specified at the beginning of syntax file. +.PP +Because of the simplicity of the implementation, there are a few +intricacies that will not be dealt with correctly but these are a minor +irritation. On the whole, a broad spectrum of quite complicated +situations are handled with these simple rules. It is a good idea to +take a look at the syntax file to see some of the nifty tricks you can +do with a little imagination. If you cannot get by with the rules I +have coded, and you think you have a rule that would be useful, please +email me with your request. However, do not ask for regular expression +support, because this is flatly impossible. +.PP +A useful hint is to work with as much as possible with the things you +can do rather than try to do things that this implementation cannot deal +with. Also remember that the aim of syntax highlighting is to make +programming less prone to error, not to make code look pretty. +.PP +The syntax highlighting can be toggled using Ctrl\-s shortcut. +.SH COLORS +The default colors may be changed by appending to the +.B MC_COLOR_TABLE +environment variable. Foreground and background colors pairs may be +specified for example with: +.PP +.nf +MC_COLOR_TABLE="$MC_COLOR_TABLE:\\ +editnormal=lightgray,black:\\ +editbold=yellow,black:\\ +editmarked=black,cyan" +.fi +.SH OPTIONS +Most options can be set from Options dialog box. See the +.B Options +menu. The following options are defined in +.B ~/.config/mc/ini +and have obvious counterparts in the dialog box. You can modify them to +change the editor behavior, by editing the file. Unless specified, a 1 +sets the option to on, and a 0 sets it to off, as usual. +.TP +.I use_internal_edit +This option is ignored when invoking +.BR mcedit . +.TP +.I editor_tab_spacing +Interpret the tab character as being of this length. +Default is 8. You should avoid using +other than 8 since most other editors and text viewers +assume a tab spacing of 8. Use +.B editor_fake_half_tabs +to simulate a smaller tab spacing. +.TP +.I editor_fill_tabs_with_spaces +Never insert a tab character. Rather insert spaces (ascii 32) to fill to the +desired tab size. +.TP +.I editor_return_does_auto_indent +Pressing return will tab across to match the indentation +of the first line above that has text on it. +.TP +.I editor_backspace_through_tabs +Make a single backspace delete all the space to the left +margin if there is no text between the cursor and the left +margin. +.TP +.I editor_fake_half_tabs +This will emulate a half tab for those who want to program +with a tab spacing of 4, but do not want the tab size changed +from 8 (so that the code will be formatted the same when displayed +by other programs). When editing between text and the left +margin, moving and tabbing will be as though a tab space were +4, while actually using spaces and normal tabs for an optimal fill. +When editing anywhere else, a normal tab is inserted. +.TP +.I editor_option_save_mode +Possible values 0, 1 and 2. The save mode (see the options menu also) +allows you to change the method of saving a file. Quick save (0) saves +the file immediately, truncating the disk file to zero length (i.e. +erasing it) and then writing the editor contents to the file. This +method is fast, but dangerous, since a system error during a file save +will leave the file only partially written, possibly rendering the data +irretrievable. When saving, the safe save (1) option enables creation +of a temporary file into which the file contents are first written. In +the event of a problem, the original file is untouched. When the +temporary file is successfully written, it is renamed to the name of the +original file, thus replacing it. The safest method is create backups +(2): a backup file is created before any changes are made. You +can specify your own backup file extension in the dialog. Note that +saving twice will replace your backup as well as your original file. +.TP +.I editor_word_wrap_line_length +Line length to wrap at. Default is 72. +.TP +.I editor_backup_extension +Symbol to add to name of backup files. Default is "~". +.TP +.I editor_line_state +Show state line of editor. Currently it shows current line number (in the future +it might show things like folding, breakpoints, etc.). M\-n toggles this option. +.TP +.I editor_visible_spaces +Toggle "show visible trailing spaces". If editor_visible_spaces=1, they are shown +as '.' +.TP +.I editor_visible_tabs +Toggle "show visible tabs". If editor_visible_tabs=1, tabs are shown as '<\-\-\-\->' +.TP +.I editor_persistent_selections +Do not remove block selection after cursor movement. +.TP +.I editor_drop_selection_on_copy +Reset selection after copy to clipboard. +.TP +.I editor_cursor_beyond_eol +Allow moving cursor beyond the end of line. +.TP +.I editor_cursor_after_inserted_block +Allow moving cursor after inserted block. +.TP +.I editor_syntax_highlighting +enable syntax highlighting. +.TP +.I editor_edit_confirm_save +Show confirmation dialog on save. +.TP +.I editor_option_typewriter_wrap +to be described +.TP +.I editor_option_auto_para_formatting +to be described +.TP +.I editor_option_save_position +Save file position on exit. +.TP +.I source_codepage +Symbol representation of codepage name for file (i.e. CP1251, ~ \- default). +.TP +.I editor_group_undo +Combine UNDO actions for several of the same type of action (inserting/overwriting, +deleting, navigating, typing) +.TP +.I editor_wordcompletion_collect_entire_file +Search autocomplete candidates in entire file (1) or just from +beginning of file to cursor position (0). +.TP +.I editor_wordcompletion_collect_all_files +Search autocomplete candidates from all loaded files (1, default), not only from +the currently edited one (0). +.TP +.I spell_language +Spelling language (en, en\-variant_0, ru, etc) installed with aspell +package (a full list can be obtained using 'aspell' utility). +Use +.B spell_language = NONE +to disable aspell support. Default value is 'en'. Option must be located +in the [Misc] section. +.TP +.I editor_stop_format_chars +Set of characters to stop paragraph formatting. If one of those characters +is found in the beginning of line, that line and all following lines of paragraph +will be untouched. Default value is +"\fB-\fR\fB+\fR\fB*\fR\fB\\\fR\fB,\fR\fB.\fR\fB;\fR\fB:\fR\fB&\fR\fB>\fR". +.TP +.I editor_state_full_filename +Show full path name in the status line. If disabled (default), only base name of the +file is shown. +.SH MISCELLANEOUS +The editor also displays non\-us characters (160+). When editing +binary files, you should set +.B display bits +to 7 bits in Midnight Commander's options menu to keep the spacing +clean. +.SH FILES +.I %pkgdatadir%/help/mc.hlp +.IP +The help file for the program. +.PP +.I %pkgdatadir%/mc.ini +.IP +The default system\-wide setup for GNU Midnight Commander, used only if +the user's own ~/.config/mc/ini file is missing. +.PP +.I %pkgdatadir%/mc.lib +.IP +Global settings for Midnight Commander. Settings in this file +affect all users, whether they have ~/.config/mc/ini or not. +.PP +.I %pkgdatadir%/syntax/* +.IP +The default system\-wide syntax files for mcedit, used only if +the corresponding user's own file in +.B ~/.local/share/mc/syntax/ +is missing. +.PP +.I ~/.config/mc/ini +.IP +User's own setup. If this file is present then the setup is loaded +from here instead of the system\-wide setup file. +.PP +.I ~/.local/share/mc/mcedit/ +.IP +User's own directory where block commands are processed and saved and +user's own syntax files are located. +.SH LICENSE +This program is distributed under the terms of the GNU General Public +License as published by the Free Software Foundation. See the built\-in +help of Midnight Commander for details on the License and the lack +of warranty. +.SH AVAILABILITY +The latest version of this program can be found at +http://ftp.midnight\-commander.org/. +.SH SEE ALSO +cooledit(1), mc(1), gpm(1), terminfo(1), scanf(3). +.SH AUTHORS +Paul Sheer (psheer@obsidian.co.za) is the original author of +Midnight Commander's internal editor. +.SH BUGS +Bugs should be reported to https://www.midnight\-commander.org/. |