summaryrefslogtreecommitdiffstats
path: root/doc/man/mcedit.1.in
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/man/mcedit.1.in661
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/.