1 .. $Id: help.etx,v 1.88 2005/02/18 11:10:30 edg 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 (but don't exclude shorter matches if that
1408 is necessary to achieve an overall match).
1410 * Match zero or more
1414 The following quantifiers are minimal matching, or "lazy", in that they match
1415 as little text as possible (but don't exclude longer matches if that is
1416 necessary to achieve an overall match).
1418 *? Match zero or more
1419 +? Match one or more
1420 ?? Match zero or one
1422 One final quantifier is the counting quantifier, or brace quantifier. It
1423 takes the following basic form:
1425 {min,max} Match from `min' to `max' times the
1426 previous regular expression atom.
1428 If `min' is omitted, it is assumed to be zero. If `max' is omitted, it is
1429 assumed to be infinity. Whether specified or assumed, `min' must be less
1430 than or equal to `max'. Note that both `min' and `max' are limited to
1431 65535. If both are omitted, then the construct is the same as `*'. Note
1432 that `{,}' and `{}' are both valid brace constructs. A single number
1433 appearing without a comma, e.g. `{3}' is short for the `{min,min}' construct,
1434 or to match exactly `min' number of times.
1436 The quantifiers `{1}' and `{1,1}' are accepted by the syntax, but are
1437 optimized away since they mean to match exactly once, which is redundant
1438 information. Also, for efficiency, certain combinations of `min' and `max'
1439 are converted to either `*', `+', or `?' as follows:
1445 Note that {0} and {0,0} are meaningless and will generate an error message at
1446 regular expression compile time.
1448 Brace quantifiers can also be "lazy". For example {2,5}? would try to match
1449 2 times if possible, and will only match 3, 4, or 5 times if that is what is
1450 necessary to achieve an overall match.
1454 A series of alternative patterns to match can be specified by separating them
1455 with vertical pipes, `|'. An example of _alternation would be `a|be|sea'.
1456 This will match `a', or `be', or `sea'. Each alternative can be an
1457 arbitrarily complex regular expression. The alternatives are attempted in
1458 the order specified. An empty alternative can be specified if desired, e.g.
1459 `a|b|'. Since an empty alternative can match nothingness (the empty string),
1460 this guarantees that the expression will match.
1464 Comments are of the form `(?#<comment text>)' and can be inserted anywhere
1465 and have no effect on the execution of the regular expression. They can be
1466 handy for documenting very complex regular expressions. Note that a comment
1467 begins with `(?#' and ends at the first occurrence of an ending parenthesis,
1468 or the end of the regular expression... period. Comments do not recognize
1469 any escape sequences.
1470 ----------------------------------------------------------------------
1475 3>Escaping Metacharacters
1477 In a regular expression (regex), most ordinary characters match themselves.
1478 For example, `ab%' would match anywhere `a' followed by `b' followed by `%'
1479 appeared in the text. Other characters don't match themselves, but are
1480 metacharacters. For example, backslash is a special metacharacter which
1481 'escapes' or changes the meaning of the character following it. Thus, to
1482 match a literal backslash would require a regular expression to have two
1483 backslashes in sequence. NEdit provides the following escape sequences so
1484 that metacharacters that are used by the regex syntax can be specified as
1485 ordinary characters.
1487 \( \) \- \[ \] \< \> \{ \}
1488 \. \| \^ \$ \* \+ \? \& \\
1490 3>Special Control Characters
1492 There are some special characters that are difficult or impossible to type.
1493 Many of these characters can be constructed as a sort of metacharacter or
1494 sequence by preceding a literal character with a backslash. NEdit recognizes
1495 the following special character sequences:
1499 \e ASCII escape character (***)
1500 \f form feed (new page)
1506 *** For environments that use the EBCDIC character set,
1507 when compiling NEdit set the EBCDIC_CHARSET compiler
1508 symbol to get the EBCDIC equivalent escape
1511 3>Octal and Hex Escape Sequences
1513 Any ASCII (or EBCDIC) character, except null, can be specified by using
1514 either an octal escape or a hexadecimal escape, each beginning with \0 or \x
1515 (or \X), respectively. For example, \052 and \X2A both specify the `*'
1516 character. Escapes for null (\00 or \x0) are not valid and will generate an
1517 error message. Also, any escape that exceeds \0377 or \xFF will either cause
1518 an error or have any additional character(s) interpreted literally. For
1519 example, \0777 will be interpreted as \077 (a `?' character) followed by `7'
1520 since \0777 is greater than \0377.
1522 An invalid digit will also end an octal or hexadecimal escape. For example,
1523 \091 will cause an error since `9' is not within an octal escape's range of
1524 allowable digits (0-7) and truncation before the `9' yields \0 which is
1527 3>Shortcut Escape Sequences
1529 NEdit defines some escape sequences that are handy shortcuts for commonly
1530 used character classes.
1533 \l letters a-z, A-Z, and locale dependent letters
1534 \s whitespace \t, \r, \v, \f, and space
1535 \w word characters letters, digits, and underscore, `_'
1537 \D, \L, \S, and \W are the same as the lowercase versions except that the
1538 resulting character class is negated. For example, \d is equivalent to
1539 `[0-9]', while \D is equivalent to `[^0-9]'.
1541 These escape sequences can also be used within a character class. For
1542 example, `[\l_]' is the same as `[a-zA-Z@_]', extended with possible locale
1543 dependent letters. The escape sequences for special characters, and octal
1544 and hexadecimal escapes are also valid within a class.
1546 3>Word Delimiter Tokens
1548 Although not strictly a character class, the following escape sequences
1549 behave similarly to character classes:
1551 \y Word delimiter character
1552 \Y Not a word delimiter character
1554 The `\y' token matches any single character that is one of the characters
1555 that NEdit recognizes as a word delimiter character, while the `\Y' token
1556 matches any character that is NOT a word delimiter character. Word delimiter
1557 characters are dynamic in nature, meaning that the user can change them through
1558 preference settings. For this reason, they must be handled differently by the
1559 regular expression engine. As a consequence of this, `\y' and `\Y' can not be
1560 used within a character class specification.
1561 ----------------------------------------------------------------------
1563 Parenthetical Constructs
1564 ------------------------
1566 3>Capturing Parentheses
1568 Capturing Parentheses are of the form `(<regex>)' and can be used to group
1569 arbitrarily complex regular expressions. Parentheses can be nested, but the
1570 total number of parentheses, nested or otherwise, is limited to 50 pairs.
1571 The text that is matched by the regular expression between a matched set of
1572 parentheses is captured and available for text substitutions and
1573 backreferences (see below.) Capturing parentheses carry a fairly high
1574 overhead both in terms of memory used and execution speed, especially if
1575 quantified by `*' or `+'.
1577 3>Non-Capturing Parentheses
1579 Non-Capturing Parentheses are of the form `(?:<regex>)' and facilitate
1580 grouping only and do not incur the overhead of normal capturing parentheses.
1581 They should not be counted when determining numbers for capturing parentheses
1582 which are used with backreferences and substitutions. Because of the limit
1583 on the number of capturing parentheses allowed in a regex, it is advisable to
1584 use non-capturing parentheses when possible.
1586 3>Positive Look-Ahead
1588 Positive look-ahead constructs are of the form `(?=<regex>)' and implement a
1589 zero width assertion of the enclosed regular expression. In other words, a
1590 match of the regular expression contained in the positive look-ahead
1591 construct is attempted. If it succeeds, control is passed to the next
1592 regular expression atom, but the text that was consumed by the positive
1593 look-ahead is first unmatched (backtracked) to the place in the text where
1594 the positive look-ahead was first encountered.
1596 One application of positive look-ahead is the manual implementation of a
1597 first character discrimination optimization. You can include a positive
1598 look-ahead that contains a character class which lists every character that
1599 the following (potentially complex) regular expression could possibly start
1600 with. This will quickly filter out match attempts that can not possibly
1603 3>Negative Look-Ahead
1605 Negative look-ahead takes the form `(?!<regex>)' and is exactly the same as
1606 positive look-ahead except that the enclosed regular expression must NOT
1607 match. This can be particularly useful when you have an expression that is
1608 general, and you want to exclude some special cases. Simply precede the
1609 general expression with a negative look-ahead that covers the special cases
1610 that need to be filtered out.
1612 3>Positive Look-Behind
1614 Positive look-behind constructs are of the form `(?<=<regex>)' and implement
1615 a zero width assertion of the enclosed regular expression in front of the
1616 current matching position. It is similar to a positive look-ahead assertion,
1617 except for the fact the the match is attempted on the text preceding the
1618 current position, possibly even in front of the start of the matching range
1619 of the entire regular expression.
1621 A restriction on look-behind expressions is the fact that the expression
1622 must match a string of a bounded size. In other words, `*', `+', and `{n,}'
1623 quantifiers are not allowed inside the look-behind expression. Moreover,
1624 matching performance is sensitive to the difference between the upper and
1625 lower bound on the matching size. The smaller the difference, the better the
1626 performance. This is especially important for regular expressions used in
1629 Positive look-behind has similar applications as positive look-ahead.
1631 3>Negative Look-Behind
1633 Negative look-behind takes the form `(?<!<regex>)' and is exactly the same as
1634 positive look-behind except that the enclosed regular expression must
1635 NOT match. The same restrictions apply.
1637 Note however, that performance is even more sensitive to the distance
1638 between the size boundaries: a negative look-behind must not match for
1639 **any** possible size, so the matching engine must check **every** size.
1643 There are two parenthetical constructs that control case sensitivity:
1645 (?i<regex>) Case insensitive; `AbcD' and `aBCd' are
1648 (?I<regex>) Case sensitive; `AbcD' and `aBCd' are
1651 Regular expressions are case sensitive by default, that is, `(?I<regex>)' is
1652 assumed. All regular expression token types respond appropriately to case
1653 insensitivity including character classes and backreferences. There is some
1654 extra overhead involved when case insensitivity is in effect, but only to the
1655 extent of converting each character compared to lower case.
1659 NEdit regular expressions by default handle the matching of newlines in a way
1660 that should seem natural for most editing tasks. There are situations,
1661 however, that require finer control over how newlines are matched by some
1662 regular expression tokens.
1664 By default, NEdit regular expressions will NOT match a newline character for
1665 the following regex tokens: dot (`.'); a negated character class (`[^...]');
1666 and the following shortcuts for character classes:
1668 `\d', `\D', `\l', `\L', `\s', `\S', `\w', `\W', `\Y'
1670 The matching of newlines can be controlled for the `.' token, negated
1671 character classes, and the `\s' and `\S' shortcuts by using one of the
1672 following parenthetical constructs:
1674 (?n<regex>) `.', `[^...]', `\s', `\S' match newlines
1676 (?N<regex>) `.', `[^...]', `\s', `\S' don't match
1679 `(?N<regex>)' is the default behavior.
1681 3>Notes on New Parenthetical Constructs
1683 Except for plain parentheses, none of the parenthetical constructs capture
1684 text. If that is desired, the construct must be wrapped with capturing
1685 parentheses, e.g. `((?i<regex))'.
1687 All parenthetical constructs can be nested as deeply as desired, except for
1688 capturing parentheses which have a limit of 50 sets of parentheses,
1689 regardless of nesting level.
1693 Backreferences allow you to match text captured by a set of capturing
1694 parenthesis at some later position in your regular expression. A
1695 backreference is specified using a single backslash followed by a single
1696 digit from 1 to 9 (example: \3). Backreferences have similar syntax to
1697 substitutions (see below), but are different from substitutions in that they
1698 appear within the regular expression, not the substitution string. The number
1699 specified with a backreference identifies which set of text capturing
1700 parentheses the backreference is associated with. The text that was most
1701 recently captured by these parentheses is used by the backreference to
1702 attempt a match. As with substitutions, open parentheses are counted from
1703 left to right beginning with 1. So the backreference `\3' will try to match
1704 another occurrence of the text most recently matched by the third set of
1705 capturing parentheses. As an example, the regular expression `(\d)\1' could
1706 match `22', `33', or `00', but wouldn't match `19' or `01'.
1708 A backreference must be associated with a parenthetical expression that is
1709 complete. The expression `(\w(\1))' contains an invalid backreference since
1710 the first set of parentheses are not complete at the point where the
1711 backreference appears.
1715 Substitution strings are used to replace text matched by a set of capturing
1716 parentheses. The substitution string is mostly interpreted as ordinary text
1719 The escape sequences described above for special characters, and octal and
1720 hexadecimal escapes are treated the same way by a substitution string. When
1721 the substitution string contains the `&' character, NEdit will substitute the
1722 entire string that was matched by the `Find...' operation. Any of the first
1723 nine sub-expressions of the match string can also be inserted into the
1724 replacement string. This is done by inserting a `\' followed by a digit from
1725 1 to 9 that represents the string matched by a parenthesized expression
1726 within the regular expression. These expressions are numbered left-to-right
1727 in order of their opening parentheses.
1729 The capitalization of text inserted by `&' or `\1', `\2', ... `\9' can be
1730 altered by preceding them with `\U', `\u', `\L', or `\l'. `\u' and `\l'
1731 change only the first character of the inserted entity, while `\U' and `\L'
1732 change the entire entity to upper or lower case, respectively.
1733 ----------------------------------------------------------------------
1740 Regular expression substitution can be used to program automatic editing
1741 operations. For example, the following are search and replace strings to find
1742 occurrences of the `C' language subroutine `get_x', reverse the first and
1743 second parameters, add a third parameter of NULL, and change the name to
1746 Search string: `get_x *\( *([^ ,]*), *([^\)]*)\)'
1747 Replace string: `new_get_x(\2, \1, NULL)'
1751 If a regular expression could match two different parts of the text, it will
1752 match the one which begins earliest. If both begin in the same place but
1753 match different lengths, or match the same length in different ways, life
1754 gets messier, as follows.
1756 In general, the possibilities in a list of alternatives are considered in
1757 left-to-right order. The possibilities for `*', `+', and `?' are considered
1758 longest-first, nested constructs are considered from the outermost in, and
1759 concatenated constructs are considered leftmost-first. The match that will be
1760 chosen is the one that uses the earliest possibility in the first choice that
1761 has to be made. If there is more than one choice, the next will be made in
1762 the same manner (earliest possibility) subject to the decision on the first
1763 choice. And so forth.
1765 For example, `(ab|a)b*c' could match `abc' in one of two ways. The first
1766 choice is between `ab' and `a'; since `ab' is earlier, and does lead to a
1767 successful overall match, it is chosen. Since the `b' is already spoken for,
1768 the `b*' must match its last possibility, the empty string, since it must
1769 respect the earlier choice.
1771 In the particular case where no `|'s are present and there is only one `*',
1772 `+', or `?', the net effect is that the longest possible match will be
1773 chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that
1774 if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x', due
1775 to the begins-earliest rule. (In effect, the decision on where to start the
1776 match is the first choice to be made, hence subsequent choices must respect
1777 it even if this leads them to less-preferred alternatives.)
1781 An excellent book on the care and feeding of regular expressions is
1783 Mastering Regular Expressions, 2nd Edition
1784 Jeffrey E. F. Friedl
1785 2002, O'Reilly & Associates
1787 ----------------------------------------------------------------------
1789 Example Regular Expressions
1790 ---------------------------
1792 The following are regular expression examples which will match:
1800 * Whitespace on a line.
1803 * Whitespace across lines.
1806 * Whitespace that spans at least two lines. Note minimal matching `*?' quantifier.
1809 * IP address (not robust).
1810 ! (?:\d{1,3}(?:\.\d{1,3}){3})
1812 * Two character US Postal state abbreviations (includes territories).
1813 ! [ACDF-IK-PR-W][A-Z]
1816 ! (?:http://)?www\.\S+
1818 * Case insensitive double words across line breaks.
1819 ! (?i(?n<(\S+)\s+\1>))
1821 * Upper case words with possible punctuation.
1824 ----------------------------------------------------------------------
1826 Macro/Shell Extensions
1827 ======================
1829 Shell Commands and Filters
1830 --------------------------
1832 The Shell menu (Unix versions only) allows you to execute Unix shell commands
1833 from within NEdit. You can add items to the menu to extend NEdit's command
1834 set or to incorporate custom automatic editing features using shell commands
1835 or editing languages like awk and sed. To add items to the menu, select
1836 Preferences -> Default Settings Customize Menus -> Shell Menu. NEdit comes
1837 pre-configured with a few useful Unix commands like spell and sort, but we
1838 encourage you to add your own custom extensions.
1840 Filter Selection... prompts you for a Unix command to use to process the
1841 currently selected text. The output from this command replaces the contents
1844 Execute Command... prompts you for a Unix command and replaces the current
1845 selection with the output of the command. If there is no selection, it
1846 deposits the output at the current insertion point. In the Shell Command
1847 field, the % character expands to the name (including directory path), and
1848 the # character expands to the current line number of the file in the window.
1849 To include a % or # character in the command, use %% or ##, respectively.
1851 Execute Command Line uses the position of the cursor in the window to
1852 indicate a line to execute as a shell command line. The cursor may be
1853 positioned anywhere on the line. This command allows you to use an NEdit
1854 window as an editable command window for saving output and saving commands
1855 for re-execution. Note that the same character expansions described above
1856 in Execute Command also occur with this command.
1858 The X resource called nedit.shell (See "Customizing_NEdit_") determines which
1859 Unix shell is used to execute commands. The default value for this resource
1861 ----------------------------------------------------------------------
1866 Selecting Learn Keystrokes from the Macro menu puts NEdit in learn mode. In
1867 learn mode, keystrokes and menu commands are recorded, to be played back
1868 later, using the Replay Keystrokes command, or pasted into a macro in the
1869 Macro Commands dialog of the Default Settings menu in Preferences.
1871 Note that only keyboard and menu commands are recorded, not mouse clicks or
1872 mouse movements since these have no absolute point of reference, such as
1873 cursor or selection position. When you do a mouse-based operation in learn
1874 mode, NEdit will beep (repeatedly) to remind you that the operation was not
1877 Learn mode is also the quickest and easiest method for writing macros. The
1878 dialog for creating macro commands contains a button labeled "Paste Learn /
1879 Replay Macro", which will deposit the last sequence learned into the body of
1882 3>Repeating Actions and Learn/Replay Sequences
1884 You can repeat the last (keyboard-based) command, or learn/replay sequence
1885 with the Repeat... command in the Macro menu. To repeat an action, first do
1886 the action (that is, insert a character, do a search, move the cursor), then
1887 select Repeat..., decide how or how many times you want it repeated, and
1888 click OK. For example, to move down 30 lines through a file, you could type:
1889 <Down Arrow> Ctrl+, 29 <Return>. To repeat a learn/replay sequence, first
1890 learn it, then select Repeat..., click on Learn/Replay and how you want it
1891 repeated, then click OK.
1893 If the commands you are repeating advance the cursor through the file, you
1894 can also repeat them within a range of characters, or from the current cursor
1895 position to the end of the file. To iterate over a range of characters, use
1896 the primary selection (drag the left mouse button over the text) to mark the
1897 range you want to operate on, and select "In Selection" in the Repeat dialog.
1899 When using In "Selection" or "To End" with a learned sequence, try to do
1900 cursor movement as the last step in the sequence, since testing of the cursor
1901 position is only done at the end of the sequence execution. If you do cursor
1902 movement first, for example searching for a particular word then doing a
1903 modification, the position of the cursor won't be checked until the sequence
1904 has potentially gone far beyond the end of your desired range.
1906 It's easy for a repeated command to get out of hand, and you can easily
1907 generate an infinite loop by using range iteration on a command which doesn't
1908 progress. To cancel a repeating command in progress, type Ctrl+. (period),
1909 or select Cancel Macro from the Macro menu.
1910 ----------------------------------------------------------------------
1915 Macros can be called from Macro menu commands, window background menu
1916 commands, within the smart-indent framework, from the autoload macro file and
1917 from the command line.
1918 Macro menu and window background menu commands are defined under Preferences
1919 -> Default Settings -> Customize Menus. Help on creating items in these
1920 menus can be found in the section, Help -> Customizing -> Preferences.
1922 The autoload macro file is a file of macro commands and definitions which
1923 NEdit will automatically execute when it is first started. Its location is
1924 dependent on your environment:
1926 * The default place for the file is '$HOME/.nedit/autoload.nm',
1927 * if the variable $NEDIT_HOME is set in your environment it is located at '$NEDIT_HOME/autoload.nm',
1928 * if you are using old-style run control files (i.e. $HOME/.nedit is a regular file) it is located in '$HOME/.neditmacro'.
1930 (For VMS, the file is in '$NEDIT_HOME/autoload.nm' if $NEDIT_HOME is set, in
1931 'SYS$LOGIN:.neditmacro' otherwise.)
1933 NEdit's macro language is a simple interpreter with integer arithmetic,
1934 dynamic strings, and C-style looping constructs (very similar to the
1935 procedural portion of the Unix awk program). From the macro language, you
1936 can call the same action routines which are bound to keyboard keys and menu
1937 items, as well additional subroutines for accessing and manipulating editor
1938 data, which are specific to the macro language (these are listed in the
1939 sections titled "Macro_Subroutines_", and "Action_Routines_").
1944 An NEdit macro language program consists of a list of statements, each
1945 terminated by a newline. Groups of statements which are executed together
1946 conditionally, such as the body of a loop, are surrounded by curly braces
1949 Blank lines and comments are also allowed. Comments begin with a "#" and end
1950 with a newline, and can appear either on a line by themselves, or at the end
1953 Statements which are too long to fit on a single line may be split across
1954 several lines, by placing a backslash "\" character at the end of each line
1960 The NEdit macro language recognizes only three data types, dynamic character
1961 strings, integer values and associative arrays. In general strings and
1962 integers can be used interchangeably. If a string represents an integer
1963 value, it can be used as an integer. Integers can be compared and
1964 concatenated with strings. Arrays may contain integers, strings, or arrays.
1965 Arrays are stored key/value pairs. Keys are always stored as strings.
1969 Integers are non-fractional numbers in the range of -2147483647 to
1970 2147483647. Integer constants must be in decimal. For example:
1975 4>Character String Constants
1977 Character string constants are enclosed in double quotes. For example:
1980 dialog("Hi there!", "OK")
1982 Strings may also include C-language style escape sequences:
1984 \\ Backslash \t Tab \f Form feed
1985 \" Double quote \b Backspace \a Alert
1986 \n Newline \r Carriage return \v Vertical tab
1988 Also allowed is the escape control character sequence:
1990 \e Escape (ASCII or EBCDIC,
1991 depending on NEdit compilation settings)
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")
1999 Other characters can be expressed as backslash-escape sequences in macro
2000 strings. The format is the same as for regular expressions, described in the
2001 paragraphs headed "Octal and Hex Escape Sequences" of the section
2002 "Metacharacters_", except that an octal escape sequence can start with any
2003 octal digit, not just 0, so the single character string "\0033" is the same
2004 as "\33", "\x1B" and "\e" (for an ASCII version of NEdit).
2006 Note that if you want to define a regular expression in a macro string,
2007 you need to "double-up" the backslashes for the metacharacters with
2008 special meaning in regular expressions. For example, the expression
2010 (?N(\s|/\*(?n(?:(?!\*/).)*)\*/|//.*\n|\n)+)
2012 which matches whitespace or C/C++/Java-style comments, should be written as
2015 "(?N(\\s|/\\*(?n(?:(?!\\*/).)*)\\*/|//.*\n|\n)+)"
2017 (The "\n"s towards the end add literal newline characters to the string. The
2018 regular expression interpretation treats the newlines as themselves. It can
2019 also interpret the sequence "\\n" as a newline, although the macro string here
2020 would then contain a literal backslash followed by a lowercase `N'.)
2025 Variable names must begin either with a letter (local variables), or a $
2026 (global variables). Beyond the first character, variables may also contain
2027 numbers and underscores `_'. Variables are called in to existence just by
2028 setting them (no explicit declarations are necessary).
2030 Local variables are limited in scope to the subroutine (or menu item
2031 definition) in which they appear. Global variables are accessible from all
2032 routines, and their values persist beyond the call which created them, until
2035 4>Built-in Variables
2037 NEdit has a number of permanently defined variables, which are used to access
2038 global editor information and information about the the window in which the
2039 macro is executing. These are listed along with the built in functions in
2040 the section titled "Macro_Subroutines_".
2043 3>Functions and Subroutines
2045 The syntax of a function or subroutine call is:
2047 function_name(arg1, arg2, ...)
2049 where arg1, arg2, etc. represent the argument values which are passed to
2050 the routine being called. A function or subroutine call can be on a line by
2051 itself, as above, or if it returns a value, can be invoked within a character
2052 or numeric expression:
2054 a = fn1(b, c) + fn2(d)
2055 dialog("fn3 says: " fn3())
2057 Arguments are passed by value. This means that you can not return values via
2058 the argument list, only through the function value or indirectly through
2059 agreed-upon global variables.
2061 4>Built-in Functions
2063 NEdit has a wide range of built in functions which can be called from the
2064 macro language. These routines are divided into two classes, macro-language
2065 functions, and editor action routines. Editor action routines are more
2066 flexible, in that they may be called either from the macro language, or bound
2067 directly to keys via translation tables. They are also limited, however, in
2068 that they can not return values. Macro language routines can return values,
2069 but can not be bound to keys in translation tables.
2071 Nearly all of the built-in subroutines operate on an implied window, which is
2072 initially the window from which the macro was started. To manipulate the
2073 contents of other windows, use the focus_window subroutine to change the
2074 focus to the ones you wish to modify. focus_window can also be used to
2075 iterate over all of the currently open windows, using the special keyword
2076 names, "last" and "next".
2078 For backwards compatibility, hyphenated action routine names are allowed, and
2079 most of the existing action routines names which contain underscores have an
2080 equivalent version containing hyphens ('-') instead of underscores. Use of
2081 these names is discouraged. The macro parser resolves the ambiguity between
2082 '-' as the subtraction/negation operator, and - as part of an action routine
2083 name by assuming subtraction unless the symbol specifically matches an action
2086 4>User Defined Functions
2088 Users can define their own macro subroutines, using the define keyword:
2090 define subroutine_name {
2091 < body of subroutine >
2094 Macro definitions can not appear within other definitions, or within macro
2095 menu item definitions (usually they are found in the autoload macro file).
2097 The arguments with which a user-defined subroutine or function was invoked,
2098 are presented as $1, $2, ... , $9 or $args[expr], where expr can be evaluated
2099 to an integer from 1 to the number of arguments. The number of arguments can
2100 be read from $n_args or $args[]. The array $args[expr] is the only way to
2101 access arguments beyond the first 9.
2103 To return a value from a subroutine, and/or to exit from the subroutine
2104 before the end of the subroutine body, use the return statement:
2106 return <value to return>
2109 3>Operators and Expressions
2111 Operators have the same meaning and precedence that they do in C, except for
2112 ^, which raises a number to a power (y^x means y to the x power), rather than
2113 bitwise exclusive OR. The table below lists operators in decreasing order of
2116 Operators Associativity
2122 > >= < <= == != left to right
2127 (concatenation) left to right
2128 = += -= *= /= %=, &= |= right to left
2130 The order in which operands are evaluated in an expression is undefined,
2131 except for && and ||, which like C, evaluate operands left to right, but stop
2132 when further evaluation would no longer change the result.
2134 4>Numerical Operators
2136 The numeric operators supported by the NEdit macro language are listed below:
2139 - subtraction or negation
2147 Increment (++) and decrement (--) operators can also be appended or prepended
2148 to variables within an expression. Prepended increment/decrement operators
2149 act before the variable is evaluated. Appended increment/decrement operators
2150 act after the variable is evaluated.
2152 4>Logical and Comparison Operators
2154 Logical operations produce a result of 0 (for false) or 1 (for true). In a
2155 logical operation, any non-zero value is recognized to mean true. The
2156 logical and comparison operators allowed in the NEdit macro language are
2166 == equal (integers and/or strings)
2167 != not equal (integers and/or strings)
2169 4>Character String Operators
2171 The "operator" for concatenating two strings is the absence of an operator.
2172 Adjoining character strings with no operator in between means concatenation:
2175 t_print("the value of a is: " a)
2177 Comparison between character strings is done with the == and != operators,
2178 (as with integers). There are a number of useful built-in routines for
2179 working with character strings, which are listed in the section called
2180 "Macro_Subroutines_".
2182 4>Arrays and Array Operators
2184 Arrays may contain either strings, integers, or other arrays. Arrays are
2185 associative, which means that they relate two pieces of information, the key
2186 and the value. The key is always a string; if you use an integer it is
2187 converted to a string.
2189 To determine if a given key is in an array, use the 'in' keyword.
2194 If the left side of the in keyword is an array, the result is true if every
2195 key in the left array is in the right array. Array values are not compared.
2197 To iterate through all the keys of an array use the 'for' looping construct.
2198 Keys are not guaranteed in any particular order:
2203 Elements can be removed from an array using the delete command:
2205 delete x[3] # deletes element with key 3
2206 delete x[] # deletes all elements
2208 The number of elements in an array can be determined by referencing the
2209 array with no indices:
2211 dialog("array x has " x[] " elements", "OK")
2213 Arrays can be combined with some operators. All the following operators only
2214 compare the keys of the arrays.
2216 result = x + y (Merge arrays)
2218 The 'result' is a new array containing keys from both x and y. If
2219 duplicates are present values from y are used.
2221 result = x - y (Remove keys)
2223 The 'result' is a new array containing all keys from x that are not in y.
2225 result = x & y (Common keys)
2227 The 'result' is a new array containing all keys which are in both x and y.
2228 The values from y are used.
2230 result = x | y (Unique keys)
2232 The 'result' is a new array containing keys which exist in either x or y,
2235 When duplicate keys are encountered using the + and & operators, the values
2236 from the array on the right side of the operators are used for the result.
2237 All of the above operators are array only, meaning both the left and right
2238 sides of the operator must be arrays. The results are also arrays.
2240 Array keys can also contain multiple dimensions:
2242 x[1, 1, 1] = "string"
2244 These are used in the expected way, e.g.:
2246 for (i = 1; i < 3; i++)
2248 for (j = 1; j < 3; j++)
2254 gives the following array:
2261 Internally all indices are part of one string, separated by the string
2262 $sub_sep (ASCII 0x1c, 'FS'). The first key in the above example is in
2267 If you need to extract one of the keys, you can use split(), using
2268 $sub_sep as the separator.
2270 You can also check for the existence of multi-dimensional array by
2271 looking for $sub_sep in the key.
2273 Last, you need $sub_sep if you want to use the 'in' keyword.
2275 if ((1,2) in myArray)
2280 if (("1" $sub_sep "2") in myArray)
2285 3>Looping and Conditionals
2287 NEdit supports looping constructs: for and while, and conditional statements:
2288 if and else, with essentially the same syntax as C:
2290 for (<init>, ...; <condition>; <increment>, ...) <body>
2292 while (<condition>) <body>
2294 if (<condition>) <body>
2296 if (<condition>) <body> else <body>
2298 <body>, as in C, can be a single statement, or a list of statements enclosed
2299 in curly braces ({}). <condition> is an expression which must evaluate to
2300 true for the statements in <body> to be executed. for loops may also contain
2301 initialization statements, <init>, executed once at the beginning of the
2302 loop, and increment/decrement statements (or any arbitrary statement), which
2303 are executed at the end of the loop, before the condition is evaluated again.
2307 for (i=0; i<100; i++)
2310 for (i=0, j=20; i<20; i++, j--) {
2326 Loops may contain break and continue statements. A break statement causes an
2327 exit from the innermost loop, a continue statement transfers control to the
2329 ----------------------------------------------------------------------
2334 3>Built in Variables
2336 These variables are read-only and can not be changed.
2338 **$1**, **$2**, **$3**, **$4**, **$5**, **$6**, **$7**, **$8**, **$9**
2341 Argument information. The first 9 arguments (if there are that many) can
2342 be referenced as read-only values using the shorthand form. All arguments
2343 can be accessed as values in the **$args** array, using a numeric index
2344 starting at 1. The total number of arguments received by a function is
2345 given by **$n_args** or **$args[]**.
2348 Index of the current pane.
2351 Contains the current preference for auto indent.
2352 Can be "off", "on" or "auto".
2355 Equals the ID of the currently displayed calltip, or 0 if no calltip is
2359 Position of the cursor in the current window.
2362 Column number of the cursor position in the current window.
2365 Width of the current pane in pixels.
2368 If tab emulation is turned on in the Tabs...
2369 dialog of the Preferences menu, value is the
2370 distance between emulated tab stops. If tab
2371 emulation is turned off, value is -1.
2374 An array with no elements. This can be used to initialize
2375 an array to an empty state.
2378 Current newline format that the file will be saved with. Can
2379 be "unix", "dos" or "macintosh".
2382 Name of the file being edited in the current
2383 window, stripped of directory component.
2386 Directory component of file being edited in the current window.
2389 Contains the current plain text font name.
2392 Contains the current bold text font name.
2394 **$font_name_bold_italic**
2395 Contains the current bold-italic text font name.
2397 **$font_name_italic**
2398 Contains the current italic text font name.
2400 **$highlight_syntax**
2401 Whether syntax highlighting is turned on.
2403 **$incremental_backup**
2404 Contains 1 if incremental auto saving is on, otherwise 0.
2406 **$incremental_search_line**
2407 Has a value of 1 if the preference is
2408 selected to always show the incremental search line, otherwise 0.
2411 Name of language mode set in the current window.
2414 Line number of the cursor position in the current window.
2417 True if the file has been locked by the user.
2419 **$make_backup_copy**
2420 Has a value of 1 if original file is kept in a
2421 backup file on save, otherwise 0.
2424 The maximum font width of all the active styles.
2425 Syntax highlighting styles are only considered if syntax highlighting
2429 The minimum font width of all the active styles.
2430 Syntax highlighting styles are only considered if syntax highlighting
2434 True if the file in the current window has
2435 been modified and the modifications have not
2438 **$n_display_lines**
2439 The number of lines visible in the currently active pane.
2442 The number of panes in the current window.
2445 True if in Overtype mode.
2448 True if the file is read only.
2450 **$selection_start, $selection_end**
2451 Beginning and ending positions of the
2452 primary selection in the current window, or
2453 -1 if there is no text selected in the current window.
2455 **$selection_left, $selection_right**
2456 Left and right character offsets of the rectangular (primary) selection in
2457 the current window, or -1 if there is no selection or it is not rectangular.
2460 Name of the current NEdit server.
2462 **$show_line_numbers**
2463 Whether line numbers are shown next to the text.
2466 Contains the current preference for showing matching pairs,
2467 such as "[]" and "{}" pairs. Can be "off", "delimiter", or "range".
2469 **$match_syntax_based**
2470 Whether pair matching should use syntax information, if available.
2472 **$statistics_line**
2473 Has a value of 1 if the statistics line is shown, otherwise 0.
2476 Contains the value of the array sub-script separation string.
2479 The distance between tab stops for a
2480 hardware tab character, as set in the
2481 Tabs... dialog of the Preferences menu.
2484 The length of the text in the current window.
2487 The line number of the top line of the currently active pane.
2490 Whether the user is allowing the NEdit to insert tab characters to maintain
2491 spacing in tab emulation and rectangular dragging operations. (The setting of
2492 the "Use tab characters in padding and emulated tabs" button in the Tabs...
2493 dialog of the Preferences menu.)
2496 The right margin in the current window for text wrapping and filling.
2499 The current wrap text mode. Values are "none", "auto" or "continuous".
2501 ..Disabled for 5.4 release.
2502 ..**$backlight_string**
2503 .. The current value of the window's backlighting specification. This is empty
2504 .. if backlighting is turned off. It can be changed through calls to the
2505 .. built-in macro function set_backlight_string().
2508 3>Built-in Subroutines
2510 **append_file( string, filename )**
2511 Appends a string to a named file. Returns 1 on successful write, or 0 if
2517 **calltip( "text_or_key" [, pos [, mode or position_modifier, ...]] )**
2518 Pops up a calltip. <pos> is an optional position in the buffer where the tip
2519 will be displayed. Passing -1 for <pos> is equivalent to not specifying a
2520 position, and it guarantees that the tip will appear on-screen somewhere even
2521 if the cursor is not. The upper-left corner of the calltip will appear below
2522 where the cursor would appear if it were at this position. <mode> is one of
2523 "tipText" (default), "tipKey", or "tagKey". "tipText" displays the text as-is,
2524 "tagKey" uses it as the key to look up a tag, then converts the tag to a
2525 calltip, and "tipKey" uses it as the key to look up a calltip, then falls back
2526 to "tagKey" behavior if that fails. You'll usually use "tipKey" or "tipText".
2527 Finally, you can modify the placement of the calltip relative to the cursor
2528 position (or <pos>) with one or more of these optional position modifiers:
2529 "center" aligns the center of the calltip with the position. "right" aligns
2530 the right edge of the calltip with the position. ("center" and "right" may
2531 not both be used.) "above" places the calltip above the position. "strict"
2532 does not allow the calltip to move from its position in order to avoid going
2533 off-screen or obscuring the cursor. Returns the ID of the calltip if it was
2534 found and/or displayed correctly, 0 otherwise.
2536 **clipboard_to_string()**
2537 Returns the contents of the clipboard as a macro string. Returns empty
2540 **dialog( message, btn_1_label, btn_2_label, ... )**
2541 Pop up a dialog for querying and presenting information to the user. First
2542 argument is a string to show in the message area of the dialog.
2543 Additional optional arguments represent labels for buttons to appear along
2544 the bottom of the dialog. Returns the number of the button pressed (the
2545 first button is number 1), or 0 if the user closed the dialog via the window
2548 **focus_window( window_name )**
2549 Sets the window on which subsequent macro commands operate. window_name can
2550 be either a fully qualified file name, or a relative filename (which will
2551 be completed from NEdit's working directory) or one of "last" for the last
2552 window created, or "next" for the next window in the chain from the currently
2553 focused window (the first window being the one returned from calling
2554 focus_window("last"). Returns the name of the newly-focused window, or an
2555 empty string if the requested window was not found.
2557 **get_character( position )**
2558 Returns the single character at the position
2559 indicated by the first argument to the routine from the current window.
2561 **get_range( start, end )**
2562 Returns the text between a starting and ending position from the current
2566 Returns a string containing the text currently selected by the primary
2567 selection either from the current window (no keyword), or from anywhere on
2568 the screen (keyword "any").
2571 Gets the value of an environment variable.
2573 **kill_calltip( [calltip_ID] )**
2574 Kills any calltip that is being displayed in the window in which the macro is
2575 running. If there is no displayed calltip this does nothing. If a calltip
2576 ID is supplied then the calltip is killed only if its ID is calltip_ID.
2578 **length( string )**
2579 Returns the length of a string
2581 **list_dialog( message, text, btn_1_label, btn_2_label, ... )**
2582 Pop up a dialog for prompting the user to choose a line from the given text
2583 string. The first argument is a message string to be used as a title for the
2584 fixed text describing the list. The second string provides the list data:
2585 this is a text string in which list entries are separated by newline
2586 characters. Additional optional arguments represent labels for
2587 buttons to appear along the bottom of the dialog. Returns the line of text
2588 selected by the user as the function value (without any newline separator) or
2589 the empty string if none was selected, and number of the button pressed (the
2590 first button is number 1), in $list_dialog_button. If the user closes the
2591 dialog via the window close box, the function returns the empty string, and
2592 $list_dialog_button returns 0.
2594 **max( n1, n2, ... )**
2595 Returns the maximum value of all of its arguments
2597 **min( n1, n2, ... )**
2598 Returns the minimum value of all of its arguments
2600 **read_file( filename )**
2601 Reads the contents of a text file into a string. On success, returns 1 in
2602 $read_status, and the contents of the file as a string in the subroutine
2603 return value. On failure, returns the empty string "" and an 0 $read_status.
2605 **replace_in_string( string, search_for, replace_with [, type, "copy"] )**
2606 Replaces all occurrences of a search string in a string with a replacement
2607 string. Arguments are 1: string to search in, 2: string to search for, 3:
2608 replacement string. There are two optional arguments. One is a search type,
2609 either "literal", "case", "word", "caseWord", "regex", or "regexNoCase".
2610 The default search type is "literal". If the optional "copy" argument is
2611 specified, a copy of the input string is returned when no replacements were
2612 performed. By default an empty string ("") will be returned in this case.
2613 Returns a new string with all of the replacements done.
2615 **replace_range( start, end, string )**
2616 Replaces all the text between two positions in the current window. If the
2617 cursor position is between start and end it will be set to start.
2619 **replace_selection( string )**
2620 Replaces the primary-selection selected text in the current window.
2622 **replace_substring( string, start, end, replace_with )**
2623 Replacing a substring between two positions in a string within another string.
2625 **search( search_for, start [, search_type, wrap, direction] )**
2626 Searches silently in a window without dialogs, beeps, or changes to the
2627 selection. Arguments are: 1: string to search for, 2: starting position.
2628 Optional arguments may include the strings: "wrap" to make the search wrap
2629 around the beginning or end of the string, "backward" or "forward" to change
2630 the search direction ("forward" is the default), "literal", "case", "word",
2631 "caseWord", "regex", or "regexNoCase" to change the search type (default is
2632 "literal"). Returns the starting position of the match, or -1 if nothing
2633 matched. Also returns the ending position of the match in $search_end.
2635 **search_string( string, search_for, start [, search_type, direction] )**
2637 Built-in macro subroutine for searching a string. Arguments are 1: string to
2638 search in, 2: string to search for, 3: starting position. Optional arguments
2639 may include the strings: "wrap" to make the search wrap around the beginning
2640 or end of the string, "backward" or "forward" to change the search direction
2641 ("forward" is the default), "literal", "case", "word", "caseWord", "regex",
2642 or "regexNoCase" to change the search type (default is "literal"). Returns
2643 the starting position of the match, or -1 if nothing matched. Also returns
2644 the ending position of the match in $search_end.
2646 **select( start, end )**
2647 Selects (with the primary selection) text in the current buffer between a
2648 starting and ending position.
2650 **select_rectangle( start, end, left, right )**
2651 Selects a rectangular area of text between a starting and ending position,
2652 and confined horizontally to characters displayed between positions "left",
2655 ..Disabled for 5.4 release.
2656 ..**set_backlight_string( [string] )**
2657 .. Applies the given string, which should be in the format of the
2658 .. nedit*backlightCharTypes X resource, to the current text window, turning on
2659 .. backlighting. If the value of the string passed is "default", or if no
2660 .. parameter is passed, the nedit.backlightCharTypes X resource's own value will
2661 .. be used. If the empty string, "", is passed, backlighting will be turned
2664 **set_cursor_pos( position )**
2665 Set the cursor position for the current window.
2667 **shell_command( command, input_string )**
2668 Executes a shell command, feeding it input from input_string. On completion,
2669 output from the command is returned as the function value, and the command's
2670 exit status is returned in the global variable $shell_cmd_status.
2672 **split(string, separation_string [, search_type])**
2673 Splits a string using the separator specified. Optionally the search_type
2674 argument can specify how the separation_string is interpreted. The default
2675 is "literal". The returned value is an array with keys beginning at 0.
2677 **string_dialog( message, btn_1_label, btn_2_label, ... )**
2678 Pops up a dialog prompting the user to enter information. The first argument
2679 is a string to show in the message area of the dialog. Additional
2680 optional arguments represent labels for buttons to appear along the bottom of
2681 the dialog. Returns the string entered by the user as the function value,
2682 and number of the button pressed (the first button is number 1), in
2683 $string_dialog_button. If the user closes the dialog via the window close
2684 box, the function returns the empty string, and $string_dialog_button returns
2687 **string_compare(string1, string2 [, consider-case])**
2688 Compare two strings and return 0 if they are equal, -1 if string1 is less
2689 than string2 or 1 if string1 is greater than string2. The values for the
2690 optional consider-case argument is either "case" or "nocase". The default
2691 is to do a case sensitive comparison.
2693 **string_to_clipboard( string )**
2694 Copy the contents of a macro string to the clipboard.
2696 **substring( string, start [, end] )**
2697 Returns the portion of a string between a start and end position (with the
2698 position of the beginning of the string being 0). If end is missing, the
2699 position of the end of the string is used. If either of the positions are
2700 negative, they are treated as relative to the end of the string. A position
2701 specified either before the start of the string or after the end of the string
2702 is repositioned to the nearest valid string position. If the start position
2703 is beyond the end position, the empty string is returned.
2705 **t_print( string1, string2, ... )**
2706 Writes strings to the terminal (stdout) from which NEdit was started.
2708 **tolower( string )**
2709 Return an all lower-case version of string.
2711 **toupper( string )**
2712 Return an all upper-case version of string.
2714 **valid_number( string )**
2715 Returns 1 if the string can be converted to a number without error
2716 following the same rules that the implicit conversion would. Otherwise 0.
2718 **write_file( string, filename )**
2719 Writes a string (parameter 1) to a file named in parameter 2. Returns 1 on
2720 successful write, or 0 if unsuccessful.
2723 3>Deprecated Functions
2725 Some functions are included only for supporting legacy macros. You should not
2726 use any of these functions in any new macro you write. Among these are all
2727 action routines with hyphens in their names; use underscores instead
2728 ('find-dialog' -> 'find_dialog').
2731 **DEPRECATED** Use select_to_matching() instead.
2733 ----------------------------------------------------------------------
2738 A rangeset is a set of ranges. A range is a contiguous range of characters
2739 defined by its start and end position in the document. The user can
2740 create rangesets, identified by arbitrary integers (chosen by the editor when
2741 the rangesets are created), and each range within a rangeset is identified by
2742 a numeric index, counting from 1, in the order of appearance in the text
2743 buffer. The ranges are adjusted when modifications are made to the text
2744 buffer: they shuffle around when characters are added or deleted. However,
2745 ranges within a set will coalesce if the characters between them are removed,
2746 or a new range is added to the set which bridges or overlaps others.
2748 Using rangesets allows non-contiguous bits of the text to be identified as a
2751 Rangesets can be assigned a background color: characters within a range of a
2752 rangeset will have the background color of the rangeset. If more than one
2753 rangeset includes a given character, its background color will be that of the
2754 most recently created rangeset which has a color defined.
2756 Rangesets must be created using the rangeset_create() function, which
2757 will return an identifier for the newly-created rangeset. This identifier
2758 is then passed to the other rangeset functions to manipulate the rangeset.
2760 There is a limit to the number of rangesets which can exist at any time -
2761 currently up to 63 in each document. Care should be taken to destroy
2762 any rangesets which are no longer needed, by using the rangeset_destroy()
2763 function, if this limit is attained.
2765 Rangesets can be named: this is useful for macros which need a fixed
2766 identification for rangesets which are used for the same purpose in
2767 different documents. Although a new rangeset's number is arbitrary, its
2768 name can be fixed. This is done using the rangeset_set_name() function.
2769 Note that rangeset names within a particular document may not be unique.
2770 For this reason, the rangeset_get_by_name() function returns an array of
2771 identifiers, which will be empty if the name has not been associated with
2774 4>How rangesets change with modifications
2776 When changes are made to the document text, ranges within each set are altered
2777 with it, according to their behavioral mode. If changes are made outside of
2778 the ranges in a rangeset, each range simply maintains its size and adjusts its
2779 position to match the changes. When text within a range is deleted, the
2780 range's length is reduced by the same amount. When changes involving new text
2781 are made within a range of the set, or to one of the extremities of a range,
2782 different behaviours may be desirable. The rangeset_set_mode() function allows
2783 these modes to be chosen.
2785 Note that the precise behaviour of these modes may change in future versions
2788 The available modes are:
2790 **maintain** or **ins_del** -
2791 Both these modes have the same behaviour. New text added at the front of a
2792 range in a set is not added to the range; new text added within the range or
2793 at the end extends the range. Replacement overlapping an extremity of the
2794 set acts as if the new text were added first, then the old text deleted.
2795 This causes curtailment at the front of the range, extension at the end.
2796 Replacement of the full text of the range removes the range from the set.
2797 The default behaviour for a newly created rangeset is **maintain**.
2800 New text added at the front or end of a range in a set is not added to the
2801 range; new text added within the range extends the range. Replacement
2802 overlapping an extremity of the set acts as if the old text were deleted
2803 first, then the new text added. This causes curtailment at either end.
2804 Replacement of the full text of the range removes the range from the set.
2807 New text added at the front or end of a range in a set extends the range, as
2808 does new text added within the range. Replacement overlapping an extremity
2809 of the set acts as if the new text were added first, then the old text
2810 deleted. This causes curtailment at the front of the range, extension at
2811 the end. Replacement of the full text of the range adds the new text to the
2812 range if the start position of the replacement is at the range's start
2816 New text added at the front or end of a range in a set does not extend the
2817 range; new text added within the range extends the range. Replacement
2818 overlapping an extremity causes curtailment of the range. Replacement of
2819 the full text of the range removes the range from the set.
2822 New text added at the front or end of a range in a set does not extend the
2823 range; new text added within the range will split the range. Replacement
2824 overlapping an extremity causes curtailment of the range. Replacement of
2825 the full text of the range removes the range from the set.
2829 A rangeset is manipulated ~only~ through macro routines. Rangesets
2830 can easily become very large, and may exceed the capacity of the running
2831 process. Coloring relies on proper color names or specifications (such as
2832 the "#rrggbb" hexadecimal digit strings), and appropriate hardware support. If
2833 an invalid color name is given, the default background color is used instead.
2834 Behaviours set using rangeset_set_mode() are subject to change in future
2837 3>Rangeset read-only variables
2840 array of active rangeset identifiers, with integer keys starting at 0,
2841 in the order the rangesets were defined.
2844 3>Rangeset functions
2846 **rangeset_create()**
2847 **rangeset_create( n )**
2848 Creates one or more new rangesets. The first form creates a single range
2849 set and returns its identifier; if there are no rangesets available it
2850 returns 0. The second form creates n new rangesets, and returns an array
2851 of the rangeset identifiers with keys beginning at 0. If the requested
2852 number of rangesets is not available it returns an empty array.
2854 **rangeset_destroy( r )**
2855 **rangeset_destroy( array )**
2856 Deletes all information about a rangeset or a number of rangesets. The
2857 first form destroys the rangeset identified by r. The second form should
2858 be passed an array of rangeset identifiers with keys beginning at 0 (i.e.
2859 the same form of array returned by rangeset_create(n); it destroys all the
2860 rangesets appearing in the array. If any of the rangesets do not exist,
2861 the function continues without errors. Does not return a value.
2863 **rangeset_add( r, [start, end] )**
2864 **rangeset_add( r, r0 )**
2865 Adds to the rangeset r. The first form adds the range identified by the
2866 current primary selection to the rangeset, unless start and end are defined,
2867 in which case the range they define is added. Returns the index of the
2868 newly-added range within the rangeset. The second form adds all ranges in
2869 the rangeset r0 to the rangeset r, and returns 0.
2871 **rangeset_subtract( r, [start, end] )**
2872 **rangeset_subtract( r, r0 )**
2873 Removes from the rangeset r. The first form removes the range identified by
2874 the current primary selection from the rangeset, unless start and end are
2875 defined, in which case the range they define is removed. The second form
2876 removes all ranges in the rangeset r0 from the rangeset r. Does not return
2879 **rangeset_invert( r )**
2880 Changes the rangeset r so that it contains all ranges not in r. Does not
2883 **rangeset_get_by_name( name )**
2884 Returns an array of active rangeset identifiers, with integer keys starting at 0,
2885 whose name matches name.
2887 **rangeset_info( r )**
2888 Returns an array containing information about the rangeset r. The array
2889 has the following keys: **defined** (whether a rangeset with identifier
2890 r is defined), **count** (the number of ranges in the rangeset), **color**
2891 (the current background color of the rangeset, an empty string if the
2892 rangeset has no color), **name** (the user supplied name of the rangeset,
2893 an empty string if the rangeset has no name), and **mode** (the name of the
2894 modify-response mode of the rangeset).
2896 **rangeset_range( r, [index] )**
2897 Returns details of a specific range in the rangeset r. The range is
2898 specified by index, which should be between 1 and n (inclusive), where
2899 n is the number of ranges in the rangeset. The return value is an array
2900 containing the keys **start** (the start position of the range) and **end**
2901 (the end position of the range). If index is not supplied, the region
2902 returned is the span of the entire rangeset (the region starting at the
2903 start of the first range and ending at the end of the last). If index
2904 is outside the correct range of values, the function returns an empty array.
2906 **rangeset_includes( r, pos )**
2907 Returns the index of the range in rangeset r which includes pos; returns
2908 0 if pos is not contained in any of the ranges of r. This can also be used
2909 as a simple true/false function which returns true if pos is contained in
2912 **rangeset_set_color( r, color )**
2913 Attempts to apply the color as a background color to the ranges of r. If
2914 color is at empty string, removes the coloring of r. No check is made
2915 regarding the validity of color: if the color is invalid (a bad name,
2916 or not supported by the hardware) this has unpredictable effects.
2918 **rangeset_set_name( r, name )**
2919 Apply the name to the rangeset r.
2921 **rangeset_set_mode( r, type )**
2922 Changes the behaviour of the rangeset r when modifications to the text
2923 buffer occur. type can be one of the following: "maintain" (the default),
2924 "break", "include", "exclude", "ins_del" or "del_ins". (These modes are
2928 Highlighting Information
2929 ------------------------
2931 The user can interrogate the current window to determine the color
2932 highlighting used on a particular piece of text. The following functions
2933 provide information on the highlighting pattern against which text at a
2934 particular position has been matched, its style, color and font attributes
2935 (whether the font is supposed to be bold and/or italic).
2937 These macro functions permit macro writers to generate formatted output which
2938 allows NEdit highlighting to be reproduced. This is suitable for the
2939 generation of HTML or Postscript output, for example.
2941 Note that if any of the functions is used while in Plain mode or while syntax
2942 highlighting is off, the behaviour is undefined.
2944 **get_pattern_by_name( pattern_name )**
2945 Returns an array containing the pattern attributes for pattern 'pattern_name'.
2946 The elements in this array are:
2948 * **style** -- Highlight style name
2950 If 'pattern_name' is invalid, an empty array is returned.
2952 **get_pattern_at_pos( pos )**
2953 Returns an array containing the pattern attributes of the character at
2954 position 'pos'. The elements in this array are:
2956 * **pattern** -- Highlight pattern name
2957 * **style** -- Highlight style name
2958 * **extent** -- The length in the text which uses the same highlighting pattern
2960 The 'extent' value is measured from position 'pos' going right/down (forward
2963 If 'pos' is invalid, an empty array is returned.
2965 **get_style_by_name( style_name )**
2966 Returns an array containing the style attributes for style 'style_name'.
2967 The elements in this array are:
2969 * **bold** -- '1' if style is bold, '0' otherwise
2970 * **italic** -- '1' if style is italic, '0' otherwise
2971 * **color** -- Name of the style's color
2972 * **background** -- Name of the background color, if any
2974 The colors use the names specified in the color definitions for the style.
2975 These will either be names matching those the X server recognises, or RGB
2976 (red/green/blue) specifications.
2978 If 'style_name' is invalid, an empty array is returned.
2980 **get_style_at_pos( pos )**
2981 Returns an array containing the style attributes of the character at
2982 position 'pos'. The elements in this array are:
2984 * **style** -- Name of the highlight style
2985 * **bold** -- '1' if style is bold, '0' otherwise
2986 * **italic** -- '1' if style is italic, '0' otherwise
2987 * **color** -- Name of the style's color
2988 * **rgb** -- Color's RGB values ('#rrggbb')
2989 * **background** -- Name of the background color, if any
2990 * **back_rgb** -- Background color's RGB values ('#rrggbb')
2991 * **extent** -- The length in the text which uses the same highlight style
2993 The colors use the names specified in the color definitions for the style.
2994 These will either be names matching those the X server recognises, or RGB
2995 specifications. The values for 'rgb' and 'back_rgb' contain the actual color
2996 values allocated by the X server for the window. If the X server cannot
2997 allocate the specified (named) color exactly, the RGB values in these
2998 entries may not match the specified ones.
3000 The 'extent' value is measured from position 'pos' going right/down (forward
3003 If 'pos' is invalid, an empty array is returned.
3005 ----------------------------------------------------------------------
3010 All of the editing capabilities of NEdit are represented as a special type of
3011 subroutine, called an action routine, which can be invoked from both macros
3012 and translation table entries (see "Key_Binding_" in the
3013 Customizing section of the Help menu).
3016 3>Actions Representing Menu Commands
3018 File Menu Search Menu
3019 ----------------------- -------------------------
3021 open() find_dialog()
3022 open_dialog() find_again()
3023 open_selected() find_selection()
3025 save() replace_dialog()
3026 save_as() replace_all()
3027 save_as_dialog() replace_in_selection()
3028 revert_to_saved() replace_again()
3029 include_file() goto_line_number()
3030 include_file_dialog() goto_line_number_dialog()
3031 load_macro_file() goto_selected()
3032 load_macro_file_dialog() mark()
3033 load_tags_file() mark_dialog()
3034 load_tags_file_dialog() goto_mark()
3035 unload_tags_file() goto_mark_dialog()
3036 load_tips_file() goto_matching()
3037 load_tips_file_dialog() select_to_matching()
3038 unload_tips_file() find_definition()
3042 -------------------------
3043 Edit Menu filter_selection_dialog()
3044 ----------------------- filter_selection()
3045 undo() execute_command()
3046 redo() execute_command_dialog()
3047 delete() execute_command_line()
3048 select_all() shell_menu_command()
3050 shift_left_by_tab() Macro Menu
3051 shift_right() -------------------------
3052 shift_right_by_tab() macro_menu_command()
3053 uppercase() repeat_macro()
3054 lowercase() repeat_dialog()
3056 control_code_dialog() Windows Menu
3057 -------------------------
3061 move_document_dialog()
3064 An action representing a menu command is usually named the same as its
3065 corresponding menu item except that all punctuation is removed, all letters
3066 are changed to lower case, and spaces are replaced with underscores. To
3067 present a dialog to ask the user for input, use the actions with the
3068 `_dialog` suffix. Actions without the `_dialog` suffix take the information
3069 from the routine's arguments (see below).
3071 3>Menu Action Routine Arguments
3073 Arguments are text strings enclosed in quotes. Below are the menu action
3074 routines which take arguments. Optional arguments are enclosed in [].
3076 **new**( ["tab" | "window" | "prefs" | "opposite"] )
3078 **close**( ["prompt" | "save" | "nosave"] )
3080 **execute_command**( shell-command )
3082 **filter_selection**( shell-command )
3084 **find**( search-string [, ~search-direction~] [, ~search-type~]
3087 **find_again**( [~search-direction~] [, ~search-wrap~] )
3089 **find_definition**( [tag-name] )
3091 **find_dialog**( [~search-direction~] [, ~search-type~]
3094 **find_selection**( [~search-direction~] [, ~search-wrap~]
3095 [, ~non-regex-search-type~] )
3097 **goto_line_number**( [~line-number~] [, ~column-number~] )
3099 **goto_mark**( ~mark-letter~ )
3101 **include_file**( ~filename~ )
3103 **load_tags_file**( ~filename~ )
3105 **macro_menu_command**( ~macro-menu-item-name~ )
3107 **mark**( ~mark-letter~ )
3109 **open**( ~filename~ )
3111 **replace**( search-string, replace-string,
3112 [, ~search-direction~] [, ~search-type~] [, ~search-wrap~] )
3114 **replace_again**( [~search-direction~] [, ~search-wrap~] )
3116 **replace_all**( search-string, replace-string [, ~search-type~] )
3118 **replace_dialog**( [~search-direction~] [, ~search-type~]
3121 **replace_in_selection**( search-string,
3122 replace-string [, ~search-type~] )
3124 **save_as**( ~filename~ )
3126 **shell_menu_command**( ~shell-menu-item-name~ )
3128 **unload_tags_file**( ~filename~ )
3130 **----------- Some notes on argument types above -----------**
3132 ~Arguments to new()~
3133 "tab": Open a new tab
3134 "window": Open a new window
3135 "prefs": Follow the user's tab/window
3137 "opposite": Opposite of user's tab/window
3139 Default behaviour is "prefs".
3141 ~filename~ Path names are relative to the directory from
3142 which NEdit was started. Shell interpreted
3143 wildcards and `~' are not expanded.
3145 ~keep-dialog~ Either "keep" or "nokeep".
3147 ~mark-letter~ The mark command limits users to single
3148 letters. Inside of macros, numeric marks are
3149 allowed, which won't interfere with marks set
3152 ~macro-menu-item-name~
3153 Name of the command exactly as specified in
3154 the Macro Menu dialogs.
3156 ~non-regex-search-type~
3157 Either "literal", "case", "word", or
3161 Either "forward" or "backward".
3163 ~search-type~ Either "literal", "case", "word",
3164 "caseWord", "regex", or "regexNoCase".
3166 ~search-wrap~ Either "wrap" or "nowrap".
3168 ~shell-menu-item-name~
3169 Name of the command exactly as specified in
3170 the Shell Menu dialogs.
3172 3>Window Preferences Actions
3174 **set_auto_indent( "off" | "on" | "smart" )**
3175 Set auto indent mode for the current window.
3177 **set_em_tab_dist( em-tab-distance )**
3178 Set the emulated tab size. An em-tab-distance value of
3179 0 or -1 translates to no emulated tabs. Em-tab-distance must
3180 be smaller than 1000.
3182 **set_fonts( font-name, italic-font-name, bold-font-name, bold-italic-font-name )**
3183 Set all the fonts used for the current window.
3185 **set_highlight_syntax( [0 | 1] )**
3186 Set syntax highlighting mode for the current window.
3187 A value of 0 turns it off and a value of 1 turns it on.
3188 If no parameters are supplied the option is toggled.
3190 **set_incremental_backup( [0 | 1] )**
3191 Set incremental backup mode for the current window.
3192 A value of 0 turns it off and a value of 1 turns it on.
3193 If no parameters are supplied the option is toggled.
3195 **set_incremental_search_line( [0 | 1] )**
3196 Show or hide the incremental search line for the current window.
3197 A value of 0 turns it off and a value of 1 turns it on.
3198 If no parameters are supplied the option is toggled.
3200 **set_language_mode( language-mode )**
3201 Set the language mode for the current window. If the language mode is
3202 "" or unrecognized, it will be set to Plain.
3204 **set_locked( [0 | 1] )**
3205 This only affects the locked status of a file, not it's read-only
3206 status. Permissions are NOT changed.
3207 A value of 0 turns it off and a value of 1 turns it on.
3208 If no parameters are supplied the option is toggled.
3210 **set_make_backup_copy( [0 | 1] )**
3211 Set whether backup copies are made during saves for the current window.
3212 A value of 0 turns it off and a value of 1 turns it on.
3213 If no parameters are supplied the option is toggled.
3215 **set_overtype_mode( [0 | 1] )**
3216 Set overtype mode for the current window.
3217 A value of 0 turns it off and a value of 1 turns it on.
3218 If no parameters are supplied the option is toggled.
3220 **set_show_line_numbers( [0 | 1] )**
3221 Show or hide line numbers for the current window.
3222 A value of 0 turns it off and a value of 1 turns it on.
3223 If no parameters are supplied the option is toggled.
3225 **set_show_matching( "off" | "delimiter" | "range" )**
3226 Set show matching (...) mode for the current window.
3228 **set_match_syntax_based( [0 | 1] )**
3229 Set whether matching should be syntax based for the current window.
3231 **set_statistics_line( [0 | 1] )**
3232 Show or hide the statistics line for the current window.
3233 A value of 0 turns it off and a value of 1 turns it on.
3234 If no parameters are supplied the option is toggled.
3236 **set_tab_dist( tab-distance )**
3237 Set the size of hardware tab spacing. Tab-distance must
3238 must be a value greater than 0 and no greater than 20.
3240 **set_use_tabs( [0 | 1] )**
3241 Set whether tabs are used for the current window.
3242 A value of 0 turns it off and a value of 1 turns it on.
3243 If no parameters are supplied the option is toggled.
3245 **set_wrap_margin( wrap-width )**
3246 Set the wrap width for text wrapping of the current window. A value
3247 of 0 means to wrap at window width.
3249 **set_wrap_text( "none" | "auto" | "continuous" )**
3250 Set wrap text mode for the current window.
3252 3>Keyboard-Only Actions
3254 In addition to the arguments listed in the call descriptions below, any
3255 routine involving cursor movement can take the argument "extend", meaning,
3256 adjust the primary selection to the new cursor position. Routines which take
3257 the "extend" argument as well as mouse dragging operations for both primary
3258 and secondary selections can take the optional keyword "rect", meaning, make
3259 the selection rectangular. Any routine that accepts the "scrollbar" argument
3260 will move the display but not the cursor or selection. Routines that accept
3261 the "nobell" argument will fail silently without beeping, when that argument
3264 **backward_character( ["nobell"] )**
3265 Moves the cursor one character to the left.
3267 **backward_paragraph(["nobell"] )**
3268 Moves the cursor to the beginning of the paragraph, or
3269 if the cursor is already at the beginning of a paragraph, moves the cursor to
3270 the beginning of the previous paragraph. Paragraphs are defined as regions
3271 of text delimited by one or more blank lines.
3273 **backward_word( ["nobell"] )**
3274 Moves the cursor to the beginning of a word, or, if the
3275 cursor is already at the beginning of a word, moves the cursor to the
3276 beginning of the previous word. Word delimiters are user-settable, and
3277 defined by the X resource wordDelimiters.
3279 **beginning_of_file( ["scrollbar"] )**
3280 Moves the cursor to the beginning of the file.
3282 **beginning_of_line( ["absolute"] )**
3283 Moves the cursor to the beginning of the line. If
3284 "absolute" is given, always moves to the absolute beginning of line,
3285 regardless of the text wrapping mode.
3287 **beginning_of_selection()**
3288 Moves the cursor to the beginning of the selection
3289 without disturbing the selection.
3291 **copy_clipboard()**
3292 Copies the current selection to the clipboard.
3295 Copies the primary selection to the cursor.
3298 If a secondary selection exists, copies the secondary selection to
3299 the cursor. If no secondary selection exists, copies the primary selection
3300 to the pointer location.
3302 **copy_to_or_end_drag()**
3303 Completes either a secondary selection operation, or a
3304 primary drag. If the user is dragging the mouse to adjust a secondary
3305 selection, the selection is copied and either inserted at the cursor
3306 location, or, if pending-delete is on and a primary selection exists in the
3307 window, replaces the primary selection. If the user is dragging a block of
3308 text (primary selection), completes the drag operation and leaves the text at
3309 it's current location.
3312 Deletes the text in the primary selection and places it in
3316 Copies the primary selection to the cursor and deletes it at
3317 its original location.
3319 **delete_selection()**
3320 Deletes the contents of the primary selection.
3322 **delete_next_character( ["nobell"] )**
3323 If a primary selection exists, deletes its contents.
3324 Otherwise, deletes the character following the cursor.
3326 **delete_previous_character( ["nobell"] )**
3327 If a primary selection exists, deletes its
3328 contents. Otherwise, deletes the character before the cursor.
3330 **delete_next_word( ["nobell"] )**
3331 If a primary selection exists, deletes its contents.
3332 Otherwise, deletes the word following the cursor.
3334 **delete_previous_word( ["nobell"] )**
3335 If a primary selection exists, deletes its contents.
3336 Otherwise, deletes the word before the cursor.
3338 **delete_to_start_of_line( ["nobell", "wrap"] )**
3339 If a primary selection exists, deletes its contents. Otherwise, deletes the
3340 characters between the cursor and the start of the line. If "wrap" is
3341 given, deletes to the previous wrap point or beginning of line, whichever
3344 **delete_to_end_of_line( ["nobell", "absolute"] )**
3345 If a primary selection exists, deletes its contents.
3346 Otherwise, deletes the characters between the cursor and the end of the line.
3347 If "absolute" is given, always deletes to the absolute end of line, regardless
3348 of the text wrapping mode.
3351 De-selects the primary selection.
3353 **end_of_file( ["scrollbar"] )**
3354 Moves the cursor to the end of the file.
3356 **end_of_line( ["absolute"] )**
3357 Moves the cursor to the end of the line. If
3358 "absolute" is given, always moves to the absolute end of line, regardless
3359 of the text wrapping mode.
3361 **end_of_selection()**
3362 Moves the cursor to the end of the selection without
3363 disturbing the selection.
3365 **exchange( ["nobell"] )**
3366 Exchange the primary and secondary selections.
3369 Attached mouse-movement events to begin a selection between
3370 the cursor and the mouse, or extend the primary selection to the mouse
3374 Completes a primary drag-selection operation.
3377 Begins a selection between the cursor and the mouse. A
3378 drag-selection operation can be started with either extend_start or
3381 **focus_pane( [relative-pane] | [positive-index] | [negative-index] )**
3382 Move the focus to the requested pane.
3383 Arguments can be specified in the form of a relative-pane
3384 ("first", "last", "next", "previous"), a positive-index
3385 (numbers greater than 0, 1 is the same as "first") or a
3386 negative-index (numbers less than 0, -1 is the same as "last").
3388 **forward_character()**
3389 Moves the cursor one character to the right.
3391 **forward_paragraph( ["nobell"] )**
3392 Moves the cursor to the beginning of the next paragraph.
3393 Paragraphs are defined as regions of text delimited by one or more blank
3396 **forward_word( ["tail"] ["nobell"] )**
3397 Moves the cursor to the beginning of the next word. Word
3398 delimiters are user-settable, and defined by the X resource wordDelimiters.
3399 If the "tail" argument is supplied the cursor will be moved to
3400 the end of the current word or the end of the next word, if the
3401 cursor is between words.
3404 Moves the cursor to the mouse pointer location, and prepares for
3405 a possible drag-selection operation (bound to extend_adjust), or multi-click
3406 operation (a further grab_focus action). If a second invocation of grab
3407 focus follows immediately, it selects a whole word, or a third, a whole line.
3409 **insert_string( "string" )**
3410 If pending delete is on and the cursor is inside the
3411 selection, replaces the selection with "string". Otherwise, inserts "string"
3412 at the cursor location.
3414 **key_select( "direction" [,"nobell"] )**
3415 Moves the cursor one character in "direction"
3416 ("left", "right", "up", or "down") and extends the selection. Same as
3417 forward/backward-character("extend"), or process-up/down("extend"), for
3418 compatibility with previous versions.
3420 **move-destination()**
3421 Moves the cursor to the pointer location without
3422 disturbing the selection. (This is an unusual way of working. We left it in
3423 for compatibility with previous versions, but if you actually use this
3424 capability, please send us some mail, otherwise it is likely to disappear in
3428 If a secondary selection exists, deletes the contents of the
3429 secondary selection and inserts it at the cursor, or if pending-delete is on
3430 and there is a primary selection, replaces the primary selection. If no
3431 secondary selection exists, moves the primary selection to the pointer
3432 location, deleting it from its original position.
3434 **move_to_or_end_drag()**
3435 Completes either a secondary selection operation, or a
3436 primary drag. If the user is dragging the mouse to adjust a secondary
3437 selection, the selection is deleted and either inserted at the cursor
3438 location, or, if pending-delete is on and a primary selection exists in the
3439 window, replaces the primary selection. If the user is dragging a block of
3440 text (primary selection), completes the drag operation and deletes the text
3441 from it's current location.
3444 Inserts a newline character. If Auto Indent is on, lines up the
3445 indentation of the cursor with the current line.
3447 **newline_and_indent()**
3448 Inserts a newline character and lines up the indentation
3449 of the cursor with the current line, regardless of the setting of Auto
3452 **newline_no_indent()**
3453 Inserts a newline character, without automatic
3454 indentation, regardless of the setting of Auto Indent.
3456 **next_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3457 Moves the cursor and scroll forward one page.
3458 The parameter "stutter" moves the cursor to the bottom of the display,
3459 unless it is already there, otherwise it will page down.
3460 The parameter "column" will maintain the preferred column while
3463 **page_left( ["scrollbar"] ["nobell"] )**
3464 Move the cursor and scroll left one page.
3466 **page_right( ["scrollbar"] ["nobell"] )**
3467 Move the cursor and scroll right one page.
3469 **paste_clipboard()**
3470 Insert the contents of the clipboard at the cursor, or if
3471 pending delete is on, replace the primary selection with the contents of the
3474 **previous_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3475 Moves the cursor and scroll backward one page.
3476 The parameter "stutter" moves the cursor to the top of the display,
3477 unless it is already there, otherwise it will page up.
3478 The parameter "column" will maintain the preferred column while
3482 Same as secondary_or_drag_start for compatibility with previous versions.
3484 **process_cancel()**
3485 Cancels the current extend_adjust, secondary_adjust, or
3486 secondary_or_drag_adjust in progress.
3488 **process_down( ["nobell", "absolute"] )**
3489 Moves the cursor down one line. If "absolute" is given, always moves to the
3490 next line in the text buffer, regardless of wrapping.
3492 **process_return()**
3493 Same as newline for compatibility with previous versions.
3495 **process_shift_down( ["nobell", "absolute"] )**
3496 Same as process_down("extend") for compatibility with previous versions.
3498 **process_shift_up( ["nobell", "absolute"] )**
3499 Same as process_up("extend") for compatibility with previous versions.
3502 If tab emulation is turned on, inserts an emulated tab,
3503 otherwise inserts a tab character.
3505 **process_up( ["nobell", "absolute"] )**
3506 Moves the cursor up one line. If "absolute" is given, always moves to the
3507 previous line in the text buffer, regardless of wrapping.
3509 **raise_window([relative-window] | [positive-index] | [negative-index] [, "focus" | "nofocus"])**
3510 Raise the current focused window to the front if no argument is supplied.
3511 Arguments can be specified in the form of a relative-window
3512 ("first", "last", "next", "previous"), a positive-index
3513 (numbers greater than 0, 1 is the same as "last") or a
3514 negative-index (numbers less than 0, -1 is the same as "first").
3516 Moreover, it can be specified whether or not the raised window should
3517 request the X input focus. By default, it depends on the setting of the
3518 nedit.focusOnRaise resource (see the section "X_Resources_") whether or not
3519 the input focus is requested.
3521 **scroll_down( nUnits, ["lines" | "pages"] )**
3522 Scroll the display down (towards the end of the file) by a given
3523 number of units, units being lines or pages. Default units are lines.
3525 **scroll_left( nPixels )**
3526 Scroll the display left by nPixels.
3528 **scroll_right( nPixels )**
3529 Scroll the display right by nPixels.
3531 **scroll_up( nUnits, ["lines" | "pages"] )**
3532 Scroll the display up (towards the beginning of the file) by a given
3533 number of units, units being lines or pages. Default units are lines.
3535 **scroll_to_line( lineNum )**
3536 Scroll to position line number lineNum at the top of
3537 the pane. The first line of a file is line 1.
3539 **secondary_adjust()**
3540 Attached mouse-movement events to extend the secondary
3541 selection to the mouse position.
3543 **secondary_or_drag_adjust()**
3544 Attached mouse-movement events to extend the
3545 secondary selection, or reposition the primary text being dragged. Takes two
3546 optional arguments, "copy", and "overlay". "copy" leaves a copy of the
3547 dragged text at the site at which the drag began. "overlay" does the drag in
3548 overlay mode, meaning the dragged text is laid on top of the existing text,
3549 obscuring and ultimately deleting it when the drag is complete.
3551 **secondary_or_drag_start()**
3552 To be attached to a mouse down event. Begins drag
3553 selecting a secondary selection, or dragging the contents of the primary
3554 selection, depending on whether the mouse is pressed inside of an existing
3557 **secondary_start()**
3558 To be attached to a mouse down event. Begin drag selecting
3559 a secondary selection.
3562 Select the entire file.
3565 To be attached to a key-press event, inserts the character
3566 equivalent of the key pressed.
3568 ----------------------------------------------------------------------
3576 NEdit can be customized many different ways. The most important
3577 user-settable options are presented in the Preferences menu, including all
3578 options that users might need to change during an editing session. Options
3579 set in the Default Settings sub-menu of the Preferences menu can be preserved
3580 between sessions by selecting Save Defaults, which writes the changes to the
3581 preferences file. See the section titled "Preferences_" for more details.
3583 User defined commands can be added to NEdit's Shell, Macro, and window
3584 background menus. Dialogs for creating items in these menus can be found
3585 under Customize Menus in the Default Settings sub menu of the Preferences
3588 For users who depend on NEdit every day and want to tune every excruciating
3589 detail, there are also X resources for tuning a vast number of such details,
3590 down to the color of each individual button. See the section "X_Resources_"
3591 for more information, as well as a list of selected resources.
3593 The most common reason customizing your X resources for NEdit, however, is
3594 key binding. While limited key binding can be done through Preferences
3595 settings (Preferences -> Default Settings -> Customize Menus), you can really
3596 only add keys this way, and each key must have a corresponding menu item.
3597 Any significant changes to key binding should be made via the Translations
3598 resource and menu accelerator resources. The sections titled "Key_Binding_"
3599 and "X_Resources_" have more information.
3600 ----------------------------------------------------------------------
3605 The Preferences menu allows you to set options for both the current editing
3606 window, and default values for newly created windows and future NEdit
3607 sessions. Options in the Preferences menu itself (not in the Default
3608 Settings sub-menu) take effect immediately and refer to the current window
3609 only. Options in the Default Settings sub-menu provide initial settings for
3610 future windows created using the New or Open commands; options affecting all
3611 windows are also set here.
3612 Preferences set in the Default Settings sub-menu can be saved in a file that
3613 is automatically read by NEdit at startup time, by selecting Save Defaults.
3617 **Default Settings**
3618 Menu of initial settings for future windows. Generally the same as the
3619 options in the main part of the menu, but apply as defaults for future
3620 windows created during this NEdit session. These settings can be saved using
3621 the Save Defaults command below, to be loaded automatically each time NEdit
3625 Save the default options as set under Default Settings for future NEdit
3629 Show the full file name, line number, and length of the file being edited.
3631 **Incremental Search Line**
3632 Keep the incremental search bar (Search -> Find Incremental) permanently
3633 displayed at the top of the window.
3635 **Show Line Numbers**
3636 Display line numbers to the right of the text.
3639 Tells NEdit what language (if any) to assume, for selecting language-specific
3640 features such as highlight patterns and smart indent macros, and setting
3641 language specific preferences like word delimiters, tab emulation, and
3642 auto-indent. See Features for Programming -> Programming_with_NEdit_ for
3646 Setting Auto Indent "on" maintains a running indent (pressing the Return key
3647 will line up the cursor with the indent level of the previous line). If
3648 smart indent macros are available for the current language mode, smart indent
3649 can be selected and NEdit will attempt to guess proper language indentation
3650 for each new line. See Help -> Features for Programming -> Automatic Indent
3651 for more information.
3654 Choose between two styles of automatic wrapping or none. Auto Newline wrap,
3655 wraps text at word boundaries when the cursor reaches the right margin, by
3656 replacing the space or tab at the last word boundary with a newline
3657 character. Continuous Wrap wraps long lines which extend past the right
3658 margin. Continuous Wrap mode is typically used to produce files where
3659 newlines are omitted within paragraphs, to make text filling automatic (a
3660 kind of poor-man's word processor). Text of this style is common on Macs and
3661 PCs but is not necessarily supported very well under Unix (except in programs
3662 which deal with e-mail, for which it is often the format of choice).
3665 Set margin for Auto Newline Wrap, Continuous Wrap, and Fill Paragraph. Lines
3666 may, be wrapped at the right margin of the window, or the margin can be set
3667 at a specific column.
3670 Set the tab distance (number of characters between tab stops) for tab
3671 characters, and control tab emulation and use of tab characters in padding
3675 Change the font(s) used to display text (fonts for menus and dialogs must be
3676 set using X resources for the text area of the window). See below for more
3679 **Highlight Syntax**
3680 If NEdit recognizes the language being edited, and highlighting patterns are
3681 available for that language, use fonts and colors to enhance viewing of the
3682 file. (See Help -> Features for Programming -> Syntax Highlighting for more
3685 **Make Backup Copy**
3686 On Save, write a backup copy of the file as it existed before the Save
3687 command with the extension .bck (Unix only).
3689 **Incremental Backup**
3690 Periodically make a backup copy of the file being edited under the name
3691 `~filename` on Unix or `_filename` on VMS (see Crash_Recovery_).
3693 **Show Matching (..)**
3694 Momentarily highlight matching parenthesis, brackets, and braces, or the
3695 range between them, when one of these characters is typed, or when the
3696 insertion cursor is positioned after it. Delimiter only highlights the
3697 matching delimiter, while Range highlights the whole range of text between
3698 the matching delimiters.
3700 Optionally, the matching can make use of syntax information if syntax
3701 highlighting is enabled. Alternatively, the matching is purely character
3702 based. In general, syntax based matching results in fewer false matches.
3705 In overtype mode, new characters entered replace the characters in front of
3706 the insertion cursor, rather than being inserted before them.
3709 Lock the file against accidental modification. This temporarily prevents the
3710 file from being modified in this NEdit session. Note that this is different
3711 from setting the file protection.
3713 3>Preferences -> Default Settings Menu
3715 Options in the Preferences -> Default Settings menu have the same meaning as
3716 those in the top-level Preferences menu, except that they apply to future
3717 NEdit windows and future NEdit sessions if saved with the Save Defaults
3718 command. Additional options which appear in this menu are:
3721 Define language recognition information (for determining language mode from
3722 file name or content) and set language specific preferences.
3725 How to react to multiple tags for the same name. Tags are described in the
3726 section: Features for Programmers -> Finding Declarations (ctags). In Show
3727 All mode, all matching tags are displayed in a dialog. In Smart mode, if one
3728 of the matching tags is in the current window, that tag is chosen, without
3729 displaying the dialog.
3732 Change the colors used to display text. The "Matching (..)" fields change the
3733 colors that matching parens, brackets and braces are flashed when the "Show
3734 Matching (..)" option is enabled. Note that the foreground colors for plain
3735 text, selected text, and matching paren flashing only apply when syntax
3736 highlighting is disabled. When syntax highlighting is enabled, text (even
3737 text that appears plain) will always be colored according to its highlighting
3738 style. (For information on changing syntax highlighting styles and matching
3739 patterns use see Help -> Features for Programming -> Syntax_Highlighting_.)
3742 Add/remove items from the Shell, Macro, and window background menus (see
3745 **Customize Window Title**
3746 Opens a dialog where the information to be displayed in the window's title
3747 field can be defined and tested. The dialog contains a Help button, providing
3748 further information about the options available.
3751 Options for controlling the behavior of Find and Replace commands:
3754 Presents search results in dialog form, asks before wrapping a
3755 search back around the beginning (or end) of the file
3756 (unless Beep On Search Wrap is turned on).
3759 Search and Replace operations wrap around the beginning (or end) of the file.
3761 ~Beep On Search Wrap~ -
3762 Beep when Search and Replace operations wrap around the beginning (or end) of
3763 the file (only if Wrap Around is turned on).
3766 Don't pop down Replace and Find boxes after searching.
3768 ~Default Search Style~ -
3769 Initial setting for search type in Find and Replace dialogs.
3771 ~Default Replace Scope~ -
3772 [THIS OPTION IS ONLY PRESENT WHEN NEDIT WAS COMPILED WITH THE
3773 -DREPLACE_SCOPE FLAG TO SELECT AN ALTERNATIVE REPLACE DIALOG LAYOUT.]
3775 Initial setting for the scope in the Replace/Find dialog, when a selection
3776 exists. It can be either "In Window", "In Selection", or "Smart". "Smart"
3777 results in "In Window" if the size of the selection is smaller than 1 line,
3778 and to "In Selection" otherwise.
3780 **Syntax Highlighting**
3781 Program and configure enhanced text display for new or supported languages
3782 (See Features for Programming -> Syntax_Highlighting_).
3785 Options for controlling the tabbed interface:
3787 ~Open File in New Tab~ -
3788 Open files in new tabs, else open files in new windows.
3791 Show/Hide the tab bar.
3793 ~Hide Tab Bar when only one Document is open~
3795 ~Next/Prev Tabs Across Windows~ -
3796 Suppose there are two windows with three tabs in the first window and two tabs in
3797 the second window. Enabling this option, if you are on the third tab in the
3798 first window, hitting Ctrl+PageDown would switch to the first tab in the second
3799 window (instead of switching to the first tab in the first window).
3801 ~Sort Tabs Alphabetically~
3804 Show file name and path in a tooltip when moving the mouse pointer over a tab
3805 (See Basic Operations -> Tabbed_Editing_).
3807 **Terminate with Line Break on Save**
3808 Some UNIX tools expect that files end with a line feed. If this option is
3809 activated, NEdit will append one if required.
3811 **Sort Open Prev. Menu**
3812 Option to order the File -> Open Previous menu alphabetically, versus in
3813 order of last access.
3815 **Popups Under Pointer**
3816 Display pop-up dialogs centered on the current mouse position, as opposed to
3817 centered on the parent window. This generally speeds interaction, and is
3818 essential for users who set their window managers so keyboard focus
3821 **Auto-Scroll Near Window Top/Bottom**
3822 When this option is enabled the window will automatically scroll when the
3823 cursor comes 4 lines from the top or bottom of the window (except at the
3824 beginning of the file). The number of lines can be customized with the
3825 nedit.autoScrollVPadding resource.
3828 Options for controlling the popping up of warning dialogs:
3830 ~File Modified Externally~ -
3831 Pop up a warning dialog when files get changed external to NEdit.
3833 ~Check Modified File Contents~ -
3834 If external file modification warnings are requested, also check the file
3835 contents iso. only the modification date.
3838 Ask before exiting when two or more files are open in an NEdit session.
3840 **Initial Window Size**
3841 Default size for new windows.
3845 The font used to display text in NEdit is set under Preferences -> Text Font
3846 (for the current window), or Preferences -> Default Settings Text Font (for
3847 future windows). These dialogs also allow you to set fonts for syntax
3848 highlighting. If you don't intend to use syntax highlighting, you can ignore
3849 most of the dialog, and just set the field labeled Primary Font.
3851 Unless you are absolutely certain about the types of files that you will be
3852 editing with NEdit, you should choose a fixed-spacing font. Many, if not
3853 most, plain-text files are written expecting to be viewed with fixed
3854 character spacing, and will look wrong with proportional spacing. NEdit's
3855 filling, wrapping, and rectangular operations will also work strangely if you
3856 choose a proportional font.
3858 Note that in the font browser (the dialog brought up by the Browse...
3859 button), the subset of fonts which are shown is narrowed depending on the
3860 characteristics already selected. It is therefore important to know that you
3861 can unselect characteristics from the lists by clicking on the selected items
3864 Fonts for syntax highlighting should ideally match the primary font in both
3865 height and spacing. A mismatch in spacing will result in similar distortions
3866 as choosing a proportional font: column alignment will sometimes look wrong,
3867 and rectangular operations, wrapping, and filling will behave strangely. A
3868 mismatch in height will cause windows to re-size themselves slightly when
3869 syntax highlighting is turned on or off, and increase the inter- line spacing
3870 of the text. Unfortunately, on some systems it is hard to find sets of fonts
3871 which match exactly in height.
3875 You can add or change items in the Shell, Macro, and window background menus
3876 under Preferences -> Default Settings -> Customize Menus. When you choose
3877 one of these, you will see a dialog with a list of the current
3878 user-configurable items from the menu on the left. To change an existing
3879 item, select it from the list, and its properties will appear in the
3880 remaining fields of the dialog, where you may change them. Selecting the
3881 item "New" from the list allows you to enter new items in the menu.
3883 Hopefully most of the characteristics are self explanatory, but here are a
3886 Accelerator keys are keyboard shortcuts which appear on the right hand side
3887 of the menus, and allow you avoid pulling down the menu and activate the
3888 command with a single keystroke. Enter accelerators by typing the keys
3889 exactly as you would to activate the command.
3891 Mnemonics are a single letter which should be part of the menu item name,
3892 which allow users to traverse and activate menu items by typing keys when the
3893 menu is pulled down.
3895 In the Shell Command field of the Shell Commands dialog, the % character
3896 expands to the name (including directory path) of the file in the window. To
3897 include a % character in the command, use %%.
3899 The Menu Entry field can contain special characters for constructing
3900 hierarchical sub-menus, and for making items which appear only in certain
3901 language modes. The right angle bracket character ">" creates a sub-menu.
3902 The name of the item itself should be the last element of the path formed
3903 from successive sub-menu names joined with ">". Menu panes are called in to
3904 existence simply by naming them as part of a Menu Entry name. To put several
3905 items in the same sub-menu, repeat the same hierarchical sequence for each.
3906 For example, in the Macro Commands dialog, two items with menu entries: a>b>c
3907 and a>b>d would create a single sub menu under the macro menu called "a",
3908 which would contain a single sub-menu, b, holding the actual items, c and d:
3915 To qualify a menu entry with a language mode, simply add an at-sign "@@" at
3916 the end of the menu command, followed (no space) by a language mode name. To
3917 make a menu item which appears in several language modes, append additional
3918 @@s and language mode names. For example, an item with the menu entry:
3920 Make C Prototypes@@C@@C++
3922 would appear only in C and C++ language modes, and:
3924 Make Class Template@@C++
3926 would appear only in C++ mode.
3928 Menu items with no qualification appear in all language modes.
3930 If a menu item is followed by the single language qualification "@@*", that
3931 item will appear only if there are no applicable language-specific items of
3932 the same name in the same submenu. For example, if you have the following
3933 three entries in the same menu:
3935 Make Prototypes@@C@@C++
3936 Make Prototypes@@Java
3939 The first will be available when the language mode is C or C++, the second
3940 when the language mode is Java, and for all other language modes (including
3941 the "Plain" non-language mode). If the entry:
3945 also exists, this will always appear, meaning that the menu will always have
3946 two "Make Prototypes" entries, whatever the language mode.
3948 3>The NEdit Preferences File
3950 The NEdit saved preferences file is an X resource file, and its contents can
3951 be moved into another X resource file (see X_Resources_). One reason for
3952 doing so would be to attach server specific preferences, such as a default
3953 font to a particular X server. Another reason for moving preferences into the
3954 X resource file would be to keep preferences menu options and resource
3955 settable options together in one place.
3956 Though the files are the same format, additional resources should not be added
3957 to the preference file since NEdit modifies this file by overwriting it
3958 completely. Note also that the contents of the preference file take
3959 precedence over the values of X resources.
3960 Using Save Defaults after moving the contents of your preference file to your
3961 .Xdefaults file will re-create the preference file, interfering with the
3962 options that you have moved.
3963 The location of NEdit's preferences file depends on your environment:
3965 * The default place for the file is '$HOME/.nedit/nedit.rc',
3966 * if the variable $NEDIT_HOME is set in your environment it is located at '$NEDIT_HOME/nedit.rc',
3967 * you may also use old-style run control files; in this case, the preferences are stored in $HOME/.nedit.
3969 (For VMS, the file is in '$NEDIT_HOME/nedit.rc' if $NEDIT_HOME is set, in
3970 'SYS$LOGIN:.nedit' otherwise.)
3972 3>Sharing Customizations with Other NEdit Users
3974 If you have written macro or shell menu commands, highlight patterns, or
3975 smart-indent macros that you want to share with other NEdit users, you can
3976 make a file which they can load into their NEdit environment.
3978 To load such a file, start NEdit with the command:
3980 nedit -import <file>
3982 In the new NEdit session, verify that the imported patterns or macros do what
3983 you want, then select Preferences -> Save Defaults. Saving incorporates the
3984 changes into the nedit preferences file, so the next time you run NEdit, you
3985 will not have to import the distribution file.
3987 Loading a customization file is automated, but creating one is not. To
3988 produce a file to be imported by other users, you must make a copy of your own
3989 NEdit configuration file, and edit it, by hand, to remove everything but the
3990 few items of interest to the recipient. Leave only the individual
3991 resource(s), and within those resources, only the particular macro, pattern,
3992 style, etc, that you wish to exchange.
3994 For example, to share a highlighting pattern set, you would include the
3995 patterns, any new styles you added, and language mode information only if the
3996 patterns are intended to support a new language rather than updating an
3997 existing one. For example:
3999 nedit.highlightPatterns:\
4001 Comment:"#":"$"::Comment::\n\
4002 Loop Header:"^[ \\t]*loop:":::Loop::\n\
4004 nedit.languageModes: My Language:.my::::::
4005 nedit.styles: Loop:blue:Bold
4007 Resources are in the format of X resource files, but the format of text
4008 within multiple-item resources like highlight patterns, language modes,
4009 macros, styles, etc., are private to NEdit. Each resource is a string which
4010 ends at the first newline character not escaped with \, so you must be
4011 careful about how you treat ends of lines. While you can generally just cut
4012 and paste indented sections, if something which was originally in the middle
4013 of a resource string is now at the end, you must remove the \ line
4014 continuation character(s) so it will not join the next line into the
4015 resource. Conversely, if something which was originally at the end of a
4016 resource is now in the middle, you'll have to add continuation character(s)
4017 to make sure that the resource string is properly continued from beginning to
4018 end, and possibly newline character(s) (\n) to make sure that it is properly
4019 separated from the next item.
4020 ----------------------------------------------------------------------
4025 NEdit has additional options to those provided in the Preferences menu which
4026 are set using X resources. Like most other X programs, NEdit can be
4027 customized to vastly unnecessary proportions, from initial window positions
4028 down to the font and shadow colors of each individual button (A complete
4029 discussion of how to do this is left to books on the X Window System). Key
4030 binding (see "Key_Binding_" is one of the most useful of these resource
4033 X resources are usually specified in a file called .Xdefaults or .Xresources
4034 in your home directory (on VMS this is sys$login:decw$xdefaults.dat). On
4035 some systems, this file is read and its information attached to the X server
4036 (your screen) when you start X. On other systems, the .Xdefaults file is
4037 read each time you run an X program. When X resource values are attached to
4038 the X server, changes to the resource file are not available to application
4039 programs until you either run the xrdb program with the appropriate file as
4040 input, or re-start the X server.
4042 3>Selected X Resource Names
4044 The following are selected NEdit resource names and default values for NEdit
4045 options not settable via the Preferences menu (for preference resource names,
4046 see your NEdit preference file):
4048 **nedit.tagFile**: (not defined)
4050 This can be the name of a file, or multiple files separated by a colon (:)
4051 character, of the type produced by Exuberant Ctags or the Unix ctags
4052 command, which NEdit will load at startup time (see ctag_support_ ). The tag
4053 file provides a database from which NEdit can automatically open files
4054 containing the definition of a particular subroutine or data type.
4056 **nedit.alwaysCheckRelativeTagsSpecs: True**
4058 When this resource is set to True, and there are tag files specified (with
4059 the nedit.tagFile resource, see above) as relative paths, NEdit will evaluate
4060 these tag value paths whenever a file is opened. All accessible tag files
4061 will be loaded at this time. When this resource value is False, relative path
4062 tag specifications will only be evaluated at NEdit startup time.
4064 **nedit.shell**: /bin/csh
4066 (Unix systems only) The Unix shell (command interpreter) to use for executing
4067 commands from the Shell menu
4069 **nedit.wordDelimiters**: .,/\\`'!@@#%^&*()-=+{}[]":;<>?
4071 The characters, in addition to blanks and tabs, which mark the boundaries
4072 between words for the move-by-word (Ctrl+Arrow) and select-word (double
4073 click) commands. Note that this default value may be overridden by the
4074 setting in Preferences -> Default Settings -> Language Modes....
4076 **nedit.remapDeleteKey**: False
4078 Setting this resource to True forcibly maps the delete key to backspace. This
4079 can be helpful on systems where the bindings have become tangled, and in
4080 environments which mix systems with PC style keyboards and systems with DEC
4081 and Macintosh keyboards. Theoretically, these bindings should be made using
4082 the standard X/Motif mechanisms, outside of NEdit. In practice, some
4083 environments where users access several different systems remotely, can be
4084 very hard to configure. If you've given up and are using a backspace key
4085 halfway off the keyboard because you can't figure out the bindings, set this
4088 **nedit.typingHidesPointer**: False
4090 Setting this resource to True causes the mouse pointer to be hidden when you
4091 type in the text area. As soon as the mouse pointer is moved, it will
4092 reappear. This is useful to stop the mouse pointer from obscuring text.
4094 **nedit.overrideDefaultVirtualKeyBindings**: Auto
4096 Motif uses a virtual key binding mechanism that shares the bindings between
4097 different Motif applications. When a first Motif application is started, it
4098 installs some default virtual key bindings and any other Motif application
4099 that runs afterwards, simply reuses them. Obviously, if the first
4100 application installs an invalid set, all others applications may have
4103 In the past, NEdit has been the victim of invalid bindings installed by other
4104 applications several times. Through this resource, NEdit can be instructed
4105 to ignore the bindings installed by other applications, and use its own
4106 private bindings. By default, NEdit tries to detect invalid bindings
4107 and ignore them automatically (Auto). Optionally, NEdit can be told to
4108 always keep the installed bindings (Never), or to always override them
4111 **nedit.stdOpenDialog**: False
4113 Setting this resource to True restores the standard Motif style of Open
4114 dialog. NEdit file open dialogs are missing a text field at the bottom of
4115 the dialog, where the file name can be entered as a string. The field is
4116 removed in NEdit to encourage users to type file names in the list, a
4117 non-standard, but much faster method for finding files.
4119 **nedit.bgMenuButton**: @~Shift@~Ctrl@~Meta@~Alt<Btn3Down>
4121 Specification for mouse button / key combination to post the background menu
4122 (in the form of an X translation table event specification). The event
4123 specification should be as specific as possible, since it will override less
4124 specific translation table entries.
4126 **nedit.maxPrevOpenFiles**: 30
4128 Number of files listed in the Open Previous sub-menu of the File menu.
4129 Setting this to zero disables the Open Previous menu item and maintenance of
4130 the NEdit file history file.
4132 **nedit.printCommand**: (system specific)
4134 Command used by the print dialog to print a file, such as, lp, lpr, etc..
4135 The command must be capable of accepting input via stdin (standard input).
4137 **nedit.printCopiesOption**: (system specific)
4139 Option name used to specify multiple copies to the print command. If the
4140 option should be separated from its argument by a space, leave a trailing
4141 space. If blank, no "Number of Copies" item will appear in the print dialog.
4143 **nedit.printQueueOption**: (system specific)
4145 Option name used to specify a print queue to the print command. If the
4146 option should be separated from its argument by a space, leave a trailing
4147 space. If blank, no "Queue" item will appear in the print dialog.
4149 **nedit.printNameOption**: (system specific)
4151 Option name used to specify a job name to the print command. If the option
4152 should be separated from its argument by a space, leave a trailing space. If
4153 blank, no job or file name will be attached to the print job or banner page.
4155 **nedit.printHostOption**: (system specific)
4157 Option name used to specify a host name to the print command. If the option
4158 should be separated from its argument by a space, leave a trailing space. If
4159 blank, no "Host" item will appear in the print dialog.
4161 **nedit.printDefaultQueue**: (system specific)
4163 The name of the default print queue. Used only to display in the print
4164 dialog, and has no effect on printing.
4166 **nedit.printDefaultHost**: (system specific)
4168 The node name of the default print host. Used only to display in the print
4169 dialog, and has no effect on printing.
4171 **nedit.visualID**: Best
4173 If your screen supports multiple visuals (color mapping models), this
4174 resource allows you to manually choose among them. The default value of
4175 "Best" chooses the deepest (most colors) visual available. Since NEdit does
4176 not depend on the specific characteristics of any given color model, Best
4177 probably IS the best choice for everyone, and the only reason for setting
4178 this resource would be to patch around some kind of X server problem. The
4179 resource may also be set to "Default", which chooses the screen's default
4180 visual (often a color-mapped, PseudoColor, visual for compatibility with
4181 older X applications). It may also be set to a numeric visual-id value (use
4182 xdpyinfo to see the list of visuals supported by your display), or a visual
4183 class name: PseudoColor, DirectColor, TrueColor, etc..
4185 If you are running under a themed environment (like KDE or CDE) that places
4186 its colors in a shallow visual, and you'd rather have that color scheme
4187 instead of more colors available, then you may need set the visual to
4188 "Default" so that NEdit doesn't choose one with more colors. (The reason
4189 for this is: if the "best" visual is not the server's default, then NEdit
4190 cannot use the colors provided by your environment. NEdit will fall back to
4191 its own default color scheme.)
4193 **nedit.installColormap**: False
4195 Force the installation of a private colormap. If you have a humble 8-bit
4196 color display, and netscape is hogging all of the color cells, you may want
4197 to try turning this on. On most systems, this will result in colors flashing
4198 wildly when you switch between NEdit and other applications. But a few
4199 systems (SGI) have hardware support for multiple simultaneous colormaps, and
4200 applications with installed colormaps are well behaved.
4202 **nedit.findReplaceUsesSelection**: False
4204 Controls if the Find and Replace dialogs are automatically loaded with the
4205 contents of the primary selection.
4207 **nedit.stickyCaseSenseButton**: True
4209 Controls if the "Case Sensitive" buttons in the Find and Replace dialogs and
4210 the incremental search bar maintain a separate state for literal and regular
4211 expression searches. Moreover, when set to True, by default literal searches
4212 are case insensitive and regular expression searches are case sensitive. When
4213 set to False, the "Case Sensitive" buttons are independent of the "Regular
4216 **nedit.multiClickTime**: (system specific)
4218 Maximum time in milliseconds allowed between mouse clicks within double and
4219 triple click actions.
4221 **nedit.undoModifiesSelection**: True
4223 By default, NEdit selects any text inserted or changed through a undo/redo
4224 action. Set this resource to False if you don't want your selection to be
4227 **nedit@*scrollBarPlacement**: BOTTOM_RIGHT
4229 How scroll bars are placed in NEdit windows, as well as various lists and
4230 text fields in the program. Other choices are: BOTTOM_LEFT, TOP_LEFT, or
4233 **nedit@*text.autoWrapPastedText**: False
4235 When Auto Newline Wrap is turned on, apply automatic wrapping (which
4236 normally only applies to typed text) to pasted text as well.
4238 **nedit@*text.heavyCursor**: False
4240 For monitors with poor resolution or users who have difficulty seeing the
4241 cursor, makes the cursor in the text editing area of the window heavier and
4244 **nedit.autoScrollVPadding**: 4
4246 Number of lines to keep the cursor away from the top or bottom line of the
4247 window when the "Auto-Scroll Near Window Top/Bottom" feature is enabled.
4248 Keyboard operations that would cause the cursor to get closer than
4249 this distance cause the window to scroll up or down instead, except at the
4250 beginning of the file. Mouse operations are not affected.
4252 **nedit@*text.blinkRate**: 500
4254 Blink rate of the text insertion cursor in milliseconds. Set to zero to stop
4257 **nedit@*text.Translations**:
4259 Modifies key bindings (see "Key_Binding_").
4261 **nedit@*foreground**: black
4263 Default foreground color for menus, dialogs, scroll bars, etc..
4265 **nedit@*background**: #b3b3b3
4267 Default background color for menus, dialogs, scroll bars, etc..
4269 **nedit@*calltipForeground**: black
4271 Foreground color for calltips
4273 **nedit@*calltipBackground**: LemonChiffon1
4275 Background color for calltips
4277 **nedit@*XmLFolder.inactiveForeground**: #666
4279 Foreground color for inactive tabs.
4281 **nedit@*fontList**: helvetica medium 12 points
4283 Default font for menus, dialogs, scroll bars, etc..
4285 **nedit.helpFont**: helvetica medium 12 points
4287 Font used for displaying online help.
4289 **nedit.boldHelpFont**: helvetica bold 12 points
4291 Bold font for online help.
4293 **nedit.italicHelpFont**: helvetica italic 12 points
4295 Italic font for online help.
4297 **nedit.fixedHelpFont**: courier medium 12 points
4299 Fixed font for online help.
4301 **nedit.boldFixedHelpFont**: courier bold 12 points
4303 Fixed bold for online help.
4305 **nedit.italicFixedHelpFont**: courier italic 12 points
4307 Fixed italic font for online help.
4309 **nedit.h1HelpFont**: helvetica bold 14 points
4311 Font for level-1 titles in help text.
4313 **nedit.h2HelpFont**: helvetica bold italic 12 points
4315 Font for level-2 titles in help text.
4317 **nedit.h3HelpFont**: courier bold 12 points
4319 Font for level-3 titles in help text.
4321 **nedit.helpLinkFont**: helvetica medium 12 points
4323 Font for hyperlinks in the help text
4325 **nedit.helpLinkColor**: #009900
4327 Color for hyperlinks in the help text
4329 **nedit.backlightCharTypes**: 0-8,10-31,127:red;9:#dedede;32,160-255:#f0f0f0;128-159:orange
4331 **NOTE: backlighting is ~experimental~** (see "Programming_with_NEdit_").
4333 A string specifying character classes as ranges of ASCII values followed by
4334 the color to be used as their background colors. The format is:
4336 low[-high]{,low[-high]}:color{;low-high{,low[-high]}:color}
4338 where low and high are ASCII values.
4341 32-255:#f0f0f0;1-31,127:red;128-159:orange;9-13:#e5e5e5
4343 **nedit.focusOnRaise**: False
4345 This resource determines whether new text windows and text windows that are
4346 raised, should also request the input focus. Conventionally, it is the task
4347 of the window manager to decide on which window gets the input focus.
4348 Therefore, NEdit's default behaviour is not to request the input focus
4353 .. The macro built-in function set_backlight_string() allows these strings to be
4354 .. set for a particular window.
4356 **nc.autoStart**: True
4358 Whether the nc program should automatically start an NEdit server (without
4359 prompting the user) if an appropriate server is not found.
4361 **nc.serverCommand**: nedit -server
4363 Command used by the nc program to start an NEdit server.
4367 Basic time-out period used in communication with an NEdit server (seconds).
4369 ----------------------------------------------------------------------
4370 ~The following are Selected widget names (to which you may append~
4371 ~.background, .foreground, .fontList, etc., to change colors, fonts~
4372 ~ and other characteristics):~
4374 **nedit@*statsAreaForm**
4376 Statistics line and incremental search bar. To get consistent results across
4377 the entire stats line and the incremental search bar, use '*' rather than '.'
4378 to separate the resource name. For example, to set the foreground color of
4379 both components use:
4380 nedit*statsAreaForm*foreground
4382 nedit*statsAreaForm.foreground
4386 Top-of-window menu-bar.
4388 **nedit@*textHorScrollBar**
4390 Horizontal scroll bar.
4392 **nedit@*textVertScrollBar**
4394 Vertical scroll bar.
4395 ----------------------------------------------------------------------
4400 There are several ways to change key bindings in NEdit. The easiest way to
4401 add a new key binding in NEdit is to define a macro in Preferences -> Default
4402 Settings -> Customize Menus -> Macro Menu. However, if you want to change
4403 existing bindings or add a significant number of new key bindings you will
4404 need to do so via X resources.
4406 Before reading this section, you must understand how to set X resources (see
4407 the help section "X_Resources_"). Since setting X resources is tricky, it is
4408 also helpful when working on key-binding, to set some easier-to-verify
4409 resource at the same time, as a simple check that the NEdit program is
4410 actually seeing your changes. The appres program is also very helpful in
4411 checking that the resource settings that you make, actually reach the program
4412 for which they are intended in the correct form.
4414 3>Key Binding in General
4416 Keyboard commands are associated with editor action routines through two
4417 separate mechanisms in NEdit. Commands which appear in pull-down menus have
4418 individual resources designating a keyboard equivalent to the menu command,
4419 called an accelerator key. Commands which do not have an associated menu
4420 item are bound to keys via the X toolkit translation mechanism. The methods
4421 for changing these two kinds of bindings are quite different.
4423 3>Key Binding Via Translations
4425 The most general way to bind actions to keys in NEdit is to use the
4426 translation table associated with the text widget. To add a binding to Alt+Y
4427 to insert the string "Hi!", for example, add lines similar to the following
4428 to your X resource file:
4430 NEdit*text.Translations: #override \n\
4431 Alt<Key>y: insert_string("Hi!") \n
4433 The Help topic "Action_Routines_" lists the actions available to be bound.
4435 Translation tables map key and mouse presses, window operations, and other
4436 kinds of events, to actions. The syntax for translation tables is
4437 simplified here, so you may need to refer to a book on the X window system
4438 for more detailed information.
4440 Note that accelerator resources (discussed below) override translations, and
4441 that most Ctrl+letter and Alt+letter combinations are already bound to an
4442 accelerator key. To use one of these combinations from a translation table,
4443 therefore, you must first un-bind the original menu accelerator.
4445 A resource for changing a translation table consists of a keyword; #override,
4446 #augment, or #replace; followed by lines (separated by newline characters)
4447 pairing events with actions. Events begin with modifiers, like Ctrl, Shift,
4448 or Alt, followed by the event type in <>. BtnDown, Btn1Down, Btn2Down,
4449 Btn1Up, Key, KeyUp are valid event types. For key presses, the event type is
4450 followed by the name of the key. You can specify a combination of events,
4451 such as a sequence of key presses, by separating them with commas. The other
4452 half of the event/action pair is a set of actions. These are separated from
4453 the event specification by a colon and from each other by spaces. Actions
4454 are names followed by parentheses, optionally containing one or more
4455 parameters separated by comas.
4457 3>Changing Menu Accelerator Keys
4459 The menu shortcut keys shown at the right of NEdit menu items can also be
4460 changed via X resources. Each menu item has two resources associated with
4461 it, accelerator, the event to trigger the menu item; and acceleratorText, the
4462 string shown in the menu. The form of the accelerator resource is the same
4463 as events for translation table entries discussed above, though multiple keys
4464 and other subtleties are not allowed. The resource name for a menu is the
4465 title in lower case, followed by "Menu", the resource name of menu item is
4466 the name in lower case, run together, with words separated by caps, and all
4467 punctuation removed. For example, to change Cut to Ctrl+X, you would add the
4468 following to your .Xdefaults file:
4470 nedit*editMenu.cut.accelerator: Ctrl<Key>x
4471 nedit*editMenu.cut.acceleratorText: Ctrl+X
4473 Accelerator keys with optional shift key modifiers, like Find..., have an
4474 additional accelerator resource with Shift appended to the name. For
4477 nedit*searchMenu.find.acceleratorText: [Shift]Alt+F
4478 nedit*searchMenu.find.accelerator: Alt<Key>f
4479 nedit*searchMenu.findShift.accelerator: Shift Alt<Key>f
4480 ----------------------------------------------------------------------
4482 Highlighting Patterns
4483 ---------------------
4485 3>Writing Syntax Highlighting Patterns
4487 Patterns are the mechanism by which language syntax highlighting is
4488 implemented in NEdit (see Syntax_Highlighting_ under the heading of Features
4489 for Programming). To create syntax highlighting patterns for a new
4490 language, or to modify existing patterns, select "Recognition Patterns" from
4491 "Syntax Highlighting" sub-section of the "Default Settings" sub-menu of the
4494 First, a word of caution. As with regular expression matching in general, it
4495 is quite possible to write patterns which are so inefficient that they
4496 essentially lock up the editor as they recursively re-examine the entire
4497 contents of the file thousands of times. With the multiplicity of patterns,
4498 the possibility of a lock-up is significantly increased in syntax
4499 highlighting. When working on highlighting patterns, be sure to save your
4502 NEdit's syntax highlighting is unusual in that it works in real-time (as you
4503 type), and yet is completely programmable using standard regular expression
4504 notation. Other syntax highlighting editors usually fall either into the
4505 category of fully programmable but unable to keep up in real-time, or
4506 real-time but limited programmability. The additional burden that NEdit
4507 places on pattern writers in order to achieve this speed/flexibility mix, is
4508 to force them to state self-imposed limitations on the amount of context that
4509 patterns may examine when re-parsing after a change. While the "Pattern
4510 Context Requirements" heading is near the end of this section, it is not
4511 optional, and must be understood before making any any serious effort at
4514 In its simplest form, a highlight pattern consists of a regular expression to
4515 match, along with a style representing the font an color for displaying any
4516 text which matches that expression. To bold the word, "highlight", wherever
4517 it appears the text, the regular expression simply would be the word
4518 "highlight". The style (selected from the menu under the heading of
4519 "Highlight Style") determines how the text will be drawn. To bold the text,
4520 either select an existing style, such as "Keyword", which bolds text, or
4521 create a new style and select it under Highlight Style.
4523 The full range of regular expression capabilities can be applied in such a
4524 pattern, with the single caveat that the expression must conclusively match
4525 or not match, within the pre-defined context distance (as discussed below
4526 under Pattern Context Requirements).
4528 To match longer ranges of text, particularly any constructs which exceed the
4529 requested context, you must use a pattern which highlights text between a
4530 starting and ending regular expression match. To do so, select "Highlight
4531 text between starting and ending REs" under "Matching", and enter both a
4532 starting and ending regular expression. For example, to highlight everything
4533 between double quotes, you would enter a double quote character in both the
4534 starting and ending regular expression fields. Patterns with both a
4535 beginning and ending expression span all characters between the two
4536 expressions, including newlines.
4538 Again, the limitation for automatic parsing to operate properly is that both
4539 expressions must match within the context distance stated for the pattern
4542 With the ability to span large distances, comes the responsibility to recover
4543 when things go wrong. Remember that syntax highlighting is called upon to
4544 parse incorrect or incomplete syntax as often as correct syntax. To stop a
4545 pattern short of matching its end expression, you can specify an error
4546 expression, which stops the pattern from gobbling up more than it should.
4547 For example, if the text between double quotes shouldn't contain newlines,
4548 the error expression might be "$". As with both starting and ending
4549 expressions, error expressions must also match within the requested context
4552 4>Coloring Sub-Expressions
4554 It is also possible to color areas of text within a regular expression
4555 match. A pattern of this type associates a style with sub-expressions
4556 references of the parent pattern (as used in regular expression substitution
4557 patterns, see the NEdit Help menu item on Regular_Expressions_).
4558 Sub-expressions of both the starting and ending patterns may be colored. For
4559 example, if the parent pattern has a starting expression "\<", and end
4560 expression "\>", (for highlighting all of the text contained within angle
4561 brackets), a sub-pattern using "&" in both the starting and ending expression
4562 fields could color the brackets differently from the intervening text. A
4563 quick shortcut to typing in pattern names in the Parent Pattern field is to
4564 use the middle mouse button to drag them from the Patterns list.
4566 In some cases, there can be interference between coloring sub-patterns and
4567 hierarchical sub-patterns (disscussed next). How this is resolved, is
4570 4>Hierarchical Patterns
4572 A hierarchical sub-pattern, is identical to a top level pattern, but is
4573 invoked only between the starting and ending expression matches of its
4574 parent pattern or, in case the parent pattern consists of a single
4575 expression, inside the text area matching that expression. Like the
4576 sub-expression coloring patterns discussed above, it is associated with a
4577 parent pattern using the Parent Pattern field in the pattern specification.
4578 Pattern names can be dragged from the pattern list with the middle mouse
4579 button to the Parent Pattern field.
4581 The matching behaviour for sub-patterns is slightly different, depending on
4582 whether the parent pattern consists of a single expression or has both a
4583 starting and an ending expression.
4585 In case the parent pattern consists of a single expression, and the syntax
4586 highlighting parser finds a match for that expression, sub-patterns are
4587 matched between the start and the end of the parent match. Sub-patterns
4588 cannot extend beyond the boundaries of the parent's match nor can they
4589 affect those boundaries (the latter can happen for starting/ending parent
4590 patterns, see below). Note that sub-patterns can ~peek~ beyond the
4591 parent's matching boundaries by means of look-ahead or look-behind
4594 In case the parent pattern is a starting/ending style pattern, after the
4595 start expression of the parent pattern matches, the syntax highlighting
4596 parser searches for either the parent's end pattern or a matching
4597 sub-pattern. When a sub-pattern matches, control is not returned to the
4598 parent pattern until the entire sub-pattern has been parsed, regardless of
4599 whether the parent's end pattern appears in the text matched by the
4600 sub-pattern. In this way, matching of the parent's ending pattern can be
4601 postponed, in contrast to the case where the parent pattern consists of a
4602 single expression. Note that, in this case, parsing of sub-patterns starts
4603 **after** the match of the parent pattern's starting expression, also in
4604 contrast to the single-expression case.
4606 The most common use for this capability is for coloring sub-structure of
4607 language constructs (smaller patterns embedded in larger patterns).
4608 Hierarchical patterns can also simplify parsing by having sub-patterns "hide"
4609 special syntax from parent patterns, such as special escape sequences or
4612 There is no depth limit in nesting hierarchical sub-patterns, but beyond the
4613 third level of nesting, automatic re-parsing will sometimes have to re-parse
4614 more than the requested context distance to guarantee a correct parse (which
4615 can slow down the maximum rate at which the user can type if large sections
4616 of text are matched only by deeply nested patterns).
4618 While this is obviously not a complete hierarchical language parser it is
4619 still useful in many text coloring situations. As a pattern writer, your
4620 goal is not to completely cover the language syntax, but to generate
4621 colorings that are useful to the programmer. Simpler patterns are usually
4622 more efficient and also more robust when applied to incorrect code.
4624 Note that in case of a single-expression parent pattern, there is a
4625 potential for conflicts between coloring-only sub-patterns and hierarchical
4626 sub-patterns (which cannot happen for starting/ending type of patterns,
4627 because sub-patterns are matched **between** the starting and ending pattern
4628 (not included)). Due to the different nature of these two kinds of
4629 sub-patterns, it is technically infeasible to follow the standard matching
4630 precedence rules, where a sub-pattern has precedence over the sub-patterns
4631 following it. Instead, coloring-only sub-patterns are always colored last,
4632 ie., they may override the coloring for overlapping sibling sub-patterns in
4633 the overlapping parts of the matches.
4635 4>Deferred (Pass-2) Parsing
4637 NEdit does pattern matching for syntax highlighting in two passes. The first
4638 pass is applied to the entire file when syntax highlighting is first turned
4639 on, and to new ranges of text when they are initially read or pasted in. The
4640 second pass is applied only as needed when text is exposed (scrolled in to
4643 If you have a particularly complex set of patterns, and parsing is beginning
4644 to add a noticeable delay to opening files or operations which change large
4645 regions of text, you can defer some of that parsing from startup time, to
4646 when it is actually needed for viewing the text. Deferred parsing can only
4647 be used with single expression patterns, or begin/end patterns which match
4648 entirely within the requested context distance. To defer the parsing of a
4649 pattern to when the text is exposed, click on the Pass-2 pattern type button
4650 in the highlight patterns dialog.
4652 Sometimes a pattern can't be deferred, not because of context requirements,
4653 but because it must run concurrently with pass-1 (non-deferred) patterns. If
4654 they didn't run concurrently, a pass-1 pattern might incorrectly match some
4655 of the characters which would normally be hidden inside of a sequence matched
4656 by the deferred pattern. For example, C has character constants enclosed in
4657 single quotes. These typically do not cross line boundaries, meaning they
4658 can be parsed entirely within the context distance of the C pattern set and
4659 should be good candidates for deferred parsing. However, they can't be
4660 deferred because they can contain sequences of characters which can trigger
4661 pass-one patterns. Specifically, the sequence, '\"', contains a double quote
4662 character, which would be matched by the string pattern and interpreted as
4663 introducing a string.
4665 4>Pattern Context Requirements
4667 The context requirements of a pattern set state how much additional text
4668 around any change must be examined to guarantee that the patterns will match
4669 what they are intended to match. Context requirements are a promise by NEdit
4670 to the pattern writer, that the regular expressions in his/her patterns will
4671 be matched against at least <line context> lines and <character context>
4672 characters, around any modified text. Combining line and character
4673 requirements guarantee that both will be met.
4675 Automatic re-parsing happens on EVERY KEYSTROKE, so the amount of context
4676 which must be examined is very critical to typing efficiency. The more
4677 complicated your patterns, the more critical the context becomes. To cover
4678 all of the keywords in a typical language, without affecting the maximum rate
4679 at which users can enter text, you may be limited to just a few lines and/or
4680 a few hundred characters of context.
4682 The default context distance is 1 line, with no minimum character
4683 requirement. There are several benefits to sticking with this default. One
4684 is simply that it is easy to understand and to comply with. Regular
4685 expression notation is designed around single line matching. To span lines
4686 in a regular expression, you must explicitly mention the newline character
4687 "\n", and matches which are restricted to a single line are virtually immune
4688 to lock-ups. Also, if you can code your patterns to work within a single
4689 line of context, without an additional character-range context requirement,
4690 the parser can take advantage the fact that patterns don't cross line
4691 boundaries, and nearly double its efficiency over a one-line and 1-character
4692 context requirement. (In a single line context, you are allowed to match
4693 newlines, but only as the first and/or last character.)
4694 ----------------------------------------------------------------------
4699 Smart indent macros can be written for any language, but are usually more
4700 difficult to write than highlighting patterns. A good place to start, of
4701 course, is to look at the existing macros for C and C++.
4703 Smart indent macros for a language mode consist of standard NEdit macro
4704 language code attached to any or all of the following three activation
4705 conditions: 1) When smart indent is first turned on for a text window
4706 containing code of the language, 2) When a newline is typed and smart indent
4707 is expected, 3) after any character is typed. To attach macro code to any of
4708 these code "hooks", enter it in the appropriate section in the Preferences ->
4709 Default Settings -> Auto Indent -> Program Smart Indent dialog.
4711 Typically most of the code should go in the initialization section, because
4712 that is the appropriate place for subroutine definitions, and smart indent
4713 macros are complicated enough that you are not likely to want to write them
4714 as one monolithic run of code. You may also put code in the Common/Shared
4715 Initialization section (accessible through the button in the upper left
4716 corner of the dialog). Unfortunately, since the C/C++ macros also reside in
4717 the common/shared section, when you add code there, you run some risk of
4718 missing out on future upgrades to these macros, because your changes will
4719 override the built-in defaults.
4721 The newline macro is invoked after the user types a newline, but before the
4722 newline is entered in the buffer. It takes a single argument ($1) which is
4723 the position at which the newline will be inserted. It must return the
4724 number of characters of indentation the line should have, or -1. A return
4725 value of -1 means to do a standard auto-indent. You must supply a newline
4726 macro, but the code: "return -1" (auto-indent), or "return 0" (no indent) is
4729 The type-in macro takes two arguments. $1 is the insert position, and $2 is
4730 the character just inserted, and does not return a value. You can do just
4731 about anything here, but keep in mind that this macro is executed for every
4732 keystroke typed, so if you try to get too fancy, you may degrade performance.
4733 ----------------------------------------------------------------------
4738 .. ? help !!#ifndef VMS
4739 **nedit** [-**read**] [-**create**] [-**line** n | +n] [-**server**]
4740 [-**do** command] [-**tags** file] [-**tabs** n] [-**wrap**]
4741 [-**nowrap**] [-**autowrap**] [-**autoindent**] [-**noautoindent**]
4742 [-**autosave**] [-**noautosave**] [-**rows** n] [-**columns** n]
4743 [-**font** font] [-**lm** languagemode] [-**geometry** geometry]
4744 [-**iconic**] [-**noiconic**] [-**display** [host]:server[.screen]
4745 [-**xrm** resourcestring] [-**svrname** name] [-**import** file]
4746 [-**background** color] [-**foreground** color]
4747 [-**tabbed**] [-**untabbed**] [-**group**] [-**V**|-**version**]
4751 Open the file Read Only regardless of the actual file protection.
4754 Don't warn about file creation when a file doesn't exist.
4760 Designate this session as an NEdit server, for processing commands from the
4761 nc program. nc can be used to interface NEdit to code development
4762 environments, mailers, etc., or just as a quick way to open files from the
4763 shell command line without starting a new NEdit session.
4766 Execute an NEdit macro or action on the file following the -do argument on
4767 the command line. -do is particularly useful from the nc program, where
4768 nc -do can remotely execute commands in an NEdit -server session.
4771 Load a file of directions for finding definitions of program subroutines and
4772 data objects. The file must be of the format generated by Exuberant Ctags,
4773 or the standard Unix ctags command.
4776 Set tab stops every n characters.
4779 Wrap long lines at the right edge of the window rather than continuing them
4780 past it. (Continuous Wrap mode)
4782 **-autowrap, -noautowrap**
4783 Wrap long lines when the cursor reaches the right edge of the window by
4784 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4786 **-autoindent, -noautoindent**
4787 Maintain a running indent.
4789 **-autosave, -noautosave**
4790 Maintain a backup copy of the file being edited under the name '~filename'.
4793 Default height in characters for an editing window.
4796 Default width in characters for an editing window.
4798 **-font font (or -fn font)**
4799 Font for text being edited (Font for menus and dialogs can be set with -xrm
4802 **-lm languagemode**
4803 Initial language mode used for editing succeeding files.
4805 **-geometry geometry (or -g geometry)**
4806 The initial size and/or location of editor windows. The argument geometry
4809 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4811 where <width> and <height> are the desired width and height of the window,
4812 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4813 the window, + for top or left, - for bottom or right. -geometry can be
4814 specified for individual files on the command line.
4816 **-iconic, -noiconic**
4817 Initial window state for succeeding files.
4819 **-display [host]:server[.screen]**
4820 The name of the X server to use. host specifies the machine, server
4821 specifies the display server number, and screen specifies the screen number.
4822 host or screen can be omitted and default to the local machine, and screen 0.
4824 **-background color (or -bg color)**
4825 User interface background color. (Background color for text can be set
4826 separately with -xrm "nedit.textBgColor: color" or using the Preferences ->
4829 **-foreground color (or -fg color)**
4830 User interface foreground color. (Foreground color for text can be set
4831 separately with -xrm "nedit.textFgColor: color" or using the Preferences
4835 Open all subsequent files in new tabs. Resets -group option.
4838 Open all subsequent files in new windows. Resets -group option.
4841 Open all subsequent files as tabs in a new window.
4843 **-xrm resourcestring**
4844 Set the value of an X resource to override a default
4845 value (see "Customizing_NEdit_").
4848 When starting NEdit in server mode, name the server, such that it responds to
4849 requests only when nc is given a corresponding -svrname argument. By naming
4850 servers, you can run several simultaneously, and direct files and commands
4851 specifically to any one. Specifying a non-empty name automatically designates
4852 this session as an NEdit server, as though -server were specified.
4855 Loads an additional preferences file on top of the existing defaults saved in
4856 your preferences file. To incorporate macros, language modes, and highlight
4857 patterns and styles written by other users, run NEdit with -import <file>,
4858 then re-save your preference file with Preferences -> Save Defaults.
4861 Prints out the NEdit version information. The -V option is synonymous.
4864 Treats all subsequent arguments as file names, even if they start with a
4865 dash. This is so NEdit can access files that begin with the dash character.
4870 .. This documentation for VMS NEdit usage should only appear in the
4871 .. generated help code, not in any of the printed documentation.
4872 .. Reasoning is that VMS usage is diminishing and there is a desire
4873 .. to not clutter up the printed documentation here.
4875 NEDIT [filespec[,...]]
4877 The following qualifiers are accepted:
4880 Open the file Read Only regardless of the actual file protection.
4883 Don't warn about file creation when a file doesn't exist.
4889 Designate this session as an NEdit server for processing commands from the nc
4890 program. The nc program can be used to interface NEdit to code development
4891 environments, mailers, etc., or just as a quick way to open files from the
4892 shell command line without starting a new NEdit session.
4895 Execute an NEdit action routine. on each file following the /do argument on
4896 the command line. /do is particularly useful from the nc program, where nc
4897 /do can remotely execute commands in an nedit /server session.
4900 Load a file of directions for finding definitions of program subroutines and
4901 data objects. The file must be of the format generated by the Unix ctags
4905 Wrap long lines at the right edge of the window rather than continuing them
4906 past it. (Continuous Wrap mode)
4908 **/autowrap, /noautowrap**
4909 Wrap long lines when the cursor reaches the right edge of the window by
4910 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4912 **/autoindent, /noautoindent**
4913 Maintain a running indent.
4915 **/autosave, /noautosave**
4916 Maintain a backup copy of the file being edited under the name '_filename'.
4919 Default width in characters for an editing window.
4922 Default height in characters for an editing window.
4924 **/font=font (or /fn=font)**
4925 Font for text being edited (Font for menus and dialogs can be set with
4926 /xrm="*fontList:font").
4928 **/display [host]:server[.screen]**
4929 The name of the X server to use. host specifies the machine, server
4930 specifies the display server number, and screen specifies the screen number.
4931 host or screen can be omitted and default to the local machine, and screen 0.
4933 **/geometry=geometry (or /g=geometry)**
4934 The initial size and/or location of editor windows. The argument geometry
4937 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4939 where <width> and <height> are the desired width and height of the window,
4940 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4941 the window, + for top or left, - for bottom or right.
4943 **/background=color (or /bg=color)**
4945 Background color. (background color for text can be set separately with
4946 /xrm="nedit:textBgColor color" or using the Preferences ->
4949 **/foreground=color (or /fg=color)**
4950 Foreground color. (foreground color for text can be set separately with
4951 /xrm="nedit:textFgColor color" or using the Preferences ->
4955 Open all subsequent files in new tabs. Resets /group option.
4958 Open all subsequent files in new windows. Resets /group option.
4961 Open all subsequent files as tabs in a new window.
4963 **/xrm=resourcestring**
4964 Set the value of an X resource to override a default value
4965 (see Customizing NEdit).
4968 When starting nedit in server mode, name the server, such that it responds to
4969 requests only when nc is given a corresponding -svrname argument. By naming
4970 servers, you can run several simultaneously, and direct files and commands
4971 specifically to any one.
4974 Loads an additional preferences file on top of the existing defaults saved in
4975 your .nedit file. To incorporate macros, language modes, and highlight
4976 patterns and styles written by other users, run nedit with /import=<file>,
4977 then re-save your .nedit file with Preferences -> Save Defaults.
4979 Unix-style command lines (but not file names) are also acceptable:
4981 nedit -rows 20 -wrap file1.c file2.c
4985 nedit /rows=20/wrap file1.c, file2.c",
4988 ----------------------------------------------------------------------
4993 NEdit can be operated on its own, or as a two-part client/server
4994 application. Client/server mode is useful for integrating NEdit with
4995 software development environments, mailers, and other programs; or just as a
4996 quick way to open files from the shell command line without starting a new
4999 To run NEdit in server mode, type:
5003 NEdit can also be started in server mode via the NEdit Client program
5004 (**nc**) when no servers are available.
5006 The nc program, which is distributed along with NEdit, sends commands to
5007 an NEdit server to open files or execute editor actions. It can also be
5008 used on files that are already opened.
5010 Listing a file on the nc command line means: Open it if it is not already
5011 open and bring the window to the front.
5014 nc supports the following command line options:
5016 **nc** [**-read**] [**-create**]
5017 [**-line** n | **+**n] [**-do** command] [**-lm** languagemode]
5018 [**-svrname** name] [**-svrcmd** command]
5019 [**-ask**] [**-noask**] [**-timeout** seconds]
5020 [**-geometry** geometry | **-g** geometry] [**-icon** | **-iconic**]
5021 [-**tabbed**] [-**untabbed**] [-**group**] [**-wait**]
5022 [**-V** | **-version**]
5023 [**-xrm** resourcestring] [**-display** [host]:server[.screen]]
5027 Open the file read-only regardless of its actual permissions. There is no
5028 effect if the file is already open.
5031 Don't warn about file creation when a file doesn't exist.
5034 Go to line number n. This will also affect files which are already open.
5037 Execute an NEdit macro or action on the file following the -do argument
5038 on the command line.
5040 If you use this command without a filename, nc would randomly choose one
5041 window to focus and execute the macro in.
5043 **-ask**, **-noask**
5044 Instructs nc to automatically start a server if one is not available. This
5045 overrides the X resource `nc.autoStart' (see X_Resources_).
5048 Explicitly instructs nc which server to connect to, an instance of
5049 nedit(1) with a corresponding -svrname argument. By naming servers, you
5050 can run several simultaneously, and direct files and commands
5051 specifically to any one.
5054 The command which nc uses to start an NEdit server. It is also settable
5055 via the X resource `nc.serverCommand' (see X_Resources_). Defaults to
5058 **-lm** languagemode
5059 Initial language mode used.
5061 **-geometry** geometry, **-g** geometry
5062 The initial size and/or location of editor windows. See
5063 NEdit_Command_Line_ for details.
5065 **-icon**, **-iconic**
5066 Initial window state.
5068 **-display** [<host>]:<server>[.<screen>]
5069 The name of the X server to use. See NEdit_Command_Line_ for details.
5071 **-timeout** seconds
5072 Basic time-out period used in communication with an NEdit server. The
5073 default is 10 seconds. Also settable via the X resource `nc.timeOut'.
5075 Under rare conditions (such as a slow connection), it may be necessary to
5076 increase the time-out period. In most cases, the default is fine.
5079 Open all subsequent files in new tabs. Resets -group option.
5082 Open all subsequent files in new windows. Resets -group option.
5085 Open all subsequent files as tabs in a new window.
5088 Instructs nc not to return to the shell until all files given are closed.
5090 Normally, nc returns once the files given in its command line are opened
5091 by the server. When this option is given, nc returns only after the last
5092 file given in this call is closed.
5094 Note that this option affects all files in the command line, not only the
5095 ones following this option.
5097 Note that nc will wait for all files given in the command line, even if
5098 the files were already opened.
5101 4>Command Line Arguments
5103 In typical Unix style, arguments affect the files which follow them on the
5104 command line, for example:
5106 incorrect: nc file.c -line 25
5107 correct: nc -line 25 file.c
5109 -read, -create, and -line affect all of the files which follow them on the
5112 The -do macro is executed only once, on the next file on the line. -do
5113 without a file following it on the command line, executes the macro on the
5114 first available window (presumably when you give a -do command without a
5115 corresponding file or window, you intend it to do something independent of
5116 the window in which it happens to execute).
5118 The -wait option affects all files named in the command line.
5122 Sometimes it is useful to have more than one NEdit server running, for
5123 example to keep mail and programming work separate. The option, -svrname, to
5124 both nedit and nc, allows you to start, and communicate with, separate named
5125 servers. A named server responds only to requests with the corresponding
5126 -svrname argument. If you use ClearCase and are within a ClearCase view, the
5127 server name will default to the name of the view (based on the value of the
5128 CLEARCASE_ROOT environment variable).
5132 Communication between nc and nedit is done through the X display. So as long
5133 as the X Window System is set up and working properly, nc will work properly
5134 as well. nc uses the DISPLAY environment variable, the machine name and your
5135 user name to find the appropriate server, meaning, if you have several
5136 machines sharing a common file system, nc will not be able to find a server
5137 that is running on a machine with a different host name, even though it may
5138 be perfectly appropriate for editing a given file.
5140 The command which nc uses to start an nedit server is settable via the X
5141 resource nc.serverCommand, by default, "nedit -server".
5142 ----------------------------------------------------------------------
5147 If a system crash, network failure, X server crash, or program error should
5148 happen while you are editing a file, you can still recover most of your
5149 work. NEdit maintains a backup file which it updates periodically (every 8
5150 editing operations or 80 characters typed). This file has the same name
5151 as the file that you are editing, but with the character `~' (tilde) on Unix
5152 or `_' (underscore) on VMS prefixed to the name. To recover a file after a
5153 crash, simply rename the file to remove the tilde or underscore character,
5154 replacing the older version of the file. (Because several of the Unix shells
5155 consider the tilde to be a special character, you may have to prefix the
5156 character with a `\' (backslash) when you move or delete an NEdit backup
5159 Example, to recover the file called "help.c" on Unix type the command:
5163 A minor caveat, is that if the file you were editing was in MS DOS format,
5164 the backup file will be in Unix format, and you will need to open the backup
5165 file in NEdit and change the file format back to MS DOS via the Save As...
5166 dialog (or use the Unix unix2dos command outside of NEdit).
5167 ----------------------------------------------------------------------
5178 .. There is build time versioning information that is handled specially
5179 .. inside help.c for this section. It needs to have a '%s' string
5180 .. made available for it to appear in the on-line help.
5184 .. ======================================================================
5185 .. The policy for credit so far is this:
5187 .. You get "written by" credit if you have contributed significant
5188 .. code or effort to the project.
5190 .. You get a syntax/indent credit if your pattern is compiled into the
5192 .. ======================================================================
5194 NEdit was written by Mark Edel, Joy Kyriakopulos, Christopher Conrad,
5195 Jim Clark, Arnulfo Zepeda-Navratil, Suresh Ravoor, Tony Balinski, Max
5196 Vohlken, Yunliang Yu, Donna Reid, Arne Førlie, Eddy De Greef, Steve
5197 LoBasso, Alexander Mai, Scott Tringali, Thorsten Haude, Steve Haehn,
5198 Andrew Hood, Nathaniel Gray, and TK Soh.
5200 The regular expression matching routines used in NEdit are adapted (with
5201 permission) from original code written by Henry Spencer at the
5202 University of Toronto.
5204 The Microline widgets are inherited from the Mozilla project.
5206 Syntax highlighting patterns and smart indent macros were contributed by:
5207 Simon T. MacDonald, Maurice Leysens, Matt Majka, Alfred Smeenk,
5208 Alain Fargues, Christopher Conrad, Scott Markinson, Konrad Bernloehr,
5209 Ivan Herman, Patrice Venant, Christian Denat, Philippe Couton,
5210 Max Vohlken, Markus Schwarzenberg, Himanshu Gohel, Steven C. Kapp,
5211 Michael Turomsha, John Fieber, Chris Ross, Nathaniel Gray, Joachim Lous,
5212 Mike Duigou, Seak Teng-Fong, Joor Loohuis, Mark Jones,
5213 and Niek van den Berg.
5215 NEdit sources, executables, additional documentation, and contributed
5216 software are available from the NEdit web site at http://www.nedit.org_.
5218 This program is free software; you can redistribute it and/or
5219 modify it under the terms of the GNU_General_Public_License_
5220 as published by the Free Software Foundation; either version 2
5221 of the License, or (at your option) any later version.
5223 In addition, as a special exception to the GNU GPL, the copyright holders
5224 give permission to link the code of this program with the Motif and Open
5225 Motif libraries (or with modified versions of these that use the same
5226 license), and distribute linked combinations including the two. You must
5227 obey the GNU General Public License in all respects for all of the code
5228 used other than linking with Motif/Open Motif. If you modify this file,
5229 you may extend this exception to your version of the file, but you are
5230 not obligated to do so. If you do not wish to do so, delete this
5231 exception statement from your version.
5233 This program is distributed in the hope that it will be useful,
5234 but WITHOUT ANY WARRANTY; without even the implied warranty of
5235 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
5236 section on the GNU_General_Public_License_ for more details.
5237 ----------------------------------------------------------------------
5239 GNU General Public License
5242 GNU GENERAL PUBLIC LICENSE
5244 Version 2, June 1991
5246 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave,
5247 Cambridge, MA 02139, USA. Everyone is permitted to copy and distribute
5248 verbatim copies of this license document, but changing it is not allowed.
5252 The licenses for most software are designed to take away your freedom to
5253 share and change it. By contrast, the GNU General Public License is intended
5254 to guarantee your freedom to share and change free software--to make sure the
5255 software is free for all its users. This General Public License applies to
5256 most of the Free Software Foundation's software and to any other program
5257 whose authors commit to using it. (Some other Free Software Foundation
5258 software is covered by the GNU Library General Public License instead.) You
5259 can apply it to your programs, too.
5261 When we speak of free software, we are referring to freedom, not price. Our
5262 General Public Licenses are designed to make sure that you have the freedom
5263 to distribute copies of free software (and charge for this service if you
5264 wish), that you receive source code or can get it if you want it, that you
5265 can change the software or use pieces of it in new free programs; and that
5266 you know you can do these things.
5268 To protect your rights, we need to make restrictions that forbid anyone to
5269 deny you these rights or to ask you to surrender the rights. These
5270 restrictions translate to certain responsibilities for you if you distribute
5271 copies of the software, or if you modify it.
5273 For example, if you distribute copies of such a program, whether gratis or
5274 for a fee, you must give the recipients all the rights that you have. You
5275 must make sure that they, too, receive or can get the source code. And you
5276 must show them these terms so they know their rights.
5278 We protect your rights with two steps: (1) copyright the software, and (2)
5279 offer you this license which gives you legal permission to copy, distribute
5280 and/or modify the software.
5282 Also, for each author's protection and ours, we want to make certain that
5283 everyone understands that there is no warranty for this free software. If the
5284 software is modified by someone else and passed on, we want its recipients to
5285 know that what they have is not the original, so that any problems introduced
5286 by others will not reflect on the original authors' reputations.
5288 Finally, any free program is threatened constantly by software patents. We
5289 wish to avoid the danger that redistributors of a free program will
5290 individually obtain patent licenses, in effect making the program
5291 proprietary. To prevent this, we have made it clear that any patent must be
5292 licensed for everyone's free use or not licensed at all.
5294 The precise terms and conditions for copying, distribution and modification
5297 GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
5300 0. This License applies to any program or other work which contains a notice
5301 placed by the copyright holder saying it may be distributed under the terms
5302 of this General Public License. The "Program", below, refers to any such
5303 program or work, and a "work based on the Program" means either the Program
5304 or any derivative work under copyright law: that is to say, a work containing
5305 the Program or a portion of it, either verbatim or with modifications and/or
5306 translated into another language. (Hereinafter, translation is included
5307 without limitation in the term "modification".) Each licensee is addressed as
5310 Activities other than copying, distribution and modification are not covered
5311 by this License; they are outside its scope. The act of running the Program
5312 is not restricted, and the output from the Program is covered only if its
5313 contents constitute a work based on the Program (independent of having been
5314 made by running the Program). Whether that is true depends on what the
5317 1. You may copy and distribute verbatim copies of the Program's source code
5318 as you receive it, in any medium, provided that you conspicuously and
5319 appropriately publish on each copy an appropriate copyright notice and
5320 disclaimer of warranty; keep intact all the notices that refer to this
5321 License and to the absence of any warranty; and give any other recipients of
5322 the Program a copy of this License along with the Program.
5324 You may charge a fee for the physical act of transferring a copy, and you may
5325 at your option offer warranty protection in exchange for a fee.
5327 2. You may modify your copy or copies of the Program or any portion of it,
5328 thus forming a work based on the Program, and copy and distribute such
5329 modifications or work under the terms of Section 1 above, provided that you
5330 also meet all of these conditions:
5332 a) You must cause the modified files to carry prominent notices stating
5333 that you changed the files and the date of any change.
5335 b) You must cause any work that you distribute or publish, that in whole or
5336 in part contains or is derived from the Program or any part thereof, to be
5337 licensed as a whole at no charge to all third parties under the terms of
5340 c) If the modified program normally reads commands interactively when run,
5341 you must cause it, when started running for such interactive use in the
5342 most ordinary way, to print or display an announcement including an
5343 appropriate copyright notice and a notice that there is no warranty (or
5344 else, saying that you provide a warranty) and that users may redistribute
5345 the program under these conditions, and telling the user how to view a copy
5346 of this License. (Exception: if the Program itself is interactive but does
5347 not normally print such an announcement, your work based on the Program is
5348 not required to print an announcement.)
5350 These requirements apply to the modified work as a whole. If identifiable
5351 sections of that work are not derived from the Program, and can be reasonably
5352 considered independent and separate works in themselves, then this License,
5353 and its terms, do not apply to those sections when you distribute them as
5354 separate works. But when you distribute the same sections as part of a whole
5355 which is a work based on the Program, the distribution of the whole must be
5356 on the terms of this License, whose permissions for other licensees extend to
5357 the entire whole, and thus to each and every part regardless of who wrote it.
5359 Thus, it is not the intent of this section to claim rights or contest your
5360 rights to work written entirely by you; rather, the intent is to exercise the
5361 right to control the distribution of derivative or collective works based on
5364 In addition, mere aggregation of another work not based on the Program with
5365 the Program (or with a work based on the Program) on a volume of a storage or
5366 distribution medium does not bring the other work under the scope of this
5369 3. You may copy and distribute the Program (or a work based on it, under
5370 Section 2) in object code or executable form under the terms of Sections 1
5371 and 2 above provided that you also do one of the following:
5373 a) Accompany it with the complete corresponding machine-readable source
5374 code, which must be distributed under the terms of Sections 1 and 2 above
5375 on a medium customarily used for software interchange; or,
5377 b) Accompany it with a written offer, valid for at least three years, to
5378 give any third party, for a charge no more than your cost of physically
5379 performing source distribution, a complete machine-readable copy of the
5380 corresponding source code, to be distributed under the terms of Sections 1
5381 and 2 above on a medium customarily used for software interchange; or,
5383 c) Accompany it with the information you received as to the offer to
5384 distribute corresponding source code. (This alternative is allowed only for
5385 noncommercial distribution and only if you received the program in object
5386 code or executable form with such an offer, in accord with Subsection b
5389 The source code for a work means the preferred form of the work for making
5390 modifications to it. For an executable work, complete source code means all
5391 the source code for all modules it contains, plus any associated interface
5392 definition files, plus the scripts used to control compilation and
5393 installation of the executable. However, as a special exception, the source
5394 code distributed need not include anything that is normally distributed (in
5395 either source or binary form) with the major components (compiler, kernel,
5396 and so on) of the operating system on which the executable runs, unless that
5397 component itself accompanies the executable.
5399 If distribution of executable or object code is made by offering access to
5400 copy from a designated place, then offering equivalent access to copy the
5401 source code from the same place counts as distribution of the source code,
5402 even though third parties are not compelled to copy the source along with the
5405 4. You may not copy, modify, sublicense, or distribute the Program except as
5406 expressly provided under this License. Any attempt otherwise to copy, modify,
5407 sublicense or distribute the Program is void, and will automatically
5408 terminate your rights under this License. However, parties who have received
5409 copies, or rights, from you under this License will not have their licenses
5410 terminated so long as such parties remain in full compliance.
5412 5. You are not required to accept this License, since you have not signed it.
5413 However, nothing else grants you permission to modify or distribute the
5414 Program or its derivative works. These actions are prohibited by law if you
5415 do not accept this License. Therefore, by modifying or distributing the
5416 Program (or any work based on the Program), you indicate your acceptance of
5417 this License to do so, and all its terms and conditions for copying,
5418 distributing or modifying the Program or works based on it.
5420 6. Each time you redistribute the Program (or any work based on the Program),
5421 the recipient automatically receives a license from the original licensor to
5422 copy, distribute or modify the Program subject to these terms and conditions.
5423 You may not impose any further restrictions on the recipients' exercise of
5424 the rights granted herein. You are not responsible for enforcing compliance
5425 by third parties to this License.
5427 7. If, as a consequence of a court judgment or allegation of patent
5428 infringement or for any other reason (not limited to patent issues),
5429 conditions are imposed on you (whether by court order, agreement or
5430 otherwise) that contradict the conditions of this License, they do not excuse
5431 you from the conditions of this License. If you cannot distribute so as to
5432 satisfy simultaneously your obligations under this License and any other
5433 pertinent obligations, then as a consequence you may not distribute the
5434 Program at all. For example, if a patent license would not permit
5435 royalty-free redistribution of the Program by all those who receive copies
5436 directly or indirectly through you, then the only way you could satisfy both
5437 it and this License would be to refrain entirely from distribution of the
5440 If any portion of this section is held invalid or unenforceable under any
5441 particular circumstance, the balance of the section is intended to apply and
5442 the section as a whole is intended to apply in other circumstances.
5444 It is not the purpose of this section to induce you to infringe any patents
5445 or other property right claims or to contest validity of any such claims;
5446 this section has the sole purpose of protecting the integrity of the free
5447 software distribution system, which is implemented by public license
5448 practices. Many people have made generous contributions to the wide range of
5449 software distributed through that system in reliance on consistent
5450 application of that system; it is up to the author/donor to decide if he or
5451 she is willing to distribute software through any other system and a licensee
5452 cannot impose that choice.
5454 This section is intended to make thoroughly clear what is believed to be a
5455 consequence of the rest of this License.
5457 8. If the distribution and/or use of the Program is restricted in certain
5458 countries either by patents or by copyrighted interfaces, the original
5459 copyright holder who places the Program under this License may add an
5460 explicit geographical distribution limitation excluding those countries, so
5461 that distribution is permitted only in or among countries not thus excluded.
5462 In such case, this License incorporates the limitation as if written in the
5463 body of this License.
5465 9. The Free Software Foundation may publish revised and/or new versions of
5466 the General Public License from time to time. Such new versions will be
5467 similar in spirit to the present version, but may differ in detail to address
5468 new problems or concerns.
5470 Each version is given a distinguishing version number. If the Program
5471 specifies a version number of this License which applies to it and "any later
5472 version", you have the option of following the terms and conditions either of
5473 that version or of any later version published by the Free Software
5474 Foundation. If the Program does not specify a version number of this License,
5475 you may choose any version ever published by the Free Software Foundation.
5477 10. If you wish to incorporate parts of the Program into other free programs
5478 whose distribution conditions are different, write to the author to ask for
5479 permission. For software which is copyrighted by the Free Software
5480 Foundation, write to the Free Software Foundation; we sometimes make
5481 exceptions for this. Our decision will be guided by the two goals of
5482 preserving the free status of all derivatives of our free software and of
5483 promoting the sharing and reuse of software generally.
5487 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
5488 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
5489 STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
5490 PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
5491 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
5492 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
5493 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
5494 YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
5496 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
5497 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
5498 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
5499 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
5500 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO
5501 LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
5502 THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
5503 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
5504 POSSIBILITY OF SUCH DAMAGES.
5506 END OF TERMS AND CONDITIONS
5507 ----------------------------------------------------------------------
5512 There are two separate mailing lists for nedit users, and one for developers.
5513 Users may post to the developer mailing list to report defects and communicate
5514 with the nedit developers. Remember that nedit is entirely a volunteer
5515 effort, so please ask questions first to the discussion list, and do your
5516 share to answer other users questions as well.
5520 General discussion, questions and answers among NEdit users and developers.
5522 announce@@nedit.org_
5524 A low-volume mailing list for announcing new versions.
5528 Communication among and with NEdit developers.
5529 Developers should also subscribe to the discuss list.
5531 To subscribe, send mail to one of the following addresses:
5533 announce-request@@nedit.org_
5534 discuss-request@@nedit.org_
5535 develop-request@@nedit.org_
5537 with the body consisting of the single word
5540 ----------------------------------------------------------------------
5545 3>Solutions to Common Problems
5547 For a much more comprehensive list of common problems and solutions, see the
5548 NEdit FAQ. The latest version of the FAQ can always be found on the NEdit
5551 http://www.nedit.org_.
5553 **P: No files are shown in the "Files" list in the Open... dialog.**
5555 S: When you use the "Filter" field, include the file specification or a
5556 complete directory specification, including the trailing "/" on Unix.
5557 (See Help in the Open... dialog).
5559 **P: Find Again and Replace Again don't continue in the same direction as the original Find or Replace.**
5561 S: Find Again and Replace Again don't use the direction of the original
5562 search. The Shift key controls the direction: Ctrl+G means forward,
5563 Shift+Ctrl+G means backward.
5565 **P: Preferences specified in the Preferences menu don't seem to get saved when I select Save Defaults.**
5567 S: NEdit has two kinds of preferences: 1) per-window preferences, in the
5568 Preferences menu, and 2) default settings for preferences in newly created
5569 windows, in the Default Settings sub-menu of the Preferences menu.
5570 Per-window preferences are not saved by Save Defaults, only Default
5573 **P: Columns and indentation don't line up.**
5575 S: NEdit is using a proportional width font. Set the font to a fixed style
5576 (see Preferences menu).
5578 **P: NEdit performs poorly on very large files.**
5580 S: Turn off Incremental Backup. With Incremental Backup on, NEdit
5581 periodically writes a full copy of the file to disk.
5583 **P: Commands added to the Shell Commands menu (Unix only) don't output anything until they are finished executing.**
5585 S: If the command output is directed to a dialog, or the input is from a
5586 selection, output is collected together and held until the command
5587 completes. De-select both of the options and the output will be shown
5588 incrementally as the command executes.
5590 **P: Dialogs don't automatically get keyboard focus when they pop up.**
5592 S: Most X Window managers allow you to choose between two categories of
5593 keyboard focus models: pointer focus, and explicit focus. Pointer focus
5594 means that as you move the mouse around the screen, the window under the
5595 mouse automatically gets the keyboard focus. NEdit users who use this
5596 focus model should set "Popups Under Pointer" in the Default Settings sub
5597 menu of the preferences menu in NEdit. Users with the explicit focus
5598 model, in some cases, may have problems with certain dialogs, such as Find
5599 and Replace. In MWM this is caused by the mwm resource startupKeyFocus
5600 being set to False (generally a bad choice for explicit focus users).
5601 NCDwm users should use the focus model "click" instead of "explicit",
5602 again, unless you have set it that way to correct specific problems, this
5603 is the appropriate setting for most explicit focus users.
5605 **P: The Backspace key doesn't work, or deletes forward rather than backward.**
5607 S: While this is an X/Motif binding problem, and should be solved outside of
5608 NEdit in the Motif virtual binding layer (or possibly xmodmap or
5609 translations), NEdit provides an out. If you set the resource:
5610 nedit.remapDeleteKey to True, NEdit will forcibly map the delete key to
5611 backspace. The default setting of this resource recently changed, so
5612 users who have been depending on this remapping will now have to set it
5613 explicitly (or fix their bindings).
5615 **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.**
5617 S: On many SunOS systems, you have to set up an nls directory before various
5618 inter-client communication features of Motif will function properly.
5619 There are instructions in README.sun in /pub/v5_0_2/individual/README.sun on
5620 ftp.nedit.org, as well as a tar file containing a complete nls
5621 directory: ftp://ftp.nedit.org/pub/v5_0_2/nls.tar.
5622 README.sun contains directions for setting up an nls directory, which
5623 is required by Motif for handling copy and paste to Motif text fields.
5627 Below is the list of known defects which affect NEdit. The defects your copy
5628 of NEdit will exhibit depend on which system you are running and with which
5629 Motif libraries it was built. Note that there are now Motif 1.2 and/or 2.0
5630 libraries available on ALL supported platforms, and as you can see below
5631 there are far fewer defects in Motif 1.2, so it is in your best interest to
5632 upgrade your system.
5637 Operations between rectangular selections on overlapping lines do nothing.
5640 None. These operations are very complicated and rarely used.
5643 Cut and Paste menu items fail, or possibly crash,
5644 for very large (multi-megabyte) selections.
5647 Use selection copy (middle mouse button click)
5648 for transferring larger quantities of data.
5649 Cut and Paste save the copied text in server
5650 memory, which is usually limited.
5654 Submit bugs through the web at:
5656 http://sf.net/tracker/?func=add&group_id=11005&atid=111005
5658 Please include the first few lines from Help > Version, which identifies
5659 NEdit's version and other system attributes important for diagnosing your
5662 The NEdit developers subscribe to both discuss@@nedit.org and
5663 develop@@nedit.org, either of which may be used for reporting defects. If
5664 you're not sure, or you think the report might be of interest to the general
5665 NEdit user community, send the report to discuss@@nedit.org_. If it's
5666 something obvious and boring, like we misspelled "anemometer" in the on-line
5667 help, send it to develop@@nedit.org_. If you don't want to subscribe to the
5668 Mailing_Lists_, please add a note to your mail about cc'ing you on responses.
5672 .. Hyperlinks for this document ==============================================
5674 .. _discuss@@nedit.org mailto:discuss@@nedit.org
5675 .. _announce@@nedit.org mailto:announce@@nedit.org
5676 .. _develop@@nedit.org mailto:develop@@nedit.org
5677 .. _discuss-request@@nedit.org mailto:discuss-request@@nedit.org
5678 .. _announce-request@@nedit.org mailto:announce-request@@nedit.org
5679 .. _develop-request@@nedit.org mailto:develop-request@@nedit.org
5680 .. _http://www.nedit.org http://www.nedit.org
5681 .. _ctag_support #ctags
5682 .. _Alternation #alternation
5684 .. =============================================================================
5686 .. Below is what is used to guide the generation of 'C'-Motif menus.
5687 .. Indentation is SIGNIFICANT in the "Menu" directive lines below. It
5688 .. is used to determine under which menu element another item will belong.
5689 .. The number of spaces indented is not significant, but items to be placed
5690 .. in the same menu panel MUST line up at the same indent level.
5691 .. ALL nodes of this menu "tree" should have help name qualifiers.
5692 .. These are used to produce the internal lists used by NEdit help code.
5694 .. By default, the first character of the menu element will be used as a
5695 .. menu mneumonic key. To use another character in the menu element for this
5696 .. purpose, surround the character with underscores (eg. I w_a_nt 'a').
5698 .. The menu title MUST match the one found in the actual help text (sans
5699 .. special mneumonic key character marking). The help text title may include
5700 .. underlines (for spaces) when it is a hyperlink target.
5702 .. The Help-name is used to generate various data structure names. For
5703 .. instance, the 'start' help name will be used to generate the HelpTopic
5704 .. enumeration value HELP_START and the character array htxt_start which
5705 .. holds the actual help text used in the menu dialogs. Consequently, these
5706 .. names need to be unique and contain only the characters that a 'C'
5707 .. compiler can digest.
5709 .. Menu separator lines use a dash (-) character for the Menu Title. They
5710 .. should also have a unique Help-name.
5712 .. A numerical value following the Help-name (separated from the name by
5713 .. a comma and/or spaces) is part of a menu element hiding scheme implemented
5714 .. in buildHelpMenu (found in 'menu.c'). When the number matches the hideIt
5715 .. value found in the procedure, that element will effectively become invisible.
5716 .. This mechanism was created for particular menu features that are not
5717 .. available to all incarnations of NEdit (in this case, the VMS version).
5719 .. A "Help" directive is used for all other text used as NEdit help, but
5720 .. does not show up in the Help menu.
5722 .. Menu Title # Help-name
5723 .. ------------------------------------------------------------
5724 .. Menu: Getting Started # start
5725 .. Menu: Basic Operation # basicOp
5726 .. Menu: Selecting Text # select
5727 .. Menu: Finding and Replacing Text # search
5728 .. Menu: Cut and Paste # clipboard
5729 .. Menu: Using the Mouse # mouse
5730 .. Menu: Keyboard Shortcuts # keyboard
5731 .. Menu: S_h_ifting and Filling # fill
5732 .. Menu: Tabbed Editing # interface
5733 .. Menu: F_i_le Format # format
5735 .. Menu: Features for Programming # features
5736 .. Menu: Programming with NEdit # programmer
5737 .. Menu: Tabs/Emulated Tabs # tabs
5738 .. Menu: Auto/Smart Indent # indent
5739 .. Menu: Syntax Highlighting # syntax
5740 .. Menu: Finding Declarations (ctags) # tags
5741 .. Menu: Calltips # calltips
5743 .. Menu: Regular Expressions # regex
5744 .. Menu: Basic Regular Expression Syntax # basicSyntax
5745 .. Menu: Metacharacters # escapeSequences
5746 .. Menu: Parenthetical Constructs # parenConstructs
5747 .. Menu: Advanced Topics # advancedTopics
5748 .. Menu: Example Regular Expressions # examples
5750 .. Menu: Macro/Shell Extensions # extensions
5751 .. Menu: Shell Commands and Filters # shell, 1
5752 .. Menu: Learn/Replay # learn
5753 .. Menu: Macro Language # macro_lang
5754 .. Menu: M_a_cro Subroutines # macro_subrs
5755 .. Menu: Range Sets # rangeset
5756 .. Menu: Highlighting Information # hiliteInfo
5757 .. Menu: Action Routines # actions
5759 .. Menu: Customizing # customizing
5760 .. Menu: Customizing NEdit # customize
5761 .. Menu: Preferences # preferences
5762 .. Menu: X Resources # resources
5763 .. Menu: Key Binding # binding
5764 .. Menu: Highlighting Patterns # patterns
5765 .. Menu: Smart Indent Macros # smart_indent
5767 .. Menu: NEdit Command Line # command_line
5768 .. Menu: Client/Server Mode # server
5769 .. Menu: Cr_a_sh Recovery # recovery
5770 .. Menu: ---------------------------------- # separator1
5771 .. Menu: Version # version
5772 .. Menu: GNU General Public License # distribution
5773 .. Menu: Mailing _L_ists # mailing_list
5774 .. Menu: Problems/Defects # defects
5775 .. ------------------------------------------------------------
5776 .. Help: Tabs Dialog # tabs_dialog
5777 .. Help: Customize Window Title Dialog # custom_title_dialog