1 .. $Id: help.etx,v 1.76 2004/08/20 19:33:08 n8gray Exp $
2 .. NOTE: Remember to supply 'version' variable on setext command line.
3 .. For example, setext -m -v "version=NEdit Version 6.0".
5 .. The following are variable definitions for the various titles below
6 .. ----------------------------------------------------------------------------
7 .. |>title=Nirvana Editor (NEdit) Help Documentation<|
8 .. |>ttlMk==========================================<|
9 .. ----------------------------------------------------------------------------
24 .. .. This table of contents is only for the HTML version of this document.
31 Basic Operation Macro/Shell Extensions
32 Selecting_Text_ Shell_Commands_and_Filters_
33 Finding_and_Replacing_Text_ Learn/Replay_
34 Cut_and_Paste_ Macro_Language_
35 Using_the_Mouse_ Macro_Subroutines_
36 Keyboard_Shortcuts_ Highlighting_Information_
37 Shifting_and_Filling_ Range_Sets_
38 Tabbed_Editing_ Action_Routines_
41 Features for Programming Customizing_NEdit_
42 Programming_with_NEdit_ Preferences_
43 Tabs/Emulated_Tabs_ X_Resources_
44 Auto/Smart_Indent_ Key_Binding_
45 Syntax_Highlighting_ Highlighting_Patterns_
46 Finding_Declarations_(ctags)_ Smart_Indent_Macros_
49 Regular Expressions NEdit_Command_Line_
50 Basic_Regular_Expression_Syntax_ Client/Server_Mode_
51 Metacharacters_ Crash_Recovery_
52 Parenthetical_Constructs_ Version_
53 Advanced_Topics_ GNU_General_Public_License_
54 Example_Regular_Expressions_ Mailing_Lists_
63 .. .. What appears below will always print whether or not NEDITDOC is defined.
66 NEdit is a standard GUI (Graphical User Interface) style text editor for
67 programs and plain-text files. Users of Macintosh and MS Windows based text
68 editors should find NEdit a familiar and comfortable environment. NEdit
69 provides all of the standard menu, dialog, editing, and mouse support, as
70 well as all of the standard shortcuts to which the users of modern GUI based
71 environments are accustomed. For users of older style Unix editors, welcome
72 to the world of mouse-based editing!
75 .. NEdit is freely distributed under the terms of the Gnu General Public
78 .. .. This stuff will always be invisible, unless NEDITDOC is defined
83 .. NEdit is a single stand-alone executable file which can be installed by simply
84 .. copying the appropriate executable "nedit" for your system. Both sources and
85 .. executables are available from http://www.nedit.org. The optional "nc" (NEdit
86 .. Client) program is also available for users who want to run nedit in
87 .. client/server mode.
93 Help sections of interest to new users are listed under the "Basic Operation"
94 heading in the top-level Help menu:
97 Finding_and_Replacing_Text_
101 Shifting_and_Filling_
103 Programmers should also read the introductory section under the "Features for
104 Programming" section:
106 Programming_with_NEdit_
108 If you get into trouble, the Undo command in the Edit menu can reverse any
109 modifications that you make. NEdit does not change the file you are editing
110 until you tell it to Save.
112 3>Editing an Existing File
114 To open an existing file, choose Open... from the file menu. Select the file
115 that you want to open in the pop-up dialog that appears and click on OK. You
116 may open any number of files at the same time. Depending on your settings
117 (cf. "Tabbed_Editing_") each file can appear in its own editor window, or it
118 can appear under a tab in the same editor window. Using Open... rather than
119 re-typing the NEdit command and running additional copies of NEdit, will give
120 you quick access to all of the files you have open via the Windows menu, and
121 ensure that you don't accidentally open the same file twice. NEdit has no
122 "main" window. It remains running as long as at least one editor window is
125 3>Creating a New File
127 If you already have an empty (Untitled) window displayed, just begin typing
128 in the window. To create a new Untitled window, choose New Window or New Tab
129 from the File menu. To give the file a name and save its contents to the
130 disk, choose Save or Save As... from the File menu.
134 NEdit maintains periodic backups of the file you are editing so that you can
135 recover the file in the event of a problem such as a system crash, network
136 failure, or X server crash. These files are saved under the name `~filename`
137 (on Unix) or `_filename` (on VMS), where filename is the name of the file you
138 were editing. If an NEdit process is killed, some of these backup files may
139 remain in your directory. (To remove one of these files on Unix, you may
140 have to prefix the `~' (tilde) character with a (backslash) to prevent the
141 shell from interpreting it as a special character.)
145 As you become more familiar with NEdit, substitute the control and function
146 keys shown on the right side of the menus for pulling down menus with the
149 Dialogs are also streamlined so you can enter information quickly and without
150 using the mouse*. To move the keyboard focus around a dialog, use the tab
151 and arrow keys. One of the buttons in a dialog is usually drawn with a
152 thick, indented, outline. This button can be activated by pressing Return or
153 Enter. The Cancel or Dismiss button can be activated by pressing escape.
154 For example, to replace the string "thing" with "things" type:
156 <ctrl-r>thing<tab>things<return>
158 To open a file named "whole_earth.c", type:
162 (how much of the filename you need to type depends on the other files in the
163 directory). See the section called "Keyboard_Shortcuts_" for more details.
165 * Users who have set their keyboard focus mode to "pointer" should set
166 "Popups Under Pointer" in the Default Settings menu to avoid the additional
167 step of moving the mouse into the dialog.
168 ----------------------------------------------------------------------
176 NEdit has two general types of selections, primary (highlighted text), and
177 secondary (underlined text). Selections can cover either a simple range of
178 text between two points in the file, or they can cover a rectangular area of
179 the file. Rectangular selections are only useful with non-proportional (fixed
182 To select text for copying, deleting, or replacing, press the left mouse
183 button with the pointer at one end of the text you want to select, and drag
184 it to the other end. The text will become highlighted. To select a whole
185 word, double click (click twice quickly in succession). Double clicking and
186 then dragging the mouse will select a number of words. Similarly, you can
187 select a whole line or a number of lines by triple clicking or triple
188 clicking and dragging. Quadruple clicking selects the whole file. After
189 releasing the mouse button, you can still adjust a selection by holding down
190 the shift key and dragging on either end of the selection. To delete the
191 selected text, press delete or backspace. To replace it, begin typing.
193 To select a rectangle or column of text, hold the Ctrl key while dragging the
194 mouse. Rectangular selections can be used in any context that normal
195 selections can be used, including cutting and pasting, filling, shifting,
196 dragging, and searching. Operations on rectangular selections automatically
197 fill in tabs and spaces to maintain alignment of text within and to the right
198 of the selection. Note that the interpretation of rectangular selections by
199 Fill Paragraph is slightly different from that of other commands, the section
200 titled "Shifting_and_Filling_" has details.
202 The middle mouse button can be used to make an additional selection (called
203 the secondary selection). As soon as the button is released, the contents of
204 this selection will be copied to the insert position of the window where the
205 mouse was last clicked (the destination window). This position is marked by a
206 caret shaped cursor when the mouse is outside of the destination window. If
207 there is a (primary) selection, adjacent to the cursor in the window, the new
208 text will replace the selected text. Holding the shift key while making the
209 secondary selection will move the text, deleting it at the site of the
210 secondary selection, rather than copying it.
212 Selected text can also be dragged to a new location in the file using the
213 middle mouse button. Holding the shift key while dragging the text will copy
214 the selected text, leaving the original text in place. Holding the control
215 key will drag the text in overlay mode.
217 Normally, dragging moves text by removing it from the selected position at
218 the start of the drag, and inserting it at a new position relative to to the
219 mouse. Dragging a block of text over existing characters, displaces the
220 characters to the end of the selection. In overlay mode, characters which are
221 occluded by blocks of text being dragged are simply removed. When dragging
222 non-rectangular selections, overlay mode also converts the selection to
223 rectangular form, allowing it to be dragged outside of the bounds of the
226 The section "Using_the_Mouse_" summarizes the mouse commands for making primary
227 and secondary selections. Primary selections can also be made via keyboard
228 commands, see "Keyboard_Shortcuts_".
229 ----------------------------------------------------------------------
231 Finding and Replacing Text
232 --------------------------
234 The Search menu contains a number of commands for finding and replacing text.
236 The Find... and Replace... commands present dialogs for entering text for
237 searching and replacing. These dialogs also allow you to choose whether you
238 want the search to be sensitive to upper and lower case, or whether to use
239 the standard Unix pattern matching characters (regular expressions).
240 Searches begin at the current text insertion position.
242 Find Again and Replace Again repeat the last find or replace command without
243 prompting for search strings. To selectively replace text, use the two
244 commands in combination: Find Again, then Replace Again if the highlighted
245 string should be replaced, or Find Again again to go to the next string.
247 Find Selection searches for the text contained in the current primary
248 selection (see Selecting_Text_). The selected text does not have to be in the
249 current editor window, it may even be in another program. For example, if
250 the word dog appears somewhere in a window on your screen, and you want to
251 find it in the file you are editing, select the word dog by dragging the
252 mouse across it, switch to your NEdit window and choose Find Selection from
255 Find Incremental, which opens the interactive search bar, is yet another variation
256 on searching, where every character typed triggers a new search. After you've
257 completed the search string, the next occurrence in the buffer is found by hitting
258 the Return key, or by clicking on the icon to the left (magnifying glass). Holding
259 a Shift key down finds the previous occurrences. To the right there is a clear
260 button with an icon resembling "|<". Clicking on it empties the search text widget
261 without disturbing selections. A middle click on the clear button copies the
262 content of any existing selection into the search text widget and triggers a new
266 3>Searching Backwards
268 Holding down the shift key while choosing any of the search or replace
269 commands from the menu (or using the keyboard shortcut), will search in the
270 reverse direction. Users who have set the search direction using the buttons
271 in the search dialog, may find it a bit confusing that Find Again and Replace
272 Again don't continue in the same direction as the original search (for
273 experienced users, consistency of the direction implied by the shift key is
276 3>Selective Replacement
278 To replace only some occurrences of a string within a file, choose Replace...
279 from the Search menu, enter the string to search for and the string to
280 substitute, and finish by pressing the Find button. When the first
281 occurrence is highlighted, use either Replace Again (^T) to replace it, or
282 Find Again (^G) to move to the next occurrence without replacing it, and
283 continue in such a manner through all occurrences of interest.
285 To replace all occurrences of a string within some range of text, select the
286 range (see Selecting_Text_), choose Replace... from the Search menu, type the
287 string to search for and the string to substitute, and press the "R. in
288 Selection" button in the dialog. Note that selecting text in the Replace...
289 dialog will unselect the text in the window.
290 ----------------------------------------------------------------------
295 The easiest way to copy and move text around in your file or between windows,
296 is to use the clipboard, an imaginary area that temporarily stores text and
297 data. The Cut command removes the selected text (see Selecting_Text_) from
298 your file and places it in the clipboard. Once text is in the clipboard, the
299 Paste command will copy it to the insert position in the current window. For
300 example, to move some text from one place to another, select it by dragging
301 the mouse over it, choose Cut to remove it, click the pointer to move the
302 insert point where you want the text inserted, then choose Paste to insert
303 it. Copy copies text to the clipboard without deleting it from your file.
304 You can also use the clipboard to transfer text to and from other Motif
305 programs and X programs which make proper use of the clipboard.
307 There are many other methods for copying and moving text within NEdit windows
308 and between NEdit and other programs. The most common such method is
309 clicking the middle mouse button to copy the primary selection (to the
310 clicked position). Copying the selection by clicking the middle mouse button
311 in many cases is the only way to transfer data to and from many X programs.
312 Holding the Shift key while clicking the middle mouse button moves the text,
313 deleting it from its original position, rather than copying it. Other
314 methods for transferring text include secondary selections, primary selection
315 dragging, keyboard-based selection copying, and drag and drop. These are
316 described in detail in the sections: "Selecting_Text_", "Using_the_Mouse_",
317 and "Keyboard_Shortcuts_".
318 ----------------------------------------------------------------------
323 Mouse-based editing is what NEdit is all about, and learning to use the more
324 advanced features like secondary selections and primary selection dragging
325 will be well worth your while.
327 If you don't have time to learn everything, you can get by adequately with
328 just the left mouse button: Clicking the left button moves the cursor.
329 Dragging with the left button makes a selection. Holding the shift key while
330 clicking extends the existing selection, or begins a selection between the
331 cursor and the mouse. Double or triple clicking selects a whole word or a
334 This section will make more sense if you also read the section called,
335 "Selecting_Text_", which explains the terminology of selections, that is,
336 what is meant by primary, secondary, rectangular, etc.
339 3>Button and Modifier Key Summary
341 General meaning of mouse buttons and modifier keys:
345 Button 1 (left) Cursor position and primary selection
347 Button 2 (middle) Secondary selections, and dragging and
348 copying the primary selection
350 Button 3 (right) Quick-access programmable menu and pan
355 Shift On primary selections, (left mouse button):
356 Extends selection to the mouse pointer
357 On secondary and copy operations, (middle):
358 Toggles between move and copy
360 Ctrl Makes selection rectangular or insertion
363 Alt* (on release) Exchange primary and secondary
369 The left mouse button is used to position the cursor and to make primary
372 Click Moves the cursor
374 Double Click Selects a whole word
376 Triple Click Selects a whole line
378 Quad Click Selects the whole file
380 Shift Click Adjusts (extends or shrinks) the
381 selection, or if there is no existing
382 selection, begins a new selection
383 between the cursor and the mouse.
385 Ctrl+Shift+ Adjusts (extends or shrinks) the
386 Click selection rectangularly.
388 Drag Selects text between where the mouse
389 was pressed and where it was released.
391 Ctrl+Drag Selects rectangle between where the
392 mouse was pressed and where it was
398 The right mouse button posts a programmable menu for frequently used commands.
400 Click/Drag Pops up the background menu (programmed
401 from Preferences -> Default Settings ->
402 Customize Menus -> Window Background).
404 Ctrl+Drag Pan scrolling. Scrolls the window
405 both vertically and horizontally, as if
406 you had grabbed it with your mouse.
409 3>Middle Mouse Button
411 The middle mouse button is for making secondary selections, and copying and
412 dragging the primary selection.
414 Click Copies the primary selection to the
417 Shift+Click Moves the primary selection to the
418 clicked position, deleting it from its
421 Drag 1) Outside of the primary selection:
422 Begins a secondary selection.
423 2) Inside of the primary selection:
424 Moves the selection by dragging.
426 Ctrl+Drag 1) Outside of the primary selection:
427 Begins a rectangular secondary
429 2) Inside of the primary selection:
430 Drags the selection in overlay
433 When the mouse button is released after creating a secondary selection:
435 No Modifiers If there is a primary selection,
436 replaces it with the secondary
437 selection. Otherwise, inserts the
438 secondary selection at the cursor
441 Shift Move the secondary selection, deleting
442 it from its original position. If
443 there is a primary selection, the move
444 will replace the primary selection
445 with the secondary selection.
446 Otherwise, moves the secondary
447 selection to to the cursor position.
449 Alt* Exchange the primary and secondary
453 While moving the primary selection by dragging with the middle mouse button:
455 Shift Leaves a copy of the original
456 selection in place rather than
457 removing it or blanking the area.
459 Ctrl Changes from insert mode to overlay
462 Escape Cancels drag in progress.
464 Overlay Mode: Normally, dragging moves text by removing it from the selected
465 position at the start of the drag, and inserting it at a new position
466 relative to to the mouse. When you drag a block of text over existing
467 characters, the existing characters are displaced to the end of the
468 selection. In overlay mode, characters which are occluded by blocks of text
469 being dragged are simply removed. When dragging non-rectangular selections,
470 overlay mode also converts the selection to rectangular form, allowing it to
471 be dragged outside of the bounds of the existing text.
473 Mouse buttons 4 and 5 are usually represented by a mouse wheel nowadays.
474 They are used to scroll up or down in the text window.
476 * The Alt key may be labeled Meta or Compose-Character on some keyboards.
477 Some window managers, including default configurations of mwm, bind
478 combinations of the Alt key and mouse buttons to window manager operations.
479 In NEdit, Alt is only used on button release, so regardless of the window
480 manager bindings for Alt-modified mouse buttons, you can still do the
481 corresponding NEdit operation by using the Alt key AFTER the initial mouse
482 press, so that Alt is held while you release the mouse button. If you find
483 this difficult or annoying, you can re-configure most window managers to skip
484 this binding, or you can re-configure NEdit to use a different key
486 ----------------------------------------------------------------------
491 Most of the keyboard shortcuts in NEdit are shown on the right hand sides of
492 the pull-down menus. However, there are more which are not as obvious. These
493 include; dialog button shortcuts; menu and dialog mnemonics; labeled keyboard
494 keys, such as the arrows, page-up, page-down, and home; and optional Shift
495 modifiers on accelerator keys, like [Shift]Ctrl+F.
500 Pressing the key combinations shown on the right of the menu items is a
501 shortcut for selecting the menu item with the mouse. Some items have the shift
502 key enclosed in brackets, such as [Shift]Ctrl+F. This indicates that the shift
503 key is optional. In search commands, including the shift key reverses the
504 direction of the search. In Shift commands, it makes the command shift the
505 selected text by a whole tab stop rather than by single characters.
510 Pressing the Alt key in combination with one of the underlined characters in
511 the menu bar pulls down that menu. Once the menu is pulled down, typing the
512 underlined characters in a menu item (without the Alt key) activates that
513 item. With a menu pulled down, you can also use the arrow keys to select menu
514 items, and the Space or Enter keys to activate them.
517 3>Keyboard Shortcuts within Dialogs
519 One button in a dialog is usually marked with a thick indented outline.
520 Pressing the Return or Enter key activates this button.
522 All dialogs have either a Cancel or Dismiss button. This button can be
523 activated by pressing the Escape (or Esc) key.
525 Pressing the tab key moves the keyboard focus to the next item in a dialog.
526 Within an associated group of buttons, the arrow keys move the focus among the
527 buttons. Shift+Tab moves backward through the items.
529 Most items in dialogs have an underline under one character in their name.
530 Pressing the Alt key along with this character, activates a button as if you
531 had pressed it with the mouse, or moves the keyboard focus to the associated
534 You can select items from a list by using the arrow keys to move the
535 selection and space to select.
537 In file selection dialogs, you can type the beginning characters of the file
538 name or directory in the list to select files
541 3>Labeled Function Keys
543 The labeled function keys on standard workstation and PC keyboards, like the
544 arrows, and page-up and page-down, are active in NEdit, though not shown in the
547 Holding down the control key while pressing a named key extends the scope of
548 the action that it performs. For example, Home normally moves the insert
549 cursor the beginning of a line. Ctrl+Home moves it to the beginning of the
550 file. Backspace deletes one character, Ctrl+Backspace deletes one word.
552 Holding down the shift key while pressing a named key begins or extends a
553 selection. Combining the shift and control keys combines their actions. For
554 example, to select a word without using the mouse, position the cursor at the
555 beginning of the word and press Ctrl+Shift+RightArrow. The Alt key modifies
556 selection commands to make the selection rectangular.
558 Under X and Motif, there are several levels of translation between keyboard
559 keys and the actions they perform in a program. The "Customizing_NEdit_", and
560 "X_Resources_" sections of the Help menu have more information on this subject.
561 Because of all of this configurability, and since keyboards and standards for
562 the meaning of some keys vary from machine to machine, the mappings may be
563 changed from the defaults listed below.
565 3>Modifier Keys (in general)
567 Ctrl Extends the scope of the action that the key
568 would otherwise perform. For example, Home
569 normally moves the insert cursor to the beginning
570 of a line. Ctrl+Home moves it to the beginning of
571 the file. Backspace deletes one character, Ctrl+
572 Backspace deletes one word.
574 Shift Extends the selection to the cursor position. If
575 there's no selection, begins one between the old
576 and new cursor positions.
578 Alt When modifying a selection, makes the selection
581 (For the effects of modifier keys on mouse button presses, see the section
582 titled "Using_the_Mouse_")
586 Escape Cancels operation in progress: menu
587 selection, drag, selection, etc. Also
588 equivalent to cancel button in dialogs.
590 Backspace Delete the character before the cursor
592 Ctrl+BS Delete the word before the cursor
596 Left Move the cursor to the left one character
598 Ctrl+Left Move the cursor backward one word
599 (Word delimiters are settable, see
600 "Customizing_NEdit_", and "X_Resources_")
602 Right Move the cursor to the right one character
604 Ctrl+Right Move the cursor forward one word
606 Up Move the cursor up one line
608 Ctrl+Up Move the cursor up one paragraph.
609 (Paragraphs are delimited by blank lines)
611 Down Move the cursor down one line.
613 Ctrl+Down Move the cursor down one paragraph.
615 Ctrl+Return Return with automatic indent, regardless
616 of the setting of Auto Indent.
618 Shift+Return Return without automatic indent,
619 regardless of the setting of Auto Indent.
621 Ctrl+Tab Insert an ASCII tab character, without
622 processing emulated tabs.
624 Alt+Ctrl+<c> Insert the control-code equivalent of
627 Ctrl+/ Select everything (same as Select
632 Ctrl+U Delete to start of line
634 3>PC Standard Keyboard
636 Ctrl+Insert Copy the primary selection to the
637 clipboard (same as Copy menu item or ^C)
638 for compatibility with Motif standard key
641 Insert Copy the primary selection to the cursor
644 Delete Delete the character before the cursor.
645 (Can be configured to delete the character
646 after the cursor, see "Customizing_NEdit_",
649 Ctrl+Delete Delete to end of line.
651 Shift+Delete Cut, remove the currently selected text
652 and place it in the clipboard. (same as
653 Cut menu item or ^X) for compatibility
654 with Motif standard key binding
656 Delete Cut the primary selection to the cursor
659 Home Move the cursor to the beginning of the
662 Ctrl+Home Move the cursor to the beginning of the
665 End Move the cursor to the end of the line
667 Ctrl+End Move the cursor to the end of the file
669 PageUp Scroll and move the cursor up by one page.
671 PageDown Scroll and move the cursor down by one
674 F10 Make the menu bar active for keyboard
675 input (Arrow Keys, Return, Escape,
678 Alt+Home Switch to the previously active document.
680 Ctrl+PageUp Switch to the previous document.
682 Ctrl+PageDown Switch to the next document.
685 3>Specialty Keyboards
687 On machines with different styles of keyboards, generally, text editing
688 actions are properly matched to the labeled keys, such as Remove,
689 Next-screen, etc.. If you prefer different key bindings, see the section
690 titled "Key_Binding_" under the Customizing heading in the Help menu.
691 ----------------------------------------------------------------------
696 3>Shift Left, Shift Right
698 While shifting blocks of text is most important for programmers (See Features
699 for Programming), it is also useful for other tasks, such as creating
702 To shift a block of text one tab stop to the right, select the text, then
703 choose Shift Right from the Edit menu. Note that the accelerator keys for
704 these menu items are Ctrl+9 and Ctrl+0, which correspond to the right and
705 left parenthesis on most keyboards. Remember them as adjusting the text in
706 the direction pointed to by the parenthesis character. Holding the Shift key
707 while selecting either Shift Left or Shift Right will shift the text by one
710 It is also possible to shift blocks of text by selecting the text
711 rectangularly, and dragging it left or right (and up or down as well). Using
712 a rectangular selection also causes tabs within the selection to be
713 recalculated and substituted, such that the non-whitespace characters remain
714 stationary with respect to the selection.
719 Text filling using the Fill Paragraph command in the Edit menu is one of the
720 most important concepts in NEdit. And it will be well worth your while to
721 understand how to use it properly.
723 In plain text files, unlike word-processor files, there is no way to tell
724 which lines are continuations of other lines, and which lines are meant to be
725 separate, because there is no distinction in meaning between newline
726 characters which separate lines in a paragraph, and ones which separate
727 paragraphs from other text. This makes it impossible for a text editor like
728 NEdit to tell parts of the text which belong together as a paragraph from
729 carefully arranged individual lines.
731 In continuous wrap mode (Preferences -> Wrap -> Continuous), lines
732 automatically wrap and unwrap themselves to line up properly at the right
733 margin. In this mode, you simply omit the newlines within paragraphs and let
734 NEdit make the line breaks as needed. Unfortunately, continuous wrap mode is
735 not appropriate in the majority of situations, because files with extremely
736 long lines are not common under Unix and may not be compatible with all
737 tools, and because you can't achieve effects like indented sections, columns,
738 or program comments, and still take advantage of the automatic wrapping.
740 Without continuous wrapping, paragraph filling is not entirely automatic.
741 Auto-Newline wrapping keeps paragraphs lined up as you type, but once
742 entered, NEdit can no longer distinguish newlines which join wrapped text,
743 and newlines which must be preserved. Therefore, editing in the middle of a
744 paragraph will often leave the right margin messy and uneven.
746 Since NEdit can't act automatically to keep your text lined up, you need to
747 tell it explicitly where to operate, and that is what Fill Paragraph is for.
748 It arranges lines to fill the space between two margins, wrapping the lines
749 neatly at word boundaries. Normally, the left margin for filling is inferred
750 from the text being filled. The first line of each paragraph is considered
751 special, and its left indentation is maintained separately from the remaining
752 lines (for leading indents, bullet points, numbered paragraphs, etc.).
753 Otherwise, the left margin is determined by the furthest left non-whitespace
754 character. The right margin is either the Wrap Margin, set in the
755 preferences menu (by default, the right edge of the window), or can also be
756 chosen on the fly by using a rectangular selection (see below).
758 There are three ways to use Fill Paragraph. The simplest is, while you are
759 typing text, and there is no selection, simply select Fill Paragraph (or type
760 Ctrl+J), and NEdit will arrange the text in the paragraph adjacent to the
761 cursor. A paragraph, in this case, means an area of text delimited by blank
764 The second way to use Fill Paragraph is with a selection. If you select a
765 range of text and then chose Fill Paragraph, all of the text in the selection
766 will be filled. Again, continuous text between blank lines is interpreted as
767 paragraphs and filled individually, respecting leading indents and blank
770 The third, and most versatile, way to use Fill Paragraph is with a
771 rectangular selection. Fill Paragraph treats rectangular selections
772 differently from other commands. Instead of simply filling the text inside
773 the rectangular selection, NEdit interprets the right edge of the selection
774 as the requested wrap margin. Text to the left of the selection is not
775 disturbed (the usual interpretation of a rectangular selection), but text to
776 the right of the selection is included in the operation and is pulled in to
777 the selected region. This method enables you to fill text to an arbitrary
778 right margin, without going back and forth to the wrap-margin dialog, as well
779 as to exclude text to the left of the selection such as comment bars or other
781 ----------------------------------------------------------------------
786 NEdit is able to display files in distinct editor windows, or to display files
787 under tabs in the same editor window. The Options for controlling the tabbed
788 interface are found under Preferences -> Default Settings -> Tabbed Editing
789 (cf. "Preferences_", also "NEdit_Command_Line_").
791 Notice that you can re-group tabs at any time by detaching and attaching them,
792 or moving them, to other windows. This can be done using the Windows menu, or
793 using the context menu, which pops up when right clicking on a tab.
795 You can switch to a tab by simply clicking on it, or you can use the keyboard.
796 The default keybindings to switch tabs (which are Ctrl+PageUp/-Down and Alt+Home,
797 see "Keyboard_Shortcuts_") can be changed using the actions previous_document(),
798 next_document() and last_document().
800 ----------------------------------------------------------------------
805 While plain-text is probably the simplest and most interchangeable file
806 format in the computer world, there is still variation in what plain-text
807 means from system to system. Plain-text files can differ in character set,
808 line termination, and wrapping.
810 While character set differences are the most obvious and pose the most
811 challenge to portability, they affect NEdit only indirectly via the same font
812 and localization mechanisms common to all X applications. If your system is
813 set up properly, you will probably never see character-set related problems
814 in NEdit. NEdit can not display Unicode text files, or any multi-byte
817 The primary difference between an MS DOS format file and a Unix format file,
818 is how the lines are terminated. Unix uses a single newline character. MS
819 DOS uses a carriage-return and a newline. NEdit can read and write both file
820 formats, but internally, it uses the single character Unix standard. NEdit
821 auto-detects MS DOS format files based on the line termination at the start
822 of the file. Files are judged to be DOS format if all of the first five line
823 terminators, within a maximum range, are DOS-style. To change the format in
824 which NEdit writes a file from DOS to Unix or visa versa, use the Save As...
825 command and check or un-check the MS DOS Format button.
827 Wrapping within text files can vary among individual users, as well as from
828 system to system. Both Windows and MacOS make frequent use of plain text
829 files with no implicit right margin. In these files, wrapping is determined
830 by the tool which displays them. Files of this style also exist on Unix
831 systems, despite the fact that they are not supported by all Unix utilities.
832 To display this kind of file properly in NEdit, you have to select the wrap
833 style called Continuous. Wrapping modes are discussed in the sections:
834 Customizing -> Preferences, and Basic Operation -> Shifting and Filling.
836 The last and most minute of format differences is the terminating newline.
837 Some Unix compilers and utilities require a final terminating newline on all
838 files they read and fail in various ways on files which do not have it. Vi
839 and approximately half of Unix editors enforce the terminating newline on all
840 files that they write; Emacs does not enforce this rule. Users are divided
841 on which is best. NEdit makes the final terminating newline optional
842 (Preferences -> Default Settings -> Terminate with Line Break on Save).
843 ----------------------------------------------------------------------
845 Features for Programming
846 ========================
848 Programming with NEdit
849 ----------------------
851 Though general in appearance, NEdit has many features intended specifically
852 for programmers. Major programming-related topics are listed in separate
853 sections under the heading: "Features for Programming": Syntax_Highlighting_,
854 Tabs/Emulated_Tabs_, Finding_Declarations_(ctags)_, Calltips_, and
855 Auto/Smart_Indent_. Minor topics related to programming are discussed below:
859 When NEdit initially reads a file, it attempts to determine whether the file
860 is in one of the computer languages that it knows about. Knowing what language
861 a file is written in allows NEdit to assign highlight patterns and smart indent
862 macros, and to set language specific preferences like word delimiters, tab
863 emulation, and auto-indent. Language mode can be recognized from both the file
864 name and from the first 200 characters of content. Language mode recognition
865 and language-specific preferences are configured in: Preferences -> Default
866 Settings -> Language Modes....
868 You can set the language mode manually for a window, by selecting it from the
869 menu: Preferences -> Language Modes.
871 3>Backlighting [EXPERIMENTAL]
873 NEdit can be made to set the background color of particular classes of
874 characters to allow easy identification of those characters. This is
875 particularly useful if you need to be able to distinguish between tabs
876 and spaces in a file where the difference is important. The colors used
877 for backlighting are specified by a resource, "nedit*backlightCharTypes".
878 You can turn backlighting on and off through the
879 Preferences -> Apply Backlighting menu entry.
881 If you prefer to have backlighting turned on for all new windows, use
882 the Preferences -> Default Settings -> Apply Backlighting menu entry.
883 This settings can be saved along with other preferences using
884 Preferences -> Save Defaults.
886 **Important:** In future versions of NEdit, the backlighting feature will be
887 extended and reworked such that it becomes easier to configure. The current
888 way of controlling it through a resource is generally considered to be below
889 NEdit's usability standards. These future changes are likely to be
890 incompatible with the current format of the "nedit*backlightCharTypes"
891 resource, though. Therefore, it is expected that there will be no automatic
892 migration path for users who customize the resource.
896 To find a particular line in a source file by line number, choose Goto Line
897 #... from the Search menu. You can also directly select the line number text
898 in the compiler message in the terminal emulator window (xterm, decterm,
899 winterm, etc.) where you ran the compiler, and choose Goto Selected from the
902 To find out the line number of a particular line in your file, turn on
903 Statistics Line in the Preferences menu and position the insertion point
904 anywhere on the line. The statistics line continuously updates the line number
905 of the line containing the cursor.
907 To go to a specific column on a given line, choose Goto Line #... from the
908 Search menu and enter a line number and a column number separated by a
909 comma. (e.g. Enter "100,12" for line 100 column 12.) If you want to go to
910 a column on the current line just leave out the line number. (e.g. Enter
911 ",45" to go the column 45 on the current line.)
913 3>Matching Parentheses
915 To help you inspect nested parentheses, brackets, braces, quotes, and other
916 characters, NEdit has both an automatic parenthesis matching mode, and a Goto
917 Matching command. Automatic parenthesis matching is activated when you type,
918 or move the insertion cursor after a parenthesis, bracket, or brace. It
919 momentarily highlights either the opposite character ('Delimiter') or the
920 entire expression ('Range') when the opposite character is visible in the
921 window. To find a matching character anywhere in the file, select it or
922 position the cursor after it, and choose Goto Matching from the Search menu.
923 If the character matches itself, such as a quote or slash, select the first
924 character of the pair. NEdit will match {, (, [, <, ", ', `, /, and \.
925 Holding the Shift key while typing the accelerator key (Shift+Ctrl+M, by
926 default), will select all of the text between the matching characters.
928 When syntax highlighting is enabled, the matching routines can optionally
929 make use of the syntax information for improved accuracy. In that case,
930 a brace inside a highlighted string will not match a brace inside a comment,
933 3>Opening Included Files
935 The Open Selected command in the File menu understands the C preprocessor's
936 #include syntax, so selecting an #include line and invoking Open Selected will
937 generally find the file referred to, unless doing so depends on the settings of
938 compiler switches or other information not available to NEdit.
940 3>Interface to Programming Tools
942 Integrated software development environments such as SGI's CaseVision and
943 Centerline Software's Code Center, can be interfaced directly with NEdit via
944 the client server interface. These tools allow you to click directly on
945 compiler and runtime error messages and request NEdit to open files, and select
946 lines of interest. The easiest method is usually to use the tool's interface
947 for character-based editors like vi, to invoke nc, but programmatic interfaces
948 can also be derived using the source code for nc.
950 There are also some simple compile/review, grep, ctree, and ctags browsers
951 available in the NEdit contrib directory on ftp.nedit.org.
952 ----------------------------------------------------------------------
957 3>Changing the Tab Distance
959 Tabs are important for programming in languages which use indentation to show
960 nesting, as short-hand for producing white-space for leading indents. As a
961 programmer, you have to decide how to use indentation, and how or whether tab
962 characters map to your indentation scheme.
964 Ideally, tab characters map directly to the amount of indent that you use to
965 distinguish nesting levels in your code. Unfortunately, the Unix standard
966 for interpretation of tab characters is eight characters (probably dating
967 back to mechanical capabilities of the original teletype), which is usually
968 too coarse for a single indent.
970 Most text editors, NEdit included, allow you to change the interpretation of
971 the tab character, and many programmers take advantage of this, and set their
972 tabs to 3 or 4 characters to match their programming style. In NEdit you set
973 the hardware tab distance in Preferences -> Tabs... for the current window,
974 or Preferences -> Default Settings -> Tabs... (general), or Preferences ->
975 Default Settings -> Language Modes... (language-specific) to change the
976 defaults for future windows.
978 Changing the meaning of the tab character makes programming much easier while
979 you're in the editor, but can cause you headaches outside of the editor,
980 because there is no way to pass along the tab setting as part of a plain-text
981 file. All of the other tools which display, print, and otherwise process
982 your source code have to be made aware of how the tabs are set, and must be
983 able to handle the change. Non-standard tabs can also confuse other
984 programmers, or make editing your code difficult for them if their text
985 editors don't support changes in tab distance.
989 An alternative to changing the interpretation of the tab character is tab
990 emulation. In the Tabs... dialog(s), turning on Emulated Tabs causes the Tab
991 key to insert the correct number of spaces and/or tabs to bring the cursor
992 the next emulated tab stop, as if tabs were set at the emulated tab distance
993 rather than the hardware tab distance. Backspacing immediately after entering
994 an emulated tab will delete the fictitious tab as a unit, but as soon as you
995 move the cursor away from the spot, NEdit will forget that the collection of
996 spaces and tabs is a tab, and will treat it as separate characters. To enter
997 a real tab character with "Emulate Tabs" turned on, use Ctrl+Tab.
999 It is also possible to tell NEdit not to insert ANY tab characters at all in
1000 the course of processing emulated tabs, and in shifting and rectangular
1001 insertion/deletion operations, for programmers who worry about the
1002 misinterpretation of tab characters on other systems.
1003 ----------------------------------------------------------------------
1007 .. The following Tabs Dialog and Customize Window Title Dialog sections
1008 .. should only appear in the online documentation, and not in any of
1009 .. the other possible forms. The rationale is that they are not directly
1010 .. obtained from the Help menu, but are buried in preference dialogs.
1016 .. The Tabs dialog controls both the operation of the Tab key, and
1017 .. the interpretation of tab characters within a file.
1019 .. The first field, Tab Spacing, controls how NEdit responds to
1020 .. tab characters in a file. On most Unix and VMS systems the
1021 .. conventional interpretation of a tab character is to advance the
1022 .. text position to the nearest multiple of eight characters (a tab
1023 .. spacing of 8). However, many programmers of C and other
1024 .. structured languages, when given the choice, prefer a tab
1025 .. spacing of 3 or 4 characters. Setting a three or four character
1026 .. hardware tab spacing is useful and convenient as long as your
1027 .. other software tools support it. Unfortunately, on Unix and VMS
1028 .. systems, system utilities, such as more, and printing software
1029 .. can't always properly display files with other than eight
1032 .. Selecting "Emulate Tabs" will cause the Tab key to insert the
1033 .. correct number of spaces or tabs to reach the next tab stop, as
1034 .. if the tab spacing were set at the value in the "Emulated tab
1035 .. spacing" field. Backspacing immediately after entering an
1036 .. emulated tab will delete it as a unit, but as soon as you move
1037 .. the cursor away from the spot, NEdit will forget that the
1038 .. collection of spaces and tabs is a tab, and will treat it as
1039 .. separate characters. To enter a real tab character with
1040 .. "Emulate Tabs" turned on, use Ctrl+Tab.
1042 .. In generating emulated tabs, and in Shift Left, Paste Column,
1043 .. and some rectangular selection operations, NEdit inserts blank
1044 .. characters (spaces or tabs) to preserve the alignment of
1045 .. non-blank characters. The bottom toggle button in the Tabs
1046 .. dialog instructs NEdit whether to insert tab characters as
1047 .. padding in such situations. Turning this off, will keep NEdit
1048 .. from automatically inserting tabs. Some software developers
1049 .. prefer to keep their source code free of tabs to avoid its
1050 .. misinterpretation on systems with different tab character
1052 .. ----------------------------------------------------------------------
1054 .. Customize Window Title Dialog
1055 .. -----------------------------
1057 .. The Customize Window Title dialog allows you to customize
1058 .. and test the way information will be displayed in each window's
1061 .. **Definition of the title**
1063 .. The upper half of the dialog can be used to select the various
1064 .. components that should be displayed in the title. The layout can be
1065 .. fine-tuned by editing the printf() like format string below the
1066 .. component buttons: additional characters can be entered, or the
1067 .. order can be changed.
1069 .. The following sequences are interpreted in the format string:
1071 .. %c ClearCase view tag (only relevant when NEdit is
1072 .. used together with ClearCase)
1073 .. %[n]d directory, with one optional numeric digit n
1074 .. specifying the maximum number of trailing directory
1075 .. components to display. Skipped components are
1076 .. replaced by an ellipsis (...).
1077 .. %f file name, without the path name
1079 .. %s NEdit server name (server mode only)
1080 .. %[*]S file status, either verbose (%S) or brief (%*S).
1081 .. In verbose mode the file status is spelled out:
1082 .. read-only, locked, and modified. In brief mode,
1083 .. abbreviations and an asterisk are used for the
1084 .. respective states: RO, LO, *.
1087 .. The format string and the component buttons are continously synchronized.
1089 .. The default format is:
1091 .. {%c} [%s] %f (%S) - %d
1093 .. The resulting title will only contain elements with
1094 .. a value. Hence, the title is compressed as follows:
1096 .. * Elements with no value are removed.
1098 .. * Empty parenthesis pairs i.e. (), [] or {}, or parenthesis
1099 .. pairs containing only space(s), are removed.
1101 .. * Sequences of spaces are replaced with one space.
1103 .. * Leading spaces and dashes are removed.
1105 .. * Trailing spaces and dashes are removed.
1107 .. If the server name and the ClearCase view tag are identical, only
1108 .. the first one specified in the format string will be displayed.
1110 .. **Previewing the settings**
1112 .. The lower part of the dialog can be used to test the selected title
1113 .. under various conditions. For some of the components that are selected
1114 .. for display, various states can be enforced on the preview.
1116 .. For instance, components that are not always active (such the
1117 .. NEdit server name) can be turned on or off in the preview.
1124 Programmers who use structured languages usually require some form of
1125 automatic indent, so that they don't have to continually re-type the
1126 sequences of tabs and/or spaces needed to maintain lengthy running indents.
1127 NEdit therefore offers "smart" indent, in addition to the traditional
1128 automatic indent which simply lines up the cursor position with the previous
1133 Smart indent macros are only available by default for C and C++, and while
1134 these can easily be configured for different default indentation distances,
1135 they may not conform to everyone's exact C programming style. Smart indent
1136 is programmed in terms of macros in the NEdit macro language which can be
1137 entered in: Preferences -> Default Settings -> Indent -> Program Smart
1138 Indent. Hooks are provided for intervening at the point that a newline is
1139 entered, either via the user pressing the Enter key, or through
1140 auto-wrapping; and for arbitrary type-in to act on specific characters typed.
1142 To type a newline character without invoking smart-indent when operating in
1143 smart-indent mode, hold the Shift key while pressing the Return or Enter key.
1147 With Indent set to Auto (the default), NEdit keeps a running indent. When
1148 you press the Return or Enter key, spaces and tabs are inserted to line up
1149 the insert point under the start of the previous line.
1151 Regardless of indent-mode, Ctrl+Return always does the automatic indent;
1152 Shift+Return always does a return without indent.
1154 3>Block Indentation Adjustment
1156 The Shift Left and Shift Right commands as well as rectangular dragging can
1157 be used to adjust the indentation for several lines at once. To shift a
1158 block of text one character to the right, select the text, then choose Shift
1159 Right from the Edit menu. Note that the accelerator keys for these menu
1160 items are Ctrl+9 and Ctrl+0, which correspond to the right and left
1161 parenthesis on most keyboards. Remember them as adjusting the text in the
1162 direction pointed to by the parenthesis character. Holding the Shift key
1163 while selecting either Shift Left or Shift Right will shift the text by one
1164 tab stop (or by one emulated tab stop if tab emulation is turned on). The
1165 help section "Shifting and Filling" under "Basic Operation" has details.
1166 ----------------------------------------------------------------------
1171 Syntax Highlighting means using colors and fonts to help distinguish language
1172 elements in programming languages and other types of structured files.
1173 Programmers use syntax highlighting to understand code faster and better, and
1174 to spot many kinds of syntax errors more quickly.
1176 To use syntax highlighting in NEdit, select Highlight Syntax in the
1177 Preferences menu. If NEdit recognizes the computer language that you are
1178 using, and highlighting rules (patterns) are available for that language, it
1179 will highlight your text, and maintain the highlighting, automatically, as
1182 If NEdit doesn't correctly recognize the type of the file you are editing,
1183 you can manually select a language mode from Language Modes in the
1184 Preferences menu. You can also program the method that NEdit uses to
1185 recognize language modes in Preferences -> Default Settings -> Language
1188 If no highlighting patterns are available for the language that you want to
1189 use, you can create new patterns relatively quickly. The Help section
1190 "Highlighting_Patterns_" under "Customizing", has details.
1192 If you are satisfied with what NEdit is highlighting, but would like it to
1193 use different colors or fonts, you can change these by selecting Preferences
1194 -> Default Settings -> Syntax Highlighting -> Text Drawing Styles.
1195 Highlighting patterns are connected with font and color information through a
1196 common set of styles so that colorings defined for one language will be
1197 similar across others, and patterns within the same language which are meant
1198 to appear identical can be changed in the same place. To understand which
1199 styles are used to highlight the language you are interested in, you may need
1200 to look at "Highlighting_Patterns_" section, as well.
1202 Syntax highlighting is CPU intensive, and under some circumstances can affect
1203 NEdit's responsiveness. If you have a particularly slow system, or work with
1204 very large files, you may not want to use it all of the time. Syntax
1205 highlighting introduces two kinds of delays. The first is an initial parsing
1206 delay, proportional to the size of the file. This delay is also incurred
1207 when pasting large sections of text, filtering text through shell commands,
1208 and other circumstances involving changes to large amounts of text. The
1209 second kind of delay happens when text which has not previously been visible
1210 is scrolled in to view. Depending on your system, and the highlight patterns
1211 you are using, this may or may not be noticeable. A typing delay is also
1212 possible, but unlikely if you are only using the built-in patterns.
1213 ----------------------------------------------------------------------
1215 Finding Declarations (ctags)
1216 ----------------------------
1218 NEdit can process tags files generated using the Unix _ctags command or the
1219 Exuberant Ctags program. Ctags creates index files correlating names of
1220 functions and declarations with their locations in C, Fortran, or Pascal source
1221 code files. (See the ctags manual page for more information). Ctags produces a
1222 file called "tags" which can be loaded by NEdit. NEdit can manage any number
1223 of tags files simultaneously. Tag collisions are handled with a popup menu to
1224 let the user decide which tag to use. In 'Smart' mode NEdit will automatically
1225 choose the desired tag based on the scope of the file or module. Once loaded,
1226 the information in the tags file enables NEdit to go directly to the
1227 declaration of a highlighted function or data structure name with a single
1228 command. To load a tags file, select "Load Tags File" from the File menu and
1229 choose a tags file to load, or specify the name of the tags file on the NEdit
1234 NEdit can also be set to load a tags file automatically when it starts up.
1235 Setting the X resource nedit.tagFile to the name of a tag file tells NEdit to
1236 look for that file at startup time (see "Customizing_NEdit_"). The file name
1237 can be either a complete path name, in which case NEdit will always load the
1238 same tags file, or a file name without a path or with a relative path, in
1239 which case NEdit will load it starting from the current directory. The
1240 second option allows you to have different tags files for different projects,
1241 each automatically loaded depending on the directory you're in when you start
1242 NEdit. Setting the name to "tags" is an obvious choice since this is the
1243 name that ctags uses. NEdit normally evaluates relative path tag file
1244 specifications every time a file is opened. All accessible tag files are
1245 loaded at this time. To disable the automatic loading of tag files specified
1246 as relative paths, set the X resource nedit.alwaysCheckRelativeTagsSpecs to
1249 To unload a tags file, select "Un-load Tags File" from the File menu and
1250 choose from the list of tags files. NEdit will keep track of tags file updates
1251 by checking the timestamp on the files, and automatically update the tags
1254 To find the definition of a function or data structure once a tags file is
1255 loaded, select the name anywhere it appears in your program (see
1256 "Selecting_Text_") and choose "Find Definition" from the Search menu.
1257 ----------------------------------------------------------------------
1262 Calltips are little yellow boxes that pop up to remind you what the arguments
1263 and return type of a function are. More generally, they're a UI mechanism to
1264 present a small amount of crucial information in a prominent location. To
1265 display a calltip, select some text and choose "Show Calltip" from the Search
1266 menu. To kill a displayed calltip, hit Esc.
1268 Calltips get their information from one of two places -- either a tags file (see
1269 "Finding_Declarations_(ctags)_") or a calltips file. First, any loaded calltips
1270 files are searched for a definition, and if nothing is found then the tags
1271 database is searched. If a tag is found that matches the highlighted text then
1272 a calltip is displayed with the first few lines of the definition -- usually
1273 enough to show you what the arguments of a function are.
1275 You can load a calltips file by using choosing "Load Calltips File" from the
1276 File menu. You can unload a calltips file by selecting it from the
1277 "Unload Calltips File" submenu of the File menu. You can also choose one or
1278 more default calltips files to be loaded for each language mode using the
1279 "Default calltips file(s)" field of the Language Modes dialog.
1281 The calltips file format is very simple. calltips files are organized in blocks
1282 separated by blank lines. The first line of the block is the key, which is the
1283 word that is matched when a calltip is requested. The rest of the block is
1284 displayed as the calltip.
1286 Almost any text at all can appear in a calltip key or a calltip. There are no
1287 special characters that need to be escaped. The only issues to note are that
1288 trailing whitespace is ignored, and you cannot have a blank line inside a
1289 calltip. (Use a single period instead -- it'll be nearly invisible.) You should
1290 also avoid calltip keys that begin and end with '@*' characters, since those are
1291 used to mark special blocks.
1293 There are five special block types--comment, include, language, alias, and
1294 version--which are distinguished by their first lines, "@* comment @*",
1295 "@* include @*", "@* language @*", "@* alias @*", and "@* version @*" respectively
1298 Comment blocks are ignored when reading calltips files.
1300 Include blocks specify additional calltips files to load, one per line. The ~
1301 character can be used for your $HOME directory, but other shell shortcuts like
1302 @* and ? can't be used. Include blocks allow you to make a calltips file for your
1303 project that includes, say, the calltips files for C, Motif, and Xt.
1305 Language blocks specify which language mode the calltips should be used with.
1306 When a calltip is requested it won't match tips from languages other than the
1307 current language mode. Language blocks only affect the tips listed after the
1310 Alias blocks allow a calltip to have multiple keys. The first line of the block
1311 is the key for the calltip to be displayed, and the rest of the lines are
1312 additional keys, one per line, that should also show the calltip.
1314 Version blocks are ignored for the time being.
1316 You can use calltips in your own macros using the calltip() and kill_calltip()
1317 macro subroutines and the $calltip_ID macro variable. See the
1318 Macro_Subroutines_ section for details.
1319 ----------------------------------------------------------------------
1324 Basic Regular Expression Syntax
1325 -------------------------------
1327 Regular expressions (regex's) are useful as a way to match inexact sequences
1328 of characters. They can be used in the `Find...' and `Replace...' search
1329 dialogs and are at the core of Color Syntax Highlighting patterns. To specify
1330 a regular expression in a search dialog, simply click on the `Regular
1331 Expression' radio button in the dialog.
1333 A regex is a specification of a pattern to be matched in the searched text.
1334 This pattern consists of a sequence of tokens, each being able to match a
1335 single character or a sequence of characters in the text, or assert that a
1336 specific position within the text has been reached (the latter is called an
1337 anchor.) Tokens (also called atoms) can be modified by adding one of a number
1338 of special quantifier tokens immediately after the token. A quantifier token
1339 specifies how many times the previous token must be matched (see below.)
1341 Tokens can be grouped together using one of a number of grouping constructs,
1342 the most common being plain parentheses. Tokens that are grouped in this way
1343 are also collectively considered to be a regex atom, since this new larger
1344 atom may also be modified by a quantifier.
1346 A regex can also be organized into a list of alternatives by separating each
1347 alternative with pipe characters, `|'. This is called alternation. A match
1348 will be attempted for each alternative listed, in the order specified, until a
1349 match results or the list of alternatives is exhausted (see Alternation_
1352 3>The 'Any' Character
1354 If a dot (`.') appears in a regex, it means to match any character exactly
1355 once. By default, dot will not match a newline character, but this behavior
1356 can be changed (see help topic Parenthetical_Constructs_, under the
1357 heading, Matching Newlines).
1361 A character class, or range, matches exactly one character of text, but the
1362 candidates for matching are limited to those specified by the class. Classes
1363 come in two flavors as described below:
1365 [...] Regular class, match only characters listed.
1366 [^...] Negated class, match only characters NOT listed.
1368 As with the dot token, by default negated character classes do not match
1369 newline, but can be made to do so.
1371 The characters that are considered special within a class specification are
1372 different than the rest of regex syntax as follows. If the first character in
1373 a class is the `]' character (second character if the first character is `^')
1374 it is a literal character and part of the class character set. This also
1375 applies if the first or last character is `-'. Outside of these rules, two
1376 characters separated by `-' form a character range which includes all the
1377 characters between the two characters as well. For example, `[^f-j]' is the
1378 same as `[^fghij]' and means to match any character that is not `f', `g',
1383 Anchors are assertions that you are at a very specific position within the
1384 search text. NEdit regular expressions support the following anchor tokens:
1388 < Left word boundary
1389 > Right word boundary
1390 \B Not a word boundary
1392 Note that the \B token ensures that neither the left nor the right
1393 character are delimiters, or that both left and right characters are
1394 delimiters. The left word anchor checks whether the previous character
1395 is a delimiter and the next character is not. The right word anchor
1396 works in a similar way.
1400 Quantifiers specify how many times the previous regular expression atom may
1401 be matched in the search text. Some quantifiers can produce a large
1402 performance penalty, and can in some instances completely lock up NEdit. To
1403 prevent this, avoid nested quantifiers, especially those of the maximal
1404 matching type (see below.)
1406 The following quantifiers are maximal matching, or "greedy", in that they
1407 match as much text as possible.
1409 * Match zero or more
1413 The following quantifiers are minimal matching, or "lazy", in that they match
1414 as little text as possible.
1416 *? Match zero or more
1417 +? Match one or more
1418 ?? Match zero or one
1420 One final quantifier is the counting quantifier, or brace quantifier. It
1421 takes the following basic form:
1423 {min,max} Match from `min' to `max' times the
1424 previous regular expression atom.
1426 If `min' is omitted, it is assumed to be zero. If `max' is omitted, it is
1427 assumed to be infinity. Whether specified or assumed, `min' must be less
1428 than or equal to `max'. Note that both `min' and `max' are limited to
1429 65535. If both are omitted, then the construct is the same as `*'. Note
1430 that `{,}' and `{}' are both valid brace constructs. A single number
1431 appearing without a comma, e.g. `{3}' is short for the `{min,min}' construct,
1432 or to match exactly `min' number of times.
1434 The quantifiers `{1}' and `{1,1}' are accepted by the syntax, but are
1435 optimized away since they mean to match exactly once, which is redundant
1436 information. Also, for efficiency, certain combinations of `min' and `max'
1437 are converted to either `*', `+', or `?' as follows:
1443 Note that {0} and {0,0} are meaningless and will generate an error message at
1444 regular expression compile time.
1446 Brace quantifiers can also be "lazy". For example {2,5}? would try to match
1447 2 times if possible, and will only match 3, 4, or 5 times if that is what is
1448 necessary to achieve an overall match.
1452 A series of alternative patterns to match can be specified by separating them
1453 with vertical pipes, `|'. An example of _alternation would be `a|be|sea'.
1454 This will match `a', or `be', or `sea'. Each alternative can be an
1455 arbitrarily complex regular expression. The alternatives are attempted in
1456 the order specified. An empty alternative can be specified if desired, e.g.
1457 `a|b|'. Since an empty alternative can match nothingness (the empty string),
1458 this guarantees that the expression will match.
1462 Comments are of the form `(?#<comment text>)' and can be inserted anywhere
1463 and have no effect on the execution of the regular expression. They can be
1464 handy for documenting very complex regular expressions. Note that a comment
1465 begins with `(?#' and ends at the first occurrence of an ending parenthesis,
1466 or the end of the regular expression... period. Comments do not recognize
1467 any escape sequences.
1468 ----------------------------------------------------------------------
1473 3>Escaping Metacharacters
1475 In a regular expression (regex), most ordinary characters match themselves.
1476 For example, `ab%' would match anywhere `a' followed by `b' followed by `%'
1477 appeared in the text. Other characters don't match themselves, but are
1478 metacharacters. For example, backslash is a special metacharacter which
1479 'escapes' or changes the meaning of the character following it. Thus, to
1480 match a literal backslash would require a regular expression to have two
1481 backslashes in sequence. NEdit provides the following escape sequences so
1482 that metacharacters that are used by the regex syntax can be specified as
1483 ordinary characters.
1485 \( \) \- \[ \] \< \> \{ \}
1486 \. \| \^ \$ \* \+ \? \& \\
1488 3>Special Control Characters
1490 There are some special characters that are difficult or impossible to type.
1491 Many of these characters can be constructed as a sort of metacharacter or
1492 sequence by preceding a literal character with a backslash. NEdit recognizes
1493 the following special character sequences:
1497 \e ASCII escape character (***)
1498 \f form feed (new page)
1504 *** For environments that use the EBCDIC character set,
1505 when compiling NEdit set the EBCDIC_CHARSET compiler
1506 symbol to get the EBCDIC equivalent escape
1509 3>Octal and Hex Escape Sequences
1511 Any ASCII (or EBCDIC) character, except null, can be specified by using
1512 either an octal escape or a hexadecimal escape, each beginning with \0 or \x
1513 (or \X), respectively. For example, \052 and \X2A both specify the `*'
1514 character. Escapes for null (\00 or \x0) are not valid and will generate an
1515 error message. Also, any escape that exceeds \0377 or \xFF will either cause
1516 an error or have any additional character(s) interpreted literally. For
1517 example, \0777 will be interpreted as \077 (a `?' character) followed by `7'
1518 since \0777 is greater than \0377.
1520 An invalid digit will also end an octal or hexadecimal escape. For example,
1521 \091 will cause an error since `9' is not within an octal escape's range of
1522 allowable digits (0-7) and truncation before the `9' yields \0 which is
1525 3>Shortcut Escape Sequences
1527 NEdit defines some escape sequences that are handy shortcuts for commonly
1528 used character classes.
1531 \l letters a-z, A-Z, and locale dependent letters
1532 \s whitespace \t, \r, \v, \f, and space
1533 \w word characters letters, digits, and underscore, `_'
1535 \D, \L, \S, and \W are the same as the lowercase versions except that the
1536 resulting character class is negated. For example, \d is equivalent to
1537 `[0-9]', while \D is equivalent to `[^0-9]'.
1539 These escape sequences can also be used within a character class. For
1540 example, `[\l_]' is the same as `[a-zA-Z@_]', extended with possible locale
1541 dependent letters. The escape sequences for special characters, and octal
1542 and hexadecimal escapes are also valid within a class.
1544 3>Word Delimiter Tokens
1546 Although not strictly a character class, the following escape sequences
1547 behave similarly to character classes:
1549 \y Word delimiter character
1550 \Y Not a word delimiter character
1552 The `\y' token matches any single character that is one of the characters
1553 that NEdit recognizes as a word delimiter character, while the `\Y' token
1554 matches any character that is NOT a word delimiter character. Word delimiter
1555 characters are dynamic in nature, meaning that the user can change them through
1556 preference settings. For this reason, they must be handled differently by the
1557 regular expression engine. As a consequence of this, `\y' and `\Y' can not be
1558 used within a character class specification.
1559 ----------------------------------------------------------------------
1561 Parenthetical Constructs
1562 ------------------------
1564 3>Capturing Parentheses
1566 Capturing Parentheses are of the form `(<regex>)' and can be used to group
1567 arbitrarily complex regular expressions. Parentheses can be nested, but the
1568 total number of parentheses, nested or otherwise, is limited to 50 pairs.
1569 The text that is matched by the regular expression between a matched set of
1570 parentheses is captured and available for text substitutions and
1571 backreferences (see below.) Capturing parentheses carry a fairly high
1572 overhead both in terms of memory used and execution speed, especially if
1573 quantified by `*' or `+'.
1575 3>Non-Capturing Parentheses
1577 Non-Capturing Parentheses are of the form `(?:<regex>)' and facilitate
1578 grouping only and do not incur the overhead of normal capturing parentheses.
1579 They should not be counted when determining numbers for capturing parentheses
1580 which are used with backreferences and substitutions. Because of the limit
1581 on the number of capturing parentheses allowed in a regex, it is advisable to
1582 use non-capturing parentheses when possible.
1584 3>Positive Look-Ahead
1586 Positive look-ahead constructs are of the form `(?=<regex>)' and implement a
1587 zero width assertion of the enclosed regular expression. In other words, a
1588 match of the regular expression contained in the positive look-ahead
1589 construct is attempted. If it succeeds, control is passed to the next
1590 regular expression atom, but the text that was consumed by the positive
1591 look-ahead is first unmatched (backtracked) to the place in the text where
1592 the positive look-ahead was first encountered.
1594 One application of positive look-ahead is the manual implementation of a
1595 first character discrimination optimization. You can include a positive
1596 look-ahead that contains a character class which lists every character that
1597 the following (potentially complex) regular expression could possibly start
1598 with. This will quickly filter out match attempts that can not possibly
1601 3>Negative Look-Ahead
1603 Negative look-ahead takes the form `(?!<regex>)' and is exactly the same as
1604 positive look-ahead except that the enclosed regular expression must NOT
1605 match. This can be particularly useful when you have an expression that is
1606 general, and you want to exclude some special cases. Simply precede the
1607 general expression with a negative look-ahead that covers the special cases
1608 that need to be filtered out.
1610 3>Positive Look-Behind
1612 Positive look-behind constructs are of the form `(?<=<regex>)' and implement
1613 a zero width assertion of the enclosed regular expression in front of the
1614 current matching position. It is similar to a positive look-ahead assertion,
1615 except for the fact the the match is attempted on the text preceding the
1616 current position, possibly even in front of the start of the matching range
1617 of the entire regular expression.
1619 A restriction on look-behind expressions is the fact that the expression
1620 must match a string of a bounded size. In other words, `*', `+', and `{n,}'
1621 quantifiers are not allowed inside the look-behind expression. Moreover,
1622 matching performance is sensitive to the difference between the upper and
1623 lower bound on the matching size. The smaller the difference, the better the
1624 performance. This is especially important for regular expressions used in
1627 Another (minor) restriction is the fact that look-**ahead** patterns, nor
1628 any construct that requires look-ahead information (such as word boundaries)
1629 are supported at the end of a look-behind pattern (no error is raised, but
1630 matching behaviour is unspecified). It is always possible to place these
1631 look-ahead patterns immediately after the look-behind pattern, where they
1632 will work as expected.
1634 Positive look-behind has similar applications as positive look-ahead.
1636 3>Negative Look-Behind
1638 Negative look-behind takes the form `(?<!<regex>)' and is exactly the same as
1639 positive look-behind except that the enclosed regular expression must
1640 NOT match. The same restrictions apply.
1642 Note however, that performance is even more sensitive to the distance
1643 between the size boundaries: a negative look-behind must not match for
1644 **any** possible size, so the matching engine must check **every** size.
1648 There are two parenthetical constructs that control case sensitivity:
1650 (?i<regex>) Case insensitive; `AbcD' and `aBCd' are
1653 (?I<regex>) Case sensitive; `AbcD' and `aBCd' are
1656 Regular expressions are case sensitive by default, that is, `(?I<regex>)' is
1657 assumed. All regular expression token types respond appropriately to case
1658 insensitivity including character classes and backreferences. There is some
1659 extra overhead involved when case insensitivity is in effect, but only to the
1660 extent of converting each character compared to lower case.
1664 NEdit regular expressions by default handle the matching of newlines in a way
1665 that should seem natural for most editing tasks. There are situations,
1666 however, that require finer control over how newlines are matched by some
1667 regular expression tokens.
1669 By default, NEdit regular expressions will NOT match a newline character for
1670 the following regex tokens: dot (`.'); a negated character class (`[^...]');
1671 and the following shortcuts for character classes:
1673 `\d', `\D', `\l', `\L', `\s', `\S', `\w', `\W', `\Y'
1675 The matching of newlines can be controlled for the `.' token, negated
1676 character classes, and the `\s' and `\S' shortcuts by using one of the
1677 following parenthetical constructs:
1679 (?n<regex>) `.', `[^...]', `\s', `\S' match newlines
1681 (?N<regex>) `.', `[^...]', `\s', `\S' don't match
1684 `(?N<regex>)' is the default behavior.
1686 3>Notes on New Parenthetical Constructs
1688 Except for plain parentheses, none of the parenthetical constructs capture
1689 text. If that is desired, the construct must be wrapped with capturing
1690 parentheses, e.g. `((?i<regex))'.
1692 All parenthetical constructs can be nested as deeply as desired, except for
1693 capturing parentheses which have a limit of 50 sets of parentheses,
1694 regardless of nesting level.
1698 Backreferences allow you to match text captured by a set of capturing
1699 parenthesis at some later position in your regular expression. A
1700 backreference is specified using a single backslash followed by a single
1701 digit from 1 to 9 (example: \3). Backreferences have similar syntax to
1702 substitutions (see below), but are different from substitutions in that they
1703 appear within the regular expression, not the substitution string. The number
1704 specified with a backreference identifies which set of text capturing
1705 parentheses the backreference is associated with. The text that was most
1706 recently captured by these parentheses is used by the backreference to
1707 attempt a match. As with substitutions, open parentheses are counted from
1708 left to right beginning with 1. So the backreference `\3' will try to match
1709 another occurrence of the text most recently matched by the third set of
1710 capturing parentheses. As an example, the regular expression `(\d)\1' could
1711 match `22', `33', or `00', but wouldn't match `19' or `01'.
1713 A backreference must be associated with a parenthetical expression that is
1714 complete. The expression `(\w(\1))' contains an invalid backreference since
1715 the first set of parentheses are not complete at the point where the
1716 backreference appears.
1720 Substitution strings are used to replace text matched by a set of capturing
1721 parentheses. The substitution string is mostly interpreted as ordinary text
1724 The escape sequences described above for special characters, and octal and
1725 hexadecimal escapes are treated the same way by a substitution string. When
1726 the substitution string contains the `&' character, NEdit will substitute the
1727 entire string that was matched by the `Find...' operation. Any of the first
1728 nine sub-expressions of the match string can also be inserted into the
1729 replacement string. This is done by inserting a `\' followed by a digit from
1730 1 to 9 that represents the string matched by a parenthesized expression
1731 within the regular expression. These expressions are numbered left-to-right
1732 in order of their opening parentheses.
1734 The capitalization of text inserted by `&' or `\1', `\2', ... `\9' can be
1735 altered by preceding them with `\U', `\u', `\L', or `\l'. `\u' and `\l'
1736 change only the first character of the inserted entity, while `\U' and `\L'
1737 change the entire entity to upper or lower case, respectively.
1738 ----------------------------------------------------------------------
1745 Regular expression substitution can be used to program automatic editing
1746 operations. For example, the following are search and replace strings to find
1747 occurrences of the `C' language subroutine `get_x', reverse the first and
1748 second parameters, add a third parameter of NULL, and change the name to
1751 Search string: `get_x *\( *([^ ,]*), *([^\)]*)\)'
1752 Replace string: `new_get_x(\2, \1, NULL)'
1756 If a regular expression could match two different parts of the text, it will
1757 match the one which begins earliest. If both begin in the same place but
1758 match different lengths, or match the same length in different ways, life
1759 gets messier, as follows.
1761 In general, the possibilities in a list of alternatives are considered in
1762 left-to-right order. The possibilities for `*', `+', and `?' are considered
1763 longest-first, nested constructs are considered from the outermost in, and
1764 concatenated constructs are considered leftmost-first. The match that will be
1765 chosen is the one that uses the earliest possibility in the first choice that
1766 has to be made. If there is more than one choice, the next will be made in
1767 the same manner (earliest possibility) subject to the decision on the first
1768 choice. And so forth.
1770 For example, `(ab|a)b*c' could match `abc' in one of two ways. The first
1771 choice is between `ab' and `a'; since `ab' is earlier, and does lead to a
1772 successful overall match, it is chosen. Since the `b' is already spoken for,
1773 the `b*' must match its last possibility, the empty string, since it must
1774 respect the earlier choice.
1776 In the particular case where no `|'s are present and there is only one `*',
1777 `+', or `?', the net effect is that the longest possible match will be
1778 chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that
1779 if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x', due
1780 to the begins-earliest rule. (In effect, the decision on where to start the
1781 match is the first choice to be made, hence subsequent choices must respect
1782 it even if this leads them to less-preferred alternatives.)
1786 An excellent book on the care and feeding of regular expressions is
1788 Mastering Regular Expressions, 2nd Edition
1789 Jeffrey E. F. Friedl
1790 2002, O'Reilly & Associates
1792 ----------------------------------------------------------------------
1794 Example Regular Expressions
1795 ---------------------------
1797 The following are regular expression examples which will match:
1805 * Whitespace on a line.
1808 * Whitespace across lines.
1811 * Whitespace that spans at least two lines. Note minimal matching `*?' quantifier.
1814 * IP address (not robust).
1815 ! (?:\d{1,3}(?:\.\d{1,3}){3})
1817 * Two character US Postal state abbreviations (includes territories).
1818 ! [ACDF-IK-PR-W][A-Z]
1821 ! (?:http://)?www\.\S+
1823 * Case insensitive double words across line breaks.
1824 ! (?i(?n<(\S+)\s+\1>))
1826 * Upper case words with possible punctuation.
1829 ----------------------------------------------------------------------
1831 Macro/Shell Extensions
1832 ======================
1834 Shell Commands and Filters
1835 --------------------------
1837 The Shell menu (Unix versions only) allows you to execute Unix shell commands
1838 from within NEdit. You can add items to the menu to extend NEdit's command
1839 set or to incorporate custom automatic editing features using shell commands
1840 or editing languages like awk and sed. To add items to the menu, select
1841 Preferences -> Default Settings Customize Menus -> Shell Menu. NEdit comes
1842 pre-configured with a few useful Unix commands like spell and sort, but we
1843 encourage you to add your own custom extensions.
1845 Filter Selection... prompts you for a Unix command to use to process the
1846 currently selected text. The output from this command replaces the contents
1849 Execute Command... prompts you for a Unix command and replaces the current
1850 selection with the output of the command. If there is no selection, it
1851 deposits the output at the current insertion point. In the Shell Command
1852 field, the % character expands to the name (including directory path), and
1853 the # character expands to the current line number of the file in the window.
1854 To include a % or # character in the command, use %% or ##, respectively.
1856 Execute Command Line uses the position of the cursor in the window to
1857 indicate a line to execute as a shell command line. The cursor may be
1858 positioned anywhere on the line. This command allows you to use an NEdit
1859 window as an editable command window for saving output and saving commands
1860 for re-execution. Note that the same character expansions described above
1861 in Execute Command also occur with this command.
1863 The X resource called nedit.shell (See "Customizing_NEdit_") determines which
1864 Unix shell is used to execute commands. The default value for this resource
1866 ----------------------------------------------------------------------
1871 Selecting Learn Keystrokes from the Macro menu puts NEdit in learn mode. In
1872 learn mode, keystrokes and menu commands are recorded, to be played back
1873 later, using the Replay Keystrokes command, or pasted into a macro in the
1874 Macro Commands dialog of the Default Settings menu in Preferences.
1876 Note that only keyboard and menu commands are recorded, not mouse clicks or
1877 mouse movements since these have no absolute point of reference, such as
1878 cursor or selection position. When you do a mouse-based operation in learn
1879 mode, NEdit will beep (repeatedly) to remind you that the operation was not
1882 Learn mode is also the quickest and easiest method for writing macros. The
1883 dialog for creating macro commands contains a button labeled "Paste Learn /
1884 Replay Macro", which will deposit the last sequence learned into the body of
1887 3>Repeating Actions and Learn/Replay Sequences
1889 You can repeat the last (keyboard-based) command, or learn/replay sequence
1890 with the Repeat... command in the Macro menu. To repeat an action, first do
1891 the action (that is, insert a character, do a search, move the cursor), then
1892 select Repeat..., decide how or how many times you want it repeated, and
1893 click OK. For example, to move down 30 lines through a file, you could type:
1894 <Down Arrow> Ctrl+, 29 <Return>. To repeat a learn/replay sequence, first
1895 learn it, then select Repeat..., click on Learn/Replay and how you want it
1896 repeated, then click OK.
1898 If the commands you are repeating advance the cursor through the file, you
1899 can also repeat them within a range of characters, or from the current cursor
1900 position to the end of the file. To iterate over a range of characters, use
1901 the primary selection (drag the left mouse button over the text) to mark the
1902 range you want to operate on, and select "In Selection" in the Repeat dialog.
1904 When using In "Selection" or "To End" with a learned sequence, try to do
1905 cursor movement as the last step in the sequence, since testing of the cursor
1906 position is only done at the end of the sequence execution. If you do cursor
1907 movement first, for example searching for a particular word then doing a
1908 modification, the position of the cursor won't be checked until the sequence
1909 has potentially gone far beyond the end of your desired range.
1911 It's easy for a repeated command to get out of hand, and you can easily
1912 generate an infinite loop by using range iteration on a command which doesn't
1913 progress. To cancel a repeating command in progress, type Ctrl+. (period),
1914 or select Cancel Macro from the Macro menu.
1915 ----------------------------------------------------------------------
1920 Macros can be called from Macro menu commands, window background menu
1921 commands, within the smart-indent framework, from the autoload macro file and
1922 from the command line.
1923 Macro menu and window background menu commands are defined under Preferences
1924 -> Default Settings -> Customize Menus. Help on creating items in these
1925 menus can be found in the section, Help -> Customizing -> Preferences.
1927 The autoload macro file is a file of macro commands and definitions which
1928 NEdit will automatically execute when it is first started. Its location is
1929 dependent on your environment:
1931 * The default place for the file is '$HOME/.nedit/autoload.nm',
1932 * if the variable $NEDIT_HOME is set in your environment it is located at '$NEDIT_HOME/autoload.nm',
1933 * if you are using old-style run control files (i.e. $HOME/.nedit is a regular file) it is located in '$HOME/.neditmacro'.
1935 (For VMS, the file is in '$NEDIT_HOME/autoload.nm' if $NEDIT_HOME is set, in
1936 'SYS$LOGIN:.neditmacro' otherwise.)
1938 NEdit's macro language is a simple interpreter with integer arithmetic,
1939 dynamic strings, and C-style looping constructs (very similar to the
1940 procedural portion of the Unix awk program). From the macro language, you
1941 can call the same action routines which are bound to keyboard keys and menu
1942 items, as well additional subroutines for accessing and manipulating editor
1943 data, which are specific to the macro language (these are listed in the
1944 sections titled "Macro_Subroutines_", and "Action_Routines_").
1949 An NEdit macro language program consists of a list of statements, each
1950 terminated by a newline. Groups of statements which are executed together
1951 conditionally, such as the body of a loop, are surrounded by curly braces
1954 Blank lines and comments are also allowed. Comments begin with a "#" and end
1955 with a newline, and can appear either on a line by themselves, or at the end
1958 Statements which are too long to fit on a single line may be split across
1959 several lines, by placing a backslash "\" character at the end of each line
1965 The NEdit macro language recognizes only three data types, dynamic character
1966 strings, integer values and associative arrays. In general strings and
1967 integers can be used interchangeably. If a string represents an integer
1968 value, it can be used as an integer. Integers can be compared and
1969 concatenated with strings. Arrays may contain integers, strings, or arrays.
1970 Arrays are stored key/value pairs. Keys are always stored as strings.
1974 Integers are non-fractional numbers in the range of -2147483647 to
1975 2147483647. Integer constants must be in decimal. For example:
1980 4>Character String Constants
1982 Character string constants are enclosed in double quotes. For example:
1985 dialog("Hi there!", "OK")
1987 Strings may also include C-language style escape sequences:
1989 \\ Backslash \t Tab \f Form feed
1990 \" Double quote \b Backspace \a Alert
1991 \n Newline \r Carriage return \v Vertical tab
1993 For example, to send output to the terminal from which NEdit was started, a
1994 newline character is necessary because, like printf, t_print requires
1995 explicit newlines, and also buffers its output on a per-line basis:
1997 t_print("a = " a "\n")
2002 Variable names must begin either with a letter (local variables), or a $
2003 (global variables). Beyond the first character, variables may also contain
2004 numbers and underscores `_'. Variables are called in to existence just by
2005 setting them (no explicit declarations are necessary).
2007 Local variables are limited in scope to the subroutine (or menu item
2008 definition) in which they appear. Global variables are accessible from all
2009 routines, and their values persist beyond the call which created them, until
2012 4>Built-in Variables
2014 NEdit has a number of permanently defined variables, which are used to access
2015 global editor information and information about the the window in which the
2016 macro is executing. These are listed along with the built in functions in
2017 the section titled "Macro_Subroutines_".
2020 3>Functions and Subroutines
2022 The syntax of a function or subroutine call is:
2024 function_name(arg1, arg2, ...)
2026 where arg1, arg2, etc. represent the argument values which are passed to
2027 the routine being called. A function or subroutine call can be on a line by
2028 itself, as above, or if it returns a value, can be invoked within a character
2029 or numeric expression:
2031 a = fn1(b, c) + fn2(d)
2032 dialog("fn3 says: " fn3())
2034 Arguments are passed by value. This means that you can not return values via
2035 the argument list, only through the function value or indirectly through
2036 agreed-upon global variables.
2038 4>Built-in Functions
2040 NEdit has a wide range of built in functions which can be called from the
2041 macro language. These routines are divided into two classes, macro-language
2042 functions, and editor action routines. Editor action routines are more
2043 flexible, in that they may be called either from the macro language, or bound
2044 directly to keys via translation tables. They are also limited, however, in
2045 that they can not return values. Macro language routines can return values,
2046 but can not be bound to keys in translation tables.
2048 Nearly all of the built-in subroutines operate on an implied window, which is
2049 initially the window from which the macro was started. To manipulate the
2050 contents of other windows, use the focus_window subroutine to change the
2051 focus to the ones you wish to modify. focus_window can also be used to
2052 iterate over all of the currently open windows, using the special keyword
2053 names, "last" and "next".
2055 For backwards compatibility, hyphenated action routine names are allowed, and
2056 most of the existing action routines names which contain underscores have an
2057 equivalent version containing hyphens ('-') instead of underscores. Use of
2058 these names is discouraged. The macro parser resolves the ambiguity between
2059 '-' as the subtraction/negation operator, and - as part of an action routine
2060 name by assuming subtraction unless the symbol specifically matches an action
2063 4>User Defined Functions
2065 Users can define their own macro subroutines, using the define keyword:
2067 define subroutine_name {
2068 < body of subroutine >
2071 Macro definitions can not appear within other definitions, or within macro
2072 menu item definitions (usually they are found in the autoload macro file).
2074 The arguments with which a user-defined subroutine or function was invoked,
2075 are presented as $1, $2, ... , $9 or $args[expr], where expr can be evaluated
2076 to an integer from 1 to the number of arguments. The number of arguments can
2077 be read from $n_args or $args[]. The array $args[expr] is the only way to
2078 access arguments beyond the first 9.
2080 To return a value from a subroutine, and/or to exit from the subroutine
2081 before the end of the subroutine body, use the return statement:
2083 return <value to return>
2086 3>Operators and Expressions
2088 Operators have the same meaning and precedence that they do in C, except for
2089 ^, which raises a number to a power (y^x means y to the x power), rather than
2090 bitwise exclusive OR. The table below lists operators in decreasing order of
2093 Operators Associativity
2099 > >= < <= == != left to right
2104 (concatenation) left to right
2105 = += -= *= /= %=, &= |= right to left
2107 The order in which operands are evaluated in an expression is undefined,
2108 except for && and ||, which like C, evaluate operands left to right, but stop
2109 when further evaluation would no longer change the result.
2111 4>Numerical Operators
2113 The numeric operators supported by the NEdit macro language are listed below:
2116 - subtraction or negation
2124 Increment (++) and decrement (--) operators can also be appended or prepended
2125 to variables within an expression. Prepended increment/decrement operators
2126 act before the variable is evaluated. Appended increment/decrement operators
2127 act after the variable is evaluated.
2129 4>Logical and Comparison Operators
2131 Logical operations produce a result of 0 (for false) or 1 (for true). In a
2132 logical operation, any non-zero value is recognized to mean true. The
2133 logical and comparison operators allowed in the NEdit macro language are
2143 == equal (integers and/or strings)
2144 != not equal (integers and/or strings)
2146 4>Character String Operators
2148 The "operator" for concatenating two strings is the absence of an operator.
2149 Adjoining character strings with no operator in between means concatenation:
2152 t_print("the value of a is: " a)
2154 Comparison between character strings is done with the == and != operators,
2155 (as with integers). There are a number of useful built-in routines for
2156 working with character strings, which are listed in the section called
2157 "Macro_Subroutines_".
2159 4>Arrays and Array Operators
2161 Arrays may contain either strings, integers, or other arrays. Arrays are
2162 associative, which means that they relate two pieces of information, the key
2163 and the value. The key is always a string; if you use an integer it is
2164 converted to a string.
2166 To determine if a given key is in an array, use the 'in' keyword.
2171 If the left side of the in keyword is an array, the result is true if every
2172 key in the left array is in the right array. Array values are not compared.
2174 To iterate through all the keys of an array use the 'for' looping construct.
2175 Keys are not guaranteed in any particular order:
2180 Elements can be removed from an array using the delete command:
2182 delete x[3] # deletes element with key 3
2183 delete x[] # deletes all elements
2185 The number of elements in an array can be determined by referencing the
2186 array with no indices:
2188 dialog("array x has " x[] " elements", "OK")
2190 Arrays can be combined with some operators. All the following operators only
2191 compare the keys of the arrays.
2193 result = x + y (Merge arrays)
2195 The 'result' is a new array containing keys from both x and y. If
2196 duplicates are present values from y are used.
2198 result = x - y (Remove keys)
2200 The 'result' is a new array containing all keys from x that are not in y.
2202 result = x & y (Common keys)
2204 The 'result' is a new array containing all keys which are in both x and y.
2205 The values from y are used.
2207 result = x | y (Unique keys)
2209 The 'result' is a new array containing keys which exist in either x or y,
2212 When duplicate keys are encountered using the + and & operators, the values
2213 from the array on the right side of the operators are used for the result.
2214 All of the above operators are array only, meaning both the left and right
2215 sides of the operator must be arrays. The results are also arrays.
2217 Array keys can also contain multiple dimensions:
2219 x[1, 1, 1] = "string"
2221 These are used in the expected way, e.g.:
2223 for (i = 1; i < 3; i++)
2225 for (j = 1; j < 3; j++)
2231 gives the following array:
2238 Internally all indices are part of one string, separated by the string
2239 $sub_sep (ASCII 0x1c, 'FS'). The first key in the above example is in
2244 If you need to extract one of the keys, you can use split(), using
2245 $sub_sep as the separator.
2247 You can also check for the existence of multi-dimensional array by
2248 looking for $sub_sep in the key.
2250 Last, you need $sub_sep if you want to use the 'in' keyword.
2252 if ((1,2) in myArray)
2257 if (("1" $sub_sep "2") in myArray)
2262 3>Looping and Conditionals
2264 NEdit supports looping constructs: for and while, and conditional statements:
2265 if and else, with essentially the same syntax as C:
2267 for (<init>, ...; <condition>; <increment>, ...) <body>
2269 while (<condition>) <body>
2271 if (<condition>) <body>
2273 if (<condition>) <body> else <body>
2275 <body>, as in C, can be a single statement, or a list of statements enclosed
2276 in curly braces ({}). <condition> is an expression which must evaluate to
2277 true for the statements in <body> to be executed. for loops may also contain
2278 initialization statements, <init>, executed once at the beginning of the
2279 loop, and increment/decrement statements (or any arbitrary statement), which
2280 are executed at the end of the loop, before the condition is evaluated again.
2284 for (i=0; i<100; i++)
2287 for (i=0, j=20; i<20; i++, j--) {
2303 Loops may contain break and continue statements. A break statement causes an
2304 exit from the innermost loop, a continue statement transfers control to the
2306 ----------------------------------------------------------------------
2311 3>Built in Variables
2313 These variables are read-only and can not be changed.
2315 **$1**, **$2**, **$3**, **$4**, **$5**, **$6**, **$7**, **$8**, **$9**
2318 Argument information. The first 9 arguments (if there are that many) can
2319 be referenced as read-only values using the shorthand form. All arguments
2320 can be accessed as values in the **$args** array, using a numeric index
2321 starting at 1. The total number of arguments received by a function is
2322 given by **$n_args** or **$args[]**.
2325 Index of the current pane.
2328 Contains the current preference for auto indent.
2329 Can be "off", "on" or "auto".
2332 Equals the ID of the currently displayed calltip, or 0 if no calltip is
2336 Position of the cursor in the current window.
2339 Column number of the cursor position in the current window.
2342 Width of the current pane in pixels.
2345 If tab emulation is turned on in the Tabs...
2346 dialog of the Preferences menu, value is the
2347 distance between emulated tab stops. If tab
2348 emulation is turned off, value is -1.
2351 An array with no elements. This can be used to initialize
2352 an array to an empty state.
2355 Current newline format that the file will be saved with. Can
2356 be "unix", "dos" or "macintosh".
2359 Name of the file being edited in the current
2360 window, stripped of directory component.
2363 Directory component of file being edited in the current window.
2366 Contains the current plain text font name.
2369 Contains the current bold text font name.
2371 **$font_name_bold_italic**
2372 Contains the current bold-italic text font name.
2374 **$font_name_italic**
2375 Contains the current italic text font name.
2377 **$highlight_syntax**
2378 Whether syntax highlighting is turned on.
2380 **$incremental_backup**
2381 Contains 1 if incremental auto saving is on, otherwise 0.
2383 **$incremental_search_line**
2384 Has a value of 1 if the preference is
2385 selected to always show the incremental search line, otherwise 0.
2388 Name of language mode set in the current window.
2391 Line number of the cursor position in the current window.
2394 True if the file has been locked by the user.
2396 **$make_backup_copy**
2397 Has a value of 1 if original file is kept in a
2398 backup file on save, otherwise 0.
2401 The maximum font width of all the active styles.
2402 Syntax highlighting styles are only considered if syntax highlighting
2406 The minimum font width of all the active styles.
2407 Syntax highlighting styles are only considered if syntax highlighting
2411 True if the file in the current window has
2412 been modified and the modifications have not
2415 **$n_display_lines**
2416 The number of lines visible in the currently active pane.
2419 The number of panes in the current window.
2422 True if in Overtype mode.
2425 True if the file is read only.
2427 **$selection_start, $selection_end**
2428 Beginning and ending positions of the
2429 primary selection in the current window, or
2430 -1 if there is no text selected in the current window.
2432 **$selection_left, $selection_right**
2433 Left and right character offsets of the rectangular (primary) selection in
2434 the current window, or -1 if there is no selection or it is not rectangular.
2437 Name of the current NEdit server.
2439 **$show_line_numbers**
2440 Whether line numbers are shown next to the text.
2443 Contains the current preference for showing matching pairs,
2444 such as "[]" and "{}" pairs. Can be "off", "delimiter", or "range".
2446 **$match_syntax_based**
2447 Whether pair matching should use syntax information, if available.
2449 **$statistics_line**
2450 Has a value of 1 if the statistics line is shown, otherwise 0.
2453 Contains the value of the array sub-script separation string.
2456 The distance between tab stops for a
2457 hardware tab character, as set in the
2458 Tabs... dialog of the Preferences menu.
2461 The length of the text in the current window.
2464 The line number of the top line of the currently active pane.
2467 Whether the user is allowing the NEdit to insert tab characters to maintain
2468 spacing in tab emulation and rectangular dragging operations. (The setting of
2469 the "Use tab characters in padding and emulated tabs" button in the Tabs...
2470 dialog of the Preferences menu.)
2473 The right margin in the current window for text wrapping and filling.
2476 The current wrap text mode. Values are "none", "auto" or "continuous".
2478 ..Disabled for 5.4 release.
2479 ..**$backlight_string**
2480 .. The current value of the window's backlighting specification. This is empty
2481 .. if backlighting is turned off. It can be changed through calls to the
2482 .. built-in macro function set_backlight_string().
2485 3>Built-in Subroutines
2487 **append_file( string, filename )**
2488 Appends a string to a named file. Returns 1 on successful write, or 0 if
2494 **calltip( "text_or_key" [, pos [, mode or position_modifier, ...]] )**
2495 Pops up a calltip. <pos> is an optional position in the buffer where the tip
2496 will be displayed. Passing -1 for <pos> is equivalent to not specifying a
2497 position, and it guarantees that the tip will appear on-screen somewhere even
2498 if the cursor is not. The upper-left corner of the calltip will appear below
2499 where the cursor would appear if it were at this position. <mode> is one of
2500 "tipText" (default), "tipKey", or "tagKey". "tipText" displays the text as-is,
2501 "tagKey" uses it as the key to look up a tag, then converts the tag to a
2502 calltip, and "tipKey" uses it as the key to look up a calltip, then falls back
2503 to "tagKey" behavior if that fails. You'll usually use "tipKey" or "tipText".
2504 Finally, you can modify the placement of the calltip relative to the cursor
2505 position (or <pos>) with one or more of these optional position modifiers:
2506 "center" aligns the center of the calltip with the position. "right" aligns
2507 the right edge of the calltip with the position. ("center" and "right" may
2508 not both be used.) "above" places the calltip above the position. "strict"
2509 does not allow the calltip to move from its position in order to avoid going
2510 off-screen or obscuring the cursor. Returns the ID of the calltip if it was
2511 found and/or displayed correctly, 0 otherwise.
2513 **clipboard_to_string()**
2514 Returns the contents of the clipboard as a macro string. Returns empty
2517 **dialog( message, btn_1_label, btn_2_label, ... )**
2518 Pop up a dialog for querying and presenting information to the user. First
2519 argument is a string to show in the message area of the dialog. Up to eight
2520 additional optional arguments represent labels for buttons to appear along
2521 the bottom of the dialog. Returns the number of the button pressed (the
2522 first button is number 1), or 0 if the user closed the dialog via the window
2525 **focus_window( window_name )**
2526 Sets the window on which subsequent macro commands operate. window_name can
2527 be either a fully qualified file name, or one of "last" for the last window
2528 created, or "next" for the next window in the chain from the currently
2529 focused window (the first window being the one returned from calling
2530 focus_window("last"). Returns the name of the newly-focused window, or an
2531 empty string if the requested window was not found.
2533 **get_character( position )**
2534 Returns the single character at the position
2535 indicated by the first argument to the routine from the current window.
2537 **get_range( start, end )**
2538 Returns the text between a starting and ending position from the current
2542 Returns a string containing the text currently selected by the primary
2543 selection either from the current window (no keyword), or from anywhere on
2544 the screen (keyword "any").
2547 Gets the value of an environment variable.
2549 **kill_calltip( [calltip_ID] )**
2550 Kills any calltip that is being displayed in the window in which the macro is
2551 running. If there is no displayed calltip this does nothing. If a calltip
2552 ID is supplied then the calltip is killed only if its ID is calltip_ID.
2554 **length( string )**
2555 Returns the length of a string
2557 **list_dialog( message, text, btn_1_label, btn_2_label, ... )**
2558 Pop up a dialog for prompting the user to choose a line from the given text
2559 string. The first argument is a message string to be used as a title for the
2560 fixed text describing the list. The second string provides the list data:
2561 this is a text string in which list entries are separated by newline
2562 characters. Up to seven additional optional arguments represent labels for
2563 buttons to appear along the bottom of the dialog. Returns the line of text
2564 selected by the user as the function value (without any newline separator) or
2565 the empty string if none was selected, and number of the button pressed (the
2566 first button is number 1), in $list_dialog_button. If the user closes the
2567 dialog via the window close box, the function returns the empty string, and
2568 $list_dialog_button returns 0.
2570 **max( n1, n2, ... )**
2571 Returns the maximum value of all of its arguments
2573 **min( n1, n2, ... )**
2574 Returns the minimum value of all of its arguments
2576 **read_file( filename )**
2577 Reads the contents of a text file into a string. On success, returns 1 in
2578 $read_status, and the contents of the file as a string in the subroutine
2579 return value. On failure, returns the empty string "" and an 0 $read_status.
2581 **replace_in_string( string, search_for, replace_with [, type, "copy"] )**
2582 Replaces all occurrences of a search string in a string with a replacement
2583 string. Arguments are 1: string to search in, 2: string to search for, 3:
2584 replacement string. There are two optional arguments. One is a search type,
2585 either "literal", "case", "word", "caseWord", "regex", or "regexNoCase".
2586 The default search type is "literal". If the optional "copy" argument is
2587 specified, a copy of the input string is returned when no replacements were
2588 performed. By default an empty string ("") will be returned in this case.
2589 Returns a new string with all of the replacements done.
2591 **replace_range( start, end, string )**
2592 Replaces all of the text in the current window between two positions.
2594 **replace_selection( string )**
2595 Replaces the primary-selection selected text in the current window.
2597 **replace_substring( string, start, end, replace_with )**
2598 Replacing a substring between two positions in a string within another string.
2600 **search( search_for, start [, search_type, wrap, direction] )**
2601 Searches silently in a window without dialogs, beeps, or changes to the
2602 selection. Arguments are: 1: string to search for, 2: starting position.
2603 Optional arguments may include the strings: "wrap" to make the search wrap
2604 around the beginning or end of the string, "backward" or "forward" to change
2605 the search direction ("forward" is the default), "literal", "case", "word",
2606 "caseWord", "regex", or "regexNoCase" to change the search type (default is
2607 "literal"). Returns the starting position of the match, or -1 if nothing
2608 matched. Also returns the ending position of the match in $search_end.
2610 **search_string( string, search_for, start [, search_type, direction] )**
2612 Built-in macro subroutine for searching a string. Arguments are 1: string to
2613 search in, 2: string to search for, 3: starting position. Optional arguments
2614 may include the strings: "wrap" to make the search wrap around the beginning
2615 or end of the string, "backward" or "forward" to change the search direction
2616 ("forward" is the default), "literal", "case", "word", "caseWord", "regex",
2617 or "regexNoCase" to change the search type (default is "literal"). Returns
2618 the starting position of the match, or -1 if nothing matched. Also returns
2619 the ending position of the match in $search_end.
2621 **select( start, end )**
2622 Selects (with the primary selection) text in the current buffer between a
2623 starting and ending position.
2625 **select_rectangle( start, end, left, right )**
2626 Selects a rectangular area of text between a starting and ending position,
2627 and confined horizontally to characters displayed between positions "left",
2630 ..Disabled for 5.4 release.
2631 ..**set_backlight_string( [string] )**
2632 .. Applies the given string, which should be in the format of the
2633 .. nedit*backlightCharTypes X resource, to the current text window, turning on
2634 .. backlighting. If the value of the string passed is "default", or if no
2635 .. parameter is passed, the nedit.backlightCharTypes X resource's own value will
2636 .. be used. If the empty string, "", is passed, backlighting will be turned
2639 **set_cursor_pos( position )**
2640 Set the cursor position for the current window.
2642 **shell_command( command, input_string )**
2643 Executes a shell command, feeding it input from input_string. On completion,
2644 output from the command is returned as the function value, and the command's
2645 exit status is returned in the global variable $shell_cmd_status.
2647 **split(string, separation_string [, search_type])**
2648 Splits a string using the separator specified. Optionally the search_type
2649 argument can specify how the separation_string is interpreted. The default
2650 is "literal". The returned value is an array with keys beginning at 0.
2652 **string_dialog( message, btn_1_label, btn_2_label, ... )**
2653 Pops up a dialog prompting the user to enter information. The first argument
2654 is a string to show in the message area of the dialog. Up to nine additional
2655 optional arguments represent labels for buttons to appear along the bottom of
2656 the dialog. Returns the string entered by the user as the function value,
2657 and number of the button pressed (the first button is number 1), in
2658 $string_dialog_button. If the user closes the dialog via the window close
2659 box, the function returns the empty string, and $string_dialog_button returns
2662 **string_compare(string1, string2 [, consider-case])**
2663 Compare two strings and return 0 if they are equal, -1 if string1 is less
2664 than string2 or 1 if string1 is greater than string2. The values for the
2665 optional consider-case argument is either "case" or "nocase". The default
2666 is to do a case sensitive comparison.
2668 **string_to_clipboard( string )**
2669 Copy the contents of a macro string to the clipboard.
2671 **substring( string, start, end )**
2672 Returns the portion of a string between a starting and ending position.
2674 **t_print( string1, string2, ... )**
2675 Writes strings to the terminal (stdout) from which NEdit was started.
2677 **tolower( string )**
2678 Return an all lower-case version of string.
2680 **toupper( string )**
2681 Return an all upper-case version of string.
2683 **valid_number( string )**
2684 Returns 1 if the string can be converted to a number without error
2685 following the same rules that the implicit conversion would. Otherwise 0.
2687 **write_file( string, filename )**
2688 Writes a string (parameter 1) to a file named in parameter 2. Returns 1 on
2689 successful write, or 0 if unsuccessful.
2692 3>Deprecated Functions
2694 Some functions are included only for supporting legacy macros. You should not
2695 use any of these functions in any new macro you write. Among these are all
2696 action routines with hyphens in their names; use underscores instead
2697 ('find-dialog' -> 'find_dialog').
2700 **DEPRECATED** Use select_to_matching() instead.
2702 ----------------------------------------------------------------------
2707 A rangeset is a set of ranges. A range is a contiguous range of characters
2708 defined by its start and end position in the document. The user can
2709 create rangesets, identified by arbitrary integers (chosen by the editor when
2710 the rangesets are created), and each range within a rangeset is identified by
2711 a numeric index, counting from 1, in the order of appearance in the text
2712 buffer. The ranges are adjusted when modifications are made to the text
2713 buffer: they shuffle around when characters are added or deleted. However,
2714 ranges within a set will coalesce if the characters between them are removed,
2715 or a new range is added to the set which bridges or overlaps others.
2717 Using rangesets allows non-contiguous bits of the text to be identified as a
2720 Rangesets can be assigned a background color: characters within a range of a
2721 rangeset will have the background color of the rangeset. If more than one
2722 rangeset includes a given character, its background color will be that of the
2723 most recently created rangeset which has a color defined.
2725 Rangesets must be created using the rangeset_create() function, which
2726 will return an identifier for the newly-created rangeset. This identifier
2727 is then passed to the other rangeset functions to manipulate the rangeset.
2729 There is a limit to the number of rangesets which can exist at any time -
2730 currently up to 63 in each document. Care should be taken to destroy
2731 any rangesets which are no longer needed, by using the rangeset_destroy()
2732 function, if this limit is attained.
2734 Rangesets can be named: this is useful for macros which need a fixed
2735 identification for rangesets which are used for the same purpose in
2736 different documents. Although a new rangeset's number is arbitrary, its
2737 name can be fixed. This is done using the rangeset_set_name() function.
2738 Note that rangeset names within a particular document may not be unique.
2739 For this reason, the rangeset_get_by_name() function returns an array of
2740 identifiers, which will be empty if the name has not been associated with
2743 4>How rangesets change with modifications
2745 When changes are made to the document text, ranges within each set are altered
2746 with it, according to their behavioral mode. If changes are made outside of
2747 the ranges in a rangeset, each range simply maintains its size and adjusts its
2748 position to match the changes. When text within a range is deleted, the
2749 range's length is reduced by the same amount. When changes involving new text
2750 are made within a range of the set, or to one of the extremities of a range,
2751 different behaviours may be desirable. The rangeset_set_mode() function allows
2752 these modes to be chosen.
2754 Note that the precise behaviour of these modes may change in future versions
2757 The available modes are:
2759 **maintain** or **ins_del** -
2760 Both these modes have the same behaviour. New text added at the front of a
2761 range in a set is not added to the range; new text added within the range or
2762 at the end extends the range. Replacement overlapping an extremity of the
2763 set acts as if the new text were added first, then the old text deleted.
2764 This causes curtailment at the front of the range, extension at the end.
2765 Replacement of the full text of the range removes the range from the set.
2766 The default behaviour for a newly created rangeset is **maintain**.
2769 New text added at the front or end of a range in a set is not added to the
2770 range; new text added within the range extends the range. Replacement
2771 overlapping an extremity of the set acts as if the old text were deleted
2772 first, then the new text added. This causes curtailment at either end.
2773 Replacement of the full text of the range removes the range from the set.
2776 New text added at the front or end of a range in a set extends the range, as
2777 does new text added within the range. Replacement overlapping an extremity
2778 of the set acts as if the new text were added first, then the old text
2779 deleted. This causes curtailment at the front of the range, extension at
2780 the end. Replacement of the full text of the range adds the new text to the
2781 range if the start position of the replacement is at the range's start
2785 New text added at the front or end of a range in a set does not extend the
2786 range; new text added within the range extends the range. Replacement
2787 overlapping an extremity causes curtailment of the range. Replacement of
2788 the full text of the range removes the range from the set.
2791 New text added at the front or end of a range in a set does not extend the
2792 range; new text added within the range will split the range. Replacement
2793 overlapping an extremity causes curtailment of the range. Replacement of
2794 the full text of the range removes the range from the set.
2798 A rangeset is manipulated ~only~ through macro routines. Rangesets
2799 can easily become very large, and may exceed the capacity of the running
2800 process. Coloring relies on proper color names or specifications (such as
2801 the "#rrggbb" hexadecimal digit strings), and appropriate hardware support. If
2802 an invalid color name is given, the default background color is used instead.
2803 Behaviours set using rangeset_set_mode() are subject to change in future
2806 3>Rangeset read-only variables
2809 array of active rangeset identifiers, with integer keys starting at 0,
2810 in the order the rangesets were defined.
2813 3>Rangeset functions
2815 **rangeset_create()**
2816 **rangeset_create( n )**
2817 Creates one or more new rangesets. The first form creates a single range
2818 set and returns its identifier; if there are no rangesets available it
2819 returns 0. The second form creates n new rangesets, and returns an array
2820 of the rangeset identifiers with keys beginning at 0. If the requested
2821 number of rangesets is not available it returns an empty array.
2823 **rangeset_destroy( r )**
2824 **rangeset_destroy( array )**
2825 Deletes all information about a rangeset or a number of rangesets. The
2826 first form destroys the rangeset identified by r. The second form should
2827 be passed an array of rangeset identifiers with keys beginning at 0 (i.e.
2828 the same form of array returned by rangeset_create(n); it destroys all the
2829 rangesets appearing in the array. If any of the rangesets do not exist,
2830 the function continues without errors. Does not return a value.
2832 **rangeset_add( r, [start, end] )**
2833 **rangeset_add( r, r0 )**
2834 Adds to the rangeset r. The first form adds the range identified by the
2835 current primary selection to the rangeset, unless start and end are defined,
2836 in which case the range they define is added. Returns the index of the
2837 newly-added range within the rangeset. The second form adds all ranges in
2838 the rangeset r0 to the rangeset r, and returns 0.
2840 **rangeset_subtract( r, [start, end] )**
2841 **rangeset_subtract( r, r0 )**
2842 Removes from the rangeset r. The first form removes the range identified by
2843 the current primary selection from the rangeset, unless start and end are
2844 defined, in which case the range they define is removed. The second form
2845 removes all ranges in the rangeset r0 from the rangeset r. Does not return
2848 **rangeset_invert( r )**
2849 Changes the rangeset r so that it contains all ranges not in r. Does not
2852 **rangeset_get_by_name( name )**
2853 Returns an array of active rangeset identifiers, with integer keys starting at 0,
2854 whose name matches name.
2856 **rangeset_info( r )**
2857 Returns an array containing information about the rangeset r. The array
2858 has the following keys: **defined** (whether a rangeset with identifier
2859 r is defined), **count** (the number of ranges in the rangeset), **color**
2860 (the current background color of the rangeset, an empty string if the
2861 rangeset has no color), **name** (the user supplied name of the rangeset,
2862 an empty string if the rangeset has no name), and **mode** (the name of the
2863 modify-response mode of the rangeset).
2865 **rangeset_range( r, [index] )**
2866 Returns details of a specific range in the rangeset r. The range is
2867 specified by index, which should be between 1 and n (inclusive), where
2868 n is the number of ranges in the rangeset. The return value is an array
2869 containing the keys **start** (the start position of the range) and **end**
2870 (the end position of the range). If index is not supplied, the region
2871 returned is the span of the entire rangeset (the region starting at the
2872 start of the first range and ending at the end of the last). If index
2873 is outside the correct range of values, the function returns an empty array.
2875 **rangeset_includes( r, pos )**
2876 Returns the index of the range in rangeset r which includes pos; returns
2877 0 if pos is not contained in any of the ranges of r. This can also be used
2878 as a simple true/false function which returns true if pos is contained in
2881 **rangeset_set_color( r, color )**
2882 Attempts to apply the color as a background color to the ranges of r. If
2883 color is at empty string, removes the coloring of r. No check is made
2884 regarding the validity of color: if the color is invalid (a bad name,
2885 or not supported by the hardware) this has unpredictable effects.
2887 **rangeset_set_name( r, name )**
2888 Apply the name to the rangeset r.
2890 **rangeset_set_mode( r, type )**
2891 Changes the behaviour of the rangeset r when modifications to the text
2892 buffer occur. type can be one of the following: "maintain" (the default),
2893 "break", "include", "exclude", "ins_del" or "del_ins". (These modes are
2897 Highlighting Information
2898 ------------------------
2900 The user can interrogate the current window to determine the color
2901 highlighting used on a particular piece of text. The following functions
2902 provide information on the highlighting pattern against which text at a
2903 particular position has been matched, its style, color and font attributes
2904 (whether the font is supposed to be bold and/or italic).
2906 These macro functions permit macro writers to generate formatted output which
2907 allows NEdit highlighting to be reproduced. This is suitable for the
2908 generation of HTML or Postscript output, for example.
2910 Note that if any of the functions is used while in Plain mode or while syntax
2911 highlighting is off, the behaviour is undefined.
2913 **get_pattern_by_name( pattern_name )**
2914 Returns an array containing the pattern attributes for pattern 'pattern_name'.
2915 The elements in this array are:
2917 * **style** -- Highlight style name
2919 If 'pattern_name' is invalid, an empty array is returned.
2921 **get_pattern_at_pos( pos )**
2922 Returns an array containing the pattern attributes of the character at
2923 position 'pos'. The elements in this array are:
2925 * **pattern** -- Highlight pattern name
2926 * **style** -- Highlight style name
2927 * **extent** -- The length in the text which uses the same highlighting pattern
2929 The 'extent' value is measured from position 'pos' going right/down (forward
2932 If 'pos' is invalid, an empty array is returned.
2934 **get_style_by_name( style_name )**
2935 Returns an array containing the style attributes for style 'style_name'.
2936 The elements in this array are:
2938 * **bold** -- '1' if style is bold, '0' otherwise
2939 * **italic** -- '1' if style is italic, '0' otherwise
2940 * **color** -- Name of the style's color
2941 * **background** -- Name of the background color, if any
2943 The colors use the names specified in the color definitions for the style.
2944 These will either be names matching those the X server recognises, or RGB
2945 (red/green/blue) specifications.
2947 If 'style_name' is invalid, an empty array is returned.
2949 **get_style_at_pos( pos )**
2950 Returns an array containing the style attributes of the character at
2951 position 'pos'. The elements in this array are:
2953 * **style** -- Name of the highlight style
2954 * **bold** -- '1' if style is bold, '0' otherwise
2955 * **italic** -- '1' if style is italic, '0' otherwise
2956 * **color** -- Name of the style's color
2957 * **rgb** -- Color's RGB values ('#rrggbb')
2958 * **background** -- Name of the background color, if any
2959 * **back_rgb** -- Background color's RGB values ('#rrggbb')
2960 * **extent** -- The length in the text which uses the same highlight style
2962 The colors use the names specified in the color definitions for the style.
2963 These will either be names matching those the X server recognises, or RGB
2964 specifications. The values for 'rgb' and 'back_rgb' contain the actual color
2965 values allocated by the X server for the window. If the X server cannot
2966 allocate the specified (named) color exactly, the RGB values in these
2967 entries may not match the specified ones.
2969 The 'extent' value is measured from position 'pos' going right/down (forward
2972 If 'pos' is invalid, an empty array is returned.
2974 ----------------------------------------------------------------------
2979 All of the editing capabilities of NEdit are represented as a special type of
2980 subroutine, called an action routine, which can be invoked from both macros
2981 and translation table entries (see "Key_Binding_" in the
2982 Customizing section of the Help menu).
2985 3>Actions Representing Menu Commands
2987 File Menu Search Menu
2988 ----------------------- -------------------------
2990 open() find_dialog()
2991 open_dialog() find_again()
2992 open_selected() find_selection()
2994 save() replace_dialog()
2995 save_as() replace_all()
2996 save_as_dialog() replace_in_selection()
2997 revert_to_saved() replace_again()
2998 include_file() goto_line_number()
2999 include_file_dialog() goto_line_number_dialog()
3000 load_macro_file() goto_selected()
3001 load_macro_file_dialog() mark()
3002 load_tags_file() mark_dialog()
3003 load_tags_file_dialog() goto_mark()
3004 unload_tags_file() goto_mark_dialog()
3005 load_tips_file() goto_matching()
3006 load_tips_file_dialog() select_to_matching()
3007 unload_tips_file() find_definition()
3011 -------------------------
3012 Edit Menu filter_selection_dialog()
3013 ----------------------- filter_selection()
3014 undo() execute_command()
3015 redo() execute_command_dialog()
3016 delete() execute_command_line()
3017 select_all() shell_menu_command()
3019 shift_left_by_tab() Macro Menu
3020 shift_right() -------------------------
3021 shift_right_by_tab() macro_menu_command()
3022 uppercase() repeat_macro()
3023 lowercase() repeat_dialog()
3025 control_code_dialog() Windows Menu
3026 -------------------------
3030 move_document_dialog()
3033 An action representing a menu command is usually named the same as its
3034 corresponding menu item except that all punctuation is removed, all letters
3035 are changed to lower case, and spaces are replaced with underscores. To
3036 present a dialog to ask the user for input, use the actions with the
3037 `_dialog` suffix. Actions without the `_dialog` suffix take the information
3038 from the routine's arguments (see below).
3040 3>Menu Action Routine Arguments
3042 Arguments are text strings enclosed in quotes. Below are the menu action
3043 routines which take arguments. Optional arguments are enclosed in [].
3045 **new**( ["tab" | "window" | "prefs" | "opposite"] )
3047 **close**( ["prompt" | "save" | "nosave"] )
3049 **execute_command**( shell-command )
3051 **filter_selection**( shell-command )
3053 **find**( search-string [, ~search-direction~] [, ~search-type~]
3056 **find_again**( [~search-direction~] [, ~search-wrap~] )
3058 **find_definition**( [tag-name] )
3060 **find_dialog**( [~search-direction~] [, ~search-type~]
3063 **find_selection**( [~search-direction~] [, ~search-wrap~]
3064 [, ~non-regex-search-type~] )
3066 **goto_line_number**( [~line-number~] [, ~column-number~] )
3068 **goto_mark**( ~mark-letter~ )
3070 **include_file**( ~filename~ )
3072 **load_tags_file**( ~filename~ )
3074 **macro_menu_command**( ~macro-menu-item-name~ )
3076 **mark**( ~mark-letter~ )
3078 **open**( ~filename~ )
3080 **replace**( search-string, replace-string,
3081 [, ~search-direction~] [, ~search-type~] [, ~search-wrap~] )
3083 **replace_again**( [~search-direction~] [, ~search-wrap~] )
3085 **replace_all**( search-string, replace-string [, ~search-type~] )
3087 **replace_dialog**( [~search-direction~] [, ~search-type~]
3090 **replace_in_selection**( search-string,
3091 replace-string [, ~search-type~] )
3093 **save_as**( ~filename~ )
3095 **shell_menu_command**( ~shell-menu-item-name~ )
3097 **unload_tags_file**( ~filename~ )
3099 **----------- Some notes on argument types above -----------**
3101 ~Arguments to new()~
3102 "tab": Open a new tab
3103 "window": Open a new window
3104 "prefs": Follow the user's tab/window
3106 "opposite": Opposite of user's tab/window
3108 Default behaviour is "prefs".
3110 ~filename~ Path names are relative to the directory from
3111 which NEdit was started. Shell interpreted
3112 wildcards and `~' are not expanded.
3114 ~keep-dialog~ Either "keep" or "nokeep".
3116 ~mark-letter~ The mark command limits users to single
3117 letters. Inside of macros, numeric marks are
3118 allowed, which won't interfere with marks set
3121 ~macro-menu-item-name~
3122 Name of the command exactly as specified in
3123 the Macro Menu dialogs.
3125 ~non-regex-search-type~
3126 Either "literal", "case", "word", or
3130 Either "forward" or "backward".
3132 ~search-type~ Either "literal", "case", "word",
3133 "caseWord", "regex", or "regexNoCase".
3135 ~search-wrap~ Either "wrap" or "nowrap".
3137 ~shell-menu-item-name~
3138 Name of the command exactly as specified in
3139 the Shell Menu dialogs.
3141 3>Window Preferences Actions
3143 **set_auto_indent( "off" | "on" | "smart" )**
3144 Set auto indent mode for the current window.
3146 **set_em_tab_dist( em-tab-distance )**
3147 Set the emulated tab size. An em-tab-distance value of
3148 0 or -1 translates to no emulated tabs. Em-tab-distance must
3149 be smaller than 1000.
3151 **set_fonts( font-name, italic-font-name, bold-font-name, bold-italic-font-name )**
3152 Set all the fonts used for the current window.
3154 **set_highlight_syntax( [0 | 1] )**
3155 Set syntax highlighting mode for the current window.
3156 A value of 0 turns it off and a value of 1 turns it on.
3157 If no parameters are supplied the option is toggled.
3159 **set_incremental_backup( [0 | 1] )**
3160 Set incremental backup mode for the current window.
3161 A value of 0 turns it off and a value of 1 turns it on.
3162 If no parameters are supplied the option is toggled.
3164 **set_incremental_search_line( [0 | 1] )**
3165 Show or hide the incremental search line for the current window.
3166 A value of 0 turns it off and a value of 1 turns it on.
3167 If no parameters are supplied the option is toggled.
3169 **set_language_mode( language-mode )**
3170 Set the language mode for the current window. If the language mode is
3171 "" or unrecognized, it will be set to Plain.
3173 **set_locked( [0 | 1] )**
3174 This only affects the locked status of a file, not it's read-only
3175 status. Permissions are NOT changed.
3176 A value of 0 turns it off and a value of 1 turns it on.
3177 If no parameters are supplied the option is toggled.
3179 **set_make_backup_copy( [0 | 1] )**
3180 Set whether backup copies are made during saves for the current window.
3181 A value of 0 turns it off and a value of 1 turns it on.
3182 If no parameters are supplied the option is toggled.
3184 **set_overtype_mode( [0 | 1] )**
3185 Set overtype mode for the current window.
3186 A value of 0 turns it off and a value of 1 turns it on.
3187 If no parameters are supplied the option is toggled.
3189 **set_show_line_numbers( [0 | 1] )**
3190 Show or hide line numbers for the current window.
3191 A value of 0 turns it off and a value of 1 turns it on.
3192 If no parameters are supplied the option is toggled.
3194 **set_show_matching( "off" | "delimiter" | "range" )**
3195 Set show matching (...) mode for the current window.
3197 **set_match_syntax_based( [0 | 1] )**
3198 Set whether matching should be syntax based for the current window.
3200 **set_statistics_line( [0 | 1] )**
3201 Show or hide the statistics line for the current window.
3202 A value of 0 turns it off and a value of 1 turns it on.
3203 If no parameters are supplied the option is toggled.
3205 **set_tab_dist( tab-distance )**
3206 Set the size of hardware tab spacing. Tab-distance must
3207 must be a value greater than 0 and no greater than 20.
3209 **set_use_tabs( [0 | 1] )**
3210 Set whether tabs are used for the current window.
3211 A value of 0 turns it off and a value of 1 turns it on.
3212 If no parameters are supplied the option is toggled.
3214 **set_wrap_margin( wrap-width )**
3215 Set the wrap width for text wrapping of the current window. A value
3216 of 0 means to wrap at window width.
3218 **set_wrap_text( "none" | "auto" | "continuous" )**
3219 Set wrap text mode for the current window.
3221 3>Keyboard-Only Actions
3223 In addition to the arguments listed in the call descriptions below, any
3224 routine involving cursor movement can take the argument "extend", meaning,
3225 adjust the primary selection to the new cursor position. Routines which take
3226 the "extend" argument as well as mouse dragging operations for both primary
3227 and secondary selections can take the optional keyword "rect", meaning, make
3228 the selection rectangular. Any routine that accepts the "scrollbar" argument
3229 will move the display but not the cursor or selection. Routines that accept
3230 the "nobell" argument will fail silently without beeping, when that argument
3233 **backward_character( ["nobell"] )**
3234 Moves the cursor one character to the left.
3236 **backward_paragraph(["nobell"] )**
3237 Moves the cursor to the beginning of the paragraph, or
3238 if the cursor is already at the beginning of a paragraph, moves the cursor to
3239 the beginning of the previous paragraph. Paragraphs are defined as regions
3240 of text delimited by one or more blank lines.
3242 **backward_word( ["nobell"] )**
3243 Moves the cursor to the beginning of a word, or, if the
3244 cursor is already at the beginning of a word, moves the cursor to the
3245 beginning of the previous word. Word delimiters are user-settable, and
3246 defined by the X resource wordDelimiters.
3248 **beginning_of_file( ["scrollbar"] )**
3249 Moves the cursor to the beginning of the file.
3251 **beginning_of_line( ["absolute"] )**
3252 Moves the cursor to the beginning of the line. If
3253 "absolute" is given, always moves to the absolute beginning of line,
3254 regardless of the text wrapping mode.
3256 **beginning_of_selection()**
3257 Moves the cursor to the beginning of the selection
3258 without disturbing the selection.
3260 **copy_clipboard()**
3261 Copies the current selection to the clipboard.
3264 Copies the primary selection to the cursor.
3267 If a secondary selection exists, copies the secondary selection to
3268 the cursor. If no secondary selection exists, copies the primary selection
3269 to the pointer location.
3271 **copy_to_or_end_drag()**
3272 Completes either a secondary selection operation, or a
3273 primary drag. If the user is dragging the mouse to adjust a secondary
3274 selection, the selection is copied and either inserted at the cursor
3275 location, or, if pending-delete is on and a primary selection exists in the
3276 window, replaces the primary selection. If the user is dragging a block of
3277 text (primary selection), completes the drag operation and leaves the text at
3278 it's current location.
3281 Deletes the text in the primary selection and places it in
3285 Copies the primary selection to the cursor and deletes it at
3286 its original location.
3288 **delete_selection()**
3289 Deletes the contents of the primary selection.
3291 **delete_next_character( ["nobell"] )**
3292 If a primary selection exists, deletes its contents.
3293 Otherwise, deletes the character following the cursor.
3295 **delete_previous_character( ["nobell"] )**
3296 If a primary selection exists, deletes its
3297 contents. Otherwise, deletes the character before the cursor.
3299 **delete_next_word( ["nobell"] )**
3300 If a primary selection exists, deletes its contents.
3301 Otherwise, deletes the word following the cursor.
3303 **delete_previous_word( ["nobell"] )**
3304 If a primary selection exists, deletes its contents.
3305 Otherwise, deletes the word before the cursor.
3307 **delete_to_start_of_line( ["nobell", "wrap"] )**
3308 If a primary selection exists, deletes its contents. Otherwise, deletes the
3309 characters between the cursor and the start of the line. If "wrap" is
3310 given, deletes to the previous wrap point or beginning of line, whichever
3313 **delete_to_end_of_line( ["nobell", "absolute"] )**
3314 If a primary selection exists, deletes its contents.
3315 Otherwise, deletes the characters between the cursor and the end of the line.
3316 If "absolute" is given, always deletes to the absolute end of line, regardless
3317 of the text wrapping mode.
3320 De-selects the primary selection.
3322 **end_of_file( ["scrollbar"] )**
3323 Moves the cursor to the end of the file.
3325 **end_of_line( ["absolute"] )**
3326 Moves the cursor to the end of the line. If
3327 "absolute" is given, always moves to the absolute end of line, regardless
3328 of the text wrapping mode.
3330 **end_of_selection()**
3331 Moves the cursor to the end of the selection without
3332 disturbing the selection.
3334 **exchange( ["nobell"] )**
3335 Exchange the primary and secondary selections.
3338 Attached mouse-movement events to begin a selection between
3339 the cursor and the mouse, or extend the primary selection to the mouse
3343 Completes a primary drag-selection operation.
3346 Begins a selection between the cursor and the mouse. A
3347 drag-selection operation can be started with either extend_start or
3350 **focus_pane( [relative-pane] | [positive-index] | [negative-index] )**
3351 Move the focus to the requested pane.
3352 Arguments can be specified in the form of a relative-pane
3353 ("first", "last", "next", "previous"), a positive-index
3354 (numbers greater than 0, 1 is the same as "first") or a
3355 negative-index (numbers less than 0, -1 is the same as "last").
3357 **forward_character()**
3358 Moves the cursor one character to the right.
3360 **forward_paragraph( ["nobell"] )**
3361 Moves the cursor to the beginning of the next paragraph.
3362 Paragraphs are defined as regions of text delimited by one or more blank
3365 **forward_word( ["tail"] ["nobell"] )**
3366 Moves the cursor to the beginning of the next word. Word
3367 delimiters are user-settable, and defined by the X resource wordDelimiters.
3368 If the "tail" argument is supplied the cursor will be moved to
3369 the end of the current word or the end of the next word, if the
3370 cursor is between words.
3373 Moves the cursor to the mouse pointer location, and prepares for
3374 a possible drag-selection operation (bound to extend_adjust), or multi-click
3375 operation (a further grab_focus action). If a second invocation of grab
3376 focus follows immediately, it selects a whole word, or a third, a whole line.
3378 **insert_string( "string" )**
3379 If pending delete is on and the cursor is inside the
3380 selection, replaces the selection with "string". Otherwise, inserts "string"
3381 at the cursor location.
3383 **key_select( "direction" [,"nobell"] )**
3384 Moves the cursor one character in "direction"
3385 ("left", "right", "up", or "down") and extends the selection. Same as
3386 forward/backward-character("extend"), or process-up/down("extend"), for
3387 compatibility with previous versions.
3389 **move-destination()**
3390 Moves the cursor to the pointer location without
3391 disturbing the selection. (This is an unusual way of working. We left it in
3392 for compatibility with previous versions, but if you actually use this
3393 capability, please send us some mail, otherwise it is likely to disappear in
3397 If a secondary selection exists, deletes the contents of the
3398 secondary selection and inserts it at the cursor, or if pending-delete is on
3399 and there is a primary selection, replaces the primary selection. If no
3400 secondary selection exists, moves the primary selection to the pointer
3401 location, deleting it from its original position.
3403 **move_to_or_end_drag()**
3404 Completes either a secondary selection operation, or a
3405 primary drag. If the user is dragging the mouse to adjust a secondary
3406 selection, the selection is deleted and either inserted at the cursor
3407 location, or, if pending-delete is on and a primary selection exists in the
3408 window, replaces the primary selection. If the user is dragging a block of
3409 text (primary selection), completes the drag operation and deletes the text
3410 from it's current location.
3413 Inserts a newline character. If Auto Indent is on, lines up the
3414 indentation of the cursor with the current line.
3416 **newline_and_indent()**
3417 Inserts a newline character and lines up the indentation
3418 of the cursor with the current line, regardless of the setting of Auto
3421 **newline_no_indent()**
3422 Inserts a newline character, without automatic
3423 indentation, regardless of the setting of Auto Indent.
3425 **next_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3426 Moves the cursor and scroll forward one page.
3427 The parameter "stutter" moves the cursor to the bottom of the display,
3428 unless it is already there, otherwise it will page down.
3429 The parameter "column" will maintain the preferred column while
3432 **page_left( ["scrollbar"] ["nobell"] )**
3433 Move the cursor and scroll left one page.
3435 **page_right( ["scrollbar"] ["nobell"] )**
3436 Move the cursor and scroll right one page.
3438 **paste_clipboard()**
3439 Insert the contents of the clipboard at the cursor, or if
3440 pending delete is on, replace the primary selection with the contents of the
3443 **previous_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3444 Moves the cursor and scroll backward one page.
3445 The parameter "stutter" moves the cursor to the top of the display,
3446 unless it is already there, otherwise it will page up.
3447 The parameter "column" will maintain the preferred column while
3451 Same as secondary_or_drag_start for compatibility with previous versions.
3453 **process_cancel()**
3454 Cancels the current extend_adjust, secondary_adjust, or
3455 secondary_or_drag_adjust in progress.
3457 **process_down( ["nobell", "absolute"] )**
3458 Moves the cursor down one line. If "absolute" is given, always moves to the
3459 next line in the text buffer, regardless of wrapping.
3461 **process_return()**
3462 Same as newline for compatibility with previous versions.
3464 **process_shift_down( ["nobell", "absolute"] )**
3465 Same as process_down("extend") for compatibility with previous versions.
3467 **process_shift_up( ["nobell", "absolute"] )**
3468 Same as process_up("extend") for compatibility with previous versions.
3471 If tab emulation is turned on, inserts an emulated tab,
3472 otherwise inserts a tab character.
3474 **process_up( ["nobell", "absolute"] )**
3475 Moves the cursor up one line. If "absolute" is given, always moves to the
3476 previous line in the text buffer, regardless of wrapping.
3478 **raise_window([relative-window] | [positive-index] | [negative-index])**
3479 Raise the current focused window to the front if no argument is supplied.
3480 Arguments can be specified in the form of a relative-window
3481 ("first", "last", "next", "previous"), a positive-index
3482 (numbers greater than 0, 1 is the same as "last") or a
3483 negative-index (numbers less than 0, -1 is the same as "first").
3485 **scroll_down( nUnits, ["lines" | "pages"] )**
3486 Scroll the display down (towards the end of the file) by a given
3487 number of units, units being lines or pages. Default units are lines.
3489 **scroll_left( nPixels )**
3490 Scroll the display left by nPixels.
3492 **scroll_right( nPixels )**
3493 Scroll the display right by nPixels.
3495 **scroll_up( nUnits, ["lines" | "pages"] )**
3496 Scroll the display up (towards the beginning of the file) by a given
3497 number of units, units being lines or pages. Default units are lines.
3499 **scroll_to_line( lineNum )**
3500 Scroll to position line number lineNum at the top of
3501 the pane. The first line of a file is line 1.
3503 **secondary_adjust()**
3504 Attached mouse-movement events to extend the secondary
3505 selection to the mouse position.
3507 **secondary_or_drag_adjust()**
3508 Attached mouse-movement events to extend the
3509 secondary selection, or reposition the primary text being dragged. Takes two
3510 optional arguments, "copy", and "overlay". "copy" leaves a copy of the
3511 dragged text at the site at which the drag began. "overlay" does the drag in
3512 overlay mode, meaning the dragged text is laid on top of the existing text,
3513 obscuring and ultimately deleting it when the drag is complete.
3515 **secondary_or_drag_start()**
3516 To be attached to a mouse down event. Begins drag
3517 selecting a secondary selection, or dragging the contents of the primary
3518 selection, depending on whether the mouse is pressed inside of an existing
3521 **secondary_start()**
3522 To be attached to a mouse down event. Begin drag selecting
3523 a secondary selection.
3526 Select the entire file.
3529 To be attached to a key-press event, inserts the character
3530 equivalent of the key pressed.
3532 ----------------------------------------------------------------------
3540 NEdit can be customized many different ways. The most important
3541 user-settable options are presented in the Preferences menu, including all
3542 options that users might need to change during an editing session. Options
3543 set in the Default Settings sub-menu of the Preferences menu can be preserved
3544 between sessions by selecting Save Defaults, which writes the changes to the
3545 preferences file. See the section titled "Preferences_" for more details.
3547 User defined commands can be added to NEdit's Shell, Macro, and window
3548 background menus. Dialogs for creating items in these menus can be found
3549 under Customize Menus in the Default Settings sub menu of the Preferences
3552 For users who depend on NEdit every day and want to tune every excruciating
3553 detail, there are also X resources for tuning a vast number of such details,
3554 down to the color of each individual button. See the section "X_Resources_"
3555 for more information, as well as a list of selected resources.
3557 The most common reason customizing your X resources for NEdit, however, is
3558 key binding. While limited key binding can be done through Preferences
3559 settings (Preferences -> Default Settings -> Customize Menus), you can really
3560 only add keys this way, and each key must have a corresponding menu item.
3561 Any significant changes to key binding should be made via the Translations
3562 resource and menu accelerator resources. The sections titled "Key_Binding_"
3563 and "X_Resources_" have more information.
3564 ----------------------------------------------------------------------
3569 The Preferences menu allows you to set options for both the current editing
3570 window, and default values for newly created windows and future NEdit
3571 sessions. Options in the Preferences menu itself (not in the Default
3572 Settings sub-menu) take effect immediately and refer to the current window
3573 only. Options in the Default Settings sub-menu provide initial settings for
3574 future windows created using the New or Open commands; options affecting all
3575 windows are also set here.
3576 Preferences set in the Default Settings sub-menu can be saved in a file that
3577 is automatically read by NEdit at startup time, by selecting Save Defaults.
3581 **Default Settings**
3582 Menu of initial settings for future windows. Generally the same as the
3583 options in the main part of the menu, but apply as defaults for future
3584 windows created during this NEdit session. These settings can be saved using
3585 the Save Defaults command below, to be loaded automatically each time NEdit
3589 Save the default options as set under Default Settings for future NEdit
3593 Show the full file name, line number, and length of the file being edited.
3595 **Incremental Search Line**
3596 Keep the incremental search bar (Search -> Find Incremental) permanently
3597 displayed at the top of the window.
3599 **Show Line Numbers**
3600 Display line numbers to the right of the text.
3603 Tells NEdit what language (if any) to assume, for selecting language-specific
3604 features such as highlight patterns and smart indent macros, and setting
3605 language specific preferences like word delimiters, tab emulation, and
3606 auto-indent. See Features for Programming -> Programming_with_NEdit_ for
3610 Setting Auto Indent "on" maintains a running indent (pressing the Return key
3611 will line up the cursor with the indent level of the previous line). If
3612 smart indent macros are available for the current language mode, smart indent
3613 can be selected and NEdit will attempt to guess proper language indentation
3614 for each new line. See Help -> Features for Programming -> Automatic Indent
3615 for more information.
3618 Choose between two styles of automatic wrapping or none. Auto Newline wrap,
3619 wraps text at word boundaries when the cursor reaches the right margin, by
3620 replacing the space or tab at the last word boundary with a newline
3621 character. Continuous Wrap wraps long lines which extend past the right
3622 margin. Continuous Wrap mode is typically used to produce files where
3623 newlines are omitted within paragraphs, to make text filling automatic (a
3624 kind of poor-man's word processor). Text of this style is common on Macs and
3625 PCs but is not necessarily supported very well under Unix (except in programs
3626 which deal with e-mail, for which it is often the format of choice).
3629 Set margin for Auto Newline Wrap, Continuous Wrap, and Fill Paragraph. Lines
3630 may, be wrapped at the right margin of the window, or the margin can be set
3631 at a specific column.
3634 Set the tab distance (number of characters between tab stops) for tab
3635 characters, and control tab emulation and use of tab characters in padding
3639 Change the font(s) used to display text (fonts for menus and dialogs must be
3640 set using X resources for the text area of the window). See below for more
3643 **Highlight Syntax**
3644 If NEdit recognizes the language being edited, and highlighting patterns are
3645 available for that language, use fonts and colors to enhance viewing of the
3646 file. (See Help -> Features for Programming -> Syntax Highlighting for more
3649 **Make Backup Copy**
3650 On Save, write a backup copy of the file as it existed before the Save
3651 command with the extension .bck (Unix only).
3653 **Incremental Backup**
3654 Periodically make a backup copy of the file being edited under the name
3655 `~filename` on Unix or `_filename` on VMS (see Crash_Recovery_).
3657 **Show Matching (..)**
3658 Momentarily highlight matching parenthesis, brackets, and braces, or the
3659 range between them, when one of these characters is typed, or when the
3660 insertion cursor is positioned after it. Delimiter only highlights the
3661 matching delimiter, while Range highlights the whole range of text between
3662 the matching delimiters.
3664 Optionally, the matching can make use of syntax information if syntax
3665 highlighting is enabled. Alternatively, the matching is purely character
3666 based. In general, syntax based matching results in fewer false matches.
3669 In overtype mode, new characters entered replace the characters in front of
3670 the insertion cursor, rather than being inserted before them.
3673 Lock the file against accidental modification. This temporarily prevents the
3674 file from being modified in this NEdit session. Note that this is different
3675 from setting the file protection.
3677 3>Preferences -> Default Settings Menu
3679 Options in the Preferences -> Default Settings menu have the same meaning as
3680 those in the top-level Preferences menu, except that they apply to future
3681 NEdit windows and future NEdit sessions if saved with the Save Defaults
3682 command. Additional options which appear in this menu are:
3685 Define language recognition information (for determining language mode from
3686 file name or content) and set language specific preferences.
3689 How to react to multiple tags for the same name. Tags are described in the
3690 section: Features for Programmers -> Finding Declarations (ctags). In Show
3691 All mode, all matching tags are displayed in a dialog. In Smart mode, if one
3692 of the matching tags is in the current window, that tag is chosen, without
3693 displaying the dialog.
3696 Change the colors used to display text. The "Matching (..)" fields change the
3697 colors that matching parens, brackets and braces are flashed when the "Show
3698 Matching (..)" option is enabled. Note that the foreground colors for plain
3699 text, selected text, and matching paren flashing only apply when syntax
3700 highlighting is disabled. When syntax highlighting is enabled, text (even
3701 text that appears plain) will always be colored according to its highlighting
3702 style. (For information on changing syntax highlighting styles and matching
3703 patterns use see Help -> Features for Programming -> Syntax_Highlighting_.)
3706 Add/remove items from the Shell, Macro, and window background menus (see
3709 **Customize Window Title**
3710 Opens a dialog where the information to be displayed in the window's title
3711 field can be defined and tested. The dialog contains a Help button, providing
3712 further information about the options available.
3715 Options for controlling the behavior of Find and Replace commands:
3718 Presents search results in dialog form, asks before wrapping a
3719 search back around the beginning (or end) of the file
3720 (unless Beep On Search Wrap is turned on).
3723 Search and Replace operations wrap around the beginning (or end) of the file.
3725 ~Beep On Search Wrap~ -
3726 Beep when Search and Replace operations wrap around the beginning (or end) of
3727 the file (only if Wrap Around is turned on).
3730 Don't pop down Replace and Find boxes after searching.
3732 ~Default Search Style~ -
3733 Initial setting for search type in Find and Replace dialogs.
3735 ~Default Replace Scope~ -
3736 [THIS OPTION IS ONLY PRESENT WHEN NEDIT WAS COMPILED WITH THE
3737 -DREPLACE_SCOPE FLAG TO SELECT AN ALTERNATIVE REPLACE DIALOG LAYOUT.]
3739 Initial setting for the scope in the Replace/Find dialog, when a selection
3740 exists. It can be either "In Window", "In Selection", or "Smart". "Smart"
3741 results in "In Window" if the size of the selection is smaller than 1 line,
3742 and to "In Selection" otherwise.
3744 **Syntax Highlighting**
3745 Program and configure enhanced text display for new or supported languages
3746 (See Features for Programming -> Syntax_Highlighting_).
3749 Options for controlling the tabbed interface:
3751 ~Open File in New Tab~ -
3752 Open files in new tabs, else open files in new windows.
3755 Show/Hide the tab bar.
3757 ~Hide Tab Bar when only one Document is open~
3759 ~Next/Prev Tabs Across Windows~ -
3760 Suppose there are two windows with three tabs in the first window and two tabs in
3761 the second window. Enabling this option, if you are on the third tab in the
3762 first window, hitting Ctrl+PageDown would switch to the first tab in the second
3763 window (instead of switching to the first tab in the first window).
3765 ~Sort Tabs Alphabetically~
3768 Show file name and path in a tooltip when moving the mouse pointer over a tab
3769 (See Basic Operations -> Tabbed_Editing_).
3771 **Terminate with Line Break on Save**
3772 Some UNIX tools expect that files end with a line feed. If this option is
3773 activated, NEdit will append one if required.
3775 **Sort Open Prev. Menu**
3776 Option to order the File -> Open Previous menu alphabetically, versus in
3777 order of last access.
3779 **Popups Under Pointer**
3780 Display pop-up dialogs centered on the current mouse position, as opposed to
3781 centered on the parent window. This generally speeds interaction, and is
3782 essential for users who set their window managers so keyboard focus
3785 **Auto-Scroll Near Window Top/Bottom**
3786 When this option is enabled the window will automatically scroll when the
3787 cursor comes 4 lines from the top or bottom of the window (except at the
3788 beginning of the file). The number of lines can be customized with the
3789 nedit.autoScrollVPadding resource.
3792 Options for controlling the popping up of warning dialogs:
3794 ~File Modified Externally~ -
3795 Pop up a warning dialog when files get changed external to NEdit.
3797 ~Check Modified File Contents~ -
3798 If external file modification warnings are requested, also check the file
3799 contents iso. only the modification date.
3802 Ask before exiting when two or more files are open in an NEdit session.
3804 **Initial Window Size**
3805 Default size for new windows.
3809 The font used to display text in NEdit is set under Preferences -> Text Font
3810 (for the current window), or Preferences -> Default Settings Text Font (for
3811 future windows). These dialogs also allow you to set fonts for syntax
3812 highlighting. If you don't intend to use syntax highlighting, you can ignore
3813 most of the dialog, and just set the field labeled Primary Font.
3815 Unless you are absolutely certain about the types of files that you will be
3816 editing with NEdit, you should choose a fixed-spacing font. Many, if not
3817 most, plain-text files are written expecting to be viewed with fixed
3818 character spacing, and will look wrong with proportional spacing. NEdit's
3819 filling, wrapping, and rectangular operations will also work strangely if you
3820 choose a proportional font.
3822 Note that in the font browser (the dialog brought up by the Browse...
3823 button), the subset of fonts which are shown is narrowed depending on the
3824 characteristics already selected. It is therefore important to know that you
3825 can unselect characteristics from the lists by clicking on the selected items
3828 Fonts for syntax highlighting should ideally match the primary font in both
3829 height and spacing. A mismatch in spacing will result in similar distortions
3830 as choosing a proportional font: column alignment will sometimes look wrong,
3831 and rectangular operations, wrapping, and filling will behave strangely. A
3832 mismatch in height will cause windows to re-size themselves slightly when
3833 syntax highlighting is turned on or off, and increase the inter- line spacing
3834 of the text. Unfortunately, on some systems it is hard to find sets of fonts
3835 which match exactly in height.
3839 You can add or change items in the Shell, Macro, and window background menus
3840 under Preferences -> Default Settings -> Customize Menus. When you choose
3841 one of these, you will see a dialog with a list of the current
3842 user-configurable items from the menu on the left. To change an existing
3843 item, select it from the list, and its properties will appear in the
3844 remaining fields of the dialog, where you may change them. Selecting the
3845 item "New" from the list allows you to enter new items in the menu.
3847 Hopefully most of the characteristics are self explanatory, but here are a
3850 Accelerator keys are keyboard shortcuts which appear on the right hand side
3851 of the menus, and allow you avoid pulling down the menu and activate the
3852 command with a single keystroke. Enter accelerators by typing the keys
3853 exactly as you would to activate the command.
3855 Mnemonics are a single letter which should be part of the menu item name,
3856 which allow users to traverse and activate menu items by typing keys when the
3857 menu is pulled down.
3859 In the Shell Command field of the Shell Commands dialog, the % character
3860 expands to the name (including directory path) of the file in the window. To
3861 include a % character in the command, use %%.
3863 The Menu Entry field can contain special characters for constructing
3864 hierarchical sub-menus, and for making items which appear only in certain
3865 language modes. The right angle bracket character ">" creates a sub-menu.
3866 The name of the item itself should be the last element of the path formed
3867 from successive sub-menu names joined with ">". Menu panes are called in to
3868 existence simply by naming them as part of a Menu Entry name. To put several
3869 items in the same sub-menu, repeat the same hierarchical sequence for each.
3870 For example, in the Macro Commands dialog, two items with menu entries: a>b>c
3871 and a>b>d would create a single sub menu under the macro menu called "a",
3872 which would contain a single sub-menu, b, holding the actual items, c and d:
3879 To qualify a menu entry with a language mode, simply add an at-sign "@@" at
3880 the end of the menu command, followed (no space) by a language mode name. To
3881 make a menu item which appears in several language modes, append additional
3882 @@s and language mode names. For example, an item with the menu entry:
3884 Make C Prototypes@@C@@C++
3886 would appear only in C and C++ language modes, and:
3888 Make Class Template@@C++
3890 would appear only in C++ mode.
3892 Menu items with no qualification appear in all language modes.
3894 If a menu item is followed by the single language qualification "@@*", that
3895 item will appear only if there are no applicable language-specific items of
3896 the same name in the same submenu. For example, if you have the following
3897 three entries in the same menu:
3899 Make Prototypes@@C@@C++
3900 Make Prototypes@@Java
3903 The first will be available when the language mode is C or C++, the second
3904 when the language mode is Java, and for all other language modes (including
3905 the "Plain" non-language mode). If the entry:
3909 also exists, this will always appear, meaning that the menu will always have
3910 two "Make Prototypes" entries, whatever the language mode.
3912 3>The NEdit Preferences File
3914 The NEdit saved preferences file is an X resource file, and its contents can
3915 be moved into another X resource file (see X_Resources_). One reason for
3916 doing so would be to attach server specific preferences, such as a default
3917 font to a particular X server. Another reason for moving preferences into the
3918 X resource file would be to keep preferences menu options and resource
3919 settable options together in one place.
3920 Though the files are the same format, additional resources should not be added
3921 to the preference file since NEdit modifies this file by overwriting it
3922 completely. Note also that the contents of the preference file take
3923 precedence over the values of X resources.
3924 Using Save Defaults after moving the contents of your preference file to your
3925 .Xdefaults file will re-create the preference file, interfering with the
3926 options that you have moved.
3927 The location of NEdit's preferences file depends on your environment:
3929 * The default place for the file is '$HOME/.nedit/nedit.rc',
3930 * if the variable $NEDIT_HOME is set in your environment it is located at '$NEDIT_HOME/nedit.rc',
3931 * you may also use old-style run control files; in this case, the preferences are stored in $HOME/.nedit.
3933 (For VMS, the file is in '$NEDIT_HOME/nedit.rc' if $NEDIT_HOME is set, in
3934 'SYS$LOGIN:.nedit' otherwise.)
3936 3>Sharing Customizations with Other NEdit Users
3938 If you have written macro or shell menu commands, highlight patterns, or
3939 smart-indent macros that you want to share with other NEdit users, you can
3940 make a file which they can load into their NEdit environment.
3942 To load such a file, start NEdit with the command:
3944 nedit -import <file>
3946 In the new NEdit session, verify that the imported patterns or macros do what
3947 you want, then select Preferences -> Save Defaults. Saving incorporates the
3948 changes into the nedit preferences file, so the next time you run NEdit, you
3949 will not have to import the distribution file.
3951 Loading a customization file is automated, but creating one is not. To
3952 produce a file to be imported by other users, you must make a copy of your own
3953 NEdit configuration file, and edit it, by hand, to remove everything but the
3954 few items of interest to the recipient. Leave only the individual
3955 resource(s), and within those resources, only the particular macro, pattern,
3956 style, etc, that you wish to exchange.
3958 For example, to share a highlighting pattern set, you would include the
3959 patterns, any new styles you added, and language mode information only if the
3960 patterns are intended to support a new language rather than updating an
3961 existing one. For example:
3963 nedit.highlightPatterns:\
3965 Comment:"#":"$"::Comment::\n\
3966 Loop Header:"^[ \\t]*loop:":::Loop::\n\
3968 nedit.languageModes: My Language:.my::::::
3969 nedit.styles: Loop:blue:Bold
3971 Resources are in the format of X resource files, but the format of text
3972 within multiple-item resources like highlight patterns, language modes,
3973 macros, styles, etc., are private to NEdit. Each resource is a string which
3974 ends at the first newline character not escaped with \, so you must be
3975 careful about how you treat ends of lines. While you can generally just cut
3976 and paste indented sections, if something which was originally in the middle
3977 of a resource string is now at the end, you must remove the \ line
3978 continuation character(s) so it will not join the next line into the
3979 resource. Conversely, if something which was originally at the end of a
3980 resource is now in the middle, you'll have to add continuation character(s)
3981 to make sure that the resource string is properly continued from beginning to
3982 end, and possibly newline character(s) (\n) to make sure that it is properly
3983 separated from the next item.
3984 ----------------------------------------------------------------------
3989 NEdit has additional options to those provided in the Preferences menu which
3990 are set using X resources. Like most other X programs, NEdit can be
3991 customized to vastly unnecessary proportions, from initial window positions
3992 down to the font and shadow colors of each individual button (A complete
3993 discussion of how to do this is left to books on the X Window System). Key
3994 binding (see "Key_Binding_" is one of the most useful of these resource
3997 X resources are usually specified in a file called .Xdefaults or .Xresources
3998 in your home directory (on VMS this is sys$login:decw$xdefaults.dat). On
3999 some systems, this file is read and its information attached to the X server
4000 (your screen) when you start X. On other systems, the .Xdefaults file is
4001 read each time you run an X program. When X resource values are attached to
4002 the X server, changes to the resource file are not available to application
4003 programs until you either run the xrdb program with the appropriate file as
4004 input, or re-start the X server.
4006 3>Selected X Resource Names
4008 The following are selected NEdit resource names and default values for NEdit
4009 options not settable via the Preferences menu (for preference resource names,
4010 see your NEdit preference file):
4012 **nedit.tagFile**: (not defined)
4014 This can be the name of a file, or multiple files separated by a colon (:)
4015 character, of the type produced by Exuberant Ctags or the Unix ctags
4016 command, which NEdit will load at startup time (see ctag_support_ ). The tag
4017 file provides a database from which NEdit can automatically open files
4018 containing the definition of a particular subroutine or data type.
4020 **nedit.alwaysCheckRelativeTagsSpecs: True**
4022 When this resource is set to True, and there are tag files specified (with
4023 the nedit.tagFile resource, see above) as relative paths, NEdit will evaluate
4024 these tag value paths whenever a file is opened. All accessible tag files
4025 will be loaded at this time. When this resource value is False, relative path
4026 tag specifications will only be evaluated at NEdit startup time.
4028 **nedit.shell**: /bin/csh
4030 (Unix systems only) The Unix shell (command interpreter) to use for executing
4031 commands from the Shell menu
4033 **nedit.wordDelimiters**: .,/\\`'!@@#%^&*()-=+{}[]":;<>?
4035 The characters, in addition to blanks and tabs, which mark the boundaries
4036 between words for the move-by-word (Ctrl+Arrow) and select-word (double
4037 click) commands. Note that this default value may be overridden by the
4038 setting in Preferences -> Default Settings -> Language Modes....
4040 **nedit.remapDeleteKey**: False
4042 Setting this resource to True forcibly maps the delete key to backspace. This
4043 can be helpful on systems where the bindings have become tangled, and in
4044 environments which mix systems with PC style keyboards and systems with DEC
4045 and Macintosh keyboards. Theoretically, these bindings should be made using
4046 the standard X/Motif mechanisms, outside of NEdit. In practice, some
4047 environments where users access several different systems remotely, can be
4048 very hard to configure. If you've given up and are using a backspace key
4049 halfway off the keyboard because you can't figure out the bindings, set this
4052 **nedit.typingHidesPointer**: False
4054 Setting this resource to True causes the mouse pointer to be hidden when you
4055 type in the text area. As soon as the mouse pointer is moved, it will
4056 reappear. This is useful to stop the mouse pointer from obscuring text.
4058 **nedit.overrideDefaultVirtualKeyBindings**: Auto
4060 Motif uses a virtual key binding mechanism that shares the bindings between
4061 different Motif applications. When a first Motif application is started, it
4062 installs some default virtual key bindings and any other Motif application
4063 that runs afterwards, simply reuses them. Obviously, if the first
4064 application installs an invalid set, all others applications may have
4067 In the past, NEdit has been the victim of invalid bindings installed by other
4068 applications several times. Through this resource, NEdit can be instructed
4069 to ignore the bindings installed by other applications, and use its own
4070 private bindings. By default, NEdit tries to detect invalid bindings
4071 and ignore them automatically (Auto). Optionally, NEdit can be told to
4072 always keep the installed bindings (Never), or to always override them
4075 **nedit.stdOpenDialog**: False
4077 Setting this resource to True restores the standard Motif style of Open
4078 dialog. NEdit file open dialogs are missing a text field at the bottom of
4079 the dialog, where the file name can be entered as a string. The field is
4080 removed in NEdit to encourage users to type file names in the list, a
4081 non-standard, but much faster method for finding files.
4083 **nedit.bgMenuButton**: @~Shift@~Ctrl@~Meta@~Alt<Btn3Down>
4085 Specification for mouse button / key combination to post the background menu
4086 (in the form of an X translation table event specification). The event
4087 specification should be as specific as possible, since it will override less
4088 specific translation table entries.
4090 **nedit.maxPrevOpenFiles**: 30
4092 Number of files listed in the Open Previous sub-menu of the File menu.
4093 Setting this to zero disables the Open Previous menu item and maintenance of
4094 the NEdit file history file.
4096 **nedit.printCommand**: (system specific)
4098 Command used by the print dialog to print a file, such as, lp, lpr, etc..
4099 The command must be capable of accepting input via stdin (standard input).
4101 **nedit.printCopiesOption**: (system specific)
4103 Option name used to specify multiple copies to the print command. If the
4104 option should be separated from its argument by a space, leave a trailing
4105 space. If blank, no "Number of Copies" item will appear in the print dialog.
4107 **nedit.printQueueOption**: (system specific)
4109 Option name used to specify a print queue to the print command. If the
4110 option should be separated from its argument by a space, leave a trailing
4111 space. If blank, no "Queue" item will appear in the print dialog.
4113 **nedit.printNameOption**: (system specific)
4115 Option name used to specify a job name to the print command. If the option
4116 should be separated from its argument by a space, leave a trailing space. If
4117 blank, no job or file name will be attached to the print job or banner page.
4119 **nedit.printHostOption**: (system specific)
4121 Option name used to specify a host name to the print command. If the option
4122 should be separated from its argument by a space, leave a trailing space. If
4123 blank, no "Host" item will appear in the print dialog.
4125 **nedit.printDefaultQueue**: (system specific)
4127 The name of the default print queue. Used only to display in the print
4128 dialog, and has no effect on printing.
4130 **nedit.printDefaultHost**: (system specific)
4132 The node name of the default print host. Used only to display in the print
4133 dialog, and has no effect on printing.
4135 **nedit.visualID**: Best
4137 If your screen supports multiple visuals (color mapping models), this
4138 resource allows you to manually choose among them. The default value of
4139 "Best" chooses the deepest (most colors) visual available. Since NEdit does
4140 not depend on the specific characteristics of any given color model, Best
4141 probably IS the best choice for everyone, and the only reason for setting
4142 this resource would be to patch around some kind of X server problem. The
4143 resource may also be set to "Default", which chooses the screen's default
4144 visual (often a color-mapped, PseudoColor, visual for compatibility with
4145 older X applications). It may also be set to a numeric visual-id value (use
4146 xdpyinfo to see the list of visuals supported by your display), or a visual
4147 class name: PseudoColor, DirectColor, TrueColor, etc..
4149 If you are running under a themed environment (like KDE or CDE) that places
4150 its colors in a shallow visual, and you'd rather have that color scheme
4151 instead of more colors available, then you may need set the visual to
4152 "Default" so that NEdit doesn't choose one with more colors. (The reason
4153 for this is: if the "best" visual is not the server's default, then NEdit
4154 cannot use the colors provided by your environment. NEdit will fall back to
4155 its own default color scheme.)
4157 **nedit.installColormap**: False
4159 Force the installation of a private colormap. If you have a humble 8-bit
4160 color display, and netscape is hogging all of the color cells, you may want
4161 to try turning this on. On most systems, this will result in colors flashing
4162 wildly when you switch between NEdit and other applications. But a few
4163 systems (SGI) have hardware support for multiple simultaneous colormaps, and
4164 applications with installed colormaps are well behaved.
4166 **nedit.findReplaceUsesSelection**: False
4168 Controls if the Find and Replace dialogs are automatically loaded with the
4169 contents of the primary selection.
4171 **nedit.stickyCaseSenseButton**: True
4173 Controls if the "Case Sensitive" buttons in the Find and Replace dialogs and
4174 the incremental search bar maintain a separate state for literal and regular
4175 expression searches. Moreover, when set to True, by default literal searches
4176 are case insensitive and regular expression searches are case sensitive. When
4177 set to False, the "Case Sensitive" buttons are independent of the "Regular
4180 **nedit.multiClickTime**: (system specific)
4182 Maximum time in milliseconds allowed between mouse clicks within double and
4183 triple click actions.
4185 **nedit.undoModifiesSelection**: True
4187 By default, NEdit selects any text inserted or changed through a undo/redo
4188 action. Set this resource to False if you don't want your selection to be
4191 **nedit@*scrollBarPlacement**: BOTTOM_RIGHT
4193 How scroll bars are placed in NEdit windows, as well as various lists and
4194 text fields in the program. Other choices are: BOTTOM_LEFT, TOP_LEFT, or
4197 **nedit@*text.autoWrapPastedText**: False
4199 When Auto Newline Wrap is turned on, apply automatic wrapping (which
4200 normally only applies to typed text) to pasted text as well.
4202 **nedit@*text.heavyCursor**: False
4204 For monitors with poor resolution or users who have difficulty seeing the
4205 cursor, makes the cursor in the text editing area of the window heavier and
4208 **nedit.autoScrollVPadding**: 4
4210 Number of lines to keep the cursor away from the top or bottom line of the
4211 window when the "Auto-Scroll Near Window Top/Bottom" feature is enabled.
4212 Keyboard operations that would cause the cursor to get closer than
4213 this distance cause the window to scroll up or down instead, except at the
4214 beginning of the file. Mouse operations are not affected.
4216 **nedit@*text.blinkRate**: 500
4218 Blink rate of the text insertion cursor in milliseconds. Set to zero to stop
4221 **nedit@*text.Translations**:
4223 Modifies key bindings (see "Key_Binding_").
4225 **nedit@*foreground**: black
4227 Default foreground color for menus, dialogs, scroll bars, etc..
4229 **nedit@*background**: #b3b3b3
4231 Default background color for menus, dialogs, scroll bars, etc..
4233 **nedit@*calltipForeground**: black
4235 Foreground color for calltips
4237 **nedit@*calltipBackground**: LemonChiffon1
4239 Background color for calltips
4241 **nedit@*XmLFolder.inactiveForeground**: #666
4243 Foreground color for inactive tabs.
4245 **nedit@*fontList**: helvetica medium 12 points
4247 Default font for menus, dialogs, scroll bars, etc..
4249 **nedit.helpFont**: helvetica medium 12 points
4251 Font used for displaying online help.
4253 **nedit.boldHelpFont**: helvetica bold 12 points
4255 Bold font for online help.
4257 **nedit.italicHelpFont**: helvetica italic 12 points
4259 Italic font for online help.
4261 **nedit.fixedHelpFont**: courier medium 12 points
4263 Fixed font for online help.
4265 **nedit.boldFixedHelpFont**: courier bold 12 points
4267 Fixed bold for online help.
4269 **nedit.italicFixedHelpFont**: courier italic 12 points
4271 Fixed italic font for online help.
4273 **nedit.h1HelpFont**: helvetica bold 14 points
4275 Font for level-1 titles in help text.
4277 **nedit.h2HelpFont**: helvetica bold italic 12 points
4279 Font for level-2 titles in help text.
4281 **nedit.h3HelpFont**: courier bold 12 points
4283 Font for level-3 titles in help text.
4285 **nedit.helpLinkFont**: helvetica medium 12 points
4287 Font for hyperlinks in the help text
4289 **nedit.helpLinkColor**: #009900
4291 Color for hyperlinks in the help text
4293 **nedit.backlightCharTypes**: 0-8,10-31,127:red;9:#dedede;32,160-255:#f0f0f0;128-159:orange
4295 **NOTE: backlighting is ~experimental~** (see "Programming_with_NEdit_").
4297 A string specifying character classes as ranges of ASCII values followed by
4298 the color to be used as their background colors. The format is:
4300 low[-high]{,low[-high]}:color{;low-high{,low[-high]}:color}
4302 where low and high are ASCII values.
4305 32-255:#f0f0f0;1-31,127:red;128-159:orange;9-13:#e5e5e5
4308 .. The macro built-in function set_backlight_string() allows these strings to be
4309 .. set for a particular window.
4311 **nc.autoStart**: True
4313 Whether the nc program should automatically start an NEdit server (without
4314 prompting the user) if an appropriate server is not found.
4316 **nc.serverCommand**: nedit -server
4318 Command used by the nc program to start an NEdit server.
4322 Basic time-out period used in communication with an NEdit server (seconds).
4324 ----------------------------------------------------------------------
4325 ~The following are Selected widget names (to which you may append~
4326 ~.background, .foreground, .fontList, etc., to change colors, fonts~
4327 ~ and other characteristics):~
4329 **nedit@*statsAreaForm**
4331 Statistics line and incremental search bar. To get consistent results across
4332 the entire stats line and the incremental search bar, use '*' rather than '.'
4333 to separate the resource name. For example, to set the foreground color of
4334 both components use:
4335 nedit*statsAreaForm*foreground
4337 nedit*statsAreaForm.foreground
4341 Top-of-window menu-bar.
4343 **nedit@*textHorScrollBar**
4345 Horizontal scroll bar.
4347 **nedit@*textVertScrollBar**
4349 Vertical scroll bar.
4350 ----------------------------------------------------------------------
4355 There are several ways to change key bindings in NEdit. The easiest way to
4356 add a new key binding in NEdit is to define a macro in Preferences -> Default
4357 Settings -> Customize Menus -> Macro Menu. However, if you want to change
4358 existing bindings or add a significant number of new key bindings you will
4359 need to do so via X resources.
4361 Before reading this section, you must understand how to set X resources (see
4362 the help section "X_Resources_"). Since setting X resources is tricky, it is
4363 also helpful when working on key-binding, to set some easier-to-verify
4364 resource at the same time, as a simple check that the NEdit program is
4365 actually seeing your changes. The appres program is also very helpful in
4366 checking that the resource settings that you make, actually reach the program
4367 for which they are intended in the correct form.
4369 3>Key Binding in General
4371 Keyboard commands are associated with editor action routines through two
4372 separate mechanisms in NEdit. Commands which appear in pull-down menus have
4373 individual resources designating a keyboard equivalent to the menu command,
4374 called an accelerator key. Commands which do not have an associated menu
4375 item are bound to keys via the X toolkit translation mechanism. The methods
4376 for changing these two kinds of bindings are quite different.
4378 3>Key Binding Via Translations
4380 The most general way to bind actions to keys in NEdit is to use the
4381 translation table associated with the text widget. To add a binding to Alt+Y
4382 to insert the string "Hi!", for example, add lines similar to the following
4383 to your X resource file:
4385 NEdit*text.Translations: #override \n\
4386 Alt<Key>y: insert_string("Hi!") \n
4388 The Help topic "Action_Routines_" lists the actions available to be bound.
4390 Translation tables map key and mouse presses, window operations, and other
4391 kinds of events, to actions. The syntax for translation tables is
4392 simplified here, so you may need to refer to a book on the X window system
4393 for more detailed information.
4395 Note that accelerator resources (discussed below) override translations, and
4396 that most Ctrl+letter and Alt+letter combinations are already bound to an
4397 accelerator key. To use one of these combinations from a translation table,
4398 therefore, you must first un-bind the original menu accelerator.
4400 A resource for changing a translation table consists of a keyword; #override,
4401 #augment, or #replace; followed by lines (separated by newline characters)
4402 pairing events with actions. Events begin with modifiers, like Ctrl, Shift,
4403 or Alt, followed by the event type in <>. BtnDown, Btn1Down, Btn2Down,
4404 Btn1Up, Key, KeyUp are valid event types. For key presses, the event type is
4405 followed by the name of the key. You can specify a combination of events,
4406 such as a sequence of key presses, by separating them with commas. The other
4407 half of the event/action pair is a set of actions. These are separated from
4408 the event specification by a colon and from each other by spaces. Actions
4409 are names followed by parentheses, optionally containing one or more
4410 parameters separated by comas.
4412 3>Changing Menu Accelerator Keys
4414 The menu shortcut keys shown at the right of NEdit menu items can also be
4415 changed via X resources. Each menu item has two resources associated with
4416 it, accelerator, the event to trigger the menu item; and acceleratorText, the
4417 string shown in the menu. The form of the accelerator resource is the same
4418 as events for translation table entries discussed above, though multiple keys
4419 and other subtleties are not allowed. The resource name for a menu is the
4420 title in lower case, followed by "Menu", the resource name of menu item is
4421 the name in lower case, run together, with words separated by caps, and all
4422 punctuation removed. For example, to change Cut to Ctrl+X, you would add the
4423 following to your .Xdefaults file:
4425 nedit*editMenu.cut.accelerator: Ctrl<Key>x
4426 nedit*editMenu.cut.acceleratorText: Ctrl+X
4428 Accelerator keys with optional shift key modifiers, like Find..., have an
4429 additional accelerator resource with Shift appended to the name. For
4432 nedit*searchMenu.find.acceleratorText: [Shift]Alt+F
4433 nedit*searchMenu.find.accelerator: Alt<Key>f
4434 nedit*searchMenu.findShift.accelerator: Shift Alt<Key>f
4435 ----------------------------------------------------------------------
4437 Highlighting Patterns
4438 ---------------------
4440 3>Writing Syntax Highlighting Patterns
4442 Patterns are the mechanism by which language syntax highlighting is
4443 implemented in NEdit (see Syntax_Highlighting_ under the heading of Features
4444 for Programming). To create syntax highlighting patterns for a new
4445 language, or to modify existing patterns, select "Recognition Patterns" from
4446 "Syntax Highlighting" sub-section of the "Default Settings" sub-menu of the
4449 First, a word of caution. As with regular expression matching in general, it
4450 is quite possible to write patterns which are so inefficient that they
4451 essentially lock up the editor as they recursively re-examine the entire
4452 contents of the file thousands of times. With the multiplicity of patterns,
4453 the possibility of a lock-up is significantly increased in syntax
4454 highlighting. When working on highlighting patterns, be sure to save your
4457 NEdit's syntax highlighting is unusual in that it works in real-time (as you
4458 type), and yet is completely programmable using standard regular expression
4459 notation. Other syntax highlighting editors usually fall either into the
4460 category of fully programmable but unable to keep up in real-time, or
4461 real-time but limited programmability. The additional burden that NEdit
4462 places on pattern writers in order to achieve this speed/flexibility mix, is
4463 to force them to state self-imposed limitations on the amount of context that
4464 patterns may examine when re-parsing after a change. While the "Pattern
4465 Context Requirements" heading is near the end of this section, it is not
4466 optional, and must be understood before making any any serious effort at
4469 In its simplest form, a highlight pattern consists of a regular expression to
4470 match, along with a style representing the font an color for displaying any
4471 text which matches that expression. To bold the word, "highlight", wherever
4472 it appears the text, the regular expression simply would be the word
4473 "highlight". The style (selected from the menu under the heading of
4474 "Highlight Style") determines how the text will be drawn. To bold the text,
4475 either select an existing style, such as "Keyword", which bolds text, or
4476 create a new style and select it under Highlight Style.
4478 The full range of regular expression capabilities can be applied in such a
4479 pattern, with the single caveat that the expression must conclusively match
4480 or not match, within the pre-defined context distance (as discussed below
4481 under Pattern Context Requirements).
4483 To match longer ranges of text, particularly any constructs which exceed the
4484 requested context, you must use a pattern which highlights text between a
4485 starting and ending regular expression match. To do so, select "Highlight
4486 text between starting and ending REs" under "Matching", and enter both a
4487 starting and ending regular expression. For example, to highlight everything
4488 between double quotes, you would enter a double quote character in both the
4489 starting and ending regular expression fields. Patterns with both a
4490 beginning and ending expression span all characters between the two
4491 expressions, including newlines.
4493 Again, the limitation for automatic parsing to operate properly is that both
4494 expressions must match within the context distance stated for the pattern
4497 With the ability to span large distances, comes the responsibility to recover
4498 when things go wrong. Remember that syntax highlighting is called upon to
4499 parse incorrect or incomplete syntax as often as correct syntax. To stop a
4500 pattern short of matching its end expression, you can specify an error
4501 expression, which stops the pattern from gobbling up more than it should.
4502 For example, if the text between double quotes shouldn't contain newlines,
4503 the error expression might be "$". As with both starting and ending
4504 expressions, error expressions must also match within the requested context
4507 4>Coloring Sub-Expressions
4509 It is also possible to color areas of text within a regular expression
4510 match. A pattern of this type associates a style with sub-expressions
4511 references of the parent pattern (as used in regular expression substitution
4512 patterns, see the NEdit Help menu item on Regular_Expressions_).
4513 Sub-expressions of both the starting and ending patterns may be colored. For
4514 example, if the parent pattern has a starting expression "\<", and end
4515 expression "\>", (for highlighting all of the text contained within angle
4516 brackets), a sub-pattern using "&" in both the starting and ending expression
4517 fields could color the brackets differently from the intervening text. A
4518 quick shortcut to typing in pattern names in the Parent Pattern field is to
4519 use the middle mouse button to drag them from the Patterns list.
4521 4>Hierarchical Patterns
4523 A hierarchical sub-pattern, is identical to a top level pattern, but is
4524 invoked only between the beginning and ending expression matches of its
4525 parent pattern. Like the sub-expression coloring patterns discussed above,
4526 it is associated with a parent pattern using the Parent Pattern field in the
4527 pattern specification. Pattern names can be dragged from the pattern list
4528 with the middle mouse button to the Parent Pattern field.
4530 After the start expression of the parent pattern matches, the syntax
4531 highlighting parser searches for either the parent's end pattern or a
4532 matching sub-pattern. When a sub-pattern matches, control is not returned to
4533 the parent pattern until the entire sub-pattern has been parsed, regardless
4534 of whether the parent's end pattern appears in the text matched by the
4537 The most common use for this capability is for coloring sub-structure of
4538 language constructs (smaller patterns embedded in larger patterns).
4539 Hierarchical patterns can also simplify parsing by having sub-patterns "hide"
4540 special syntax from parent patterns, such as special escape sequences or
4543 There is no depth limit in nesting hierarchical sub-patterns, but beyond the
4544 third level of nesting, automatic re-parsing will sometimes have to re-parse
4545 more than the requested context distance to guarantee a correct parse (which
4546 can slow down the maximum rate at which the user can type if large sections
4547 of text are matched only by deeply nested patterns).
4549 While this is obviously not a complete hierarchical language parser it is
4550 still useful in many text coloring situations. As a pattern writer, your
4551 goal is not to completely cover the language syntax, but to generate
4552 colorings that are useful to the programmer. Simpler patterns are usually
4553 more efficient and also more robust when applied to incorrect code.
4555 4>Deferred (Pass-2) Parsing
4557 NEdit does pattern matching for syntax highlighting in two passes. The first
4558 pass is applied to the entire file when syntax highlighting is first turned
4559 on, and to new ranges of text when they are initially read or pasted in. The
4560 second pass is applied only as needed when text is exposed (scrolled in to
4563 If you have a particularly complex set of patterns, and parsing is beginning
4564 to add a noticeable delay to opening files or operations which change large
4565 regions of text, you can defer some of that parsing from startup time, to
4566 when it is actually needed for viewing the text. Deferred parsing can only
4567 be used with single expression patterns, or begin/end patterns which match
4568 entirely within the requested context distance. To defer the parsing of a
4569 pattern to when the text is exposed, click on the Pass-2 pattern type button
4570 in the highlight patterns dialog.
4572 Sometimes a pattern can't be deferred, not because of context requirements,
4573 but because it must run concurrently with pass-1 (non-deferred) patterns. If
4574 they didn't run concurrently, a pass-1 pattern might incorrectly match some
4575 of the characters which would normally be hidden inside of a sequence matched
4576 by the deferred pattern. For example, C has character constants enclosed in
4577 single quotes. These typically do not cross line boundaries, meaning they
4578 can be parsed entirely within the context distance of the C pattern set and
4579 should be good candidates for deferred parsing. However, they can't be
4580 deferred because they can contain sequences of characters which can trigger
4581 pass-one patterns. Specifically, the sequence, '\"', contains a double quote
4582 character, which would be matched by the string pattern and interpreted as
4583 introducing a string.
4585 4>Pattern Context Requirements
4587 The context requirements of a pattern set state how much additional text
4588 around any change must be examined to guarantee that the patterns will match
4589 what they are intended to match. Context requirements are a promise by NEdit
4590 to the pattern writer, that the regular expressions in his/her patterns will
4591 be matched against at least <line context> lines and <character context>
4592 characters, around any modified text. Combining line and character
4593 requirements guarantee that both will be met.
4595 Automatic re-parsing happens on EVERY KEYSTROKE, so the amount of context
4596 which must be examined is very critical to typing efficiency. The more
4597 complicated your patterns, the more critical the context becomes. To cover
4598 all of the keywords in a typical language, without affecting the maximum rate
4599 at which users can enter text, you may be limited to just a few lines and/or
4600 a few hundred characters of context.
4602 The default context distance is 1 line, with no minimum character
4603 requirement. There are several benefits to sticking with this default. One
4604 is simply that it is easy to understand and to comply with. Regular
4605 expression notation is designed around single line matching. To span lines
4606 in a regular expression, you must explicitly mention the newline character
4607 "\n", and matches which are restricted to a single line are virtually immune
4608 to lock-ups. Also, if you can code your patterns to work within a single
4609 line of context, without an additional character-range context requirement,
4610 the parser can take advantage the fact that patterns don't cross line
4611 boundaries, and nearly double its efficiency over a one-line and 1-character
4612 context requirement. (In a single line context, you are allowed to match
4613 newlines, but only as the first and/or last character.)
4614 ----------------------------------------------------------------------
4619 Smart indent macros can be written for any language, but are usually more
4620 difficult to write than highlighting patterns. A good place to start, of
4621 course, is to look at the existing macros for C and C++.
4623 Smart indent macros for a language mode consist of standard NEdit macro
4624 language code attached to any or all of the following three activation
4625 conditions: 1) When smart indent is first turned on for a text window
4626 containing code of the language, 2) When a newline is typed and smart indent
4627 is expected, 3) after any character is typed. To attach macro code to any of
4628 these code "hooks", enter it in the appropriate section in the Preferences ->
4629 Default Settings -> Auto Indent -> Program Smart Indent dialog.
4631 Typically most of the code should go in the initialization section, because
4632 that is the appropriate place for subroutine definitions, and smart indent
4633 macros are complicated enough that you are not likely to want to write them
4634 as one monolithic run of code. You may also put code in the Common/Shared
4635 Initialization section (accessible through the button in the upper left
4636 corner of the dialog). Unfortunately, since the C/C++ macros also reside in
4637 the common/shared section, when you add code there, you run some risk of
4638 missing out on future upgrades to these macros, because your changes will
4639 override the built-in defaults.
4641 The newline macro is invoked after the user types a newline, but before the
4642 newline is entered in the buffer. It takes a single argument ($1) which is
4643 the position at which the newline will be inserted. It must return the
4644 number of characters of indentation the line should have, or -1. A return
4645 value of -1 means to do a standard auto-indent. You must supply a newline
4646 macro, but the code: "return -1" (auto-indent), or "return 0" (no indent) is
4649 The type-in macro takes two arguments. $1 is the insert position, and $2 is
4650 the character just inserted, and does not return a value. You can do just
4651 about anything here, but keep in mind that this macro is executed for every
4652 keystroke typed, so if you try to get too fancy, you may degrade performance.
4653 ----------------------------------------------------------------------
4658 .. ? help !!#ifndef VMS
4659 **nedit** [-**read**] [-**create**] [-**line** n | +n] [-**server**]
4660 [-**do** command] [-**tags** file] [-**tabs** n] [-**wrap**]
4661 [-**nowrap**] [-**autowrap**] [-**autoindent**] [-**noautoindent**]
4662 [-**autosave**] [-**noautosave**] [-**rows** n] [-**columns** n]
4663 [-**font** font] [-**lm** languagemode] [-**geometry** geometry]
4664 [-**iconic**] [-**noiconic**] [-**display** [host]:server[.screen]
4665 [-**xrm** resourcestring] [-**svrname** name] [-**import** file]
4666 [-**background** color] [-**foreground** color]
4667 [-**tabbed**] [-**untabbed**] [-**group**] [-**V**|-**version**]
4671 Open the file Read Only regardless of the actual file protection.
4674 Don't warn about file creation when a file doesn't exist.
4680 Designate this session as an NEdit server, for processing commands from the
4681 nc program. nc can be used to interface NEdit to code development
4682 environments, mailers, etc., or just as a quick way to open files from the
4683 shell command line without starting a new NEdit session.
4686 Execute an NEdit macro or action on the file following the -do argument on
4687 the command line. -do is particularly useful from the nc program, where
4688 nc -do can remotely execute commands in an NEdit -server session.
4691 Load a file of directions for finding definitions of program subroutines and
4692 data objects. The file must be of the format generated by Exuberant Ctags,
4693 or the standard Unix ctags command.
4696 Set tab stops every n characters.
4699 Wrap long lines at the right edge of the window rather than continuing them
4700 past it. (Continuous Wrap mode)
4702 **-autowrap, -noautowrap**
4703 Wrap long lines when the cursor reaches the right edge of the window by
4704 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4706 **-autoindent, -noautoindent**
4707 Maintain a running indent.
4709 **-autosave, -noautosave**
4710 Maintain a backup copy of the file being edited under the name '~filename'.
4713 Default height in characters for an editing window.
4716 Default width in characters for an editing window.
4718 **-font font (or -fn font)**
4719 Font for text being edited (Font for menus and dialogs can be set with -xrm
4722 **-lm languagemode**
4723 Initial language mode used for editing succeeding files.
4725 **-geometry geometry (or -g geometry)**
4726 The initial size and/or location of editor windows. The argument geometry
4729 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4731 where <width> and <height> are the desired width and height of the window,
4732 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4733 the window, + for top or left, - for bottom or right. -geometry can be
4734 specified for individual files on the command line.
4736 **-iconic, -noiconic**
4737 Initial window state for succeeding files.
4739 **-display [host]:server[.screen]**
4740 The name of the X server to use. host specifies the machine, server
4741 specifies the display server number, and screen specifies the screen number.
4742 host or screen can be omitted and default to the local machine, and screen 0.
4744 **-background color (or -bg color)**
4745 User interface background color. (Background color for text can be set
4746 separately with -xrm "nedit.textBgColor: color" or using the Preferences ->
4749 **-foreground color (or -fg color)**
4750 User interface foreground color. (Foreground color for text can be set
4751 separately with -xrm "nedit.textFgColor: color" or using the Preferences
4755 Open all subsequent files in new tabs. Resets -group option.
4758 Open all subsequent files in new windows. Resets -group option.
4761 Open all subsequent files as tabs in a new window.
4763 **-xrm resourcestring**
4764 Set the value of an X resource to override a default
4765 value (see "Customizing_NEdit_").
4768 When starting NEdit in server mode, name the server, such that it responds to
4769 requests only when nc is given a corresponding -svrname argument. By naming
4770 servers, you can run several simultaneously, and direct files and commands
4771 specifically to any one. Specifying a non-empty name automatically designates
4772 this session as an NEdit server, as though -server were specified.
4775 Loads an additional preferences file on top of the existing defaults saved in
4776 your preferences file. To incorporate macros, language modes, and highlight
4777 patterns and styles written by other users, run NEdit with -import <file>,
4778 then re-save your preference file with Preferences -> Save Defaults.
4781 Prints out the NEdit version information. The -V option is synonymous.
4784 Treats all subsequent arguments as file names, even if they start with a
4785 dash. This is so NEdit can access files that begin with the dash character.
4790 .. This documentation for VMS NEdit usage should only appear in the
4791 .. generated help code, not in any of the printed documentation.
4792 .. Reasoning is that VMS usage is diminishing and there is a desire
4793 .. to not clutter up the printed documentation here.
4795 NEDIT [filespec[,...]]
4797 The following qualifiers are accepted:
4800 Open the file Read Only regardless of the actual file protection.
4803 Don't warn about file creation when a file doesn't exist.
4809 Designate this session as an NEdit server for processing commands from the nc
4810 program. The nc program can be used to interface NEdit to code development
4811 environments, mailers, etc., or just as a quick way to open files from the
4812 shell command line without starting a new NEdit session.
4815 Execute an NEdit action routine. on each file following the /do argument on
4816 the command line. /do is particularly useful from the nc program, where nc
4817 /do can remotely execute commands in an nedit /server session.
4820 Load a file of directions for finding definitions of program subroutines and
4821 data objects. The file must be of the format generated by the Unix ctags
4825 Wrap long lines at the right edge of the window rather than continuing them
4826 past it. (Continuous Wrap mode)
4828 **/autowrap, /noautowrap**
4829 Wrap long lines when the cursor reaches the right edge of the window by
4830 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4832 **/autoindent, /noautoindent**
4833 Maintain a running indent.
4835 **/autosave, /noautosave**
4836 Maintain a backup copy of the file being edited under the name '_filename'.
4839 Default width in characters for an editing window.
4842 Default height in characters for an editing window.
4844 **/font=font (or /fn=font)**
4845 Font for text being edited (Font for menus and dialogs can be set with
4846 /xrm="*fontList:font").
4848 **/display [host]:server[.screen]**
4849 The name of the X server to use. host specifies the machine, server
4850 specifies the display server number, and screen specifies the screen number.
4851 host or screen can be omitted and default to the local machine, and screen 0.
4853 **/geometry=geometry (or /g=geometry)**
4854 The initial size and/or location of editor windows. The argument geometry
4857 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4859 where <width> and <height> are the desired width and height of the window,
4860 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4861 the window, + for top or left, - for bottom or right.
4863 **/background=color (or /bg=color)**
4865 Background color. (background color for text can be set separately with
4866 /xrm="nedit:textBgColor color" or using the Preferences ->
4869 **/foreground=color (or /fg=color)**
4870 Foreground color. (foreground color for text can be set separately with
4871 /xrm="nedit:textFgColor color" or using the Preferences ->
4875 Open all subsequent files in new tabs. Resets /group option.
4878 Open all subsequent files in new windows. Resets /group option.
4881 Open all subsequent files as tabs in a new window.
4883 **/xrm=resourcestring**
4884 Set the value of an X resource to override a default value
4885 (see Customizing NEdit).
4888 When starting nedit in server mode, name the server, such that it responds to
4889 requests only when nc is given a corresponding -svrname argument. By naming
4890 servers, you can run several simultaneously, and direct files and commands
4891 specifically to any one.
4894 Loads an additional preferences file on top of the existing defaults saved in
4895 your .nedit file. To incorporate macros, language modes, and highlight
4896 patterns and styles written by other users, run nedit with /import=<file>,
4897 then re-save your .nedit file with Preferences -> Save Defaults.
4899 Unix-style command lines (but not file names) are also acceptable:
4901 nedit -rows 20 -wrap file1.c file2.c
4905 nedit /rows=20/wrap file1.c, file2.c",
4908 ----------------------------------------------------------------------
4913 NEdit can be operated on its own, or as a two-part client/server
4914 application. Client/server mode is useful for integrating NEdit with
4915 software development environments, mailers, and other programs; or just as a
4916 quick way to open files from the shell command line without starting a new
4919 To run NEdit in server mode, type:
4923 NEdit can also be started in server mode via the NEdit Client program
4924 (**nc**) when no servers are available.
4926 The nc program, which is distributed along with NEdit, sends commands to
4927 an NEdit server to open files or execute editor actions. It can also be
4928 used on files that are already opened.
4930 Listing a file on the nc command line means: Open it if it is not already
4931 open and bring the window to the front.
4934 nc supports the following command line options:
4936 **nc** [**-read**] [**-create**]
4937 [**-line** n | **+**n] [**-do** command] [**-lm** languagemode]
4938 [**-svrname** name] [**-svrcmd** command]
4939 [**-ask**] [**-noask**] [**-timeout** seconds]
4940 [**-geometry** geometry | **-g** geometry] [**-icon** | **-iconic**]
4941 [-**tabbed**] [-**untabbed**] [-**group**] [**-wait**]
4942 [**-V** | **-version**]
4943 [**-xrm** resourcestring] [**-display** [host]:server[.screen]]
4947 Open the file read-only regardless of its actual permissions. There is no
4948 effect if the file is already open.
4951 Don't warn about file creation when a file doesn't exist.
4954 Go to line number n. This will also affect files which are already open.
4957 Execute an NEdit macro or action on the file following the -do argument
4958 on the command line.
4960 If you use this command without a filename, nc would randomly choose one
4961 window to focus and execute the macro in.
4963 **-ask**, **-noask**
4964 Instructs nc to automatically start a server if one is not available. This
4965 overrides the X resource `nc.autoStart' (see X_Resources_).
4968 Explicitly instructs nc which server to connect to, an instance of
4969 nedit(1) with a corresponding -svrname argument. By naming servers, you
4970 can run several simultaneously, and direct files and commands
4971 specifically to any one.
4974 The command which nc uses to start an NEdit server. It is also settable
4975 via the X resource `nc.serverCommand' (see X_Resources_). Defaults to
4978 **-lm** languagemode
4979 Initial language mode used.
4981 **-geometry** geometry, **-g** geometry
4982 The initial size and/or location of editor windows. See
4983 NEdit_Command_Line_ for details.
4985 **-icon**, **-iconic**
4986 Initial window state.
4988 **-display** [<host>]:<server>[.<screen>]
4989 The name of the X server to use. See NEdit_Command_Line_ for details.
4991 **-timeout** seconds
4992 Basic time-out period used in communication with an NEdit server. The
4993 default is 10 seconds. Also settable via the X resource `nc.timeOut'.
4995 Under rare conditions (such as a slow connection), it may be necessary to
4996 increase the time-out period. In most cases, the default is fine.
4999 Open all subsequent files in new tabs. Resets -group option.
5002 Open all subsequent files in new windows. Resets -group option.
5005 Open all subsequent files as tabs in a new window.
5008 Instructs nc not to return to the shell until all files given are closed.
5010 Normally, nc returns once the files given in its command line are opened
5011 by the server. When this option is given, nc returns only after the last
5012 file given in this call is closed.
5014 Note that this option affects all files in the command line, not only the
5015 ones following this option.
5017 Note that nc will wait for all files given in the command line, even if
5018 the files were already opened.
5021 4>Command Line Arguments
5023 In typical Unix style, arguments affect the files which follow them on the
5024 command line, for example:
5026 incorrect: nc file.c -line 25
5027 correct: nc -line 25 file.c
5029 -read, -create, and -line affect all of the files which follow them on the
5032 The -do macro is executed only once, on the next file on the line. -do
5033 without a file following it on the command line, executes the macro on the
5034 first available window (presumably when you give a -do command without a
5035 corresponding file or window, you intend it to do something independent of
5036 the window in which it happens to execute).
5038 The -wait option affects all files named in the command line.
5042 Sometimes it is useful to have more than one NEdit server running, for
5043 example to keep mail and programming work separate. The option, -svrname, to
5044 both nedit and nc, allows you to start, and communicate with, separate named
5045 servers. A named server responds only to requests with the corresponding
5046 -svrname argument. If you use ClearCase and are within a ClearCase view, the
5047 server name will default to the name of the view (based on the value of the
5048 CLEARCASE_ROOT environment variable).
5052 Communication between nc and nedit is done through the X display. So as long
5053 as the X Window System is set up and working properly, nc will work properly
5054 as well. nc uses the DISPLAY environment variable, the machine name and your
5055 user name to find the appropriate server, meaning, if you have several
5056 machines sharing a common file system, nc will not be able to find a server
5057 that is running on a machine with a different host name, even though it may
5058 be perfectly appropriate for editing a given file.
5060 The command which nc uses to start an nedit server is settable via the X
5061 resource nc.serverCommand, by default, "nedit -server".
5062 ----------------------------------------------------------------------
5067 If a system crash, network failure, X server crash, or program error should
5068 happen while you are editing a file, you can still recover most of your
5069 work. NEdit maintains a backup file which it updates periodically (every 8
5070 editing operations or 80 characters typed). This file has the same name
5071 as the file that you are editing, but with the character `~' (tilde) on Unix
5072 or `_' (underscore) on VMS prefixed to the name. To recover a file after a
5073 crash, simply rename the file to remove the tilde or underscore character,
5074 replacing the older version of the file. (Because several of the Unix shells
5075 consider the tilde to be a special character, you may have to prefix the
5076 character with a `\' (backslash) when you move or delete an NEdit backup
5079 Example, to recover the file called "help.c" on Unix type the command:
5083 A minor caveat, is that if the file you were editing was in MS DOS format,
5084 the backup file will be in Unix format, and you will need to open the backup
5085 file in NEdit and change the file format back to MS DOS via the Save As...
5086 dialog (or use the Unix unix2dos command outside of NEdit).
5087 ----------------------------------------------------------------------
5098 .. There is build time versioning information that is handled specially
5099 .. inside help.c for this section. It needs to have a '%s' string
5100 .. made available for it to appear in the on-line help.
5104 .. ======================================================================
5105 .. The policy for credit so far is this:
5107 .. You get "written by" credit if you have contributed significant
5108 .. code or effort to the project.
5110 .. You get a syntax/indent credit if your pattern is compiled into the
5112 .. ======================================================================
5114 NEdit was written by Mark Edel, Joy Kyriakopulos, Christopher Conrad,
5115 Jim Clark, Arnulfo Zepeda-Navratil, Suresh Ravoor, Tony Balinski, Max
5116 Vohlken, Yunliang Yu, Donna Reid, Arne Førlie, Eddy De Greef, Steve
5117 LoBasso, Alexander Mai, Scott Tringali, Thorsten Haude, Steve Haehn,
5118 Andrew Hood, Nathaniel Gray, and TK Soh.
5120 The regular expression matching routines used in NEdit are adapted (with
5121 permission) from original code written by Henry Spencer at the
5122 University of Toronto.
5124 The Microline widgets are inherited from the Mozilla project.
5126 Syntax highlighting patterns and smart indent macros were contributed by:
5127 Simon T. MacDonald, Maurice Leysens, Matt Majka, Alfred Smeenk,
5128 Alain Fargues, Christopher Conrad, Scott Markinson, Konrad Bernloehr,
5129 Ivan Herman, Patrice Venant, Christian Denat, Philippe Couton,
5130 Max Vohlken, Markus Schwarzenberg, Himanshu Gohel, Steven C. Kapp,
5131 Michael Turomsha, John Fieber, Chris Ross, Nathaniel Gray, Joachim Lous,
5132 Mike Duigou, Seak Teng-Fong, Joor Loohuis, Mark Jones,
5133 and Niek van den Berg.
5135 NEdit sources, executables, additional documentation, and contributed
5136 software are available from the NEdit web site at http://www.nedit.org_.
5138 This program is free software; you can redistribute it and/or
5139 modify it under the terms of the GNU_General_Public_License_
5140 as published by the Free Software Foundation; either version 2
5141 of the License, or (at your option) any later version.
5143 In addition, as a special exception to the GNU GPL, the copyright holders
5144 give permission to link the code of this program with the Motif and Open
5145 Motif libraries (or with modified versions of these that use the same
5146 license), and distribute linked combinations including the two. You must
5147 obey the GNU General Public License in all respects for all of the code
5148 used other than linking with Motif/Open Motif. If you modify this file,
5149 you may extend this exception to your version of the file, but you are
5150 not obligated to do so. If you do not wish to do so, delete this
5151 exception statement from your version.
5153 This program is distributed in the hope that it will be useful,
5154 but WITHOUT ANY WARRANTY; without even the implied warranty of
5155 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
5156 section on the GNU_General_Public_License_ for more details.
5157 ----------------------------------------------------------------------
5159 GNU General Public License
5162 GNU GENERAL PUBLIC LICENSE
5164 Version 2, June 1991
5166 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave,
5167 Cambridge, MA 02139, USA. Everyone is permitted to copy and distribute
5168 verbatim copies of this license document, but changing it is not allowed.
5172 The licenses for most software are designed to take away your freedom to
5173 share and change it. By contrast, the GNU General Public License is intended
5174 to guarantee your freedom to share and change free software--to make sure the
5175 software is free for all its users. This General Public License applies to
5176 most of the Free Software Foundation's software and to any other program
5177 whose authors commit to using it. (Some other Free Software Foundation
5178 software is covered by the GNU Library General Public License instead.) You
5179 can apply it to your programs, too.
5181 When we speak of free software, we are referring to freedom, not price. Our
5182 General Public Licenses are designed to make sure that you have the freedom
5183 to distribute copies of free software (and charge for this service if you
5184 wish), that you receive source code or can get it if you want it, that you
5185 can change the software or use pieces of it in new free programs; and that
5186 you know you can do these things.
5188 To protect your rights, we need to make restrictions that forbid anyone to
5189 deny you these rights or to ask you to surrender the rights. These
5190 restrictions translate to certain responsibilities for you if you distribute
5191 copies of the software, or if you modify it.
5193 For example, if you distribute copies of such a program, whether gratis or
5194 for a fee, you must give the recipients all the rights that you have. You
5195 must make sure that they, too, receive or can get the source code. And you
5196 must show them these terms so they know their rights.
5198 We protect your rights with two steps: (1) copyright the software, and (2)
5199 offer you this license which gives you legal permission to copy, distribute
5200 and/or modify the software.
5202 Also, for each author's protection and ours, we want to make certain that
5203 everyone understands that there is no warranty for this free software. If the
5204 software is modified by someone else and passed on, we want its recipients to
5205 know that what they have is not the original, so that any problems introduced
5206 by others will not reflect on the original authors' reputations.
5208 Finally, any free program is threatened constantly by software patents. We
5209 wish to avoid the danger that redistributors of a free program will
5210 individually obtain patent licenses, in effect making the program
5211 proprietary. To prevent this, we have made it clear that any patent must be
5212 licensed for everyone's free use or not licensed at all.
5214 The precise terms and conditions for copying, distribution and modification
5217 GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
5220 0. This License applies to any program or other work which contains a notice
5221 placed by the copyright holder saying it may be distributed under the terms
5222 of this General Public License. The "Program", below, refers to any such
5223 program or work, and a "work based on the Program" means either the Program
5224 or any derivative work under copyright law: that is to say, a work containing
5225 the Program or a portion of it, either verbatim or with modifications and/or
5226 translated into another language. (Hereinafter, translation is included
5227 without limitation in the term "modification".) Each licensee is addressed as
5230 Activities other than copying, distribution and modification are not covered
5231 by this License; they are outside its scope. The act of running the Program
5232 is not restricted, and the output from the Program is covered only if its
5233 contents constitute a work based on the Program (independent of having been
5234 made by running the Program). Whether that is true depends on what the
5237 1. You may copy and distribute verbatim copies of the Program's source code
5238 as you receive it, in any medium, provided that you conspicuously and
5239 appropriately publish on each copy an appropriate copyright notice and
5240 disclaimer of warranty; keep intact all the notices that refer to this
5241 License and to the absence of any warranty; and give any other recipients of
5242 the Program a copy of this License along with the Program.
5244 You may charge a fee for the physical act of transferring a copy, and you may
5245 at your option offer warranty protection in exchange for a fee.
5247 2. You may modify your copy or copies of the Program or any portion of it,
5248 thus forming a work based on the Program, and copy and distribute such
5249 modifications or work under the terms of Section 1 above, provided that you
5250 also meet all of these conditions:
5252 a) You must cause the modified files to carry prominent notices stating
5253 that you changed the files and the date of any change.
5255 b) You must cause any work that you distribute or publish, that in whole or
5256 in part contains or is derived from the Program or any part thereof, to be
5257 licensed as a whole at no charge to all third parties under the terms of
5260 c) If the modified program normally reads commands interactively when run,
5261 you must cause it, when started running for such interactive use in the
5262 most ordinary way, to print or display an announcement including an
5263 appropriate copyright notice and a notice that there is no warranty (or
5264 else, saying that you provide a warranty) and that users may redistribute
5265 the program under these conditions, and telling the user how to view a copy
5266 of this License. (Exception: if the Program itself is interactive but does
5267 not normally print such an announcement, your work based on the Program is
5268 not required to print an announcement.)
5270 These requirements apply to the modified work as a whole. If identifiable
5271 sections of that work are not derived from the Program, and can be reasonably
5272 considered independent and separate works in themselves, then this License,
5273 and its terms, do not apply to those sections when you distribute them as
5274 separate works. But when you distribute the same sections as part of a whole
5275 which is a work based on the Program, the distribution of the whole must be
5276 on the terms of this License, whose permissions for other licensees extend to
5277 the entire whole, and thus to each and every part regardless of who wrote it.
5279 Thus, it is not the intent of this section to claim rights or contest your
5280 rights to work written entirely by you; rather, the intent is to exercise the
5281 right to control the distribution of derivative or collective works based on
5284 In addition, mere aggregation of another work not based on the Program with
5285 the Program (or with a work based on the Program) on a volume of a storage or
5286 distribution medium does not bring the other work under the scope of this
5289 3. You may copy and distribute the Program (or a work based on it, under
5290 Section 2) in object code or executable form under the terms of Sections 1
5291 and 2 above provided that you also do one of the following:
5293 a) Accompany it with the complete corresponding machine-readable source
5294 code, which must be distributed under the terms of Sections 1 and 2 above
5295 on a medium customarily used for software interchange; or,
5297 b) Accompany it with a written offer, valid for at least three years, to
5298 give any third party, for a charge no more than your cost of physically
5299 performing source distribution, a complete machine-readable copy of the
5300 corresponding source code, to be distributed under the terms of Sections 1
5301 and 2 above on a medium customarily used for software interchange; or,
5303 c) Accompany it with the information you received as to the offer to
5304 distribute corresponding source code. (This alternative is allowed only for
5305 noncommercial distribution and only if you received the program in object
5306 code or executable form with such an offer, in accord with Subsection b
5309 The source code for a work means the preferred form of the work for making
5310 modifications to it. For an executable work, complete source code means all
5311 the source code for all modules it contains, plus any associated interface
5312 definition files, plus the scripts used to control compilation and
5313 installation of the executable. However, as a special exception, the source
5314 code distributed need not include anything that is normally distributed (in
5315 either source or binary form) with the major components (compiler, kernel,
5316 and so on) of the operating system on which the executable runs, unless that
5317 component itself accompanies the executable.
5319 If distribution of executable or object code is made by offering access to
5320 copy from a designated place, then offering equivalent access to copy the
5321 source code from the same place counts as distribution of the source code,
5322 even though third parties are not compelled to copy the source along with the
5325 4. You may not copy, modify, sublicense, or distribute the Program except as
5326 expressly provided under this License. Any attempt otherwise to copy, modify,
5327 sublicense or distribute the Program is void, and will automatically
5328 terminate your rights under this License. However, parties who have received
5329 copies, or rights, from you under this License will not have their licenses
5330 terminated so long as such parties remain in full compliance.
5332 5. You are not required to accept this License, since you have not signed it.
5333 However, nothing else grants you permission to modify or distribute the
5334 Program or its derivative works. These actions are prohibited by law if you
5335 do not accept this License. Therefore, by modifying or distributing the
5336 Program (or any work based on the Program), you indicate your acceptance of
5337 this License to do so, and all its terms and conditions for copying,
5338 distributing or modifying the Program or works based on it.
5340 6. Each time you redistribute the Program (or any work based on the Program),
5341 the recipient automatically receives a license from the original licensor to
5342 copy, distribute or modify the Program subject to these terms and conditions.
5343 You may not impose any further restrictions on the recipients' exercise of
5344 the rights granted herein. You are not responsible for enforcing compliance
5345 by third parties to this License.
5347 7. If, as a consequence of a court judgment or allegation of patent
5348 infringement or for any other reason (not limited to patent issues),
5349 conditions are imposed on you (whether by court order, agreement or
5350 otherwise) that contradict the conditions of this License, they do not excuse
5351 you from the conditions of this License. If you cannot distribute so as to
5352 satisfy simultaneously your obligations under this License and any other
5353 pertinent obligations, then as a consequence you may not distribute the
5354 Program at all. For example, if a patent license would not permit
5355 royalty-free redistribution of the Program by all those who receive copies
5356 directly or indirectly through you, then the only way you could satisfy both
5357 it and this License would be to refrain entirely from distribution of the
5360 If any portion of this section is held invalid or unenforceable under any
5361 particular circumstance, the balance of the section is intended to apply and
5362 the section as a whole is intended to apply in other circumstances.
5364 It is not the purpose of this section to induce you to infringe any patents
5365 or other property right claims or to contest validity of any such claims;
5366 this section has the sole purpose of protecting the integrity of the free
5367 software distribution system, which is implemented by public license
5368 practices. Many people have made generous contributions to the wide range of
5369 software distributed through that system in reliance on consistent
5370 application of that system; it is up to the author/donor to decide if he or
5371 she is willing to distribute software through any other system and a licensee
5372 cannot impose that choice.
5374 This section is intended to make thoroughly clear what is believed to be a
5375 consequence of the rest of this License.
5377 8. If the distribution and/or use of the Program is restricted in certain
5378 countries either by patents or by copyrighted interfaces, the original
5379 copyright holder who places the Program under this License may add an
5380 explicit geographical distribution limitation excluding those countries, so
5381 that distribution is permitted only in or among countries not thus excluded.
5382 In such case, this License incorporates the limitation as if written in the
5383 body of this License.
5385 9. The Free Software Foundation may publish revised and/or new versions of
5386 the General Public License from time to time. Such new versions will be
5387 similar in spirit to the present version, but may differ in detail to address
5388 new problems or concerns.
5390 Each version is given a distinguishing version number. If the Program
5391 specifies a version number of this License which applies to it and "any later
5392 version", you have the option of following the terms and conditions either of
5393 that version or of any later version published by the Free Software
5394 Foundation. If the Program does not specify a version number of this License,
5395 you may choose any version ever published by the Free Software Foundation.
5397 10. If you wish to incorporate parts of the Program into other free programs
5398 whose distribution conditions are different, write to the author to ask for
5399 permission. For software which is copyrighted by the Free Software
5400 Foundation, write to the Free Software Foundation; we sometimes make
5401 exceptions for this. Our decision will be guided by the two goals of
5402 preserving the free status of all derivatives of our free software and of
5403 promoting the sharing and reuse of software generally.
5407 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
5408 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
5409 STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
5410 PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
5411 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
5412 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
5413 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
5414 YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
5416 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
5417 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
5418 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
5419 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
5420 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO
5421 LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
5422 THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
5423 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
5424 POSSIBILITY OF SUCH DAMAGES.
5426 END OF TERMS AND CONDITIONS
5427 ----------------------------------------------------------------------
5432 There are two separate mailing lists for nedit users, and one for developers.
5433 Users may post to the developer mailing list to report defects and communicate
5434 with the nedit developers. Remember that nedit is entirely a volunteer
5435 effort, so please ask questions first to the discussion list, and do your
5436 share to answer other users questions as well.
5440 General discussion, questions and answers among NEdit users and developers.
5442 announce@@nedit.org_
5444 A low-volume mailing list for announcing new versions.
5448 Communication among and with NEdit developers.
5449 Developers should also subscribe to the discuss list.
5451 To subscribe, send mail to one of the following addresses:
5453 announce-request@@nedit.org_
5454 discuss-request@@nedit.org_
5455 develop-request@@nedit.org_
5457 with the body consisting of the single word
5460 ----------------------------------------------------------------------
5465 3>Solutions to Common Problems
5467 For a much more comprehensive list of common problems and solutions, see the
5468 NEdit FAQ. The latest version of the FAQ can always be found on the NEdit
5471 http://www.nedit.org_.
5473 **P: No files are shown in the "Files" list in the Open... dialog.**
5475 S: When you use the "Filter" field, include the file specification or a
5476 complete directory specification, including the trailing "/" on Unix.
5477 (See Help in the Open... dialog).
5479 **P: Find Again and Replace Again don't continue in the same direction as the original Find or Replace.**
5481 S: Find Again and Replace Again don't use the direction of the original
5482 search. The Shift key controls the direction: Ctrl+G means forward,
5483 Shift+Ctrl+G means backward.
5485 **P: Preferences specified in the Preferences menu don't seem to get saved when I select Save Defaults.**
5487 S: NEdit has two kinds of preferences: 1) per-window preferences, in the
5488 Preferences menu, and 2) default settings for preferences in newly created
5489 windows, in the Default Settings sub-menu of the Preferences menu.
5490 Per-window preferences are not saved by Save Defaults, only Default
5493 **P: Columns and indentation don't line up.**
5495 S: NEdit is using a proportional width font. Set the font to a fixed style
5496 (see Preferences menu).
5498 **P: NEdit performs poorly on very large files.**
5500 S: Turn off Incremental Backup. With Incremental Backup on, NEdit
5501 periodically writes a full copy of the file to disk.
5503 **P: Commands added to the Shell Commands menu (Unix only) don't output anything until they are finished executing.**
5505 S: If the command output is directed to a dialog, or the input is from a
5506 selection, output is collected together and held until the command
5507 completes. De-select both of the options and the output will be shown
5508 incrementally as the command executes.
5510 **P: Dialogs don't automatically get keyboard focus when they pop up.**
5512 S: Most X Window managers allow you to choose between two categories of
5513 keyboard focus models: pointer focus, and explicit focus. Pointer focus
5514 means that as you move the mouse around the screen, the window under the
5515 mouse automatically gets the keyboard focus. NEdit users who use this
5516 focus model should set "Popups Under Pointer" in the Default Settings sub
5517 menu of the preferences menu in NEdit. Users with the explicit focus
5518 model, in some cases, may have problems with certain dialogs, such as Find
5519 and Replace. In MWM this is caused by the mwm resource startupKeyFocus
5520 being set to False (generally a bad choice for explicit focus users).
5521 NCDwm users should use the focus model "click" instead of "explicit",
5522 again, unless you have set it that way to correct specific problems, this
5523 is the appropriate setting for most explicit focus users.
5525 **P: The Backspace key doesn't work, or deletes forward rather than backward.**
5527 S: While this is an X/Motif binding problem, and should be solved outside of
5528 NEdit in the Motif virtual binding layer (or possibly xmodmap or
5529 translations), NEdit provides an out. If you set the resource:
5530 nedit.remapDeleteKey to True, NEdit will forcibly map the delete key to
5531 backspace. The default setting of this resource recently changed, so
5532 users who have been depending on this remapping will now have to set it
5533 explicitly (or fix their bindings).
5535 **P: NEdit crashes when I try to paste text in to a text field in a dialog (like Find or Replace) on my SunOS system.**
5537 S: On many SunOS systems, you have to set up an nls directory before various
5538 inter-client communication features of Motif will function properly.
5539 There are instructions in README.sun in /pub/v5_0_2/individual/README.sun on
5540 ftp.nedit.org, as well as a tar file containing a complete nls
5541 directory: ftp://ftp.nedit.org/pub/v5_0_2/nls.tar.
5542 README.sun contains directions for setting up an nls directory, which
5543 is required by Motif for handling copy and paste to Motif text fields.
5547 Below is the list of known defects which affect NEdit. The defects your copy
5548 of NEdit will exhibit depend on which system you are running and with which
5549 Motif libraries it was built. Note that there are now Motif 1.2 and/or 2.0
5550 libraries available on ALL supported platforms, and as you can see below
5551 there are far fewer defects in Motif 1.2, so it is in your best interest to
5552 upgrade your system.
5557 Operations between rectangular selections on overlapping lines do nothing.
5560 None. These operations are very complicated and rarely used.
5563 Cut and Paste menu items fail, or possibly crash,
5564 for very large (multi-megabyte) selections.
5567 Use selection copy (middle mouse button click)
5568 for transferring larger quantities of data.
5569 Cut and Paste save the copied text in server
5570 memory, which is usually limited.
5574 Submit bugs through the web at:
5576 http://sf.net/tracker/?func=add&group_id=11005&atid=111005
5578 Please include the first few lines from Help > Version, which identifies
5579 NEdit's version and other system attributes important for diagnosing your
5582 The NEdit developers subscribe to both discuss@@nedit.org and
5583 develop@@nedit.org, either of which may be used for reporting defects. If
5584 you're not sure, or you think the report might be of interest to the general
5585 NEdit user community, send the report to discuss@@nedit.org_. If it's
5586 something obvious and boring, like we misspelled "anemometer" in the on-line
5587 help, send it to develop@@nedit.org_. If you don't want to subscribe to the
5588 Mailing_Lists_, please add a note to your mail about cc'ing you on responses.
5592 .. Hyperlinks for this document ==============================================
5594 .. _discuss@@nedit.org mailto:discuss@@nedit.org
5595 .. _announce@@nedit.org mailto:announce@@nedit.org
5596 .. _develop@@nedit.org mailto:develop@@nedit.org
5597 .. _discuss-request@@nedit.org mailto:discuss-request@@nedit.org
5598 .. _announce-request@@nedit.org mailto:announce-request@@nedit.org
5599 .. _develop-request@@nedit.org mailto:develop-request@@nedit.org
5600 .. _http://www.nedit.org http://www.nedit.org
5601 .. _ctag_support #ctags
5602 .. _Alternation #alternation
5604 .. =============================================================================
5606 .. Below is what is used to guide the generation of 'C'-Motif menus.
5607 .. Indentation is SIGNIFICANT in the "Menu" directive lines below. It
5608 .. is used to determine under which menu element another item will belong.
5609 .. The number of spaces indented is not significant, but items to be placed
5610 .. in the same menu panel MUST line up at the same indent level.
5611 .. ALL nodes of this menu "tree" should have help name qualifiers.
5612 .. These are used to produce the internal lists used by NEdit help code.
5614 .. By default, the first character of the menu element will be used as a
5615 .. menu mneumonic key. To use another character in the menu element for this
5616 .. purpose, surround the character with underscores (eg. I w_a_nt 'a').
5618 .. The menu title MUST match the one found in the actual help text (sans
5619 .. special mneumonic key character marking). The help text title may include
5620 .. underlines (for spaces) when it is a hyperlink target.
5622 .. The Help-name is used to generate various data structure names. For
5623 .. instance, the 'start' help name will be used to generate the HelpTopic
5624 .. enumeration value HELP_START and the character array htxt_start which
5625 .. holds the actual help text used in the menu dialogs. Consequently, these
5626 .. names need to be unique and contain only the characters that a 'C'
5627 .. compiler can digest.
5629 .. Menu separator lines use a dash (-) character for the Menu Title. They
5630 .. should also have a unique Help-name.
5632 .. A numerical value following the Help-name (separated from the name by
5633 .. a comma and/or spaces) is part of a menu element hiding scheme implemented
5634 .. in buildHelpMenu (found in 'menu.c'). When the number matches the hideIt
5635 .. value found in the procedure, that element will effectively become invisible.
5636 .. This mechanism was created for particular menu features that are not
5637 .. available to all incarnations of NEdit (in this case, the VMS version).
5639 .. A "Help" directive is used for all other text used as NEdit help, but
5640 .. does not show up in the Help menu.
5642 .. Menu Title # Help-name
5643 .. ------------------------------------------------------------
5644 .. Menu: Getting Started # start
5645 .. Menu: Basic Operation # basicOp
5646 .. Menu: Selecting Text # select
5647 .. Menu: Finding and Replacing Text # search
5648 .. Menu: Cut and Paste # clipboard
5649 .. Menu: Using the Mouse # mouse
5650 .. Menu: Keyboard Shortcuts # keyboard
5651 .. Menu: S_h_ifting and Filling # fill
5652 .. Menu: Tabbed Editing # interface
5653 .. Menu: F_i_le Format # format
5655 .. Menu: Features for Programming # features
5656 .. Menu: Programming with NEdit # programmer
5657 .. Menu: Tabs/Emulated Tabs # tabs
5658 .. Menu: Auto/Smart Indent # indent
5659 .. Menu: Syntax Highlighting # syntax
5660 .. Menu: Finding Declarations (ctags) # tags
5661 .. Menu: Calltips # calltips
5663 .. Menu: Regular Expressions # regex
5664 .. Menu: Basic Regular Expression Syntax # basicSyntax
5665 .. Menu: Metacharacters # escapeSequences
5666 .. Menu: Parenthetical Constructs # parenConstructs
5667 .. Menu: Advanced Topics # advancedTopics
5668 .. Menu: Example Regular Expressions # examples
5670 .. Menu: Macro/Shell Extensions # extensions
5671 .. Menu: Shell Commands and Filters # shell, 1
5672 .. Menu: Learn/Replay # learn
5673 .. Menu: Macro Language # macro_lang
5674 .. Menu: M_a_cro Subroutines # macro_subrs
5675 .. Menu: Range Sets # rangeset
5676 .. Menu: Highlighting Information # hiliteInfo
5677 .. Menu: Action Routines # actions
5679 .. Menu: Customizing # customizing
5680 .. Menu: Customizing NEdit # customize
5681 .. Menu: Preferences # preferences
5682 .. Menu: X Resources # resources
5683 .. Menu: Key Binding # binding
5684 .. Menu: Highlighting Patterns # patterns
5685 .. Menu: Smart Indent Macros # smart_indent
5687 .. Menu: NEdit Command Line # command_line
5688 .. Menu: Client/Server Mode # server
5689 .. Menu: Cr_a_sh Recovery # recovery
5690 .. Menu: ---------------------------------- # separator1
5691 .. Menu: Version # version
5692 .. Menu: GNU General Public License # distribution
5693 .. Menu: Mailing _L_ists # mailing_list
5694 .. Menu: Problems/Defects # defects
5695 .. ------------------------------------------------------------
5696 .. Help: Tabs Dialog # tabs_dialog
5697 .. Help: Customize Window Title Dialog # custom_title_dialog