1 .\" $OpenBSD: mg.1,v 1.68 2012/07/11 19:56:13 sobrado Exp $
2 .\" This file is in the public domain.
4 .Dd $Mdocdate: July 11 2012 $
9 .Nd emacs-like text editor
18 is intended to be a small, fast, and portable editor for
19 people who can't (or don't want to) run emacs for one
20 reason or another, or are not familiar with the
23 It is compatible with emacs because there shouldn't
24 be any reason to learn more editor types than emacs or
27 The options are as follows:
30 Go to the line specified by number (do not insert
34 If a negative number is specified, the line number counts
35 backwards from the end of the file i.e. +-1 will be the last
36 line of the file, +-2 will be second last, and so on.
38 Run the mode command for all buffers created from
39 arguments on the command line, including the
40 scratch buffer and all files.
42 Turn off backup file generation.
44 .Sh WINDOWS AND BUFFERS
45 When a file is loaded into
49 This buffer may be displayed on the screen in more than one window.
50 At present, windows may only be split horizontally, so each window is
51 delineated by a modeline at the bottom.
52 If changes are made to a buffer, it will be reflected in all open windows.
54 If a buffer name begins and ends with an asterisk, the buffer is considered
55 throwaway; i.e. the user will not be prompted to save changes when
58 The current cursor location in
64 It is possible to define a window-specific region of text by setting a second
69 is the text between point and mark inclusive.
70 Deleting the character at the mark position leaves
71 the mark at the point of deletion.
73 Note: The point and mark are window-specific in
75 not buffer-specific, as in other emacs flavours.
79 character appended to the file name and
80 are created in the current working directory by default.
81 Whether to create backup files or not can be toggled with the
82 make-backup-file command.
83 The backup file location can either be in the current
84 working directory, or all backups can be moved to a
86 directory where files retain their path name to retain uniqueness.
87 Use the backup-to-home-directory to alternate between these two locations.
88 Further, if any application creates backup files in the
90 these can be left with the leave-tmpdir-backups command.
93 supports tag files created by
95 allowing the user to quickly locate various object definitions.
96 Note though that emacs uses etags, not ctags.
99 supports navigating source code using cscope.
102 requires cscope and cscope-indexer executables to be present in
105 .Sh DEFAULT KEY BINDINGS
106 Normal editing commands are very similar to GNU Emacs.
107 In the following examples, C-x means Control-x, and M-x means Meta-x,
108 where the Meta key may be either a special key on the keyboard
109 or the ALT key; otherwise ESC followed by the key X works as well.
111 .Bl -tag -width xxxxxxxxxxxx -offset indent -compact
119 cscope-find-functions-calling-this-function
121 cscope-find-global-definition
123 cscope-find-egrep-pattern
125 cscope-find-this-file
127 cscope-find-files-including-file
133 cscope-find-this-symbol
135 cscope-find-this-text-string
183 save-buffers-kill-emacs
205 exchange-point-and-mark
215 split-window-vertically
217 find-file-other-window
221 switch-to-buffer-other-window
223 find-file-other-window
275 delete-horizontal-space
303 execute-extended-command
307 shell-command-on-region
322 For a complete description of
326 To see the active keybindings at any time, type
327 .Dq M-x describe-bindings .
329 Commands are invoked by
331 or by binding to a key.
332 Many commands take an optional numerical parameter,
334 This parameter is set either by
337 is the numerical argument) before the command, or by
338 one or more invocations of the universal argument, usually bound to C-u.
339 When invoked in this manner, the value of the numeric parameter to
340 be passed is displayed in the minibuffer before the M-x.
341 One common use of the parameter is in mode toggles (e.g.\&
343 If no parameter is supplied, the mode is toggled to its
345 If a positive parameter is supplied, the mode is forced to on.
346 Otherwise, it is forced to off.
348 .Bl -tag -width xxxxx
351 Prompt the user for a string, open the *help* buffer,
354 commands that contain that string.
356 Register an auto-execute hook; that is, specify a filename pattern
357 (conforming to the shell's filename globbing rules) and an associated
358 function to execute when a file matching the specified pattern
359 is read into a buffer.
361 Toggle auto-fill mode (sometimes called mail-mode),
362 where text inserted past the fill column is automatically wrapped
365 Toggle indent mode, where indentation is preserved after a newline.
366 .It back-to-indentation
367 Move the dot to the first non-whitespace character on the current line.
368 .It backup-to-home-directory
369 Save backup copies to a
371 directory instead of working directory.
372 Requires make-backup-files to be on.
374 Move cursor backwards one character.
375 .It backward-kill-word
376 Kill text backwards by
379 .It backward-paragraph
380 Move cursor backwards
383 Paragraphs are delimited by <NL><NL> or <NL><TAB> or <NL><SPACE>.
385 Move cursor backwards by the specified number of words.
386 .It beginning-of-buffer
387 Move cursor to the top of the buffer.
388 .It beginning-of-line
389 Move cursor to the beginning of the line.
391 Self-insert a character, then search backwards and blink its
393 For delimiters other than
394 parenthesis, brackets, and braces, the character itself
395 is used as its own match.
397 Toggle bsmap mode, where DEL and C-h are swapped.
399 Toggle a KNF-compliant mode for editing C program files.
400 .It call-last-kbd-macro
401 Invoke the keyboard macro.
405 words; i.e. convert the first character of the word to
406 upper case, and subsequent letters to lower case.
408 Change the global working directory.
409 See also global-wd-mode.
410 .It copy-region-as-kill
411 Copy all of the characters in the region to the kill buffer,
412 clearing the mark afterwards.
413 This is a bit like a kill-region followed by a yank.
415 Count the number of lines matching the supplied regular expression.
416 .It count-non-matches
417 Count the number of lines not matching the supplied regular expression.
418 .It cscope-find-this-symbol
419 List the matches for the given symbol.
420 .It cscope-find-global-definition
421 List global definitions for the given literal.
422 .It cscope-find-called-functions
423 List functions called from the given function.
424 .It cscope-find-functions-calling-this-function
425 List functions calling the given function.
426 .It cscope-find-this-text-string
427 List locations matching the given text string.
428 .It cscope-find-egrep-pattern
429 List locations matching the given extended regular expression pattern.
430 .It cscope-find-this-file
431 List filenames matching the given filename.
432 .It cscope-find-files-including-file
433 List files that #include the given filename.
434 .It cscope-next-symbol
435 Navigate to the next match.
436 .It cscope-prev-symbol
437 Navigate to the previous match.
439 Navigate to the next file.
441 Navigate to the previous file.
442 .It cscope-create-list-of-files-to-index
443 Create cscope's List and Index in the given directory.
445 Prompts the user for a named keymap (mode),
448 command, then creates a keybinding in the appropriate
450 .It delete-backward-char
454 Like delete-char, this actually does a kill if presented
456 .It delete-blank-lines
457 Delete blank lines around dot.
458 If dot is sitting on a blank line, this command
459 deletes all the blank lines above and below the current line.
460 Otherwise, it deletes all of the blank lines after the current line.
465 If any argument is present, it kills rather than deletes,
466 saving the result in the kill buffer.
467 .It delete-horizontal-space
468 Delete any whitespace around the dot.
469 .It delete-leading-space
470 Delete leading whitespace on the current line.
471 .It delete-trailing-space
472 Delete trailing whitespace on the current line.
473 .It delete-matching-lines
474 Delete all lines after dot that contain a string matching
475 the supplied regular expression.
476 .It delete-non-matching-lines
477 Delete all lines after dot that contain a string matching
478 the supplied regular expression.
479 .It delete-other-windows
480 Make the current window the only window visible on the screen.
482 Delete current window.
483 .It describe-bindings
484 List all global and local keybindings, putting the result in
486 .It describe-key-briefly
487 Read a key from the keyboard, and look it up in the keymap.
488 Display the name of the function currently bound to the key.
490 Process a numerical argument for keyboard-invoked functions.
492 Set all characters in the region to lower case.
494 Set characters to lower case, starting at the dot, and ending
502 Stop defining a keyboard macro.
504 Move cursor to the end of the buffer.
506 Move cursor to the end of the line.
508 Enlarge the current window by shrinking either the window above
510 .It eval-current-buffer
511 Evaluate the current buffer as a series of
518 Get one line from the user, and run it.
519 Useful for testing expressions in
522 .It exchange-point-and-mark
523 Swap the values of "dot" and "mark" in the current window.
524 Return an error if no mark is set.
525 .It execute-extended-command
526 Invoke an extended command; i.e. M-x.
527 Call the message line routine to read in the command name and apply
528 autocompletion to it.
529 When it comes back, look the name up in the symbol table and run the
530 command if it is found, passing arguments as necessary.
531 Print an error if there is anything wrong.
533 Justify a paragraph, wrapping text at the current fill column.
535 Select a file for editing.
536 First check if the file can be found
537 in another buffer; if it is there, just switch to that buffer.
538 If the file cannot be found, create a new buffer, read in the
539 file from disk, and switch to the new buffer.
540 .It find-file-read-only
541 Same as find-file, except the new buffer is set to read-only.
542 .It find-alternate-file
543 Replace the current file with an alternate one.
544 Semantics for finding the replacement file are the same as
545 find-file, except the current buffer is killed before the switch.
546 If the kill fails, or is aborted, revert to the original file.
547 .It find-file-other-window
548 Opens the specified file in a second buffer.
549 Splits the current window if necessary.
551 Jump to definition of tag at dot.
553 Move cursor forwards (or backwards, if
558 Returns an error if the end of buffer is reached.
559 .It forward-paragraph
563 Paragraphs are delimited by <NL><NL> or <NL><TAB> or <NL><SPACE>.
565 Move the cursor forward by the specified number of words.
567 Bind a key in the global (fundamental) key map.
569 Unbind a key from the global (fundamental) key map; i.e. set it to 'rescan'.
571 Toggle global working-directory mode.
574 defaults to opening files (and executing commands like compile and grep)
575 relative to the global working directory.
576 When disabled, a working directory is set for each buffer.
578 Go to a specific line.
579 If an argument is present, then
580 it is the line number, else prompt for a line number to use.
582 Prompts for one of (a)propos, (b)indings, des(c)ribe key briefly.
584 Insert a string, mainly for use from macros.
586 Insert the contents of another buffer at dot.
588 Insert a file into the current buffer at dot.
590 Insert the bound character with word wrap.
591 Check to see if we're past the fill column, and if so,
594 Use incremental searching, initially in the reverse direction.
595 isearch ignores any explicit arguments.
596 If invoked during macro definition or evaluation, the non-incremental
597 search-backward is invoked instead.
599 Use incremental searching, initially in the forward direction.
600 isearch ignores any explicit arguments.
601 If invoked during macro definition or evaluation, the non-incremental
602 search-forward is invoked instead.
604 Join the current line to the previous.
605 If called with an argument,
606 join the next line to the current one.
608 Delete any whitespace around dot, then insert a space.
610 Abort the current action.
612 Dispose of a buffer, by name.
613 If the buffer name does not start and end with an asterisk,
614 prompt the user if the buffer
618 If called without an argument, it kills from dot to the end
619 of the line, unless it is at the end of the line, when it kills the
621 If called with an argument of 0, it kills from the start of the
623 If called with a positive argument, it kills from dot
624 forward over that number of newlines.
625 If called with a negative argument
626 it kills any text before dot on the current line, then it kills back
631 paragraphs starting with the current one.
633 Kill the currently defined region.
638 .It leave-tmpdir-backups
639 Modifies the behaviour of backup-to-home-directory.
640 Backup files that would normally reside in the system
642 are left there and not moved to the
646 Toggle whether line and column numbers are displayed in the modeline.
648 Display the list of available buffers.
650 Prompt the user for a filename, and then execute commands
653 Bind a key mapping in the local (topmost) mode.
655 Unbind a key mapping in the local (topmost) mode.
656 .It make-backup-files
657 Toggle generation of backup files.
658 .It mark-whole-buffer
659 Marks whole buffer as a region by putting dot at the beginning and mark
660 at the end of buffer.
662 When disabled, the meta key can be used to insert extended-ascii (8-bit)
664 When enabled, the meta key acts as usual.
665 .It negative-argument
666 Process a negative argument for keyboard-invoked functions.
668 Insert a newline into the current buffer.
669 .It newline-and-indent
670 Insert a newline, then enough tabs and spaces to duplicate the indentation
671 of the previous line.
672 Assumes tabs are every eight characters.
679 In this mode, spaces are inserted rather than tabs.
681 Turn off the modified flag in the current buffer.
683 Open up some blank space.
686 newlines, then back up over them.
688 The command to make the next (down the screen) window the current
690 There are no real errors, although the command does nothing if
691 there is only 1 window on the screen.
693 Toggle overwrite mode, where typing in a buffer overwrites
694 existing characters rather than inserting them.
696 Inserts a prefix string before each line of a region.
697 The prefix string is settable by using 'set-prefix-string'.
703 This command makes the previous (up the screen) window the
705 There are no errors, although the command does not do
706 a lot if there is only 1 window.
708 Return to position where find-tag was previously invoked.
712 and switch to alternate screen, if available.
714 Display current (global) working directory in the status area.
717 Search and replace strings selectively, prompting after each match.
719 Replace string globally without individual prompting.
720 .It query-replace-regexp
721 Replace strings selectively.
722 Does a search and replace operation using regular
723 expressions for both patterns.
725 Insert the next character verbatim into the current buffer; i.e. ignore
726 any function bound to that key.
728 Perform a regular expression search again, using the same search
729 string and direction as the last search command.
730 .It re-search-backward
731 Search backwards using a regular expression.
732 Get a search string from the user, and search, starting at dot
733 and proceeding toward the front of the buffer.
734 If found, dot is left
735 pointing at the first character of the pattern [the last character that
737 .It re-search-forward
738 Search forward using a regular expression.
739 Get a search string from the user and search for it starting at dot.
740 If found, move dot to just after the matched characters.
743 If not found, it just prints a message.
745 Reposition dot in the current window.
746 By default, the dot is centered.
747 If given a positive argument (n), the display is repositioned to line
751 is negative, it is that line from the bottom.
754 Recomputes all window sizes in case something has changed.
756 Save the contents of the current buffer if it has been changed,
757 optionally creating a backup copy.
758 .It save-buffers-kill-emacs
759 Offer to save modified buffers and quit
761 .It save-some-buffers
762 Look through the list of buffers, offering to save any buffer that
764 Buffers that are not associated with files (such
765 as *scratch*, *grep*, *compile*) are ignored.
770 A two-line overlap between pages is
772 If given a repeat argument, scrolls back lines, not pages.
773 .It scroll-one-line-down
774 Scroll the display down
776 lines without changing the cursor position.
777 .It scroll-one-line-up
780 lines up without moving the cursor position.
781 .It scroll-other-window
782 Scroll the next window in the window list window forward
786 Scroll forward one page.
787 A two-line overlap between pages is
789 If given a repeat argument, scrolls back lines, not pages.
791 Search again, using the same search string and direction as the last
795 Get a search string from the user, and search, starting
796 at dot and proceeding toward the front of the buffer.
798 left pointing at the first character of the pattern (the last character
802 Get a search string from the user, and search for it
804 If found, dot gets moved to just after the matched
805 characters, if not found, print a message.
806 .It self-insert-command
808 .It set-case-fold-search
809 Set case-fold searching, causing case not to matter
810 in regular expression searches.
813 Append the supplied mode to the list of default modes
814 used by subsequent buffer creation.
815 Built in modes include: fill, indent, overwrite, and notab.
817 Prompt the user for a fill column.
818 Used by auto-fill-mode.
820 Sets the mark in the current window to the current dot location.
821 .It set-prefix-string
822 Sets the prefix string to be used by the 'prefix-region' command.
823 .It shell-command-on-region
824 Provide the text in region to the shell command as input.
826 Shrink current window by one line.
827 The window immediately below is expanded to pick up the slack.
828 If only one window is present, this command has no effect.
830 Insert enough spaces to reach the next tab-stop position.
831 By default, tab-stops occur every 8 characters.
832 .It split-window-vertically
833 Split the current window.
834 A window smaller than 3 lines cannot be split.
836 Start defining a keyboard macro.
837 Macro definition is ended by invoking end-kbd-macro.
841 and switch back to alternate screen, if in use.
843 Prompt and switch to a new buffer in the current window.
844 .It switch-to-buffer-other-window
845 Switch to buffer in another window.
847 Toggle the read-only flag on the current buffer.
849 Transpose the two characters on either side of dot.
850 If dot is at the end of the line, transpose the two characters before it.
851 Return with an error if dot is at the beginning of line;
852 it seems to be a bit pointless to
855 Undo the most recent action.
856 If invoked again without an intervening command,
857 move the undo pointer to the previous action and undo it.
859 Add an undo boundary.
860 This is not usually done interactively.
861 .It undo-boundary-toggle
862 Toggle whether undo boundaries are generated.
863 Undo boundaries are often disabled before operations that should
864 be considered atomically undoable.
866 Toggle whether undo information is kept.
868 Show the undo records for the current buffer in a new buffer.
869 .It universal-argument
870 Repeat the next command 4 times.
871 Usually bound to C-u.
872 This command may be stacked; e.g.\&
873 C-u C-u C-f moves the cursor forward 16 characters.
876 Change all of the lower case characters in the region to
879 Move the cursor forward by the specified number of words.
880 As it moves, convert any characters to upper case.
882 Record name of the tags file to be used for subsequent find-tag.
883 .It what-cursor-position
884 Display a bunch of useful information about the current location of
886 The character under the cursor (in octal), the current line, row,
887 and column, and approximate position of the cursor in the file (as a
888 percentage) is displayed.
889 The column position assumes an infinite
890 position display; it does not truncate just because the screen does.
892 Ask for a file name and write the contents of the current buffer to
894 Update the remembered file name and clear the buffer
897 Yank text from kill-buffer.
900 kill buffer consists only
901 of the most recent kill.
904 .Sh CONFIGURATION FILES
905 There are two configuration files,
911 represents the name of the terminal type; e.g. if the terminal type
918 The terminal type startup file is used first.
920 The startup file format is a list of commands, one per line, as used for
921 interactive evaluation.
922 Strings that are normally entered by the user at any subsequent prompts
923 may be specified after the command name; e.g.:
924 .Bd -literal -offset indent
925 global-set-key ")" self-insert-command
926 global-set-key "\e^x\e^f" find-file
927 global-set-key "\ee[Z" backward-char
928 set-default-mode fill
930 auto-execute *.c c-mode
933 .Bl -tag -width /usr/share/doc/mg/tutorial -compact
937 terminal-specific startup file
939 alternative backup file location
940 .It Pa /usr/share/doc/mg/tutorial
947 Since it is written completely in C, there is currently no
948 language in which extensions can be written;
949 however, keys can be rebound and certain parameters can be changed
952 In order to use 8-bit characters (such as German umlauts), the Meta key
953 needs to be disabled via the
projects / pd_readline / blob