1 .. NOTE: Remember to supply 'version' variable on setext command line.
2 .. For example, setext -m -v "version=NEdit Version 6.0".
4 .. The following are variable definitions for the various titles below
5 .. ----------------------------------------------------------------------------
6 .. |>title=Nirvana Editor (NEdit) Help Documentation<|
7 .. |>ttlMk==========================================<|
8 .. ----------------------------------------------------------------------------
23 .. .. This table of contents is only for the HTML version of this document.
30 Basic Operation Macro/Shell Extensions
31 Selecting_Text_ Shell_Commands_and_Filters_
32 Finding_and_Replacing_Text_ Learn/Replay_
33 Cut_and_Paste_ Macro_Language_
34 Using_the_Mouse_ Macro_Subroutines_
35 Keyboard_Shortcuts_ Action_Routines_
39 Features for Programming Customizing_NEdit_
40 Programming_with_NEdit_ Preferences_
41 Tabs/Emulated_Tabs_ X_Resources_
42 Auto/Smart_Indent_ Key_Binding_
43 Syntax_Highlighting_ Highlighting_Patterns_
44 Finding_Declarations_(ctags)_ Smart_Indent_Macros_
47 Regular Expressions NEdit_Command_Line_
48 Basic_Regular_Expression_Syntax_ Client/Server_Mode_
49 Metacharacters_ Crash_Recovery_
50 Parenthetical_Constructs_ Version_
51 Advanced_Topics_ Distribution_Policy_
52 Example_Regular_Expressions_ Mailing_Lists_
61 .. .. What appears below will always print whether or not NEDITDOC is defined.
64 NEdit is a standard GUI (Graphical User Interface) style text editor for
65 programs and plain-text files. Users of Macintosh and MS Windows based text
66 editors should find NEdit a familiar and comfortable environment. NEdit
67 provides all of the standard menu, dialog, editing, and mouse support, as
68 well as all of the standard shortcuts to which the users of modern GUI based
69 environments are accustomed. For users of older style Unix editors, welcome
70 to the world of mouse-based editing!
73 .. NEdit is freely distributed under the terms of the Gnu General Public
76 .. .. This stuff will always be invisible, unless NEDITDOC is defined
81 .. NEdit is a single stand-alone executable file which can be installed by simply
82 .. copying the appropriate executable "nedit" for your system. Both sources and
83 .. executables are available from http://www.nedit.org. The optional "nc" (NEdit
84 .. Client) program is also available for users who want to run nedit in
85 .. client/server mode.
91 Help sections of interest to new users are listed under the "Basic Operation"
92 heading in the top-level Help menu:
95 * Finding_and_Replacing_Text_
99 * Shifting_and_Filling_
101 Programmers should also read the introductory section under the "Features for
102 Programming" section:
104 Programming_with_NEdit_
106 If you get into trouble, the Undo command in the Edit menu can reverse any
107 modifications that you make. NEdit does not change the file you are editing
108 until you tell it to Save.
110 3>Editing an Existing File
112 To open an existing file, choose Open... from the file menu. Select the file
113 that you want to open in the pop-up dialog that appears and click on OK. You
114 may open any number of files at the same time. Each file will appear in its
115 own editor window. Using Open... rather than re-typing the NEdit command and
116 running additional copies of NEdit, will give you quick access to all of the
117 files you have open via the Windows menu, and ensure that you don't
118 accidentally open the same file twice. NEdit has no "main" window. It
119 remains running as long as at least one editor window is open.
121 3>Creating a New File
123 If you already have an empty (Untitled) window displayed, just begin typing
124 in the window. To create a new Untitled window, choose New from the File
125 menu. To give the file a name and save its contents to the disk, choose Save
126 or Save As... from the File menu.
130 NEdit maintains periodic backups of the file you are editing so that you can
131 recover the file in the event of a problem such as a system crash, network
132 failure, or X server crash. These files are saved under the name `~filename`
133 (on Unix) or `_filename` (on VMS), where filename is the name of the file you
134 were editing. If an NEdit process is killed, some of these backup files may
135 remain in your directory. (To remove one of these files on Unix, you may
136 have to prefix the `~' (tilde) character with a (backslash) to prevent the
137 shell from interpreting it as a special character.)
141 As you become more familiar with NEdit, substitute the control and function
142 keys shown on the right side of the menus for pulling down menus with the
145 Dialogs are also streamlined so you can enter information quickly and without
146 using the mouse*. To move the keyboard focus around a dialog, use the tab
147 and arrow keys. One of the buttons in a dialog is usually drawn with a
148 thick, indented, outline. This button can be activated by pressing Return or
149 Enter. The Cancel or Dismiss button can be activated by pressing escape.
150 For example, to replace the string "thing" with "things" type:
152 <ctrl-r>thing<tab>things<return>
154 To open a file named "whole_earth.c", type:
158 (how much of the filename you need to type depends on the other files in the
159 directory). See the section called "Keyboard_Shortcuts_" for more details.
161 * Users who have set their keyboard focus mode to "pointer" should set
162 "Popups Under Pointer" in the Default Settings menu to avoid the additional
163 step of moving the mouse into the dialog.
164 ----------------------------------------------------------------------
172 NEdit has two general types of selections, primary (highlighted text), and
173 secondary (underlined text). Selections can cover either a simple range of
174 text between two points in the file, or they can cover a rectangular area of
175 the file. Rectangular selections are only useful with non-proportional (fixed
178 To select text for copying, deleting, or replacing, press the left mouse
179 button with the pointer at one end of the text you want to select, and drag
180 it to the other end. The text will become highlighted. To select a whole
181 word, double click (click twice quickly in succession). Double clicking and
182 then dragging the mouse will select a number of words. Similarly, you can
183 select a whole line or a number of lines by triple clicking or triple
184 clicking and dragging. Quadruple clicking selects the whole file. After
185 releasing the mouse button, you can still adjust a selection by holding down
186 the shift key and dragging on either end of the selection. To delete the
187 selected text, press delete or backspace. To replace it, begin typing.
189 To select a rectangle or column of text, hold the Ctrl key while dragging the
190 mouse. Rectangular selections can be used in any context that normal
191 selections can be used, including cutting and pasting, filling, shifting,
192 dragging, and searching. Operations on rectangular selections automatically
193 fill in tabs and spaces to maintain alignment of text within and to the right
194 of the selection. Note that the interpretation of rectangular selections by
195 Fill Paragraph is slightly different from that of other commands, the section
196 titled "Shifting_and_Filling_" has details.
198 The middle mouse button can be used to make an additional selection (called
199 the secondary selection). As soon as the button is released, the contents of
200 this selection will be copied to the insert position of the window where the
201 mouse was last clicked (the destination window). This position is marked by a
202 caret shaped cursor when the mouse is outside of the destination window. If
203 there is a (primary) selection, adjacent to the cursor in the window, the new
204 text will replace the selected text. Holding the shift key while making the
205 secondary selection will move the text, deleting it at the site of the
206 secondary selection, rather than copying it.
208 Selected text can also be dragged to a new location in the file using the
209 middle mouse button. Holding the shift key while dragging the text will copy
210 the selected text, leaving the original text in place. Holding the control
211 key will drag the text in overlay mode.
213 Normally, dragging moves text by removing it from the selected position at
214 the start of the drag, and inserting it at a new position relative to to the
215 mouse. Dragging a block of text over existing characters, displaces the
216 characters to the end of the selection. In overlay mode, characters which are
217 occluded by blocks of text being dragged are simply removed. When dragging
218 non-rectangular selections, overlay mode also converts the selection to
219 rectangular form, allowing it to be dragged outside of the bounds of the
222 The section "Using_the_Mouse_" sumarizes the mouse commands for making primary
223 and secondary selections. Primary selections can also be made via keyboard
224 commands, see "Keyboard_Shortcuts_".
225 ----------------------------------------------------------------------
227 Finding and Replacing Text
228 --------------------------
230 The Search menu contains a number of commands for finding and replacing text.
232 The Find... and Replace... commands present dialogs for entering text for
233 searching and replacing. These dialogs also allow you to choose whether you
234 want the search to be sensitive to upper and lower case, or whether to use
235 the standard Unix pattern matching characters (regular expressions).
236 Searches begin at the current text insertion position.
238 Find Again and Replace Again repeat the last find or replace command without
239 prompting for search strings. To selectively replace text, use the two
240 commands in combination: Find Again, then Replace Again if the highlighted
241 string should be replaced, or Find Again again to go to the next string.
243 Find Selection searches for the text contained in the current primary
244 selection (see Selecting_Text_). The selected text does not have to be in the
245 current editor window, it may even be in another program. For example, if
246 the word dog appears somewhere in a window on your screen, and you want to
247 find it in the file you are editing, select the word dog by dragging the
248 mouse across it, switch to your NEdit window and choose Find Selection from
251 Find Incremental is yet another variation on searching, where every character
252 typed triggers a new search. Incremental searching is generally the quickest
253 way to find something in a file, because it gives you the immediate feedback
254 of seeing how your search is progressing, so you never need to type more than
255 the minimally sufficient search string to reach your target.
257 3>Searching Backwards
259 Holding down the shift key while choosing any of the search or replace
260 commands from the menu (or using the keyboard shortcut), will search in the
261 reverse direction. Users who have set the search direction using the buttons
262 in the search dialog, may find it a bit confusing that Find Again and Replace
263 Again don't continue in the same direction as the original search (for
264 experienced users, consistency of the direction implied by the shift key is
267 3>Selective Replacement
269 To replace only some occurrences of a string within a file, choose Replace...
270 from the Search menu, enter the string to search for and the string to
271 substitute, and finish by pressing the Find button. When the first
272 occurrence is highlighted, use either Replace Again (^T) to replace it, or
273 Find Again (^G) to move to the next occurrence without replacing it, and
274 continue in such a manner through all occurrences of interest.
276 To replace all occurrences of a string within some range of text, select the
277 range (see Selecting_Text_), choose Replace... from the Search menu, type the
278 string to search for and the string to substitute, and press the "R. in
279 Selection" button in the dialog. Note that selecting text in the Replace...
280 dialog will unselect the text in the window.
281 ----------------------------------------------------------------------
286 The easiest way to copy and move text around in your file or between windows,
287 is to use the clipboard, an imaginary area that temporarily stores text and
288 data. The Cut command removes the selected text (see Selecting_Text_) from
289 your file and places it in the clipboard. Once text is in the clipboard, the
290 Paste command will copy it to the insert position in the current window. For
291 example, to move some text from one place to another, select it by dragging
292 the mouse over it, choose Cut to remove it, click the pointer to move the
293 insert point where you want the text inserted, then choose Paste to insert
294 it. Copy copies text to the clipboard without deleting it from your file.
295 You can also use the clipboard to transfer text to and from other Motif
296 programs and X programs which make proper use of the clipboard.
298 There are many other methods for copying and moving text within NEdit windows
299 and between NEdit and other programs. The most common such method is
300 clicking the middle mouse button to copy the primary selection (to the
301 clicked position). Copying the selection by clicking the middle mouse button
302 in many cases is the only way to transfer data to and from many X programs.
303 Holding the Shift key while clicking the middle mouse button moves the text,
304 deleting it from its original position, rather than copying it. Other
305 methods for transferring text include secondary selections, primary selection
306 dragging, keyboard-based selection copying, and drag and drop. These are
307 described in detail in the sections: "Selecting_Text_", "Using_the_Mouse_",
308 and "Keyboard_Shortcuts_".
309 ----------------------------------------------------------------------
314 Mouse-based editing is what NEdit is all about, and learning to use the more
315 advanced features like secondary selections and primary selection dragging
316 will be well worth your while.
318 If you don't have time to learn everything, you can get by adequately with
319 just the left mouse button: Clicking the left button moves the cursor.
320 Dragging with the left button makes a selection. Holding the shift key while
321 clicking extends the existing selection, or begins a selection between the
322 cursor and the mouse. Double or triple clicking selects a whole word or a
325 This section will make more sense if you also read the section called,
326 "Selecting_Text_", which explains the terminology of selections, that is,
327 what is meant by primary, secondary, rectangular, etc.
330 3>Button and Modifier Key Summary
332 General meaning of mouse buttons and modifier keys:
336 Button 1 (left) Cursor position and primary selection
338 Button 2 (middle) Secondary selections, and dragging and
339 copying the primary selection
341 Button 3 (right) Quick-access programmable menu and pan
346 Shift On primary selections, (left mouse button):
347 Extends selection to the mouse pointer
348 On secondary and copy operations, (middle):
349 Toggles between move and copy
351 Ctrl Makes selection rectangular or insertion
354 Alt* (on release) Exchange primary and secondary
360 The left mouse button is used to position the cursor and to make primary
363 Click Moves the cursor
365 Double Click Selects a whole word
367 Triple Click Selects a whole line
369 Quad Click Selects the whole file
371 Shift Click Adjusts (extends or shrinks) the
372 selection, or if there is no existing
373 selection, begins a new selection
374 between the cursor and the mouse.
376 Ctrl+Shift+ Adjusts (extends or shrinks) the
377 Click selection rectangularly.
379 Drag Selects text between where the mouse
380 was pressed and where it was released.
382 Ctrl+Drag Selects rectangle between where the
383 mouse was pressed and where it was
389 The right mouse button posts a programmable menu for frequently used commands.
391 Click/Drag Pops up the background menu (programmed
392 from Preferences -> Default Settings ->
393 Customize Menus -> Window Background).
395 Ctrl+Drag Pan scrolling. Scrolls the window
396 both vertically and horizontally, as if
397 you had grabbed it with your mouse.
400 3>Middle Mouse Button
402 The middle mouse button is for making secondary selections, and copying and
403 dragging the primary selection.
405 Click Copies the primary selection to the
408 Shift+Click Moves the primary selection to the
409 clicked position, deleting it from its
412 Drag 1) Outside of the primary selection:
413 Begins a secondary selection.
414 2) Inside of the primary selection:
415 Moves the selection by dragging.
417 Ctrl+Drag 1) Outside of the primary selection:
418 Begins a rectangular secondary
420 2) Inside of the primary selection:
421 Drags the selection in overlay
424 When the mouse button is released after creating a secondary selection:
426 No Modifiers If there is a primary selection,
427 replaces it with the secondary
428 selection. Otherwise, inserts the
429 secondary selection at the cursor
432 Shift Move the secondary selection, deleting
433 it from its original position. If
434 there is a primary selection, the move
435 will replace the primary selection
436 with the secondary selection.
437 Otherwise, moves the secondary
438 selection to to the cursor position.
440 Alt* Exchange the primary and secondary
444 While moving the primary selection by dragging with the middle mouse button:
446 Shift Leaves a copy of the original
447 selection in place rather than
448 removing it or blanking the area.
450 Ctrl Changes from insert mode to overlay
453 Escape Cancels drag in progress.
455 Overlay Mode: Normally, dragging moves text by removing it from the selected
456 position at the start of the drag, and inserting it at a new position
457 relative to to the mouse. When you drag a block of text over existing
458 characters, the existing characters are displaced to the end of the
459 selection. In overlay mode, characters which are occluded by blocks of text
460 being dragged are simply removed. When dragging non-rectangular selections,
461 overlay mode also converts the selection to rectangular form, allowing it to
462 be dragged outside of the bounds of the existing text.
464 Mouse buttons 4 and 5 are usually represented by a mouse wheel nowadays.
465 They are used to scroll up or down in the text window.
467 * The Alt key may be labeled Meta or Compose-Character on some keyboards.
468 Some window managers, including default configurations of mwm, bind
469 combinations of the Alt key and mouse buttons to window manager operations.
470 In NEdit, Alt is only used on button release, so regardless of the window
471 manager bindings for Alt-modified mouse buttons, you can still do the
472 corresponding NEdit operation by using the Alt key AFTER the initial mouse
473 press, so that Alt is held while you release the mouse button. If you find
474 this difficult or annoying, you can re-configure most window managers to skip
475 this binding, or you can re-configure NEdit to use a different key
477 ----------------------------------------------------------------------
482 Most of the keyboard shortcuts in NEdit are shown on the right hand sides of
483 the pull-down menus. However, there are more which are not as obvious. These
484 include; dialog button shortcuts; menu and dialog mnemonics; labeled keyboard
485 keys, such as the arrows, page-up, page-down, and home; and optional Shift
486 modifiers on accelerator keys, like [Shift]Ctrl+F.
491 Pressing the key combinations shown on the right of the menu items is a
492 shortcut for selecting the menu item with the mouse. Some items have the shift
493 key enclosed in brackets, such as [Shift]Ctrl+F. This indicates that the shift
494 key is optional. In search commands, including the shift key reverses the
495 direction of the search. In Shift commands, it makes the command shift the
496 selected text by a whole tab stop rather than by single characters.
501 Pressing the Alt key in combination with one of the underlined characters in
502 the menu bar pulls down that menu. Once the menu is pulled down, typing the
503 underlined characters in a menu item (without the Alt key) activates that
504 item. With a menu pulled down, you can also use the arrow keys to select menu
505 items, and the Space or Enter keys to activate them.
508 3>Keyboard Shortcuts within Dialogs
510 One button in a dialog is usually marked with a thick indented outline.
511 Pressing the Return or Enter key activates this button.
513 All dialogs have either a Cancel or Dismiss button. This button can be
514 activated by pressing the Escape (or Esc) key.
516 Pressing the tab key moves the keyboard focus to the next item in a dialog.
517 Within an associated group of buttons, the arrow keys move the focus among the
518 buttons. Shift+Tab moves backward through the items.
520 Most items in dialogs have an underline under one character in their name.
521 Pressing the Alt key along with this character, activates a button as if you
522 had pressed it with the mouse, or moves the keyboard focus to the associated
525 You can select items from a list by using the arrow keys to move the
526 selection and space to select.
528 In file selection dialogs, you can type the beginning characters of the file
529 name or directory in the list to select files
532 3>Labeled Function Keys
534 The labeled function keys on standard workstation and PC keyboards, like the
535 arrows, and page-up and page-down, are active in NEdit, though not shown in the
538 Holding down the control key while pressing a named key extends the scope of
539 the action that it performs. For example, Home normally moves the insert
540 cursor the beginning of a line. Ctrl+Home moves it to the beginning of the
541 file. Backspace deletes one character, Ctrl+Backspace deletes one word.
543 Holding down the shift key while pressing a named key begins or extends a
544 selection. Combining the shift and control keys combines their actions. For
545 example, to select a word without using the mouse, position the cursor at the
546 beginning of the word and press Ctrl+Shift+RightArrow. The Alt key modifies
547 selection commands to make the selection rectangular.
549 Under X and Motif, there are several levels of translation between keyboard
550 keys and the actions they perform in a program. The "Customizing_NEdit_", and
551 "X_Resources_" sections of the Help menu have more information on this subject.
552 Because of all of this configurability, and since keyboards and standards for
553 the meaning of some keys vary from machine to machine, the mappings may be
554 changed from the defaults listed below.
556 3>Modifier Keys (in general)
558 Ctrl Extends the scope of the action that the key
559 would otherwise perform. For example, Home
560 normally moves the insert cursor to the beginning
561 of a line. Ctrl+Home moves it to the beginning of
562 the file. Backspace deletes one character, Ctrl+
563 Backspace deletes one word.
565 Shift Extends the selection to the cursor position. If
566 there's no selection, begins one between the old
567 and new cursor positions.
569 Alt When modifying a selection, makes the selection
572 (For the effects of modifier keys on mouse button presses, see the section
573 titled "Using_the_Mouse_")
577 Escape Cancels operation in progress: menu
578 selection, drag, selection, etc. Also
579 equivalent to cancel button in dialogs.
581 Backspace Delete the character before the cursor
583 Ctrl+BS Delete the word before the cursor
587 Left Move the cursor to the left one character
589 Ctrl+Left Move the cursor backward one word
590 (Word delimiters are settable, see
591 "Customizing_NEdit_", and "X_Resources_")
593 Right Move the cursor to the right one character
595 Ctrl+Right Move the cursor forward one word
597 Up Move the cursor up one line
599 Ctrl+Up Move the cursor up one paragraph.
600 (Paragraphs are delimited by blank lines)
602 Down Move the cursor down one line.
604 Ctrl+Down Move the cursor down one paragraph.
606 Ctrl+Return Return with automatic indent, regardless
607 of the setting of Auto Indent.
609 Shift+Return Return without automatic indent,
610 regardless of the setting of Auto Indent.
612 Ctrl+Tab Insert an ASCII tab character, without
613 processing emulated tabs.
615 Alt+Ctrl+<c> Insert the control-code equivalent of
618 Ctrl+/ Select everything (same as Select
623 Ctrl+U Delete to start of line
625 3>PC Standard Keyboard
627 Ctrl+Insert Copy the primary selection to the
628 clipboard (same as Copy menu item or ^C)
629 for compatibility with Motif standard key
632 Insert Copy the primary selection to the cursor
635 Delete Delete the character before the cursor.
636 (Can be configured to delete the character
637 after the cursor, see "Customizing_NEdit_",
640 Ctrl+Delete Delete to end of line.
642 Shift+Delete Cut, remove the currently selected text
643 and place it in the clipboard. (same as
644 Cut menu item or ^X) for compatibility
645 with Motif standard key binding
647 Delete Cut the primary selection to the cursor
650 Home Move the cursor to the beginning of the
653 Ctrl+Home Move the cursor to the beginning of the
656 End Move the cursor to the end of the line
658 Ctrl+End Move the cursor to the end of the file
660 PageUp Scroll and move the cursor up by one page.
662 Ctrl+PageUp Scroll and move the cursor left by one
664 PageDown Scroll and move the cursor down by one
667 Ctrl+PageDown Scroll and move the cursor right by one
670 F10 Make the menu bar active for keyboard
671 input (Arrow Keys, Return, Escape,
674 3>Specialty Keyboards
676 On machines with different styles of keyboards, generally, text editing
677 actions are properly matched to the labeled keys, such as Remove,
678 Next-screen, etc.. If you prefer different key bindings, see the section
679 titled "Key_Binding_" under the Customizing heading in the Help menu.
680 ----------------------------------------------------------------------
685 3>Shift Left, Shift Right
687 While shifting blocks of text is most important for programmers (See Features
688 for Programming), it is also useful for other tasks, such as creating
691 To shift a block of text one tab stop to the right, select the text, then
692 choose Shift Right from the Edit menu. Note that the accelerator keys for
693 these menu items are Ctrl+9 and Ctrl+0, which correspond to the right and
694 left parenthesis on most keyboards. Remember them as adjusting the text in
695 the direction pointed to by the parenthesis character. Holding the Shift key
696 while selecting either Shift Left or Shift Right will shift the text by one
699 It is also possible to shift blocks of text by selecting the text
700 rectangularly, and dragging it left or right (and up or down as well). Using
701 a rectangular selection also causes tabs within the selection to be
702 recalculated and substituted, such that the non-whitespace characters remain
703 stationary with respect to the selection.
708 Text filling using the Fill Paragraph command in the Edit menu is one of the
709 most important concepts in NEdit. And it will be well worth your while to
710 understand how to use it properly.
712 In plain text files, unlike word-processor files, there is no way to tell
713 which lines are continuations of other lines, and which lines are meant to be
714 separate, because there is no distinction in meaning between newline
715 characters which separate lines in a paragraph, and ones which separate
716 paragraphs from other text. This makes it impossible for a text editor like
717 NEdit to tell parts of the text which belong together as a paragraph from
718 carefully arranged individual lines.
720 In continuous wrap mode (Preferences -> Wrap -> Continuous), lines
721 automatically wrap and unwrap themselves to line up properly at the right
722 margin. In this mode, you simply omit the newlines within paragraphs and let
723 NEdit make the line breaks as needed. Unfortunately, continuous wrap mode is
724 not appropriate in the majority of situations, because files with extremely
725 long lines are not common under Unix and may not be compatible with all
726 tools, and because you can't achieve effects like indented sections, columns,
727 or program comments, and still take advantage of the automatic wrapping.
729 Without continuous wrapping, paragraph filling is not entirely automatic.
730 Auto-Newline wrapping keeps paragraphs lined up as you type, but once
731 entered, NEdit can no longer distinguish newlines which join wrapped text,
732 and newlines which must be preserved. Therefore, editing in the middle of a
733 paragraph will often leave the right margin messy and uneven.
735 Since NEdit can't act automatically to keep your text lined up, you need to
736 tell it explicitly where to operate, and that is what Fill Paragraph is for.
737 It arranges lines to fill the space between two margins, wrapping the lines
738 neatly at word boundaries. Normally, the left margin for filling is inferred
739 from the text being filled. The first line of each paragraph is considered
740 special, and its left indentation is maintained separately from the remaining
741 lines (for leading indents, bullet points, numbered paragraphs, etc.).
742 Otherwise, the left margin is determined by the furthest left non-whitespace
743 character. The right margin is either the Wrap Margin, set in the
744 preferences menu (by default, the right edge of the window), or can also be
745 chosen on the fly by using a rectangular selection (see below).
747 There are three ways to use Fill Paragraph. The simplest is, while you are
748 typing text, and there is no selection, simply select Fill Paragraph (or type
749 Ctrl+J), and NEdit will arrange the text in the paragraph adjacent to the
750 cursor. A paragraph, in this case, means an area of text delimited by blank
753 The second way to use Fill Paragraph is with a selection. If you select a
754 range of text and then chose Fill Paragraph, all of the text in the selection
755 will be filled. Again, continuous text between blank lines is interpreted as
756 paragraphs and filled individually, respecting leading indents and blank
759 The third, and most versatile, way to use Fill Paragraph is with a
760 rectangular selection. Fill Paragraph treats rectangular selections
761 differently from other commands. Instead of simply filling the text inside
762 the rectangular selection, NEdit interprets the right edge of the selection
763 as the requested wrap margin. Text to the left of the selection is not
764 disturbed (the usual interpretation of a rectangular selection), but text to
765 the right of the selection is included in the operation and is pulled in to
766 the selected region. This method enables you to fill text to an arbitrary
767 right margin, without going back and forth to the wrap-margin dialog, as well
768 as to exclude text to the left of the selection such as comment bars or other
770 ----------------------------------------------------------------------
775 While plain-text is probably the simplest and most interchangeable file
776 format in the computer world, there is still variation in what plain-text
777 means from system to system. Plain-text files can differ in character set,
778 line termination, and wrapping.
780 While character set differences are the most obvious and pose the most
781 challenge to portability, they affect NEdit only indirectly via the same font
782 and localization mechanisms common to all X applications. If your system is
783 set up properly, you will probably never see character-set related problems
784 in NEdit. NEdit can not display Unicode text files, or any multi-byte
787 The primary difference between an MS DOS format file and a Unix format file,
788 is how the lines are terminated. Unix uses a single newline character. MS
789 DOS uses a carriage-return and a newline. NEdit can read and write both file
790 formats, but internally, it uses the single character Unix standard. NEdit
791 auto-detects MS DOS format files based on the line termination at the start
792 of the file. Files are judged to be DOS format if all of the first five line
793 terminators, within a maximum range, are DOS-style. To change the format in
794 which NEdit writes a file from DOS to Unix or visa versa, use the Save As...
795 command and check or un-check the MS DOS Format button.
797 Wrapping within text files can vary among individual users, as well as from
798 system to system. Both Windows and MacOS make frequent use of plain text
799 files with no implicit right margin. In these files, wrapping is determined
800 by the tool which displays them. Files of this style also exist on Unix
801 systems, despite the fact that they are not supported by all Unix utilities.
802 To display this kind of file properly in NEdit, you have to select the wrap
803 style called Continuous. Wrapping modes are discussed in the sections:
804 Customizing -> Preferences, and Basic Operation -> Shifting and Filling.
806 The last and most minute of format differences is the terminating newline.
807 Some Unix compilers and utilities require a final terminating newline on all
808 files they read and fail in various ways on files which do not have it. Vi
809 and approximately half of Unix editors enforce the terminating newline on all
810 files that they write; Emacs does not enforce this rule. Users are divided
811 on which is best. NEdit makes the final terminating newline optional
812 (Preferences -> Default Settings -> Append Line Feed on Save).
813 ----------------------------------------------------------------------
815 Features for Programming
816 ========================
818 Programming with NEdit
819 ----------------------
821 Though general in appearance, NEdit has many features intended specifically
822 for programmers. Major programming-related topics are listed in separate
823 sections under the heading: "Features for Programming": Syntax_Highlighting_,
824 Tabs/Emulated_Tabs_, Finding_Declarations_(ctags)_, Calltips_, and
825 Auto/Smart_Indent_. Minor topics related to programming are discussed below:
829 When NEdit initially reads a file, it attempts to determine whether the file
830 is in one of the computer languages that it knows about. Knowing what language
831 a file is written in allows NEdit to assign highlight patterns and smart indent
832 macros, and to set language specific preferences like word delimiters, tab
833 emulation, and auto-indent. Language mode can be recognized from both the file
834 name and from the first 200 characters of content. Language mode recognition
835 and language-specific preferences are configured in: Preferences -> Default
836 Settings -> Language Modes....
838 You can set the language mode manually for a window, by selecting it from the
839 menu: Preferences -> Language Modes.
843 To find a particular line in a source file by line number, choose Goto Line
844 #... from the Search menu. You can also directly select the line number text
845 in the compiler message in the terminal emulator window (xterm, decterm,
846 winterm, etc.) where you ran the compiler, and choose Goto Selected from the
849 To find out the line number of a particular line in your file, turn on
850 Statistics Line in the Preferences menu and position the insertion point
851 anywhere on the line. The statistics line continuously updates the line number
852 of the line containing the cursor.
854 3>Matching Parentheses
856 To help you inspect nested parentheses, brackets, braces, quotes, and other
857 characters, NEdit has both an automatic parenthesis matching mode, and a Goto
858 Matching command. Automatic parenthesis matching is activated when you type,
859 or move the insertion cursor after a parenthesis, bracket, or brace. It
860 momentarily highlights either the opposite character ('Delimiter') or the
861 entire expression ('Range') when the opposite character is visible in the
862 window. To find a matching character anywhere in the file, select it or
863 position the cursor after it, and choose Goto Matching from the Search menu.
864 If the character matches itself, such as a quote or slash, select the first
865 character of the pair. NEdit will match {, (, [, <, ", ', `, /, and \.
866 Holding the Shift key while typing the accelerator key (Shift+Ctrl+M, by
867 default), will select all of the text between the matching characters.
869 When syntax highlighting is enabled, the matching routines can optionally
870 make use of the syntax information for improved accuracy. In that case,
871 a brace inside a highlighted string will not match a brace inside a comment,
874 3>Opening Included Files
876 The Open Selected command in the File menu understands the C preprocessor's
877 #include syntax, so selecting an #include line and invoking Open Selected will
878 generally find the file referred to, unless doing so depends on the settings of
879 compiler switches or other information not available to NEdit.
881 3>Interface to Programming Tools
883 Integrated software development environments such as SGI's CaseVision and
884 Centerline Software's Code Center, can be interfaced directly with NEdit via
885 the client server interface. These tools allow you to click directly on
886 compiler and runtime error messages and request NEdit to open files, and select
887 lines of interest. The easiest method is usually to use the tool's interface
888 for character-based editors like vi, to invoke nc, but programmatic interfaces
889 can also be derived using the source code for nc.
891 There are also some simple compile/review, grep, ctree, and ctags browsers
892 available in the NEdit contrib directory on ftp.nedit.org.
893 ----------------------------------------------------------------------
898 3>Changing the Tab Distance
900 Tabs are important for programming in languages which use indentation to show
901 nesting, as short-hand for producing white-space for leading indents. As a
902 programmer, you have to decide how to use indentation, and how or whether tab
903 characters map to your indentation scheme.
905 Ideally, tab characters map directly to the amount of indent that you use to
906 distinguish nesting levels in your code. Unfortunately, the Unix standard
907 for interpretation of tab characters is eight characters (probably dating
908 back to mechanical capabilities of the original teletype), which is usually
909 too coarse for a single indent.
911 Most text editors, NEdit included, allow you to change the interpretation of
912 the tab character, and many programmers take advantage of this, and set their
913 tabs to 3 or 4 characters to match their programming style. In NEdit you set
914 the hardware tab distance in Preferences -> Tabs... for the current window,
915 or Preferences -> Default Settings -> Tabs... (general), or Preferences ->
916 Default Settings -> Language Modes... (language-specific) to change the
917 defaults for future windows.
919 Changing the meaning of the tab character makes programming much easier while
920 you're in the editor, but can cause you headaches outside of the editor,
921 because there is no way to pass along the tab setting as part of a plain-text
922 file. All of the other tools which display, print, and otherwise process
923 your source code have to be made aware of how the tabs are set, and must be
924 able to handle the change. Non-standard tabs can also confuse other
925 programmers, or make editing your code difficult for them if their text
926 editors don't support changes in tab distance.
930 An alternative to changing the interpretation of the tab character is tab
931 emulation. In the Tabs... dialog(s), turning on Emulated Tabs causes the Tab
932 key to insert the correct number of spaces and/or tabs to bring the cursor
933 the next emulated tab stop, as if tabs were set at the emulated tab distance
934 rather than the hardware tab distance. Backspacing immediately after entering
935 an emulated tab will delete the fictitious tab as a unit, but as soon as you
936 move the cursor away from the spot, NEdit will forget that the collection of
937 spaces and tabs is a tab, and will treat it as separate characters. To enter
938 a real tab character with "Emulate Tabs" turned on, use Ctrl+Tab.
940 It is also possible to tell NEdit not to insert ANY tab characters at all in
941 the course of processing emulated tabs, and in shifting and rectangular
942 insertion/deletion operations, for programmers who worry about the
943 misinterpretation of tab characters on other systems.
944 ----------------------------------------------------------------------
948 .. The following Tabs Dialog and Customize Window Title Dialog sections
949 .. should only appear in the online documentation, and not in any of
950 .. the other possible forms. The rationale is that they are not directly
951 .. obtained from the Help menu, but are buried in preference dialogs.
957 .. The Tabs dialog controls both the operation of the Tab key, and
958 .. the interpretation of tab characters within a file.
960 .. The first field, Tab Spacing, controls how NEdit responds to
961 .. tab characters in a file. On most Unix and VMS systems the
962 .. conventional interpretation of a tab character is to advance the
963 .. text position to the nearest multiple of eight characters (a tab
964 .. spacing of 8). However, many programmers of C and other
965 .. structured languages, when given the choice, prefer a tab
966 .. spacing of 3 or 4 characters. Setting a three or four character
967 .. hardware tab spacing is useful and convenient as long as your
968 .. other software tools support it. Unfortunately, on Unix and VMS
969 .. systems, system utilities, such as more, and printing software
970 .. can't always properly display files with other than eight
973 .. Selecting "Emulate Tabs" will cause the Tab key to insert the
974 .. correct number of spaces or tabs to reach the next tab stop, as
975 .. if the tab spacing were set at the value in the "Emulated tab
976 .. spacing" field. Backspacing immediately after entering an
977 .. emulated tab will delete it as a unit, but as soon as you move
978 .. the cursor away from the spot, NEdit will forget that the
979 .. collection of spaces and tabs is a tab, and will treat it as
980 .. separate characters. To enter a real tab character with
981 .. "Emulate Tabs" turned on, use Ctrl+Tab.
983 .. In generating emulated tabs, and in Shift Left, Paste Column,
984 .. and some rectangular selection operations, NEdit inserts blank
985 .. characters (spaces or tabs) to preserve the alignment of
986 .. non-blank characters. The bottom toggle button in the Tabs
987 .. dialog instructs NEdit whether to insert tab characters as
988 .. padding in such situations. Turning this off, will keep NEdit
989 .. from automatically inserting tabs. Some software developers
990 .. prefer to keep their source code free of tabs to avoid its
991 .. misinterpretation on systems with different tab character
993 .. ----------------------------------------------------------------------
995 .. Customize Window Title Dialog
996 .. -----------------------------
998 .. The Customize Window Title dialog allows you to customize
999 .. and test the way information will be displayed in each window's
1002 .. **Definition of the title**
1004 .. The upper half of the dialog can be used to select the various
1005 .. components that should be displayed in the title. The layout can be
1006 .. fine-tuned by editing the printf() like format string below the
1007 .. component buttons: additional characters can be entered, or the
1008 .. order can be changed.
1010 .. The following sequences are interpreted in the format string:
1012 .. %c ClearCase view tag (only relevant when NEdit is
1013 .. used together with ClearCase)
1014 .. %[n]d directory, with one optional numeric digit n
1015 .. specifying the maximum number of trailing directory
1016 .. components to display. Skipped components are
1017 .. replaced by an ellipsis (...).
1018 .. %f file name, without the path name
1020 .. %s NEdit server name (server mode only)
1021 .. %[*]S file status, either verbose (%S) or brief (%*S).
1022 .. In verbose mode the file status is spelled out:
1023 .. read-only, locked, and modified. In brief mode,
1024 .. abbreviations and an asterisk are used for the
1025 .. respective states: RO, LO, *.
1028 .. The format string and the component buttons are continously synchronized.
1030 .. The default format is:
1032 .. {%c} [%s] %f (%S) - %d
1034 .. The resulting title will only contain elements with
1035 .. a value. Hence, the title is compressed as follows:
1037 .. * Elements with no value are removed.
1039 .. * Empty parenthesis pairs i.e. (), [] or {}, or parenthesis
1040 .. pairs containing only space(s), are removed.
1042 .. * Sequences of spaces are replaced with one space.
1044 .. * Leading spaces and dashes are removed.
1046 .. * Trailing spaces and dashes are removed.
1048 .. If the server name and the ClearCase view tag are identical, only
1049 .. the first one specified in the format string will be displayed.
1051 .. **Previewing the settings**
1053 .. The lower part of the dialog can be used to test the selected title
1054 .. under various conditions. For some of the components that are selected
1055 .. for display, various states can be enforced on the preview.
1057 .. For instance, components that are not always active (such the
1058 .. NEdit server name) can be turned on or off in the preview.
1065 Programmers who use structured languages usually require some form of
1066 automatic indent, so that they don't have to continually re-type the
1067 sequences of tabs and/or spaces needed to maintain lengthy running indents.
1068 Version 5.0 of NEdit is the first release of NEdit to offer "smart" indent,
1069 at least experimentally, in addition to the traditional automatic indent
1070 which simply lines up the cursor position with the previous line.
1074 Smart Indent in this release must still be considered somewhat experimental.
1075 Smart indent macros are only available by default for C and C++, and while
1076 these can easily be configured for different default indentation distances,
1077 they may not conform to everyone's exact C programming style. Smart indent
1078 is programmed in terms of macros in the NEdit macro language which can be
1079 entered in: Preferences -> Default Settings -> Indent -> Program Smart
1080 Indent. Hooks are provided for intervening at the point that a newline is
1081 entered, either via the user pressing the Enter key, or through
1082 auto-wrapping; and for arbitrary type-in to act on specific characters typed.
1084 To type a newline character without invoking smart-indent when operating in
1085 smart-indent mode, hold the Ctrl key while pressing the Return or Enter key.
1089 With Indent set to Auto (the default), NEdit keeps a running indent. When
1090 you press the Return or Enter key, spaces and tabs are inserted to line up
1091 the insert point under the start of the previous line. Ctrl+Return in
1092 auto-indent mode acts like a normal Return, With auto-indent turned off,
1093 Ctrl+Return does indentation.
1095 3>Block Indentation Adjustment
1097 The Shift Left and Shift Right commands as well as rectangular dragging can
1098 be used to adjust the indentation for several lines at once. To shift a
1099 block of text one character to the right, select the text, then choose Shift
1100 Right from the Edit menu. Note that the accelerator keys for these menu
1101 items are Ctrl+9 and Ctrl+0, which correspond to the right and left
1102 parenthesis on most keyboards. Remember them as adjusting the text in the
1103 direction pointed to by the parenthesis character. Holding the Shift key
1104 while selecting either Shift Left or Shift Right will shift the text by one
1105 tab stop (or by one emulated tab stop if tab emulation is turned on). The
1106 help section "Shifting and Filling" under "Basic Operation" has details.
1107 ----------------------------------------------------------------------
1112 Syntax Highlighting means using colors and fonts to help distinguish language
1113 elements in programming languages and other types of structured files.
1114 Programmers use syntax highlighting to understand code faster and better, and
1115 to spot many kinds of syntax errors more quickly.
1117 To use syntax highlighting in NEdit, select Highlight Syntax in the
1118 Preferences menu. If NEdit recognizes the computer language that you are
1119 using, and highlighting rules (patterns) are available for that language, it
1120 will highlight your text, and maintain the highlighting, automatically, as
1123 If NEdit doesn't correctly recognize the type of the file you are editing,
1124 you can manually select a language mode from Language Modes in the
1125 Preferences menu. You can also program the method that NEdit uses to
1126 recognize language modes in Preferences -> Default Settings -> Language
1129 If no highlighting patterns are available for the language that you want to
1130 use, you can create new patterns relatively quickly. The Help section
1131 "Highlighting_Patterns_" under "Customizing", has details.
1133 If you are satisfied with what NEdit is highlighting, but would like it to
1134 use different colors or fonts, you can change these by selecting Preferences
1135 -> Default Settings -> Syntax Highlighting -> Text Drawing Styles.
1136 Highlighting patterns are connected with font and color information through a
1137 common set of styles so that colorings defined for one language will be
1138 similar across others, and patterns within the same language which are meant
1139 to appear identical can be changed in the same place. To understand which
1140 styles are used to highlight the language you are interested in, you may need
1141 to look at "Highlighting_Patterns_" section, as well.
1143 Syntax highlighting is CPU intensive, and under some circumstances can affect
1144 NEdit's responsiveness. If you have a particularly slow system, or work with
1145 very large files, you may not want to use it all of the time. Syntax
1146 highlighting introduces two kinds of delays. The first is an initial parsing
1147 delay, proportional to the size of the file. This delay is also incurred
1148 when pasting large sections of text, filtering text through shell commands,
1149 and other circumstances involving changes to large amounts of text. The
1150 second kind of delay happens when text which has not previously been visible
1151 is scrolled in to view. Depending on your system, and the highlight patterns
1152 you are using, this may or may not be noticeable. A typing delay is also
1153 possible, but unlikely if you are only using the built-in patterns.
1154 ----------------------------------------------------------------------
1156 Finding Declarations (ctags)
1157 ----------------------------
1159 NEdit can process tags files generated using the Unix _ctags command or the
1160 Exuberant Ctags program. Ctags creates index files correlating names of
1161 functions and declarations with their locations in C, Fortran, or Pascal source
1162 code files. (See the ctags manual page for more information). Ctags produces a
1163 file called "tags" which can be loaded by NEdit. NEdit can manage any number
1164 of tags files simultaneously. Tag collisions are handled with a popup menu to
1165 let the user decide which tag to use. In 'Smart' mode NEdit will automatically
1166 choose the desired tag based on the scope of the file or module. Once loaded,
1167 the information in the tags file enables NEdit to go directly to the
1168 declaration of a highlighted function or data structure name with a single
1169 command. To load a tags file, select "Load Tags File" from the File menu and
1170 choose a tags file to load, or specify the name of the tags file on the NEdit
1175 NEdit can also be set to load a tags file automatically when it starts up.
1176 Setting the X resource nedit.tagFile to the name of a tag file tells NEdit to
1177 look for that file at startup time (see "Customizing_NEdit_"). The file name
1178 can be either a complete path name, in which case NEdit will always load the
1179 same tags file, or a file name without a path or with a relative path, in
1180 which case NEdit will load it starting from the current directory. The
1181 second option allows you to have different tags files for different projects,
1182 each automatically loaded depending on the directory you're in when you start
1183 NEdit. Setting the name to "tags" is an obvious choice since this is the
1184 name that ctags uses. NEdit normally evaluates relative path tag file
1185 specifications every time a file is opened. All accessible tag files are
1186 loaded at this time. To disable the automatic loading of tag files specified
1187 as relative paths, set the X resource nedit.alwaysCheckRelativeTagsSpecs to
1190 To unload a tags file, select "Un-load Tags File" from the File menu and
1191 choose from the list of tags files. NEdit will keep track of tags file updates
1192 by checking the timestamp on the files, and automatically update the tags
1195 To find the definition of a function or data structure once a tags file is
1196 loaded, select the name anywhere it appears in your program (see
1197 "Selecting_Text_") and choose "Find Definition" from the Search menu.
1198 ----------------------------------------------------------------------
1203 Calltips are little yellow boxes that pop up to remind you what the arguments
1204 and return type of a function are. More generally, they're a UI mechanism to
1205 present a small amount of crucial information in a prominent location. To
1206 display a calltip, select some text and choose "Show Calltip" from the Search
1209 Calltips get their information from one of two places -- either a tags file (see
1210 "Finding_Declarations_(ctags)_") or a calltips file. First, any loaded calltips
1211 files are searched for a definition, and if nothing is found then the tags
1212 database is searched. If a tag is found that matches the hilighted text then
1213 a calltip is displayed with the first few lines of the definition -- usually
1214 enough to show you what the arguments of a function are.
1216 You can load a calltips file by using choosing "Load Calltips File" from the
1217 File menu. You can unload a calltips file by selecting it from the
1218 "Unload Calltips File" submenu of the File menu. You can also choose one or
1219 more default calltips files to be loaded for each language mode using the
1220 "Default calltips file(s)" field of the Language Modes dialog.
1222 The calltips file format is very simple. calltips files are organized in blocks
1223 separated by blank lines. The first line of the block is the key, which is the
1224 word that is matched when a calltip is requested. The rest of the block is
1225 displayed as the calltip.
1227 Almost any text at all can appear in a calltip key or a calltip. There are no
1228 special characters that need to be escaped. The only issues to note are that
1229 trailing whitespace is ignored, and you cannot have a blank line inside a
1230 calltip. (Use a single period instead -- it'll be nearly invisible.) You should
1231 also avoid calltip keys that begin and end with '@*' characters, since those are
1232 used to mark special blocks.
1234 There are five special block types--comment, include, language, alias, and
1235 version--which are distinguished by their first lines, "@* comment @*",
1236 "@* include @*", "@* language @*", "@* alias @*", and "@* version @*" respectively
1239 Comment blocks are ignored when reading calltips files.
1241 Include blocks specify additional calltips files to load, one per line. The ~
1242 character can be used for your $HOME directory, but other shell shortcuts like
1243 @* and ? can't be used. Include blocks allow you to make a calltips file for your
1244 project that includes, say, the calltips files for C, Motif, and Xt.
1246 Language blocks specify which language mode the calltips should be used with.
1247 When a calltip is requested it won't match tips from languages other than the
1248 current language mode. Language blocks only affect the tips listed after the
1251 Alias blocks allow a calltip to have multiple keys. The first line of the block
1252 is the key for the calltip to be displayed, and the rest of the lines are
1253 additional keys, one per line, that should also show the calltip.
1255 Version blocks are ignored for the time being.
1257 You can use calltips in your own macros using the calltip() and kill_calltip()
1258 macro subroutines and the $calltip_ID macro variable. See the
1259 Macro_Subroutines_ section for details.
1260 ----------------------------------------------------------------------
1265 Basic Regular Expression Syntax
1266 -------------------------------
1268 Regular expressions (regex's) are useful as a way to match inexact sequences
1269 of characters. They can be used in the `Find...' and `Replace...' search
1270 dialogs and are at the core of Color Syntax Highlighting patterns. To specify
1271 a regular expression in a search dialog, simply click on the `Regular
1272 Expression' radio button in the dialog.
1274 A regex is a specification of a pattern to be matched in the searched text.
1275 This pattern consists of a sequence of tokens, each being able to match a
1276 single character or a sequence of characters in the text, or assert that a
1277 specific position within the text has been reached (the latter is called an
1278 anchor.) Tokens (also called atoms) can be modified by adding one of a number
1279 of special quantifier tokens immediately after the token. A quantifier token
1280 specifies how many times the previous token must be matched (see below.)
1282 Tokens can be grouped together using one of a number of grouping constructs,
1283 the most common being plain parentheses. Tokens that are grouped in this way
1284 are also collectively considered to be a regex atom, since this new larger
1285 atom may also be modified by a quantifier.
1287 A regex can also be organized into a list of alternatives by separating each
1288 alternative with pipe characters, `|'. This is called alternation. A match
1289 will be attempted for each alternative listed, in the order specified, until a
1290 match results or the list of alternatives is exhausted (see Alternation_
1293 3>The 'Any' Character
1295 If a dot (`.') appears in a regex, it means to match any character exactly
1296 once. By default, dot will not match a newline character, but this behavior
1297 can be changed (see help topic Parenthetical_Constructs_, under the
1298 heading, Matching Newlines).
1302 A character class, or range, matches exactly one character of text, but the
1303 candidates for matching are limited to those specified by the class. Classes
1304 come in two flavors as described below:
1306 [...] Regular class, match only characters listed.
1307 [^...] Negated class, match only characters NOT listed.
1309 As with the dot token, by default negated character classes do not match
1310 newline, but can be made to do so.
1312 The characters that are considered special within a class specification are
1313 different than the rest of regex syntax as follows. If the first character in
1314 a class is the `]' character (second character if the first character is `^')
1315 it is a literal character and part of the class character set. This also
1316 applies if the first or last character is `-'. Outside of these rules, two
1317 characters separated by `-' form a character range which includes all the
1318 characters between the two characters as well. For example, `[^f-j]' is the
1319 same as `[^fghij]' and means to match any character that is not `f', `g',
1324 Anchors are assertions that you are at a very specific position within the
1325 search text. NEdit regular expressions support the following anchor tokens:
1329 < Left word boundary
1330 > Right word boundary
1331 \B Not a word boundary
1333 Note that the \B token ensures that the left and right characters are both
1334 delimiter characters, or that both left and right characters are
1335 non-delimiter characters. Currently word anchors check only one character,
1336 e.g. the left word anchor `<' only asserts that the left character is a word
1337 delimiter character. Similarly the right word anchor checks the right
1342 Quantifiers specify how many times the previous regular expression atom may
1343 be matched in the search text. Some quantifiers can produce a large
1344 performance penalty, and can in some instances completely lock up NEdit. To
1345 prevent this, avoid nested quantifiers, especially those of the maximal
1346 matching type (see below.)
1348 The following quantifiers are maximal matching, or "greedy", in that they
1349 match as much text as possible.
1351 * Match zero or more
1355 The following quantifiers are minimal matching, or "lazy", in that they match
1356 as little text as possible.
1358 *? Match zero or more
1359 +? Match one or more
1360 ?? Match zero or one
1362 One final quantifier is the counting quantifier, or brace quantifier. It
1363 takes the following basic form:
1365 {min,max} Match from `min' to `max' times the
1366 previous regular expression atom.
1368 If `min' is omitted, it is assumed to be zero. If `max' is omitted, it is
1369 assumed to be infinity. Whether specified or assumed, `min' must be less
1370 than or equal to `max'. Note that both `min' and `max' are limited to
1371 65535. If both are omitted, then the construct is the same as `*'. Note
1372 that `{,}' and `{}' are both valid brace constructs. A single number
1373 appearing without a comma, e.g. `{3}' is short for the `{min,min}' construct,
1374 or to match exactly `min' number of times.
1376 The quantifiers `{1}' and `{1,1}' are accepted by the syntax, but are
1377 optimized away since they mean to match exactly once, which is redundant
1378 information. Also, for efficiency, certain combinations of `min' and `max'
1379 are converted to either `*', `+', or `?' as follows:
1385 Note that {0} and {0,0} are meaningless and will generate an error message at
1386 regular expression compile time.
1388 Brace quantifiers can also be "lazy". For example {2,5}? would try to match
1389 2 times if possible, and will only match 3, 4, or 5 times if that is what is
1390 necessary to achieve an overall match.
1394 A series of alternative patterns to match can be specified by separating them
1395 with vertical pipes, `|'. An example of _alternation would be `a|be|sea'.
1396 This will match `a', or `be', or `sea'. Each alternative can be an
1397 arbitrarily complex regular expression. The alternatives are attempted in
1398 the order specified. An empty alternative can be specified if desired, e.g.
1399 `a|b|'. Since an empty alternative can match nothingness (the empty string),
1400 this guarantees that the expression will match.
1404 Comments are of the form `(?#<comment text>)' and can be inserted anywhere
1405 and have no effect on the execution of the regular expression. They can be
1406 handy for documenting very complex regular expressions. Note that a comment
1407 begins with `(?#' and ends at the first occurrence of an ending parenthesis,
1408 or the end of the regular expression... period. Comments do not recognize
1409 any escape sequences.
1410 ----------------------------------------------------------------------
1415 3>Escaping Metacharacters
1417 In a regular expression (regex), most ordinary characters match themselves.
1418 For example, `ab%' would match anywhere `a' followed by `b' followed by `%'
1419 appeared in the text. Other characters don't match themselves, but are
1420 metacharacters. For example, backslash is a special metacharacter which
1421 'escapes' or changes the meaning of the character following it. Thus, to
1422 match a literal backslash would require a regular expression to have two
1423 backslashes in sequence. NEdit provides the following escape sequences so
1424 that metacharacters that are used by the regex syntax can be specified as
1425 ordinary characters.
1427 \( \) \- \[ \] \< \> \{ \}
1428 \. \| \^ \$ \* \+ \? \& \\
1430 3>Special Control Characters
1432 There are some special characters that are difficult or impossible to type.
1433 Many of these characters can be constructed as a sort of metacharacter or
1434 sequence by preceding a literal character with a backslash. NEdit recognizes
1435 the following special character sequences:
1439 \e ASCII escape character (***)
1440 \f form feed (new page)
1446 *** For environments that use the EBCDIC character set,
1447 when compiling NEdit set the EBCDIC_CHARSET compiler
1448 symbol to get the EBCDIC equivalent escape
1451 3>Octal and Hex Escape Sequences
1453 Any ASCII (or EBCDIC) character, except null, can be specified by using
1454 either an octal escape or a hexadecimal escape, each beginning with \0 or \x
1455 (or \X), respectively. For example, \052 and \X2A both specify the `*'
1456 character. Escapes for null (\00 or \x0) are not valid and will generate an
1457 error message. Also, any escape that exceeds \0377 or \xFF will either cause
1458 an error or have any additional character(s) interpreted literally. For
1459 example, \0777 will be interpreted as \077 (a `?' character) followed by `7'
1460 since \0777 is greater than \0377.
1462 An invalid digit will also end an octal or hexadecimal escape. For example,
1463 \091 will cause an error since `9' is not within an octal escape's range of
1464 allowable digits (0-7) and truncation before the `9' yields \0 which is
1467 3>Shortcut Escape Sequences
1469 NEdit defines some escape sequences that are handy shortcuts for commonly
1470 used character classes.
1473 \l letters a-z, A-Z, and locale dependent letters
1474 \s whitespace \t, \r, \v, \f, and space
1475 \w word characters letters, digits, and underscore, `_'
1477 \D, \L, \S, and \W are the same as the lowercase versions except that the
1478 resulting character class is negated. For example, \d is equivalent to
1479 `[0-9]', while \D is equivalent to `[^0-9]'.
1481 These escape sequences can also be used within a character class. For
1482 example, `[\l_]' is the same as `[a-zA-Z@_]', extended with possible locale
1483 dependent letters. The escape sequences for special characters, and octal
1484 and hexadecimal escapes are also valid within a class.
1486 3>Word Delimiter Tokens
1488 Although not strictly a character class, the following escape sequences
1489 behave similarly to character classes:
1491 \y Word delimiter character
1492 \Y Not a word delimiter character
1494 The `\y' token matches any single character that is one of the characters
1495 that NEdit recognizes as a word delimiter character, while the `\Y' token
1496 matches any character that is NOT a word delimiter character. Word delimiter
1497 characters are dynamic in nature, meaning that the user can change them through
1498 preference settings. For this reason, they must be handled differently by the
1499 regular expression engine. As a consequence of this, `\y' and `\Y' can not be
1500 used within a character class specification.
1501 ----------------------------------------------------------------------
1503 Parenthetical Constructs
1504 ------------------------
1506 3>Capturing Parentheses
1508 Capturing Parentheses are of the form `(<regex>)' and can be used to group
1509 arbitrarily complex regular expressions. Parentheses can be nested, but the
1510 total number of parentheses, nested or otherwise, is limited to 50 pairs.
1511 The text that is matched by the regular expression between a matched set of
1512 parentheses is captured and available for text substitutions and
1513 backreferences (see below.) Capturing parentheses carry a fairly high
1514 overhead both in terms of memory used and execution speed, especially if
1515 quantified by `*' or `+'.
1517 3>Non-Capturing Parentheses
1519 Non-Capturing Parentheses are of the form `(?:<regex>)' and facilitate
1520 grouping only and do not incur the overhead of normal capturing parentheses.
1521 They should not be counted when determining numbers for capturing parentheses
1522 which are used with backreferences and substitutions. Because of the limit
1523 on the number of capturing parentheses allowed in a regex, it is advisable to
1524 use non-capturing parentheses when possible.
1526 3>Positive Look-Ahead
1528 Positive look-ahead constructs are of the form `(?=<regex>)' and implement a
1529 zero width assertion of the enclosed regular expression. In other words, a
1530 match of the regular expression contained in the positive look-ahead
1531 construct is attempted. If it succeeds, control is passed to the next
1532 regular expression atom, but the text that was consumed by the positive
1533 look-ahead is first unmatched (backtracked) to the place in the text where
1534 the positive look-ahead was first encountered.
1536 One application of positive look-ahead is the manual implementation of a
1537 first character discrimination optimization. You can include a positive
1538 look-ahead that contains a character class which lists every character that
1539 the following (potentially complex) regular expression could possibly start
1540 with. This will quickly filter out match attempts that can not possibly
1543 3>Negative Look-Ahead
1545 Negative look-ahead takes the form `(?!<regex>)' and is exactly the same as
1546 positive look-ahead except that the enclosed regular expression must NOT
1547 match. This can be particularly useful when you have an expression that is
1548 general, and you want to exclude some special cases. Simply precede the
1549 general expression with a negative look-ahead that covers the special cases
1550 that need to be filtered out.
1552 3>Positive Look-Behind
1554 Positive look-behind constructs are of the form `(?<=<regex>)' and implement
1555 a zero width assertion of the enclosed regular expression in front of the
1556 current matching position. It is similar to a positive look-ahead assertion,
1557 except for the fact the the match is attempted on the text preceeding the
1558 current position, possibly even in front of the start of the matching range
1559 of the entire regular expression.
1561 A restriction on look-behind expressions is the fact that the expression
1562 must match a string of a bounded size. In other words, `*', `+', and `{n,}'
1563 quantifiers are not allowed inside the look-behind expression. Moreover,
1564 matching performance is sensitive to the difference between the upper and
1565 lower bound on the matching size. The smaller the difference, the better the
1566 performance. This is especially important for regular expressions used in
1569 Another (minor) restriction is the fact that look-**ahead** patterns, nor
1570 any construct that requires look-ahead information (such as word boundaries)
1571 are supported at the end of a look-behind pattern (no error is raised, but
1572 matching behaviour is unspecified). It is always possible to place these
1573 look-ahead patterns immediately after the look-behind pattern, where they
1574 will work as expected.
1576 Positive look-behind has similar applications as positive look-ahead.
1578 3>Negative Look-Behind
1580 Negative look-behind takes the form `(?<!<regex>)' and is exactly the same as
1581 positive look-behind except that the enclosed regular expression must
1582 NOT match. The same restrictions apply.
1584 Note however, that performance is even more sensitive to the distance
1585 between the size boundaries: a negative look-behind must not match for
1586 **any** possible size, so the matching engine must check **every** size.
1590 There are two parenthetical constructs that control case sensitivity:
1592 (?i<regex>) Case insensitive; `AbcD' and `aBCd' are
1595 (?I<regex>) Case sensitive; `AbcD' and `aBCd' are
1598 Regular expressions are case sensitive by default, that is, `(?I<regex>)' is
1599 assumed. All regular expression token types respond appropriately to case
1600 insensitivity including character classes and backreferences. There is some
1601 extra overhead involved when case insensitivity is in effect, but only to the
1602 extent of converting each character compared to lower case.
1606 NEdit regular expressions by default handle the matching of newlines in a way
1607 that should seem natural for most editing tasks. There are situations,
1608 however, that require finer control over how newlines are matched by some
1609 regular expression tokens.
1611 By default, NEdit regular expressions will NOT match a newline character for
1612 the following regex tokens: dot (`.'); a negated character class (`[^...]');
1613 and the following shortcuts for character classes:
1615 `\d', `\D', `\l', `\L', `\s', `\S', `\w', `\W', `\Y'
1617 The matching of newlines can be controlled for the `.' token, negated
1618 character classes, and the `\s' and `\S' shortcuts by using one of the
1619 following parenthetical constructs:
1621 (?n<regex>) `.', `[^...]', `\s', `\S' match newlines
1623 (?N<regex>) `.', `[^...]', `\s', `\S' don't match
1626 `(?N<regex>)' is the default behavior.
1628 3>Notes on New Parenthetical Constructs
1630 Except for plain parentheses, none of the parenthetical constructs capture
1631 text. If that is desired, the construct must be wrapped with capturing
1632 parentheses, e.g. `((?i<regex))'.
1634 All parenthetical constructs can be nested as deeply as desired, except for
1635 capturing parentheses which have a limit of 50 sets of parentheses,
1636 regardless of nesting level.
1640 Backreferences allow you to match text captured by a set of capturing
1641 parenthesis at some later position in your regular expression. A
1642 backreference is specified using a single backslash followed by a single
1643 digit from 1 to 9 (example: \3). Backreferences have similar syntax to
1644 substitutions (see below), but are different from substitutions in that they
1645 appear within the regular expression, not the substitution string. The number
1646 specified with a backreference identifies which set of text capturing
1647 parentheses the backreference is associated with. The text that was most
1648 recently captured by these parentheses is used by the backreference to
1649 attempt a match. As with substitutions, open parentheses are counted from
1650 left to right beginning with 1. So the backreference `\3' will try to match
1651 another occurrence of the text most recently matched by the third set of
1652 capturing parentheses. As an example, the regular expression `(\d)\1' could
1653 match `22', `33', or `00', but wouldn't match `19' or `01'.
1655 A backreference must be associated with a parenthetical expression that is
1656 complete. The expression `(\w(\1))' contains an invalid backreference since
1657 the first set of parentheses are not complete at the point where the
1658 backreference appears.
1662 Substitution strings are used to replace text matched by a set of capturing
1663 parentheses. The substitution string is mostly interpreted as ordinary text
1666 The escape sequences described above for special characters, and octal and
1667 hexadecimal escapes are treated the same way by a substitution string. When
1668 the substitution string contains the `&' character, NEdit will substitute the
1669 entire string that was matched by the `Find...' operation. Any of the first
1670 nine sub-expressions of the match string can also be inserted into the
1671 replacement string. This is done by inserting a `\' followed by a digit from
1672 1 to 9 that represents the string matched by a parenthesized expression
1673 within the regular expression. These expressions are numbered left-to-right
1674 in order of their opening parentheses.
1676 The capitalization of text inserted by `&' or `\1', `\2', ... `\9' can be
1677 altered by preceding them with `\U', `\u', `\L', or `\l'. `\u' and `\l'
1678 change only the first character of the inserted entity, while `\U' and `\L'
1679 change the entire entity to upper or lower case, respectively.
1680 ----------------------------------------------------------------------
1687 Regular expression substitution can be used to program automatic editing
1688 operations. For example, the following are search and replace strings to find
1689 occurrences of the `C' language subroutine `get_x', reverse the first and
1690 second parameters, add a third parameter of NULL, and change the name to
1693 Search string: `get_x *\( *([^ ,]*), *([^\)]*)\)'
1694 Replace string: `new_get_x(\2, \1, NULL)'
1698 If a regular expression could match two different parts of the text, it will
1699 match the one which begins earliest. If both begin in the same place but
1700 match different lengths, or match the same length in different ways, life
1701 gets messier, as follows.
1703 In general, the possibilities in a list of alternatives are considered in
1704 left-to-right order. The possibilities for `*', `+', and `?' are considered
1705 longest-first, nested constructs are considered from the outermost in, and
1706 concatenated constructs are considered leftmost-first. The match that will be
1707 chosen is the one that uses the earliest possibility in the first choice that
1708 has to be made. If there is more than one choice, the next will be made in
1709 the same manner (earliest possibility) subject to the decision on the first
1710 choice. And so forth.
1712 For example, `(ab|a)b*c' could match `abc' in one of two ways. The first
1713 choice is between `ab' and `a'; since `ab' is earlier, and does lead to a
1714 successful overall match, it is chosen. Since the `b' is already spoken for,
1715 the `b*' must match its last possibility, the empty string, since it must
1716 respect the earlier choice.
1718 In the particular case where no `|'s are present and there is only one `*',
1719 `+', or `?', the net effect is that the longest possible match will be
1720 chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that
1721 if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x', due
1722 to the begins-earliest rule. (In effect, the decision on where to start the
1723 match is the first choice to be made, hence subsequent choices must respect
1724 it even if this leads them to less-preferred alternatives.)
1728 An excellent book on the care and feeding of regular expressions is
1730 "Mastering Regular Expressions"
1731 Jeffrey E. F. Friedl
1732 (c) 1997, O'Reilly & Associates
1734 ----------------------------------------------------------------------
1736 Example Regular Expressions
1737 ---------------------------
1739 The following are regular expression examples which will match:
1747 * Whitespace on a line.
1750 * Whitespace across lines.
1753 * Whitespace that spans at least two lines. Note minimal matching `*?' quantifier.
1756 * IP address (not robust).
1757 ! (?:\d{1,3}(?:\.\d{1,3}){3})
1759 * Two character US Postal state abbreviations (includes territories).
1760 ! [ACDF-IK-PR-W][A-Z]
1763 ! (?:http://)?www\.\S+
1765 * Case insensitive double words across line breaks.
1766 ! (?i(?n<(\S+)\s+\1>))
1768 * Upper case words with possible punctuation.
1770 ----------------------------------------------------------------------
1772 Macro/Shell Extensions
1773 ======================
1775 Shell Commands and Filters
1776 --------------------------
1778 The Shell menu (Unix versions only) allows you to execute Unix shell commands
1779 from within NEdit. You can add items to the menu to extend NEdit's command
1780 set or to incorporate custom automatic editing features using shell commands
1781 or editing languages like awk and sed. To add items to the menu, select
1782 Preferences -> Default Settings Customize Menus -> Shell Menu. NEdit comes
1783 pre-configured with a few useful Unix commands like spell and sort, but we
1784 encourage you to add your own custom extensions.
1786 Filter Selection... prompts you for a Unix command to use to process the
1787 currently selected text. The output from this command replaces the contents
1790 Execute Command... prompts you for a Unix command and replaces the current
1791 selection with the output of the command. If there is no selection, it
1792 deposits the output at the current insertion point. In the Shell Command
1793 field, the % character expands to the name (including directory path), and
1794 the # character expands to the current line number of the file in the window.
1795 To include a % or # character in the command, use %% or ##, respectively.
1797 Execute Command Line uses the position of the cursor in the window to
1798 indicate a line to execute as a shell command line. The cursor may be
1799 positioned anywhere on the line. This command allows you to use an NEdit
1800 window as an editable command window for saving output and saving commands
1801 for re-execution. Note that the same character expansions described above
1802 in Execute Command also occur with this command.
1804 The X resource called nedit.shell (See "Customizing_NEdit_") determines which
1805 Unix shell is used to execute commands. The default value for this resource
1807 ----------------------------------------------------------------------
1812 Selecting Learn Keystrokes from the Macro menu puts NEdit in learn mode. In
1813 learn mode, keystrokes and menu commands are recorded, to be played back
1814 later, using the Replay Keystrokes command, or pasted into a macro in the
1815 Macro Commands dialog of the Default Settings menu in Preferences.
1817 Note that only keyboard and menu commands are recorded, not mouse clicks or
1818 mouse movements since these have no absolute point of reference, such as
1819 cursor or selection position. When you do a mouse-based operation in learn
1820 mode, NEdit will beep (repeatedly) to remind you that the operation was not
1823 Learn mode is also the quickest and easiest method for writing macros. The
1824 dialog for creating macro commands contains a button labeled "Paste Learn /
1825 Replay Macro", which will deposit the last sequence learned into the body of
1828 3>Repeating Actions and Learn/Replay Sequences
1830 You can repeat the last (keyboard-based) command, or learn/replay sequence
1831 with the Repeat... command in the Macro menu. To repeat an action, first do
1832 the action (that is, insert a character, do a search, move the cursor), then
1833 select Repeat..., decide how or how many times you want it repeated, and
1834 click OK. For example, to move down 30 lines through a file, you could type:
1835 <Down Arrow> Ctrl+, 29 <Return>. To repeat a learn/replay sequence, first
1836 learn it, then select Repeat..., click on Learn/Replay and how you want it
1837 repeated, then click OK.
1839 If the commands you are repeating advance the cursor through the file, you
1840 can also repeat them within a range of characters, or from the current cursor
1841 position to the end of the file. To iterate over a range of characters, use
1842 the primary selection (drag the left mouse button over the text) to mark the
1843 range you want to operate on, and select "In Selection" in the Repeat dialog.
1845 When using In "Selection" or "To End" with a learned sequence, try to do
1846 cursor movement as the last step in the sequence, since testing of the cursor
1847 position is only done at the end of the sequence execution. If you do cursor
1848 movement first, for example searching for a particular word then doing a
1849 modification, the position of the cursor won't be checked until the sequence
1850 has potentially gone far beyond the end of your desired range.
1852 It's easy for a repeated command to get out of hand, and you can easily
1853 generate an infinite loop by using range iteration on a command which doesn't
1854 progress. To cancel a repeating command in progress, type Ctrl+. (period),
1855 or select Cancel Macro from the Macro menu.
1856 ----------------------------------------------------------------------
1861 Macros can be called from Macro menu commands, window background menu
1862 commands, within the smart-indent framework, from the autoload macro file and
1863 from the command line.
1864 Macro menu and window background menu commands are defined under Preferences
1865 -> Default Settings -> Customize Menus. Help on creating items in these
1866 menus can be found in the section, Help -> Customizing -> Preferences.
1868 The autoload macro file is a file of macro commands and definitions which
1869 NEdit will automatically execute when it is first started. Its location is
1870 dependent on your environment:
1872 * The default place for the file is '$HOME/.nedit/autoload.nm',
1873 * if the variable $NEDIT_HOME is set in your environment it is located at '$NEDIT_HOME/autoload.nm',
1874 * if you are using old-style run control files (i.e. $HOME/.nedit is a regular file) it is located in '$HOME/.neditmacro'.
1876 (For VMS, the file is in '$NEDIT_HOME/autoload.nm' if $NEDIT_HOME is set, in
1877 'SYS$LOGIN:.neditmacro' otherwise.)
1879 NEdit's macro language is a simple interpreter with integer arithmetic,
1880 dynamic strings, and C-style looping constructs (very similar to the
1881 procedural portion of the Unix awk program). From the macro language, you
1882 can call the same action routines which are bound to keyboard keys and menu
1883 items, as well additional subroutines for accessing and manipulating editor
1884 data, which are specific to the macro language (these are listed in the
1885 sections titled "Macro_Subroutines_", and "Action_Routines_").
1890 An NEdit macro language program consists of a list of statements, each
1891 terminated by a newline. Groups of statements which are executed together
1892 conditionally, such as the body of a loop, are surrounded by curly braces
1895 Blank lines and comments are also allowed. Comments begin with a "#" and end
1896 with a newline, and can appear either on a line by themselves, or at the end
1899 Statements which are too long to fit on a single line may be split across
1900 several lines, by placing a backslash "\" character at the end of each line
1906 The NEdit macro language recognizes only three data types, dynamic character
1907 strings, integer values and associative arrays. In general strings and
1908 integers can be used interchangeably. If a string represents an integer
1909 value, it can be used as an integer. Integers can be compared and
1910 concatenated with strings. Arrays may contain integers, strings, or arrays.
1911 Arrays are stored key/value pairs. Keys are always stored as strings.
1915 Integers are non-fractional numbers in the range of -2147483647 to
1916 2147483647. Integer constants must be in decimal. For example:
1921 4>Character String Constants
1923 Character string constants are enclosed in double quotes. For example:
1926 dialog("Hi there!", "Dismiss")
1928 Strings may also include C-language style escape sequences:
1930 \\ Backslash \t Tab \f Form feed
1931 \" Double quote \b Backspace \a Alert
1932 \n Newline \r Carriage return \v Vertical tab
1934 For example, to send output to the terminal from which NEdit was started, a
1935 newline character is necessary because, like printf, t_print requires
1936 explicit newlines, and also buffers its output on a per-line basis:
1938 t_print("a = " a "\n")
1943 Variable names must begin either with a letter (local variables), or a $
1944 (global variables). Beyond the first character, variables may also contain
1945 numbers and underscores `_'. Variables are called in to existence just by
1946 setting them (no explicit declarations are necessary).
1948 Local variables are limited in scope to the subroutine (or menu item
1949 definition) in which they appear. Global variables are accessible from all
1950 routines, and their values persist beyond the call which created them, until
1953 4>Built-in Variables
1955 NEdit has a number of permanently defined variables, which are used to access
1956 global editor information and information about the the window in which the
1957 macro is executing. These are listed along with the built in functions in
1958 the section titled "Macro_Subroutines_".
1961 3>Functions and Subroutines
1963 The syntax of a function or subroutine call is:
1965 function_name(arg1, arg2, ...)
1967 where arg1, arg2, etc. represent up to 9 argument values which are passed to
1968 the routine being called. A function or subroutine call can be on a line by
1969 itself, as above, or if it returns a value, can be invoked within a character
1970 or numeric expression:
1972 a = fn1(b, c) + fn2(d)
1973 dialog("fn3 says: " fn3())
1975 Arguments are passed by value. This means that you can not return values via
1976 the argument list, only through the function value or indirectly through
1977 agreed-upon global variables.
1979 4>Built-in Functions
1981 NEdit has a wide range of built in functions which can be called from the
1982 macro language. These routines are divided into two classes, macro-language
1983 functions, and editor action routines. Editor action routines are more
1984 flexible, in that they may be called either from the macro language, or bound
1985 directly to keys via translation tables. They are also limited, however, in
1986 that they can not return values. Macro language routines can return values,
1987 but can not be bound to keys in translation tables.
1989 Nearly all of the built-in subroutines operate on an implied window, which is
1990 initially the window from which the macro was started. To manipulate the
1991 contents of other windows, use the focus_window subroutine to change the
1992 focus to the ones you wish to modify. focus_window can also be used to
1993 iterate over all of the currently open windows, using the special keyword
1994 names, "last" and "next".
1996 For backwards compatibility, hyphenated action routine names are allowed, and
1997 most of the existing action routines names which contain underscores have an
1998 equivalent version containing hyphens ('-') instead of underscores. Use of
1999 these names is discouraged. The macro parser resolves the ambiguity between
2000 '-' as the subtraction/negation operator, and - as part of an action routine
2001 name by assuming subtraction unless the symbol specifically matches an action
2004 4>User Defined Functions
2006 Users can define their own macro subroutines, using the define keyword:
2008 define subroutine_name {
2009 < body of subroutine >
2012 Macro definitions can not appear within other definitions, or within macro
2013 menu item definitions (usually they are found in the autoload macro file).
2015 The arguments with which a user-defined subroutine or function was invoked,
2016 are presented as $1, $2, ... , $9. The number of arguments can be read from
2019 To return a value from a subroutine, and/or to exit from the subroutine
2020 before the end of the subroutine body, use the return statement:
2022 return <value to return>
2025 3>Operators and Expressions
2027 Operators have the same meaning and precedence that they do in C, except for
2028 ^, which raises a number to a power (y^x means y to the x power), rather than
2029 bitwise exclusive OR. The table below lists operators in decreasing order of
2032 Operators Associativity
2038 > >= < <= == != left to right
2043 (concatenation) left to right
2044 = += -= *= /= %=, &= |= right to left
2046 The order in which operands are evaluated in an expression is undefined,
2047 except for && and ||, which like C, evaluate operands left to right, but stop
2048 when further evaluation would no longer change the result.
2050 4>Numerical Operators
2052 The numeric operators supported by the NEdit macro language are listed below:
2055 - subtraction or negation
2063 Increment (++) and decrement (--) operators can also be appended or prepended
2064 to variables within an expression. Prepended increment/decrement operators
2065 act before the variable is evaluated. Appended increment/decrement operators
2066 act after the variable is evaluated.
2068 4>Logical and Comparison Operators
2070 Logical operations produce a result of 0 (for false) or 1 (for true). In a
2071 logical operation, any non-zero value is recognized to mean true. The
2072 logical and comparison operators allowed in the NEdit macro language are
2082 == equal (integers and/or strings)
2083 != not equal (integers and/or strings)
2085 4>Character String Operators
2087 The "operator" for concatenating two strings is the absence of an operator.
2088 Adjoining character strings with no operator in between means concatenation:
2091 t_print("the value of a is: " a)
2093 Comparison between character strings is done with the == and != operators,
2094 (as with integers). There are a number of useful built-in routines for
2095 working with character strings, which are listed in the section called
2096 "Macro_Subroutines_".
2098 4>Arrays and Array Operators
2100 Arrays may contain either strings, integers, or other arrays. Arrays are
2101 associative, which means that they relate two pieces of information, the key
2102 and the value. The key is always a string; if you use an integer it is
2103 converted to a string.
2105 To determine if a given key is in an array, use the 'in' keyword.
2110 If the left side of the in keyword is an array, the result is true if every
2111 key in the left array is in the right array. Array values are not compared.
2113 To iterate through all the keys of an array use the 'for' looping construct.
2114 Keys are not guaranteed in any particular order:
2119 Elements can be removed from an array using the delete command:
2121 delete x[3] # deletes element with key 3
2122 delete x[] # deletes all elements
2124 The number of elements in an array can be determined by referencing the
2125 array with no indices:
2127 dialog("array x has " x[] " elements", "OK")
2129 Arrays can be combined with some operators. All the following operators only
2130 compare the keys of the arrays.
2132 result = x + y (Merge arrays)
2134 The 'result' is a new array containing keys from both x and y. If
2135 duplicates are present values from y are used.
2137 result = x - y (Remove keys)
2139 The 'result' is a new array containing all keys from x that are not in y.
2141 result = x & y (Common keys)
2143 The 'result' is a new array containing all keys which are in both x and y.
2144 The values from y are used.
2146 result = x | y (Unique keys)
2148 The 'result' is a new array containing keys which exist in either x or y,
2151 When duplicate keys are encountered using the + and & operators, the values
2152 from the array on the right side of the operators are used for the result.
2153 All of the above operators are array only, meaning both the left and right
2154 sides of the operator must be arrays. The results are also arrays.
2156 Array keys can also contain multiple dimensions:
2158 x[1, 1, 1] = "string"
2160 These are used in the expected way, e.g.:
2162 for (i = 1; i < 3; i++)
2164 for (j = 1; j < 3; j++)
2170 gives the following array:
2177 Internally all indices are part of one string, separated by the string
2178 $sub_sep (ASCII 0x18). The first key in the above example is in fact
2182 If you need to extract one of the keys, you can use split(), using
2183 $sub_sep as the separator.
2185 You can also check for the existence of multi-dimensional array by
2186 looking for $sub_sep in the key.
2188 Last, you need $sub_sep if you want to use the 'in' keyword.
2190 if ((1,2) in myArray)
2195 if (("1" $sub_sep "2") in myArray)
2200 3>Looping and Conditionals
2202 NEdit supports looping constructs: for and while, and conditional statements:
2203 if and else, with essentially the same syntax as C:
2205 for (<init>, ...; <condition>; <increment>, ...) <body>
2207 while (<condition>) <body>
2209 if (<condition>) <body>
2211 if (<condition>) <body> else <body>
2213 <body>, as in C, can be a single statement, or a list of statements enclosed
2214 in curly braces ({}). <condition> is an expression which must evaluate to
2215 true for the statements in <body> to be executed. for loops may also contain
2216 initialization statements, <init>, executed once at the beginning of the
2217 loop, and increment/decrement statements (or any arbitrary statement), which
2218 are executed at the end of the loop, before the condition is evaluated again.
2222 for (i=0; i<100; i++)
2225 for (i=0, j=20; i<20; i++, j--) {
2241 Loops may contain break and continue statements. A break statement causes an
2242 exit from the innermost loop, a continue statement transfers control to the
2244 ----------------------------------------------------------------------
2249 3>Built in Variables
2251 These variables are read-only and can not be changed.
2254 Index of the current pane.
2257 Contains the current preference for auto indent.
2258 Can be "off", "on" or "auto".
2261 Equals the ID of the currently displayed calltip, or 0 if no calltip is
2265 Position of the cursor in the current window.
2268 Column number of the cursor position in the current window.
2271 Width of the current pane in pixels.
2274 If tab emulation is turned on in the Tabs...
2275 dialog of the Preferences menu, value is the
2276 distance between emulated tab stops. If tab
2277 emulation is turned off, value is -1.
2280 An array with no elements. This can be used to initialize
2281 an array to an empty state.
2284 Current newline format that the file will be saved with. Can
2285 be "unix", "dos" or "macintosh".
2288 Name of the file being edited in the current
2289 window, stripped of directory component.
2292 Directory component of file being edited in the current window.
2295 Contains the current plain text font name.
2298 Contains the current bold text font name.
2300 **$font_name_bold_italic**
2301 Contains the current bold-italic text font name.
2303 **$font_name_italic**
2304 Contains the current italic text font name.
2306 **$highlight_syntax**
2307 Whether syntax highlighting is turned on.
2309 **$incremental_backup**
2310 Contains 1 if incremental auto saving is on, otherwise 0.
2312 **$incremental_search_line**
2313 Has a value of 1 if the preference is
2314 selected to always show the incremental search line, otherwise 0.
2317 Name of language mode set in the current window.
2320 Line number of the cursor position in the current window.
2323 True if the file has been locked by the user.
2325 **$make_backup_copy**
2326 Has a value of 1 if original file is kept in a
2327 backup file on save, otherwise 0.
2330 The maximum font width of all the active styles.
2331 Syntax highlighting styles are only considered if syntax highlighting
2335 The minimum font width of all the active styles.
2336 Syntax highlighting styles are only considered if syntax highlighting
2340 True if the file in the current window has
2341 been modified and the modifications have not
2344 **$n_display_lines**
2345 The number of lines visible in the currently active pane.
2348 The number of panes in the current window.
2351 True if in Overtype mode.
2354 True if the file is read only.
2356 **$selection_start, $selection_end**
2357 Beginning and ending positions of the
2358 primary selection in the current window, or
2359 -1 if there is no text selected in the current window.
2361 **$selection_left, $selection_right**
2362 Left and right character offsets of the rectangular (primary) selection in
2363 the current window, or -1 if there is no selection or it is not rectangular.
2366 Name of the current NEdit server.
2368 **$show_line_numbers**
2369 Whether line numbers are shown next to the text.
2372 Contains the current preference for showing matching pairs,
2373 such as "[]" and "{}" pairs. Can be "off", "delimiter", or "range".
2375 **$match_syntax_based**
2376 Whether pair matching should use syntax information, if available.
2378 **$statistics_line**
2379 Has a value of 1 if the statistics line is shown, otherwise 0.
2382 Contains the value of the array sub-script separation string.
2385 The distance between tab stops for a
2386 hardware tab character, as set in the
2387 Tabs... dialog of the Preferences menu.
2390 The length of the text in the current window.
2393 The line number of the top line of the currently active pane.
2396 Whether the user is allowing the NEdit to insert tab characters to maintain
2397 spacing in tab emulation and rectangular dragging operations. (The setting of
2398 the "Use tab characters in padding and emulated tabs" button in the Tabs...
2399 dialog of the Preferences menu.)
2402 The right margin in the current window for text wrapping and filling.
2405 The current wrap text mode. Values are "none", "auto" or "continuous".
2408 3>Built-in Subroutines
2410 **append_file( string, filename )**
2411 Appends a string to a named file. Returns 1 on successful write, or 0 if
2417 **calltip( "text_or_key" [, mode [, pos]] )**
2418 Pops up a calltip. <pos> is an optional position in the buffer where the tip
2419 will be displayed. The upper-left corner of the calltip will appear below
2420 where the cursor would appear if it were at this position. <mode> is one of
2421 "tipText" (default), "tipKey", or "tagKey". "tipText" displays the text as-is,
2422 "tagKey" uses it as the key to look up a tag, then converts the tag to a
2423 calltip, and "tipKey uses it as the key to look up a calltip, then falls back
2424 to a tag if that fails. You'll usually use "tipKey" or "tipText".
2425 Returns the ID of the calltip if it was found and/or displayed correctly,
2428 **clipboard_to_string()**
2429 Returns the contents of the clipboard as a macro string. Returns empty
2432 **dialog( message, btn_1_label, btn_2_label, ... )**
2433 Pop up a dialog for querying and presenting information to the user. First
2434 argument is a string to show in the message area of the dialog. Up to eight
2435 additional optional arguments represent labels for buttons to appear along
2436 the bottom of the dialog. Returns the number of the button pressed (the
2437 first button is number 1), or 0 if the user closed the dialog via the window
2440 **focus_window( window_name )**
2441 Sets the window on which subsequent macro commands operate. window_name can
2442 be either a fully qualified file name, or one of "last" for the last window
2443 created, or "next" for the next window in the chain from the currently
2444 focused window (the first window being the one returned from calling
2445 focus_window("last"). Returns the name of the newly-focused window, or an
2446 empty string if the requested window was not found.
2448 **get_character( position )**
2449 Returns the single character at the position
2450 indicated by the first argument to the routine from the current window.
2452 **get_range( start, end )**
2453 Returns the text between a starting and ending position from the current
2457 Returns a string containing the text currently selected by the primary
2458 selection either from the current window (no keyword), or from anywhere on
2459 the screen (keyword "any").
2462 Gets the value of an environment variable.
2464 **kill_calltip( [calltip_ID] )**
2465 Kills any calltip that is being displayed in the window in which the macro is
2466 running. If there is no displayed calltip this does nothing. If a calltip
2467 ID is supplied then the calltip is killed only if its ID is calltip_ID.
2469 **length( string )**
2470 Returns the length of a string
2472 **list_dialog( message, text, btn_1_label, btn_2_label, ... )**
2473 Pop up a dialog for prompting the user to choose a line from the given text
2474 string. The first argument is a message string to be used as a title for the
2475 fixed text describing the list. The second string provides the list data:
2476 this is a text string in which list entries are separated by newline
2477 characters. Up to seven additional optional arguments represent labels for
2478 buttons to appear along the bottom of the dialog. Returns the line of text
2479 selected by the user as the function value (without any newline separator) or
2480 the empty string if none was selected, and number of the button pressed (the
2481 first button is number 1), in $list_dialog_button. If the user closes the
2482 dialog via the window close box, the function returns the empty string, and
2483 $list_dialog_button returns 0.
2485 **max( n1, n2, ... )**
2486 Returns the maximum value of all of its arguments
2488 **min( n1, n2, ... )**
2489 Returns the minimum value of all of its arguments
2491 **read_file( filename )**
2492 Reads the contents of a text file into a string. On success, returns 1 in
2493 $read_status, and the contents of the file as a string in the subroutine
2494 return value. On failure, returns the empty string "" and an 0 $read_status.
2496 **replace_in_string( string, search_for, replace_with [, type, "copy"] )**
2497 Replaces all occurrences of a search string in a string with a replacement
2498 string. Arguments are 1: string to search in, 2: string to search for, 3:
2499 replacement string. There are two optional arguments. One is a search type,
2500 either "literal", "case", "word", "caseWord", "regex", or "regexNoCase".
2501 The default search type is "literal". If the optional "copy" argument is
2502 specified, a copy of the input string is returned when no replacements were
2503 performed. By default an empty string ("") will be returned in this case.
2504 Returns a new string with all of the replacements done.
2506 **replace_range( start, end, string )**
2507 Replaces all of the text in the current window between two positions.
2509 **replace_selection( string )**
2510 Replaces the primary-selection selected text in the current window.
2512 **replace_substring( string, start, end, replace_with )**
2513 Replacing a substring between two positions in a string within another string.
2515 **search( search_for, start [, search_type, wrap, direction] )**
2516 Searches silently in a window without dialogs, beeps, or changes to the
2517 selection. Arguments are: 1: string to search for, 2: starting position.
2518 Optional arguments may include the strings: "wrap" to make the search wrap
2519 around the beginning or end of the string, "backward" or "forward" to change
2520 the search direction ("forward" is the default), "literal", "case", "word",
2521 "caseWord", "regex", or "regexNoCase" to change the search type (default is
2522 "literal"). Returns the starting position of the match, or -1 if nothing
2523 matched. Also returns the ending position of the match in $search_end.
2525 **search_string( string, search_for, start [, search_type, direction] )**
2527 Built-in macro subroutine for searching a string. Arguments are 1: string to
2528 search in, 2: string to search for, 3: starting position. Optional arguments
2529 may include the strings: "wrap" to make the search wrap around the beginning
2530 or end of the string, "backward" or "forward" to change the search direction
2531 ("forward" is the default), "literal", "case", "word", "caseWord", "regex",
2532 or "regexNoCase" to change the search type (default is "literal"). Returns
2533 the starting position of the match, or -1 if nothing matched. Also returns
2534 the ending position of the match in $search_end.
2536 **select( start, end )**
2537 Selects (with the primary selection) text in the current buffer between a
2538 starting and ending position.
2540 **select_rectangle( start, end, left, right )**
2541 Selects a rectangular area of text between a starting and ending position,
2542 and confined horizontally to characters displayed between positions "left",
2545 **set_cursor_pos( position )**
2546 Set the cursor position for the current window.
2548 **shell_command( command, input_string )**
2549 Executes a shell command, feeding it input from input_string. On completion,
2550 output from the command is returned as the function value, and the command's
2551 exit status is returned in the global variable $shell_cmd_status.
2553 **split(string, separation_string [, search_type])**
2554 Splits a string using the separator specified. Optionally the search_type
2555 argument can specify how the separation_string is interpreted. The default
2556 is "literal". The returned value is an array with keys beginning at 0.
2558 **string_dialog( message, btn_1_label, btn_2_label, ... )**
2559 Pops up a dialog prompting the user to enter information. The first argument
2560 is a string to show in the message area of the dialog. Up to nine additional
2561 optional arguments represent labels for buttons to appear along the bottom of
2562 the dialog. Returns the string entered by the user as the function value,
2563 and number of the button pressed (the first button is number 1), in
2564 $string_dialog_button. If the user closes the dialog via the window close
2565 box, the function returns the empty string, and $string_dialog_button returns
2568 **string_compare(string1, string2 [, consider-case])**
2569 Compare two strings and return 0 if they are equal, -1 if string1 is less
2570 than string2 or 1 if string1 is greater than string2. The values for the
2571 optional consider-case argument is either "case" or "nocase". The default
2572 is to do a case sensitive comparison.
2574 **string_to_clipboard( string )**
2575 Copy the contents of a macro string to the clipboard.
2577 **substring( string, start, end )**
2578 Returns the portion of a string between a starting and ending position.
2580 **t_print( string1, string2, ... )**
2581 Writes strings to the terminal (stdout) from which NEdit was started.
2583 **tolower( string )**
2584 Return an all lower-case version of string.
2586 **toupper( string )**
2587 Return an all upper-case version of string.
2589 **write_file( string, filename )**
2590 Writes a string (parameter 1) to a file named in parameter 2. Returns 1 on
2591 successful write, or 0 if unsuccessful.
2592 ----------------------------------------------------------------------
2597 All of the editing capabilities of NEdit are represented as a special type of
2598 subroutine, called an action routine, which can be invoked from both macros
2599 and translation table entries (see "Key_Binding_" in the
2600 Customizing section of the Help menu).
2603 3>Actions Representing Menu Commands
2605 File Menu Search Menu
2606 ----------------------- -------------------------
2608 open() find_dialog()
2609 open_dialog() find_again()
2610 open_selected() find_selection()
2612 save() replace_dialog()
2613 save_as() replace_all()
2614 save_as_dialog() replace_in_selection()
2615 revert_to_saved() replace_again()
2616 include_file() goto_line_number()
2617 include_file_dialog() goto_line_number_dialog()
2618 load_macro_file() goto_selected()
2619 load_macro_file_dialog() mark()
2620 load_tags_file() mark_dialog()
2621 load_tags_file_dialog() goto_mark()
2622 unload_tags_file() goto_mark_dialog()
2623 print() goto_matching()
2624 print_selection() select_to_matching()
2625 exit() find_definition()
2627 Edit Menu Shell Menu
2628 ----------------------- -------------------------
2629 undo() filter_selection_dialog()
2630 redo() filter_selection()
2631 delete() execute_command()
2632 select_all() execute_command_dialog()
2633 shift_left() execute_command_line()
2634 shift_left_by_tab() shell_menu_command()
2636 shift_right_by_tab() Macro Menu
2637 uppercase() -------------------------
2638 lowercase() macro_menu_command()
2639 fill_paragraph() repeat_macro()
2640 control_code_dialog() repeat_dialog()
2643 -------------------------
2647 An action representing a menu command is named the same as its corresponding
2648 menu item except that all punctuation is removed, all letters are changed to
2649 lower case, and spaces are replaced with underscores. To present a dialog to
2650 ask the user for input, use the actions with the `_dialog` suffix. Actions
2651 without the `_dialog` suffix take the information from the routine's
2652 arguments (see below).
2654 3>Menu Action Routine Arguments
2656 Arguments are text strings enclosed in quotes. Below are the menu action
2657 routines which take arguments. Optional arguments are enclosed in [].
2659 **close**( ["prompt" | "save" | "nosave"] )
2661 **execute_command**( shell-command )
2663 **filter_selection**( shell-command )
2665 **find**( search-string [, ~search-direction~] [, ~search-type~]
2668 **find_again**( [~search-direction~] [, ~search-wrap~] )
2670 **find_definition**( [tag-name] )
2672 **find_dialog**( [~search-direction~] [, ~search-type~]
2675 **find_selection**( [~search-direction~] [, ~search-wrap~]
2676 [, ~non-regex-search-type~] )
2678 **goto_line_number**( [line-number] )
2680 **goto_mark**( ~mark-letter~ )
2682 **include_file**( ~filename~ )
2684 **load_tags_file**( ~filename~ )
2686 **macro_menu_command**( ~macro-menu-item-name~ )
2688 **mark**( ~mark-letter~ )
2690 **open**( ~filename~ )
2692 **replace**( search-string, replace-string,
2693 [, ~search-direction~] [, ~search-type~] [, ~search-wrap~] )
2695 **replace_again**( [~search-direction~] [, ~search-wrap~] )
2697 **replace_dialog**( [~search-direction~] [, ~search-type~]
2700 **replace_in_selection**( search-string,
2701 replace-string [, ~search-type~] )
2703 **save_as**( ~filename~ )
2705 **shell_menu_command**( ~shell-menu-item-name~ )
2707 **unload_tags_file**( ~filename~ )
2709 **----------- Some notes on argument types above -----------**
2711 ~filename~ Path names are relative to the directory from
2712 which NEdit was started. Shell interpreted
2713 wildcards and `~' are not expanded.
2715 ~keep-dialog~ Either "keep" or "nokeep".
2717 ~mark-letter~ The mark command limits users to single
2718 letters. Inside of macros, numeric marks are
2719 allowed, which won't interfere with marks set
2722 ~macro-menu-item-name~
2723 Name of the command exactly as specified in
2724 the Macro Menu dialogs.
2726 ~non-regex-search-type~
2727 Either "literal", "case", "word", or
2731 Either "forward" or "backward".
2733 ~search-type~ Either "literal", "case", "word",
2734 "caseWord", "regex", or "regexNoCase".
2736 ~search-wrap~ Either "wrap" or "nowrap".
2738 ~shell-menu-item-name~
2739 Name of the command exactly as specified in
2740 the Shell Menu dialogs.
2742 3>Window Preferences Actions
2744 **set_auto_indent( "off" | "on" | "smart" )**
2745 Set auto indent mode for the current window.
2747 **set_em_tab_dist( em-tab-distance )**
2748 Set the emulated tab size. An em-tab-distance value of
2749 0 or -1 translates to no emulated tabs. Em-tab-distance must
2750 be smaller than 1000.
2752 **set_fonts( font-name, italic-font-name, bold-font-name, bold-italic-font-name )**
2753 Set all the fonts used for the current window.
2755 **set_highlight_syntax( [0 | 1] )**
2756 Set syntax highlighting mode for the current window.
2757 A value of 0 turns it off and a value of 1 turns it on.
2758 If no parameters are supplied the option is toggled.
2760 **set_incremental_backup( [0 | 1] )**
2761 Set incremental backup mode for the current window.
2762 A value of 0 turns it off and a value of 1 turns it on.
2763 If no parameters are supplied the option is toggled.
2765 **set_incremental_search_line( [0 | 1] )**
2766 Show or hide the incremental search line for the current window.
2767 A value of 0 turns it off and a value of 1 turns it on.
2768 If no parameters are supplied the option is toggled.
2770 **set_language_mode( language-mode )**
2771 Set the language mode for the current window. If the language mode is
2772 "" or unrecognized, it will be set to Plain.
2774 **set_locked( [0 | 1] )**
2775 This only affects the locked status of a file, not it's read-only
2776 status. Permissions are NOT changed.
2777 A value of 0 turns it off and a value of 1 turns it on.
2778 If no parameters are supplied the option is toggled.
2780 **set_make_backup_copy( [0 | 1] )**
2781 Set whether backup copies are made during saves for the current window.
2782 A value of 0 turns it off and a value of 1 turns it on.
2783 If no parameters are supplied the option is toggled.
2785 **set_overtype_mode( [0 | 1] )**
2786 Set overtype mode for the current window.
2787 A value of 0 turns it off and a value of 1 turns it on.
2788 If no parameters are supplied the option is toggled.
2790 **set_show_line_numbers( [0 | 1] )**
2791 Show or hide line numbers for the current window.
2792 A value of 0 turns it off and a value of 1 turns it on.
2793 If no parameters are supplied the option is toggled.
2795 **set_show_matching( "off" | "delimiter" | "range" )**
2796 Set show matching (...) mode for the current window.
2798 **set_match_syntax_based( [0 | 1] )**
2799 Set whether matching should be syntax based for the current window.
2801 **set_statistics_line( [0 | 1] )**
2802 Show or hide the statistics line for the current window.
2803 A value of 0 turns it off and a value of 1 turns it on.
2804 If no parameters are supplied the option is toggled.
2806 **set_tab_dist( tab-distance )**
2807 Set the size of hardware tab spacing. Tab-distance must
2808 must be a value greater than 0 and no greater than 20.
2810 **set_use_tabs( [0 | 1] )**
2811 Set whether tabs are used for the current window.
2812 A value of 0 turns it off and a value of 1 turns it on.
2813 If no parameters are supplied the option is toggled.
2815 **set_wrap_margin( wrap-width )**
2816 Set the wrap width for text wrapping of the current window. A value
2817 of 0 means to wrap at window width.
2819 **set_wrap_text( "none" | "auto" | "continuous" )**
2820 Set wrap text mode for the current window.
2822 3>Keyboard-Only Actions
2824 In addition to the arguments listed in the call descriptions below, any
2825 routine involving cursor movement can take the argument "extend", meaning,
2826 adjust the primary selection to the new cursor position. Routines which take
2827 the "extend" argument as well as mouse dragging operations for both primary
2828 and secondary selections can take the optional keyword "rect", meaning, make
2829 the selection rectangular. Any routine that accepts the "scrollbar" argument
2830 will move the display but not the cursor or selection. Routines that accept
2831 the "nobell" argument will fail silently without beeping, when that argument
2834 **backward_character( ["nobell"] )**
2835 Moves the cursor one character to the left.
2837 **backward_paragraph(["nobell"] )**
2838 Moves the cursor to the beginning of the paragraph, or
2839 if the cursor is already at the beginning of a paragraph, moves the cursor to
2840 the beginning of the previous paragraph. Paragraphs are defined as regions
2841 of text delimited by one or more blank lines.
2843 **backward_word( ["nobell"] )**
2844 Moves the cursor to the beginning of a word, or, if the
2845 cursor is already at the beginning of a word, moves the cursor to the
2846 beginning of the previous word. Word delimiters are user-settable, and
2847 defined by the X resource wordDelimiters.
2849 **beginning_of_file( ["scrollbar"] )**
2850 Moves the cursor to the beginning of the file.
2852 **beginning_of_line( ["absolute"] )**
2853 Moves the cursor to the beginning of the line. If
2854 "absolute" is given, always moves to the absolute beginning of line,
2855 regardless of the text wrapping mode.
2857 **beginning_of_selection()**
2858 Moves the cursor to the beginning of the selection
2859 without disturbing the selection.
2861 **copy_clipboard()**
2862 Copies the current selection to the clipboard.
2865 Copies the primary selection to the cursor.
2868 If a secondary selection exists, copies the secondary selection to
2869 the cursor. If no secondary selection exists, copies the primary selection
2870 to the pointer location.
2872 **copy_to_or_end_drag()**
2873 Completes either a secondary selection operation, or a
2874 primary drag. If the user is dragging the mouse to adjust a secondary
2875 selection, the selection is copied and either inserted at the cursor
2876 location, or, if pending-delete is on and a primary selection exists in the
2877 window, replaces the primary selection. If the user is dragging a block of
2878 text (primary selection), completes the drag operation and leaves the text at
2879 it's current location.
2882 Deletes the text in the primary selection and places it in
2886 Copies the primary selection to the cursor and deletes it at
2887 its original location.
2889 **delete_selection()**
2890 Deletes the contents of the primary selection.
2892 **delete_next_character( ["nobell"] )**
2893 If a primary selection exists, deletes its contents.
2894 Otherwise, deletes the character following the cursor.
2896 **delete_previous_character( ["nobell"] )**
2897 If a primary selection exists, deletes its
2898 contents. Otherwise, deletes the character before the cursor.
2900 **delete_next_word( ["nobell"] )**
2901 If a primary selection exists, deletes its contents.
2902 Otherwise, deletes the word following the cursor.
2904 **delete_previous_word( ["nobell"] )**
2905 If a primary selection exists, deletes its contents.
2906 Otherwise, deletes the word before the cursor.
2908 **delete_to_start_of_line( ["nobell", "wrap"] )**
2909 If a primary selection exists, deletes its contents. Otherwise, deletes the
2910 characters between the cursor and the start of the line. If "wrap" is
2911 given, deletes to the previous wrap point or beginning of line, whichever
2914 **delete_to_end_of_line( ["nobell", "absolute"] )**
2915 If a primary selection exists, deletes its contents.
2916 Otherwise, deletes the characters between the cursor and the end of the line.
2917 If "absolute" is given, always deletes to the absolute end of line, regardless
2918 of the text wrapping mode.
2921 De-selects the primary selection.
2923 **end_of_file( ["scrollbar"] )**
2924 Moves the cursor to the end of the file.
2926 **end_of_line( ["absolute"] )**
2927 Moves the cursor to the end of the line. If
2928 "absolute" is given, always moves to the absolute end of line, regardless
2929 of the text wrapping mode.
2931 **end_of_selection()**
2932 Moves the cursor to the end of the selection without
2933 disturbing the selection.
2935 **exchange( ["nobell"] )**
2936 Exchange the primary and secondary selections.
2939 Attached mouse-movement events to begin a selection between
2940 the cursor and the mouse, or extend the primary selection to the mouse
2944 Completes a primary drag-selection operation.
2947 Begins a selection between the cursor and the mouse. A
2948 drag-selection operation can be started with either extend_start or
2951 **focus_pane( [relative-pane] | [positive-index] | [negative-index] )**
2952 Move the focus to the requested pane.
2953 Arguments can be specified in the form of a relative-pane
2954 ("first", "last", "next", "previous"), a positive-index
2955 (numbers greater than 0, 1 is the same as "first") or a
2956 negative-index (numbers less than 0, -1 is the same as "last").
2958 **forward_character()**
2959 Moves the cursor one character to the right.
2961 **forward_paragraph( ["nobell"] )**
2962 Moves the cursor to the beginning of the next paragraph.
2963 Paragraphs are defined as regions of text delimited by one or more blank
2966 **forward_word( ["tail"] ["nobell"] )**
2967 Moves the cursor to the beginning of the next word. Word
2968 delimiters are user-settable, and defined by the X resource wordDelimiters.
2969 If the "tail" argument is supplied the cursor will be moved to
2970 the end of the current word or the end of the next word, if the
2971 cursor is between words.
2974 Moves the cursor to the mouse pointer location, and prepares for
2975 a possible drag-selection operation (bound to extend_adjust), or multi-click
2976 operation (a further grab_focus action). If a second invocation of grab
2977 focus follows immediately, it selects a whole word, or a third, a whole line.
2979 **insert_string( "string" )**
2980 If pending delete is on and the cursor is inside the
2981 selection, replaces the selection with "string". Otherwise, inserts "string"
2982 at the cursor location.
2984 **key_select( "direction" [,"nobell"] )**
2985 Moves the cursor one character in "direction"
2986 ("left", "right", "up", or "down") and extends the selection. Same as
2987 forward/backward-character("extend"), or process-up/down("extend"), for
2988 compatibility with previous versions.
2990 **move-destination()**
2991 Moves the cursor to the pointer location without
2992 disturbing the selection. (This is an unusual way of working. We left it in
2993 for compatibility with previous versions, but if you actually use this
2994 capability, please send us some mail, otherwise it is likely to disappear in
2998 If a secondary selection exists, deletes the contents of the
2999 secondary selection and inserts it at the cursor, or if pending-delete is on
3000 and there is a primary selection, replaces the primary selection. If no
3001 secondary selection exists, moves the primary selection to the pointer
3002 location, deleting it from its original position.
3004 **move_to_or_end_drag()**
3005 Completes either a secondary selection operation, or a
3006 primary drag. If the user is dragging the mouse to adjust a secondary
3007 selection, the selection is deleted and either inserted at the cursor
3008 location, or, if pending-delete is on and a primary selection exists in the
3009 window, replaces the primary selection. If the user is dragging a block of
3010 text (primary selection), completes the drag operation and deletes the text
3011 from it's current location.
3014 Inserts a newline character. If Auto Indent is on, lines up the
3015 indentation of the cursor with the current line.
3017 **newline_and_indent()**
3018 Inserts a newline character and lines up the indentation
3019 of the cursor with the current line, regardless of the setting of Auto
3022 **newline_no_indent()**
3023 Inserts a newline character, without automatic
3024 indentation, regardless of the setting of Auto Indent.
3026 **next_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3027 Moves the cursor and scroll forward one page.
3028 The parameter "stutter" moves the cursor to the bottom of the display,
3029 unless it is already there, otherwise it will page down.
3030 The parameter "column" will maintain the preferred column while
3033 **page_left( ["scrollbar"] ["nobell"] )**
3034 Move the cursor and scroll left one page.
3036 **page_right( ["scrollbar"] ["nobell"] )**
3037 Move the cursor and scroll right one page.
3039 **paste_clipboard()**
3040 Insert the contents of the clipboard at the cursor, or if
3041 pending delete is on, replace the primary selection with the contents of the
3044 **previous_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3045 Moves the cursor and scroll backward one page.
3046 The parameter "stutter" moves the cursor to the top of the display,
3047 unless it is already there, otherwise it will page up.
3048 The parameter "column" will maintain the preferred column while
3052 Same as secondary_or_drag_start for compatibility with previous versions.
3054 **process_cancel()**
3055 Cancels the current extend_adjust, secondary_adjust, or
3056 secondary_or_drag_adjust in progress.
3058 **process_down( ["nobell", "absolute"] )**
3059 Moves the cursor down one line. If "absolute" is given, always moves to the
3060 next line in the text buffer, regardless of wrapping.
3062 **process_return()**
3063 Same as newline for compatibility with previous versions.
3065 **process_shift_down( ["nobell", "absolute"] )**
3066 Same as process_down("extend") for compatibility with previous versions.
3068 **process_shift_up( ["nobell", "absolute"] )**
3069 Same as process_up("extend") for compatibility with previous versions.
3072 If tab emulation is turned on, inserts an emulated tab,
3073 otherwise inserts a tab character.
3075 **process_up( ["nobell", "absolute"] )**
3076 Moves the cursor up one line. If "absolute" is given, always moves to the
3077 previous line in the text buffer, regardless of wrapping.
3079 **raise_window([relative-window] | [positive-index] | [negative-index])**
3080 Raise the current focused window to the front if no argument is supplied.
3081 Arguments can be specified in the form of a relative-window
3082 ("first", "last", "next", "previous"), a positive-index
3083 (numbers greater than 0, 1 is the same as "last") or a
3084 negative-index (numbers less than 0, -1 is the same as "first").
3086 **scroll_down(nLines)**
3087 Scroll the display down (towards the end of the file) by nLines.
3089 **scroll_left( nPixels )**
3090 Scroll the display left by nPixels.
3092 **scroll_right( nPixels )**
3093 Scroll the display right by nPixels.
3095 **scroll_up( nLines )**
3096 Scroll the display up (towards the beginning of the file) by nLines.
3098 **scroll_to_line( lineNum )**
3099 Scroll to position line number lineNum at the top of
3100 the pane. The first line of a file is line 1.
3102 **secondary_adjust()**
3103 Attached mouse-movement events to extend the secondary
3104 selection to the mouse position.
3106 **secondary_or_drag_adjust()**
3107 Attached mouse-movement events to extend the
3108 secondary selection, or reposition the primary text being dragged. Takes two
3109 optional arguments, "copy", and "overlay". "copy" leaves a copy of the
3110 dragged text at the site at which the drag began. "overlay" does the drag in
3111 overlay mode, meaning the dragged text is laid on top of the existing text,
3112 obscuring and ultimately deleting it when the drag is complete.
3114 **secondary_or_drag_start()**
3115 To be attached to a mouse down event. Begins drag
3116 selecting a secondary selection, or dragging the contents of the primary
3117 selection, depending on whether the mouse is pressed inside of an existing
3120 **secondary_start()**
3121 To be attached to a mouse down event. Begin drag selecting
3122 a secondary selection.
3125 Select the entire file.
3128 To be attached to a key-press event, inserts the character
3129 equivalent of the key pressed.
3131 ----------------------------------------------------------------------
3139 NEdit can be customized many different ways. The most important
3140 user-settable options are presented in the Preferences menu, including all
3141 options that users might need to change during an editing session. Options
3142 set in the Default Settings sub-menu of the Preferences menu can be preserved
3143 between sessions by selecting Save Defaults, which writes the changes to the
3144 preferences file. See the section titled "Preferences_" for more details.
3146 User defined commands can be added to NEdit's Shell, Macro, and window
3147 background menus. Dialogs for creating items in these menus can be found
3148 under Customize Menus in the Default Settings sub menu of the Preferences
3151 For users who depend on NEdit every day and want to tune every excruciating
3152 detail, there are also X resources for tuning a vast number of such details,
3153 down to the color of each individual button. See the section "X_Resources_"
3154 for more information, as well as a list of selected resources.
3156 The most common reason customizing your X resources for NEdit, however, is
3157 key binding. While limited key binding can be done through Preferences
3158 settings (Preferences -> Default Settings -> Customize Menus), you can really
3159 only add keys this way, and each key must have a corresponding menu item.
3160 Any significant changes to key binding should be made via the Translations
3161 resource and menu accelerator resources. The sections titled "Key_Binding_"
3162 and "X_Resources_" have more information.
3163 ----------------------------------------------------------------------
3168 The Preferences menu allows you to set options for both the current editing
3169 window, and default values for newly created windows and future NEdit
3170 sessions. Options in the Preferences menu itself (not in the Default
3171 Settings sub-menu) take effect immediately and refer to the current window
3172 only. Options in the Default Settings sub-menu provide initial settings for
3173 future windows created using the New or Open commands; options affecting all
3174 windows are also set here.
3175 Preferences set in the Default Settings sub-menu can be saved in a file that
3176 is automatically read by NEdit at startup time, by selecting Save Defaults.
3180 **Default Settings**
3181 Menu of initial settings for future windows. Generally the same as the
3182 options in the main part of the menu, but apply as defaults for future
3183 windows created during this NEdit session. These settings can be saved using
3184 the Save Defaults command below, to be loaded automatically each time NEdit
3188 Save the default options as set under Default Settings for future NEdit
3192 Show the full file name, line number, and length of the file being edited.
3194 **Incremental Search Line**
3195 Keep the incremental search bar (Search -> Find Incremental) permanently
3196 displayed at the top of the window.
3198 **Show Line Numbers**
3199 Display line numbers to the right of the text.
3202 Tells NEdit what language (if any) to assume, for selecting language-specific
3203 features such as highlight patterns and smart indent macros, and setting
3204 language specific preferences like word delimiters, tab emulation, and
3205 auto-indent. See Features for Programming -> Programming_with_NEdit_ for
3209 Setting Auto Indent "on" maintains a running indent (pressing the Return key
3210 will line up the cursor with the indent level of the previous line). If
3211 smart indent macros are available for the current language mode, smart indent
3212 can be selected and NEdit will attempt to guess proper language indentation
3213 for each new line. See Help -> Features for Programming -> Automatic Indent
3214 for more information.
3217 Choose between two styles of automatic wrapping or none. Auto Newline wrap,
3218 wraps text at word boundaries when the cursor reaches the right margin, by
3219 replacing the space or tab at the last word boundary with a newline
3220 character. Continuous Wrap wraps long lines which extend past the right
3221 margin. Continuous Wrap mode is typically used to produce files where
3222 newlines are omitted within paragraphs, to make text filling automatic (a
3223 kind of poor-man's word processor). Text of this style is common on Macs and
3224 PCs but is not necessarily supported very well under Unix (except in programs
3225 which deal with e-mail, for which it is often the format of choice).
3228 Set margin for Auto Newline Wrap, Continuous Wrap, and Fill Paragraph. Lines
3229 may, be wrapped at the right margin of the window, or the margin can be set
3230 at a specific column.
3233 Set the tab distance (number of characters between tab stops) for tab
3234 characters, and control tab emulation and use of tab characters in padding
3238 Change the font(s) used to display text (fonts for menus and dialogs must be
3239 set using X resources for the text area of the window). See below for more
3242 **Highlight Syntax**
3243 If NEdit recognizes the language being edited, and highlighting patterns are
3244 available for that language, use fonts and colors to enhance viewing of the
3245 file. (See Help -> Features for Programming -> Syntax Highlighting for more
3248 **Make Backup Copy**
3249 On Save, write a backup copy of the file as it existed before the Save
3250 command with the extension .bck (Unix only).
3252 **Incremental Backup**
3253 Periodically make a backup copy of the file being edited under the name
3254 `~filename` on Unix or `_filename` on VMS (see Crash_Recovery_).
3256 **Show Matching (..)**
3257 Momentarily highlight matching parenthesis, brackets, and braces, or the
3258 range between them, when one of these characters is typed, or when the
3259 insertion cursor is positioned after it. Delimiter only highlights the
3260 matching delimiter, while Range highlights the whole range of text between
3261 the matching delimiters.
3263 Optionally, the matching can make use of syntax information if syntax
3264 highlighting is enabled. Alternatively, the matching is purely character
3265 based. In general, syntax based matching results in fewer false matches.
3268 In overtype mode, new characters entered replace the characters in front of
3269 the insertion cursor, rather than being inserted before them.
3272 Lock the file against accidental modification. This temporarily prevents the
3273 file from being modified in this NEdit session. Note that this is different
3274 from setting the file protection.
3276 3>Preferences -> Default Settings Menu
3278 Options in the Preferences -> Default Settings menu have the same meaning as
3279 those in the top-level Preferences menu, except that they apply to future
3280 NEdit windows and future NEdit sessions if saved with the Save Defaults
3281 command. Additional options which appear in this menu are:
3284 Define language recognition information (for determining language mode from
3285 file name or content) and set language specific preferences.
3288 How to react to multiple tags for the same name. Tags are described in the
3289 section: Features for Programmers -> Finding Declarations (ctags). In Show
3290 All mode, all matching tags are displayed in a dialog. In Smart mode, if one
3291 of the matching tags is in the current window, that tag is chosen, without
3292 displaying the dialog.
3295 Add/remove items from the Shell, Macro, and window background menus (see
3298 **Customize Window Title**
3299 Opens a dialog where the information to be displayed in the windows's title
3300 field can be defined and tested. The dialog contains a Help button, providing
3301 further information about the options available.
3304 Options for controlling the behavior of Find and Replace commands:
3307 Presents search results in dialog form, asks before wrapping a
3308 search back around the beginning (or end) of the file
3309 (unless Beep On Search Wrap is turned on).
3312 Search and Replace operations wrap around the beginning (or end) of the file.
3314 ~Beep On Search Wrap~ -
3315 Beep when Search and Replace operations wrap around the beginning (or end) of
3316 the file (only if Wrap Around is turned on).
3319 Don't pop down Replace and Find boxes after searching.
3321 ~Default Search Style~ -
3322 Initial setting for search type in Find and Replace dialogs.
3324 ~Default Replace Scope~ -
3325 [THIS OPTION IS ONLY PRESENT WHEN NEDIT WAS COMPILED WITH THE
3326 -DREPLACE_SCOPE FLAG TO SELECT AN ALTERNATIVE REPLACE DIALOG LAYOUT.]
3328 Initial setting for the scope in the Replace/Find dialog, when a selection
3329 exists. It can be either "In Window", "In Selection", or "Smart". "Smart"
3330 results in "In Window" if the size of the selection is smaller than 1 line,
3331 and to "In Selection" otherwise.
3333 **Syntax Highlighting**
3334 Program and configure enhanced text display for new or supported languages
3335 (See Features for Programming -> Syntax_Highlighting_).
3337 **Append Line Feed on Save**
3338 Some UNIX tools expect that files end with a line feed. If this option is
3339 activated, NEdit will append one if required.
3341 **Sort Open Prev. Menu**
3342 Option to order the File -> Open Previous menu alphabetically, versus in
3343 order of last access.
3345 **Popups Under Pointer**
3346 Display pop-up dialogs centered on the current mouse position, as opposed to
3347 centered on the parent window. This generally speeds interaction, and is
3348 essential for users who users who set their window managers so keyboard focus
3351 **Modification Warnings**
3352 Pop up a warning dialog when files get changed external to NEdit.
3355 Ask before exiting when two or more files are open in an NEdit session.
3357 **Initial Window Size**
3358 Default size for new windows.
3362 The font used to display text in NEdit is set under Preferences -> Text Font
3363 (for the current window), or Preferences -> Default Settings Text Font (for
3364 future windows). These dialogs also allow you to set fonts for syntax
3365 highlighting. If you don't intend to use syntax highlighting, you can ignore
3366 most of the dialog, and just set the field labeled Primary Font.
3368 Unless you are absolutely certain about the types of files that you will be
3369 editing with NEdit, you should choose a fixed-spacing font. Many, if not
3370 most, plain-text files are written expecting to be viewed with fixed
3371 character spacing, and will look wrong with proportional spacing. NEdit's
3372 filling, wrapping, and rectangular operations will also work strangely if you
3373 choose a proportional font.
3375 Note that in the font browser (the dialog brought up by the Browse...
3376 button), the subset of fonts which are shown is narrowed depending on the
3377 characteristics already selected. It is therefore important to know that you
3378 can unselect characteristics from the lists by clicking on the selected items
3381 Fonts for syntax highlighting should ideally match the primary font in both
3382 height and spacing. A mismatch in spacing will result in similar distortions
3383 as choosing a proportional font: column alignment will sometimes look wrong,
3384 and rectangular operations, wrapping, and filling will behave strangely. A
3385 mismatch in height will cause windows to re-size themselves slightly when
3386 syntax highlighting is turned on or off, and increase the inter- line spacing
3387 of the text. Unfortunately, on some systems it is hard to find sets of fonts
3388 which match exactly in height.
3392 You can add or change items in the Shell, Macro, and window background menus
3393 under Preferences -> Default Settings -> Customize Menus. When you choose
3394 one of these, you will see a dialog with a list of the current
3395 user-configurable items from the menu on the left. To change an existing
3396 item, select it from the list, and its properties will appear in the
3397 remaining fields of the dialog, where you may change them. Selecting the
3398 item "New" from the list allows you to enter new items in the menu.
3400 Hopefully most of the characteristics are self explanatory, but here are a
3403 Accelerator keys are keyboard shortcuts which appear on the right hand side
3404 of the menus, and allow you avoid pulling down the menu and activate the
3405 command with a single keystroke. Enter accelerators by typing the keys
3406 exactly as you would to activate the command.
3408 Mnemonics are a single letter which should be part of the menu item name,
3409 which allow users to traverse and activate menu items by typing keys when the
3410 menu is pulled down.
3412 In the Shell Command field of the Shell Commands dialog, the % character
3413 expands to the name (including directory path) of the file in the window. To
3414 include a % character in the command, use %%.
3416 The Menu Entry field can contain special characters for constructing
3417 hierarchical sub-menus, and for making items which appear only in certain
3418 language modes. The right angle bracket character ">" creates a sub-menu.
3419 The name of the item itself should be the last element of the path formed
3420 from successive sub-menu names joined with ">". Menu panes are called in to
3421 existence simply by naming them as part of a Menu Entry name. To put several
3422 items in the same sub-menu, repeat the same hierarchical sequence for each.
3423 For example, in the Macro Commands dialog, two items with menu entries: a>b>c
3424 and a>b>d would create a single sub menu under the macro menu called "a",
3425 which would contain a single sub-menu, b, holding the actual items, c and d:
3432 To qualify a menu entry with a language mode, simply add an at-sign "@@" at
3433 the end of the menu command, followed (no space) by a language mode name. To
3434 make a menu item which appears in several language modes, append additional
3435 @@s and language mode names. For example, an item with the menu entry:
3437 Make C Prototypes@@C@@C++
3439 would appear only in C and C++ language modes, and:
3441 Make Class Template@@C++
3443 would appear only in C++ mode.
3445 Menu items with no qualification appear in all language modes.
3447 If a menu item is followed by the single language qualification "@@*", that
3448 item will appear only if there are no applicable language-specific items of
3449 the same name in the same submenu. For example, if you have the following
3450 three entries in the same menu:
3452 Make Prototypes@@C@@C++
3453 Make Prototypes@@Java
3456 The first will be available when the language mode is C or C++, the second
3457 when the language mode is Java, and for all other language modes (including
3458 the "Plain" non-language mode). If the entry:
3462 also exists, this will always appear, meaning that the menu will always have
3463 two "Make Prototypes" entries, whatever the language mode.
3465 3>The NEdit Preferences File
3467 The NEdit saved preferences file is an X resource file, and its contents can
3468 be moved into another X resource file (see X_Resources_). One reason for
3469 doing so would be to attach server specific preferences, such as a default
3470 font to a particular X server. Another reason for moving preferences into the
3471 X resource file would be to keep preferences menu options and resource
3472 settable options together in one place.
3473 Though the files are the same format, additional resources should not be added
3474 to the preference file since NEdit modifies this file by overwriting it
3475 completely. Note also that the contents of the preference file take
3476 precedence over the values of X resources.
3477 Using Save Defaults after moving the contents of your preference file to your
3478 .Xdefaults file will re-create the preference file, interfering with the
3479 options that you have moved.
3480 The location of NEdit's preferences file depends on your environment:
3482 * The default place for the file is '$HOME/.nedit/nedit.rc',
3483 * if the variable $NEDIT_HOME is set in your environment it is located at '$NEDIT_HOME/nedit.rc',
3484 * you may also use old-style run control files; in this case, the preferences are stored in $HOME/.nedit.
3486 (For VMS, the file is in '$NEDIT_HOME/nedit.rc' if $NEDIT_HOME is set, in
3487 'SYS$LOGIN:.nedit' otherwise.)
3489 3>Sharing Customizations with Other NEdit Users
3491 If you have written macro or shell menu commands, highlight patterns, or
3492 smart-indent macros that you want to share with other NEdit users, you can
3493 make a file which they can load into their NEdit environment.
3495 To load such a file, start NEdit with the command:
3497 nedit -import <file>
3499 In the new NEdit session, verify that the imported patterns or macros do what
3500 you want, then select Preferences -> Save Defaults. Saving incorporates the
3501 changes into the nedit preferences file, so the next time you run NEdit, you
3502 will not have to import the distribution file.
3504 Loading a customization file is automated, but creating one is not. To
3505 produce a file to be imported by other users, you must make a copy of your own
3506 NEdit configuration file, and edit it, by hand, to remove everything but the
3507 few items of interest to the recipient. Leave only the individual
3508 resource(s), and within those resources, only the particular macro, pattern,
3509 style, etc, that you wish to exchange.
3511 For example, to share a highlighting pattern set, you would include the
3512 patterns, any new styles you added, and language mode information only if the
3513 patterns are intended to support a new language rather than updating an
3514 existing one. For example:
3516 nedit.highlightPatterns:\
3518 Comment:"#":"$"::Comment::\n\
3519 Loop Header:"^[ \\t]*loop:":::Loop::\n\
3521 nedit.languageModes: My Language:.my::::::
3522 nedit.styles: Loop:blue:Bold
3524 Resources are in the format of X resource files, but the format of text
3525 within multiple-item resources like highlight patterns, language modes,
3526 macros, styles, etc., are private to NEdit. Each resource is a string which
3527 ends at the first newline character not escaped with \, so you must be
3528 careful about how you treat ends of lines. While you can generally just cut
3529 and paste indented sections, if something which was originally in the middle
3530 of a resource string is now at the end, you must remove the \ line
3531 continuation character(s) so it will not join the next line into the
3532 resource. Conversely, if something which was originally at the end of a
3533 resource is now in the middle, you'll have to add continuation character(s)
3534 to make sure that the resource string is properly continued from beginning to
3535 end, and possibly newline character(s) (\n) to make sure that it is properly
3536 separated from the next item.
3537 ----------------------------------------------------------------------
3542 NEdit has additional options to those provided in the Preferences menu which
3543 are set using X resources. Like most other X programs, NEdit can be
3544 customized to vastly unnecessary proportions, from initial window positions
3545 down to the font and shadow colors of each individual button (A complete
3546 discussion of how to do this is left to books on the X Windows System). Key
3547 binding (see "Key_Binding_" is one of the most useful of these resource
3550 X resources are usually specified in a file called .Xdefaults or .Xresources
3551 in your home directory (on VMS this is sys$login:decw$xdefaults.dat). On
3552 some systems, this file is read and its information attached to the X server
3553 (your screen) when you start X. On other systems, the .Xdefaults file is
3554 read each time you run an X program. When X resource values are attached to
3555 the X server, changes to the resource file are not available to application
3556 programs until you either run the xrdb program with the appropriate file as
3557 input, or re-start the X server.
3559 3>Selected X Resource Names
3561 The following are selected NEdit resource names and default values for NEdit
3562 options not settable via the Preferences menu (for preference resource names,
3563 see your NEdit preference file):
3565 **nedit.tagFile**: (not defined)
3567 This can be the name of a file, or multiple files separated by a colon (:)
3568 character, of the type produced by Exuberant Ctags or the Unix ctags
3569 command, which NEdit will load at startup time (see ctag_support_ ). The tag
3570 file provides a database from which NEdit can automatically open files
3571 containing the definition of a particular subroutine or data type.
3573 **nedit.alwaysCheckRelativeTagsSpecs: True**
3575 When this resource is set to True, and there are tag files specified (with
3576 the nedit.tagFile resource, see above) as relative paths, NEdit will evaluate
3577 these tag value paths whenever a file is opened. All accessible tag files
3578 will be loaded at this time. When this resource value is False, relative path
3579 tag specifications will only be evaluated at NEdit startup time.
3581 **nedit.shell**: /bin/csh
3583 (Unix systems only) The Unix shell (command interpreter) to use for executing
3584 commands from the Shell menu
3586 **nedit.wordDelimiters**: .,/\\`'!@@#%^&*()-=+{}[]":;<>?
3588 The characters, in addition to blanks and tabs, which mark the boundaries
3589 between words for the move-by-word (Ctrl+Arrow) and select-word (double
3590 click) commands. Note that this default value may be overridden by the
3591 setting in Preferences -> Default Settings -> Language Modes....
3593 **nedit.remapDeleteKey**: False
3595 Setting this resource to True forcibly maps the delete key to backspace. This
3596 can be helpful on systems where the bindings have become tangled, and in
3597 environments which mix systems with PC style keyboards and systems with DEC
3598 and Macintosh keyboards. Theoretically, these bindings should be made using
3599 the standard X/Motif mechanisms, outside of NEdit. In practice, some
3600 environments where users access several different systems remotely, can be
3601 very hard to configure. If you've given up and are using a backspace key
3602 halfway off the keyboard because you can't figure out the bindings, set this
3605 **nedit.typingHidesPointer**: False
3607 Setting this resource to True causes the mouse pointer to be hidden when you
3608 type in the text area. As soon as the mouse pointer is moved, it will
3609 reappear. This is useful to stop the mouse pointer from obscuring text.
3611 **nedit.overrideDefaultVirtualKeyBindings**: Auto
3613 Motif uses a virtual key binding mechanism that shares the bindings between
3614 different Motif applications. When a first Motif application is started, it
3615 installs some default virtual key bindings and any other Motif application
3616 that runs afterwards, simply reuses them. Obviously, if the first
3617 application installs an invalid set, all others applications may have
3620 In the past, NEdit has been the victim of invalid bindings installed by other
3621 applications several times. Through this resource, NEdit can be instructed
3622 to ignore the bindings installed by other applications, and use its own
3623 private bindings. By default, NEdit tries to detect invalid bindings
3624 and ignore them automatically (Auto). Optionally, NEdit can be told to
3625 always keep the installed bindings (Never), or to always override them
3628 **nedit.stdOpenDialog**: False
3630 Setting this resource to True restores the standard Motif style of Open
3631 dialog. NEdit file open dialogs are missing a text field at the bottom of
3632 the dialog, where the file name can be entered as a string. The field is
3633 removed in NEdit to encourage users to type file names in the list, a
3634 non-standard, but much faster method for finding files.
3636 **nedit.bgMenuButton**: @~Shift@~Ctrl@~Meta@~Alt<Btn3Down>
3638 Specification for mouse button / key combination to post the background menu
3639 (in the form of an X translation table event specification). The event
3640 specification should be as specific as possible, since it will override less
3641 specific translation table entries.
3643 **nedit.maxPrevOpenFiles**: 30
3645 Number of files listed in the Open Previous sub-menu of the File menu.
3646 Setting this to zero disables the Open Previous menu item and maintenance of
3647 the NEdit file history file.
3649 **nedit.printCommand**: (system specific)
3651 Command used by the print dialog to print a file, such as, lp, lpr, etc..
3652 The command must be capable of accepting input via stdin (standard input).
3654 **nedit.printCopiesOption**: (system specific)
3656 Option name used to specify multiple copies to the print command. If the
3657 option should be separated from its argument by a space, leave a trailing
3658 space. If blank, no "Number of Copies" item will appear in the print dialog.
3660 **nedit.printQueueOption**: (system specific)
3662 Option name used to specify a print queue to the print command. If the
3663 option should be separated from its argument by a space, leave a trailing
3664 space. If blank, no "Queue" item will appear in the print dialog.
3666 **nedit.printNameOption**: (system specific)
3668 Option name used to specify a job name to the print command. If the option
3669 should be separated from its argument by a space, leave a trailing space. If
3670 blank, no job or file name will be attached to the print job or banner page.
3672 **nedit.printHostOption**: (system specific)
3674 Option name used to specify a host name to the print command. If the option
3675 should be separated from its argument by a space, leave a trailing space. If
3676 blank, no "Host" item will appear in the print dialog.
3678 **nedit.printDefaultQueue**: (system specific)
3680 The name of the default print queue. Used only to display in the print
3681 dialog, and has no effect on printing.
3683 **nedit.visualID**: Best
3685 If your screen supports multiple visuals (color mapping models), this
3686 resource allows you to manually choose among them. The default value of
3687 "Best" chooses the deepest (most colors) visual available. Since NEdit does
3688 not depend on the specific characteristics of any given color model, Best
3689 probably IS the best choice for everyone, and the only reason for setting
3690 this resource would be to patch around some kind of X server problem. The
3691 resource may also be set to "Default", which chooses the screen's default
3692 visual (often a color-mapped, PseudoColor, visual for compatibility with
3693 older X applications). It may also be set to a numeric visual-id value (use
3694 xdpyinfo to see the list of visuals supported by your display), or a visual
3695 class name: PseudoColor, DirectColor, TrueColor, etc..
3697 If you are running under a themed environment (like KDE or CDE) that places
3698 its colors in a shallow visual, and you'd rather have that color scheme
3699 instead of more colors available, then you may need set the visual to
3700 "Default" so that NEdit doesn't choose one with more colors. (The reason
3701 for this is: if the "best" visual is not the server's default, then NEdit
3702 cannot use the colors provided by your environment. NEdit will fall back to
3703 its own default color scheme.)
3705 **nedit.installColormap**: False
3707 Force the installation of a private colormap. If you have a humble 8-bit
3708 color display, and netscape is hogging all of the color cells, you may want
3709 to try turning this on. On most systems, this will result in colors flashing
3710 wildly when you switch between NEdit and other applications. But a few
3711 systems (SGI) have hardware support for multiple simultaneous colormaps, and
3712 applications with installed colormaps are well behaved.
3714 **nedit.findReplaceUsesSelection**: False
3716 Controls if the Find and Replace dialogs are automatically loaded with the
3717 contents of the primary selection.
3719 **nedit.stickyCaseSenseButton**: True
3721 Controls if the "Case Sensitive" buttons in the Find and Replace dialogs and
3722 the incremental search bar maintain a separate state for literal and regular
3723 expression searches. Moreover, when set to True, by default literal searches
3724 are case insensitive and regular expression searches are case sensitive. When
3725 set to False, the "Case Sensitive" buttons are independent of the "Regular
3728 **nedit.printDefaultHost**: (system specific)
3730 The node name of the default print host. Used only to display in the print
3731 dialog, and has no effect on printing.
3733 **nedit.multiClickTime**: (system specific)
3735 Maximum time in milliseconds allowed between mouse clicks within double and
3736 triple click actions.
3738 **nedit@*scrollBarPlacement**: BOTTOM_LEFT
3740 How scroll bars are placed in NEdit windows, as well as various lists and
3741 text fields in the program. Other choices are: BOTTOM_RIGHT, TOP_LEFT, or
3744 **nedit@*text.autoWrapPastedText**: False
3746 When Auto Newline Wrap is turned on, apply automatic wrapping (which
3747 normally only applies to typed text) to pasted text as well.
3749 **nedit@*text.foreground**: black
3751 Foreground color of the text editing area of the NEdit window.
3753 **nedit@*text.background**: white
3755 Background color of the text editing area of the NEdit window.
3757 **nedit@*text.selectForeground**: black
3759 Foreground (text) color for selections in the text editing area of the NEdit
3762 **nedit@*text.selectBackground**: gray80
3764 Color for selections in the text editing area of the NEdit window.
3766 **nedit@*text.highlightForeground**: white
3768 Foreground (text) color for highlights (parenthesis flashing) in the text
3769 editing area of the NEdit window.
3771 **nedit@*text.highlightBackground**: red
3773 Color for highlights (parenthesis flashing) in the text editing area of the
3776 **nedit@*text.cursorForeground**: black
3778 Color for text cursor in the text editing area of the NEdit window.
3780 **nedit@*text.lineNumForeground**: gray47
3782 Color for displaying line numbers in the NEdit window.
3784 **nedit@*text.heavyCursor**: False
3786 For monitors with poor resolution or users who have difficulty seeing the
3787 cursor, makes the cursor in the text editing area of the window heavier and
3790 **nedit@*text.cursorVPadding**: 0
3792 Number of lines to keep the cursor away from the top or bottom line of the
3793 window. Keyboard operations that would cause the cursor to get closer than
3794 this distance cause the window to scroll up or down instead, except at the
3795 beginning of the file. Mouse operations are not affected.
3797 **nedit@*text.blinkRate**: 500
3799 Blink rate of the text insertion cursor in milliseconds. Set to zero to stop
3802 **nedit@*text.Translations**:
3804 Modifies key bindings (see below).
3806 **nedit@*foreground**: black
3808 Default foreground color for menus, dialogs, scroll bars, etc..
3810 **nedit@*background**: #b3b3b3
3812 Default background color for menus, dialogs, scroll bars, etc..
3814 **nedit@*fontList**: helvetica medium 12 points
3816 Default font for menus, dialogs, scroll bars, etc..
3818 **nedit.helpFont**: helvetica medium 12 points
3820 Font used for displaying online help.
3822 **nedit.boldHelpFont**: helvetica bold 12 points
3824 Bold font for online help.
3826 **nedit.italicHelpFont**: helvetica italic 12 points
3828 Italic font for online help.
3830 **nedit.fixedHelpFont**: courier medium 12 points
3832 Fixed font for online help.
3834 **nedit.boldFixedHelpFont**: courier bold 12 points
3836 Fixed bold for online help.
3838 **nedit.italicFixedHelpFont**: courier italic 12 points
3840 Fixed italic font for online help.
3842 **nedit.h1HelpFont**: helvetica bold 14 points
3844 Font for level-1 titles in help text.
3846 **nedit.h2HelpFont**: helvetica bold italic 12 points
3848 Font for level-2 titles in help text.
3850 **nedit.h3HelpFont**: courier bold 12 points
3852 Font for level-3 titles in help text.
3854 **nedit.helpLinkFont**: helvetica medium 12 points
3856 Font for hyperlinks in the help text
3858 **nedit.helpLinkColor**: #009900
3860 Color for hyperlinks in the help text
3862 **nc.autoStart**: True
3864 Whether the nc program should automatically start an NEdit server (without
3865 prompting the user) if an appropriate server is not found.
3867 **nc.serverCommand**: nedit -server
3869 Command used by the nc program to start an NEdit server.
3871 ----------------------------------------------------------------------
3872 ~The following are Selected widget names (to which you may append~
3873 ~.background, .foreground, .fontList, etc., to change colors, fonts~
3874 ~ and other characteristics):~
3876 **nedit@*statsAreaForm**
3878 Statistics line and incremental search bar. To get consistent results across
3879 the entire stats line and the incremental search bar, use '*' rather than '.'
3880 to separate the resource name. For example, to set the foreground color of
3881 both components use:
3882 nedit*statsAreaForm*foreground
3884 nedit*statsAreaForm.foreground
3888 Top-of-window menu-bar.
3890 **nedit@*textHorScrollBar**
3892 Horizontal scroll bar.
3894 **nedit@*textVertScrollBar**
3896 Vertical scroll bar.
3901 ----------------------------------------------------------------------
3906 There are several ways to change key bindings in NEdit. The easiest way to
3907 add a new key binding in NEdit is to define a macro in Preferences -> Default
3908 Settings -> Customize Menus -> Macro Menu. However, if you want to change
3909 existing bindings or add a significant number of new key bindings you will
3910 need to do so via X resources.
3912 Before reading this section, you must understand how to set X resources (see
3913 the help section "X_Resources_"). Since setting X resources is tricky, it is
3914 also helpful when working on key-binding, to set some easier-to-verify
3915 resource at the same time, as a simple check that the NEdit program is
3916 actually seeing your changes. The appres program is also very helpful in
3917 checking that the resource settings that you make, actually reach the program
3918 for which they are intended in the correct form.
3920 3>Key Binding in General
3922 Keyboard commands are associated with editor action routines through two
3923 separate mechanisms in NEdit. Commands which appear in pull-down menus have
3924 individual resources designating a keyboard equivalent to the menu command,
3925 called an accelerator key. Commands which do not have an associated menu
3926 item are bound to keys via the X toolkit translation mechanism. The methods
3927 for changing these two kinds of bindings are quite different.
3929 3>Key Binding Via Translations
3931 The most general way to bind actions to keys in NEdit is to use the
3932 translation table associated with the text widget. To add a binding to Alt+Y
3933 to insert the string "Hi!", for example, add lines similar to the following
3934 to your X resource file:
3936 NEdit*text.Translations: #override \n\
3937 Alt<Key>y: insert_string("Hi!") \n
3939 The Help topic "Action_Routines_" lists the actions available to be bound.
3941 Translation tables map key and mouse presses, window operations, and other
3942 kinds of events, to actions. The syntax for translation tables is
3943 simplified here, so you may need to refer to a book on the X window system
3944 for more detailed information.
3946 Note that accelerator resources (discussed below) override translations, and
3947 that most Ctrl+letter and Alt+letter combinations are already bound to an
3948 accelerator key. To use one of these combinations from a translation table,
3949 therefore, you must first un-bind the original menu accelerator.
3951 A resource for changing a translation table consists of a keyword; #override,
3952 #augment, or #replace; followed by lines (separated by newline characters)
3953 pairing events with actions. Events begin with modifiers, like Ctrl, Shift,
3954 or Alt, followed by the event type in <>. BtnDown, Btn1Down, Btn2Down,
3955 Btn1Up, Key, KeyUp are valid event types. For key presses, the event type is
3956 followed by the name of the key. You can specify a combination of events,
3957 such as a sequence of key presses, by separating them with commas. The other
3958 half of the event/action pair is a set of actions. These are separated from
3959 the event specification by a colon and from each other by spaces. Actions
3960 are names followed by parentheses, optionally containing one or more
3961 parameters separated by comas.
3963 3>Changing Menu Accelerator Keys
3965 The menu shortcut keys shown at the right of NEdit menu items can also be
3966 changed via X resources. Each menu item has two resources associated with
3967 it, accelerator, the event to trigger the menu item; and acceleratorText, the
3968 string shown in the menu. The form of the accelerator resource is the same
3969 as events for translation table entries discussed above, though multiple keys
3970 and other subtleties are not allowed. The resource name for a menu is the
3971 title in lower case, followed by "Menu", the resource name of menu item is
3972 the name in lower case, run together, with words separated by caps, and all
3973 punctuation removed. For example, to change Cut to Ctrl+X, you would add the
3974 following to your .Xdefaults file:
3976 nedit*editMenu.cut.accelerator: Ctrl<Key>x
3977 nedit*editMenu.cut.acceleratorText: Ctrl+X
3979 Accelerator keys with optional shift key modifiers, like Find..., have an
3980 additional accelerator resource with Shift appended to the name. For
3983 nedit*searchMenu.find.acceleratorText: [Shift]Alt+F
3984 nedit*searchMenu.find.accelerator: Alt<Key>f
3985 nedit*searchMenu.findShift.accelerator: Shift Alt<Key>f
3986 ----------------------------------------------------------------------
3988 Highlighting Patterns
3989 ---------------------
3991 3>Writing Syntax Highlighting Patterns
3993 Patterns are the mechanism by which language syntax highlighting is
3994 implemented in NEdit (see Syntax_Highlighting_ under the heading of Features
3995 for Programming). To create syntax highlighting patterns for a new
3996 language, or to modify existing patterns, select "Recognition Patterns" from
3997 "Syntax Highlighting" sub-section of the "Default Settings" sub-menu of the
4000 First, a word of caution. As with regular expression matching in general, it
4001 is quite possible to write patterns which are so inefficient that they
4002 essentially lock up the editor as they recursively re-examine the entire
4003 contents of the file thousands of times. With the multiplicity of patterns,
4004 the possibility of a lock-up is significantly increased in syntax
4005 highlighting. When working on highlighting patterns, be sure to save your
4008 NEdit's syntax highlighting is unusual in that it works in real-time (as you
4009 type), and yet is completely programmable using standard regular expression
4010 notation. Other syntax highlighting editors usually fall either into the
4011 category of fully programmable but unable to keep up in real-time, or
4012 real-time but limited programmability. The additional burden that NEdit
4013 places on pattern writers in order to achieve this speed/flexibility mix, is
4014 to force them to state self-imposed limitations on the amount of context that
4015 patterns may examine when re-parsing after a change. While the "Pattern
4016 Context Requirements" heading is near the end of this section, it is not
4017 optional, and must be understood before making any any serious effort at
4020 In its simplest form, a highlight pattern consists of a regular expression to
4021 match, along with a style representing the font an color for displaying any
4022 text which matches that expression. To bold the word, "highlight", wherever
4023 it appears the text, the regular expression simply would be the word
4024 "highlight". The style (selected from the menu under the heading of
4025 "Highlight Style") determines how the text will be drawn. To bold the text,
4026 either select an existing style, such as "Keyword", which bolds text, or
4027 create a new style and select it under Highlight Style.
4029 The full range of regular expression capabilities can be applied in such a
4030 pattern, with the single caveat that the expression must conclusively match
4031 or not match, within the pre-defined context distance (as discussed below
4032 under Pattern Context Requirements).
4034 To match longer ranges of text, particularly any constructs which exceed the
4035 requested context, you must use a pattern which highlights text between a
4036 starting and ending regular expression match. To do so, select "Highlight
4037 text between starting and ending REs" under "Matching", and enter both a
4038 starting and ending regular expression. For example, to highlight everything
4039 between double quotes, you would enter a double quote character in both the
4040 starting and ending regular expression fields. Patterns with both a
4041 beginning and ending expression span all characters between the two
4042 expressions, including newlines.
4044 Again, the limitation for automatic parsing to operate properly is that both
4045 expressions must match within the context distance stated for the pattern
4048 With the ability to span large distances, comes the responsibility to recover
4049 when things go wrong. Remember that syntax highlighting is called upon to
4050 parse incorrect or incomplete syntax as often as correct syntax. To stop a
4051 pattern short of matching its end expression, you can specify an error
4052 expression, which stops the pattern from gobbling up more than it should.
4053 For example, if the text between double quotes shouldn't contain newlines,
4054 the error expression might be "$". As with both starting and ending
4055 expressions, error expressions must also match within the requested context
4058 4>Coloring Sub-Expressions
4060 It is also possible to color areas of text within a regular expression
4061 match. A pattern of this type associates a style with sub-expressions
4062 references of the parent pattern (as used in regular expression substitution
4063 patterns, see the NEdit Help menu item on Regular_Expressions_).
4064 Sub-expressions of both the starting and ending patterns may be colored. For
4065 example, if the parent pattern has a starting expression "\<", and end
4066 expression "\>", (for highlighting all of the text contained within angle
4067 brackets), a sub-pattern using "&" in both the starting and ending expression
4068 fields could color the brackets differently from the intervening text. A
4069 quick shortcut to typing in pattern names in the Parent Pattern field is to
4070 use the middle mouse button to drag them from the Patterns list.
4072 4>Hierarchical Patterns
4074 A hierarchical sub-pattern, is identical to a top level pattern, but is
4075 invoked only between the beginning and ending expression matches of its
4076 parent pattern. Like the sub-expression coloring patterns discussed above,
4077 it is associated with a parent pattern using the Parent Pattern field in the
4078 pattern specification. Pattern names can be dragged from the pattern list
4079 with the middle mouse button to the Parent Pattern field.
4081 After the start expression of the parent pattern matches, the syntax
4082 highlighting parser searches for either the parent's end pattern or a
4083 matching sub-pattern. When a sub-pattern matches, control is not returned to
4084 the parent pattern until the entire sub-pattern has been parsed, regardless
4085 of whether the parent's end pattern appears in the text matched by the
4088 The most common use for this capability is for coloring sub-structure of
4089 language constructs (smaller patterns embedded in larger patterns).
4090 Hierarchical patterns can also simplify parsing by having sub-patterns "hide"
4091 special syntax from parent patterns, such as special escape sequences or
4094 There is no depth limit in nesting hierarchical sub-patterns, but beyond the
4095 third level of nesting, automatic re-parsing will sometimes have to re-parse
4096 more than the requested context distance to guarantee a correct parse (which
4097 can slow down the maximum rate at which the user can type if large sections
4098 of text are matched only by deeply nested patterns).
4100 While this is obviously not a complete hierarchical language parser it is
4101 still useful in many text coloring situations. As a pattern writer, your
4102 goal is not to completely cover the language syntax, but to generate
4103 colorings that are useful to the programmer. Simpler patterns are usually
4104 more efficient and also more robust when applied to incorrect code.
4106 4>Deferred (Pass-2) Parsing
4108 NEdit does pattern matching for syntax highlighting in two passes. The first
4109 pass is applied to the entire file when syntax highlighting is first turned
4110 on, and to new ranges of text when they are initially read or pasted in. The
4111 second pass is applied only as needed when text is exposed (scrolled in to
4114 If you have a particularly complex set of patterns, and parsing is beginning
4115 to add a noticeable delay to opening files or operations which change large
4116 regions of text, you can defer some of that parsing from startup time, to
4117 when it is actually needed for viewing the text. Deferred parsing can only
4118 be used with single expression patterns, or begin/end patterns which match
4119 entirely within the requested context distance. To defer the parsing of a
4120 pattern to when the text is exposed, click on the Pass-2 pattern type button
4121 in the highlight patterns dialog.
4123 Sometimes a pattern can't be deferred, not because of context requirements,
4124 but because it must run concurrently with pass-1 (non-deferred) patterns. If
4125 they didn't run concurrently, a pass-1 pattern might incorrectly match some
4126 of the characters which would normally be hidden inside of a sequence matched
4127 by the deferred pattern. For example, C has character constants enclosed in
4128 single quotes. These typically do not cross line boundaries, meaning they
4129 can be parsed entirely within the context distance of the C pattern set and
4130 should be good candidates for deferred parsing. However, they can't be
4131 deferred because they can contain sequences of characters which can trigger
4132 pass-one patterns. Specifically, the sequence, '\"', contains a double quote
4133 character, which would be matched by the string pattern and interpreted as
4134 introducing a string.
4136 4>Pattern Context Requirements
4138 The context requirements of a pattern set state how much additional text
4139 around any change must be examined to guarantee that the patterns will match
4140 what they are intended to match. Context requirements are a promise by NEdit
4141 to the pattern writer, that the regular expressions in his/her patterns will
4142 be matched against at least <line context> lines and <character context>
4143 characters, around any modified text. Combining line and character
4144 requirements guarantee that both will be met.
4146 Automatic re-parsing happens on EVERY KEYSTROKE, so the amount of context
4147 which must be examined is very critical to typing efficiency. The more
4148 complicated your patterns, the more critical the context becomes. To cover
4149 all of the keywords in a typical language, without affecting the maximum rate
4150 at which users can enter text, you may be limited to just a few lines and/or
4151 a few hundred characters of context.
4153 The default context distance is 1 line, with no minimum character
4154 requirement. There are several benefits to sticking with this default. One
4155 is simply that it is easy to understand and to comply with. Regular
4156 expression notation is designed around single line matching. To span lines
4157 in a regular expression, you must explicitly mention the newline character
4158 "\n", and matches which are restricted to a single line are virtually immune
4159 to lock-ups. Also, if you can code your patterns to work within a single
4160 line of context, without an additional character-range context requirement,
4161 the parser can take advantage the fact that patterns don't cross line
4162 boundaries, and nearly double its efficiency over a one-line and 1-character
4163 context requirement. (In a single line context, you are allowed to match
4164 newlines, but only as the first and/or last character.)
4165 ----------------------------------------------------------------------
4170 Smart indent macros can be written for any language, but are usually more
4171 difficult to write than highlighting patterns. A good place to start, of
4172 course, is to look at the existing macros for C and C++.
4174 Smart indent macros for a language mode consist of standard NEdit macro
4175 language code attached to any or all of the following three activation
4176 conditions: 1) When smart indent is first turned on for a text window
4177 containing code of the language, 2) When a newline is typed and smart indent
4178 is expected, 3) after any character is typed. To attach macro code to any of
4179 these code "hooks", enter it in the appropriate section in the Preferences ->
4180 Default Settings -> Auto Indent -> Program Smart Indent dialog.
4182 Typically most of the code should go in the initialization section, because
4183 that is the appropriate place for subroutine definitions, and smart indent
4184 macros are complicated enough that you are not likely to want to write them
4185 as one monolithic run of code. You may also put code in the Common/Shared
4186 Initialization section (accessible through the button in the upper left
4187 corner of the dialog). Unfortunately, since the C/C++ macros also reside in
4188 the common/shared section, when you add code there, you run some risk of
4189 missing out on future upgrades to these macros, because your changes will
4190 override the built-in defaults.
4192 The newline macro is invoked after the user types a newline, but before the
4193 newline is entered in the buffer. It takes a single argument ($1) which is
4194 the position at which the newline will be inserted. It must return the
4195 number of characters of indentation the line should have, or -1. A return
4196 value of -1 means to do a standard auto-indent. You must supply a newline
4197 macro, but the code: "return -1" (auto-indent), or "return 0" (no indent) is
4200 The type-in macro takes two arguments. $1 is the insert position, and $2 is
4201 the character just inserted, and does not return a value. You can do just
4202 about anything here, but keep in mind that this macro is executed for every
4203 keystroke typed, so if you try to get too fancy, you may degrade performance.
4204 ----------------------------------------------------------------------
4209 .. ? help !!#ifndef VMS
4210 **nedit** [-**read**] [-**create**] [-**line** n | +n] [-**server**]
4211 [-**do** command] [-**tags** file] [-**tabs** n] [-**wrap**]
4212 [-**nowrap**] [-**autowrap**] [-**autoindent**] [-**noautoindent**]
4213 [-**autosave**] [-**noautosave**] [-**rows** n] [-**columns** n]
4214 [-**font** font] [-**lm** languagemode] [-**geometry** geometry]
4215 [-**iconic**] [-**noiconic**] [-**display** [host]:server[.screen]
4216 [-**xrm** resourcestring] [-**svrname** name] [-**import** file]
4217 [-**background** color] [-**foreground** color] [-**V**|-**version**]
4221 Open the file Read Only regardless of the actual file protection.
4224 Don't warn about file creation when a file doesn't exist.
4230 Designate this session as an NEdit server, for processing commands from the
4231 nc program. nc can be used to interface NEdit to code development
4232 environments, mailers, etc., or just as a quick way to open files from the
4233 shell command line without starting a new NEdit session.
4236 Execute an NEdit macro or action. On each file following the -do argument on
4237 the command line. -do is particularly useful from the nc program, where nc
4238 -do can remotely execute commands in an NEdit -server session.
4241 Load a file of directions for finding definitions of program subroutines and
4242 data objects. The file must be of the format gen- erated by Exuberant Ctags,
4243 or the standard Unix ctags command.
4246 Set tab stops every n characters.
4249 Wrap long lines at the right edge of the window rather than continuing them
4250 past it. (Continuous Wrap mode)
4252 **-autowrap, -noautowrap**
4253 Wrap long lines when the cursor reaches the right edge of the window by
4254 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4256 **-autoindent, -noautoindent**
4257 Maintain a running indent.
4259 **-autosave, -noautosave**
4260 Maintain a backup copy of the file being edited under the name '~filename'.
4263 Default height in characters for an editing window.
4266 Default width in characters for an editing window.
4268 **-font font (or -fn font)**
4269 Font for text being edited (Font for menus and dialogs can be set with -xrm
4272 **-lm languagemode**
4273 Initial language mode used for editing succeeding files.
4275 **-geometry geometry (or -g geometry)**
4276 The initial size and/or location of editor windows. The argument geometry
4279 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4281 where <width> and <height> are the desired width and height of the window,
4282 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4283 the window, + for top or left, - for bottom or right. -geometry can be
4284 specified for individual files on the command line.
4286 **-iconic, -noiconic**
4287 Initial window state for succeeding files.
4289 **-display [host]:server[.screen]**
4290 The name of the X server to use. host specifies the machine, server
4291 specifies the display server number, and screen specifies the screen number.
4292 host or screen can be omitted and default to the local machine, and screen 0.
4294 **-background color (or -bg color)**
4295 Background color. (background color for text can be set separately with
4296 -xrm "nedit*text.background: color").
4298 **-foreground color (or -fg color)**
4299 Foreground color. (foreground color for text can be set separately with -xrm
4300 "nedit*text.foreground: color").
4302 **-xrm resourcestring**
4303 Set the value of an X resource to override a default
4304 value (see "Customizing_NEdit_").
4307 When starting NEdit in server mode, name the server, such that it responds to
4308 requests only when nc is given a corresponding -svrname argument. By naming
4309 servers, you can run several simultaneously, and direct files and commands
4310 specifically to any one.
4313 Loads an additional preferences file on top of the existing defaults saved in
4314 your preferences file. To incorporate macros, language modes, and highlight
4315 patterns and styles written by other users, run NEdit with -import <file>,
4316 then re-save your preference file with Preferences -> Save Defaults.
4319 Prints out the NEdit version information. The -V option is synonymous.
4322 Treats all subsequent arguments as file names, even if they start with a
4323 dash. This is so NEdit can access files that begin with the dash character.
4328 .. This documentation for VMS NEdit usage should only appear in the
4329 .. generated help code, not in any of the printed documentation.
4330 .. Reasoning is that VMS usage is diminishing and there is a desire
4331 .. to not clutter up the printed documentation here.
4333 NEDIT [filespec[,...]]
4335 The following qualifiers are accepted:
4338 Open the file Read Only regardless of the actual file protection.
4341 Don't warn about file creation when a file doesn't exist.
4347 Designate this session as an NEdit server for processing commands from the nc
4348 program. The nc program can be used to interface NEdit to code development
4349 environments, mailers, etc., or just as a quick way to open files from the
4350 shell command line without starting a new NEdit session.
4353 Execute an NEdit action routine. on each file following the /do argument on
4354 the command line. /do is particularly useful from the nc program, where nc
4355 /do can remotely execute commands in an nedit /server session.
4358 Load a file of directions for finding definitions of program subroutines and
4359 data objects. The file must be of the format generated by the Unix ctags
4363 Wrap long lines at the right edge of the window rather than continuing them
4364 past it. (Continuous Wrap mode)
4366 **/autowrap, /noautowrap**
4367 Wrap long lines when the cursor reaches the right edge of the window by
4368 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4370 **/autoindent, /noautoindent**
4371 Maintain a running indent.
4373 **/autosave, /noautosave**
4374 Maintain a backup copy of the file being edited under the name '_filename'.
4377 Default width in characters for an editing window.
4380 Default height in characters for an editing window.
4382 **/font=font (or /fn=font)**
4383 Font for text being edited (Font for menus and dialogs can be set with
4384 /xrm="*fontList:font").
4386 **/display [host]:server[.screen]**
4387 The name of the X server to use. host specifies the machine, server
4388 specifies the display server number, and screen specifies the screen number.
4389 host or screen can be omitted and default to the local machine, and screen 0.
4391 **/geometry=geometry (or /g=geometry)**
4392 The initial size and/or location of editor windows. The argument geometry
4395 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4397 where <width> and <height> are the desired width and height of the window,
4398 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4399 the window, + for top or left, - for bottom or right.
4401 **/background=color (or /bg=color)**
4403 Background color. (background color for text can be set separately with
4404 /xrm="nedit*text:background color").
4406 **/foreground=color (or /fg=color)**
4407 Foreground color. (foreground color for text can be set separately with
4408 /xrm="nedit*text:foreground color").
4410 **/xrm=resourcestring**
4411 Set the value of an X resource to override a default value
4412 (see Customizing NEdit).
4415 When starting nedit in server mode, name the server, such that it responds to
4416 requests only when nc is given a corresponding -svrname argument. By naming
4417 servers, you can run several simultaneously, and direct files and commands
4418 specifically to any one.
4421 Loads an additional preferences file on top of the existing defaults saved in
4422 your .nedit file. To incorporate macros, language modes, and highlight
4423 patterns and styles written by other users, run nedit with /import=<file>,
4424 then re-save your .nedit file with Preferences -> Save Defaults.
4426 Unix-style command lines (but not file names) are also acceptable:
4428 nedit -rows 20 -wrap file1.c file2.c
4432 nedit /rows=20/wrap file1.c, file2.c",
4435 ----------------------------------------------------------------------
4440 NEdit can be operated on its own, or as a two-part client/server
4441 application. Client/server mode is useful for integrating NEdit with
4442 software development environments, mailers, and other programs; or just as a
4443 quick way to open files from the shell command line without starting a new
4446 To run NEdit in server mode, type:
4450 NEdit can also be started in server mode via the Nedit Client (nc) program
4451 when no servers are available.
4453 The nc program, which is distributed along with NEdit,
4454 sends commands to an nedit server to open files, select lines, or execute
4455 editor actions. It accepts a limited set of the nedit command line options:
4456 -read, -create, -line (or +n), -do, and a list of file names. Listing a file
4457 on the nc command line means, open it if it is not already open and bring the
4458 window to the front. -read and -create affect only newly opened files, but
4459 -line and -do can also be used on files which are already open
4460 (See "NEdit_Command_Line_" for more information).
4462 In typical Unix style, arguments affect the files which follow them on the
4463 command line, for example:
4465 incorrect: nc file.c -line 25
4466 correct: nc -line 25 file.c
4468 -read, -create, and -line affect all of the files which follow them on the
4469 command line. The -do macro is executed only once, on the next file on the
4470 line. -do without a file following it on the command line, executes the
4471 macro on the first available window (presumably when you give a -do command
4472 without a corresponding file or window, you intend it to do something
4473 independent of the window in which it happens to execute).
4475 nc also accepts one command line option of its own, -noask (or -ask), which
4476 instructs it whether to automatically start a server if one is not
4477 available. This is also settable via the X resource, nc.autoStart
4478 (See "X_Resources_" section).
4480 Sometimes it is useful to have more than one NEdit server running, for
4481 example to keep mail and programming work separate. The option, -svrname, to
4482 both nedit and nc, allows you to start, and communicate with, separate named
4483 servers. A named server responds only to requests with the corresponding
4484 -svrname argument. If you use ClearCase and are within a ClearCase view, the
4485 server name will default to the name of the view (based on the value of the
4486 CLEARCASE_ROOT environment variable).
4488 Communication between nc and nedit is through the X display. So as long as X
4489 windows is set up and working properly, nc will work properly as well.
4490 nc uses the DISPLAY environment variable, the machine name and your user name
4491 to find the appropriate server, meaning, if you have several machines sharing
4492 a common file system, nc will not be able to find a server that is running on
4493 a machine with a different host name, even though it may be perfectly
4494 appropriate for editing a given file.
4496 The command which nc uses to start an nedit server is settable via the X
4497 resource nc.serverCommand, by default, "nedit -server".
4498 ----------------------------------------------------------------------
4503 If a system crash, network failure, X server crash, or program error should
4504 happen while you are editing a file, you can still recover most of your
4505 work. NEdit maintains a backup file which it updates periodically (every 8
4506 editing operations or 80 characters typed). This file has the same name
4507 as the file that you are editing, but with the character `~' (tilde) on Unix
4508 or `_' (underscore) on VMS prefixed to the name. To recover a file after a
4509 crash, simply rename the file to remove the tilde or underscore character,
4510 replacing the older version of the file. (Because several of the Unix shells
4511 consider the tilde to be a special character, you may have to prefix the
4512 character with a `\' (backslash) when you move or delete an NEdit backup
4515 Example, to recover the file called "help.c" on Unix type the command:
4519 A minor caveat, is that if the file you were editing was in MS DOS format,
4520 the backup file will be in Unix format, and you will need to open the backup
4521 file in NEdit and change the file format back to MS DOS via the Save As...
4522 dialog (or use the Unix unix2dos command outside of NEdit).
4523 ----------------------------------------------------------------------
4534 .. There is build time versioning information that is handled specially
4535 .. inside help.c for this section. It needs to have a '%s' string
4536 .. made available for it to appear in the on-line help.
4540 .. ======================================================================
4541 .. The policy for credit so far is this:
4543 .. You get "written by" credit if you have contributed significant
4544 .. code or effort to the project.
4546 .. You get a syntax/indent credit if your pattern is compiled into the
4548 .. ======================================================================
4550 NEdit was written by Mark Edel, Joy Kyriakopulos, Christopher Conrad,
4551 Jim Clark, Arnulfo Zepeda-Navratil, Suresh Ravoor, Tony Balinski, Max
4552 Vohlken, Yunliang Yu, Donna Reid, Arne Førlie, Eddy De Greef, Steve
4553 LoBasso, Alexander Mai, Scott Tringali, Thorsten Haude, and Steve Haehn.
4555 The regular expression matching routines used in NEdit are adapted (with
4556 permission) from original code written by Henry Spencer at the
4557 University of Toronto.
4559 Syntax highlighting patterns and smart indent macros were contributed by:
4560 Simon T. MacDonald, Maurice Leysens, Matt Majka, Alfred Smeenk,
4561 Alain Fargues, Christopher Conrad, Scott Markinson, Konrad Bernloehr,
4562 Ivan Herman, Patrice Venant, Christian Denat, Philippe Couton,
4563 Max Vohlken, Markus Schwarzenberg, Himanshu Gohel, Steven C. Kapp,
4564 Michael Turomsha, John Fieber, Chris Ross, Nathaniel Gray, Joachim Lous,
4565 Mike Duigou, Seak Teng-Fong, Joor Loohuis, Mark Jones,
4566 and Niek van den Berg.
4568 NEdit sources, executables, additional documentation, and contributed
4569 software are available from the NEdit web site at http://www.nedit.org_.
4571 This program is free software; you can redistribute it and/or
4572 modify it under the terms of the GNU General Public License
4573 as published by the Free Software Foundation; either version 2
4574 of the License, or (at your option) any later version.
4576 This program is distributed in the hope that it will be useful,
4577 but WITHOUT ANY WARRANTY; without even the implied warranty of
4578 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4579 GNU General Public License in the Help section "Distribution_Policy_"
4581 ----------------------------------------------------------------------
4586 GNU GENERAL PUBLIC LICENSE
4588 Version 2, June 1991
4590 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave,
4591 Cambridge, MA 02139, USA. Everyone is permitted to copy and distribute
4592 verbatim copies of this license document, but changing it is not allowed.
4596 The licenses for most software are designed to take away your freedom to
4597 share and change it. By contrast, the GNU General Public License is intended
4598 to guarantee your freedom to share and change free software--to make sure the
4599 software is free for all its users. This General Public License applies to
4600 most of the Free Software Foundation's software and to any other program
4601 whose authors commit to using it. (Some other Free Software Foundation
4602 software is covered by the GNU Library General Public License instead.) You
4603 can apply it to your programs, too.
4605 When we speak of free software, we are referring to freedom, not price. Our
4606 General Public Licenses are designed to make sure that you have the freedom
4607 to distribute copies of free software (and charge for this service if you
4608 wish), that you receive source code or can get it if you want it, that you
4609 can change the software or use pieces of it in new free programs; and that
4610 you know you can do these things.
4612 To protect your rights, we need to make restrictions that forbid anyone to
4613 deny you these rights or to ask you to surrender the rights. These
4614 restrictions translate to certain responsibilities for you if you distribute
4615 copies of the software, or if you modify it.
4617 For example, if you distribute copies of such a program, whether gratis or
4618 for a fee, you must give the recipients all the rights that you have. You
4619 must make sure that they, too, receive or can get the source code. And you
4620 must show them these terms so they know their rights.
4622 We protect your rights with two steps: (1) copyright the software, and (2)
4623 offer you this license which gives you legal permission to copy, distribute
4624 and/or modify the software.
4626 Also, for each author's protection and ours, we want to make certain that
4627 everyone understands that there is no warranty for this free software. If the
4628 software is modified by someone else and passed on, we want its recipients to
4629 know that what they have is not the original, so that any problems introduced
4630 by others will not reflect on the original authors' reputations.
4632 Finally, any free program is threatened constantly by software patents. We
4633 wish to avoid the danger that redistributors of a free program will
4634 individually obtain patent licenses, in effect making the program
4635 proprietary. To prevent this, we have made it clear that any patent must be
4636 licensed for everyone's free use or not licensed at all.
4638 The precise terms and conditions for copying, distribution and modification
4641 GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
4644 0. This License applies to any program or other work which contains a notice
4645 placed by the copyright holder saying it may be distributed under the terms
4646 of this General Public License. The "Program", below, refers to any such
4647 program or work, and a "work based on the Program" means either the Program
4648 or any derivative work under copyright law: that is to say, a work containing
4649 the Program or a portion of it, either verbatim or with modifications and/or
4650 translated into another language. (Hereinafter, translation is included
4651 without limitation in the term "modification".) Each licensee is addressed as
4654 Activities other than copying, distribution and modification are not covered
4655 by this License; they are outside its scope. The act of running the Program
4656 is not restricted, and the output from the Program is covered only if its
4657 contents constitute a work based on the Program (independent of having been
4658 made by running the Program). Whether that is true depends on what the
4661 1. You may copy and distribute verbatim copies of the Program's source code
4662 as you receive it, in any medium, provided that you conspicuously and
4663 appropriately publish on each copy an appropriate copyright notice and
4664 disclaimer of warranty; keep intact all the notices that refer to this
4665 License and to the absence of any warranty; and give any other recipients of
4666 the Program a copy of this License along with the Program.
4668 You may charge a fee for the physical act of transferring a copy, and you may
4669 at your option offer warranty protection in exchange for a fee.
4671 2. You may modify your copy or copies of the Program or any portion of it,
4672 thus forming a work based on the Program, and copy and distribute such
4673 modifications or work under the terms of Section 1 above, provided that you
4674 also meet all of these conditions:
4676 a) You must cause the modified files to carry prominent notices stating
4677 that you changed the files and the date of any change.
4679 b) You must cause any work that you distribute or publish, that in whole or
4680 in part contains or is derived from the Program or any part thereof, to be
4681 licensed as a whole at no charge to all third parties under the terms of
4684 c) If the modified program normally reads commands interactively when run,
4685 you must cause it, when started running for such interactive use in the
4686 most ordinary way, to print or display an announcement including an
4687 appropriate copyright notice and a notice that there is no warranty (or
4688 else, saying that you provide a warranty) and that users may redistribute
4689 the program under these conditions, and telling the user how to view a copy
4690 of this License. (Exception: if the Program itself is interactive but does
4691 not normally print such an announcement, your work based on the Program is
4692 not required to print an announcement.)
4694 These requirements apply to the modified work as a whole. If identifiable
4695 sections of that work are not derived from the Program, and can be reasonably
4696 considered independent and separate works in themselves, then this License,
4697 and its terms, do not apply to those sections when you distribute them as
4698 separate works. But when you distribute the same sections as part of a whole
4699 which is a work based on the Program, the distribution of the whole must be
4700 on the terms of this License, whose permissions for other licensees extend to
4701 the entire whole, and thus to each and every part regardless of who wrote it.
4703 Thus, it is not the intent of this section to claim rights or contest your
4704 rights to work written entirely by you; rather, the intent is to exercise the
4705 right to control the distribution of derivative or collective works based on
4708 In addition, mere aggregation of another work not based on the Program with
4709 the Program (or with a work based on the Program) on a volume of a storage or
4710 distribution medium does not bring the other work under the scope of this
4713 3. You may copy and distribute the Program (or a work based on it, under
4714 Section 2) in object code or executable form under the terms of Sections 1
4715 and 2 above provided that you also do one of the following:
4717 a) Accompany it with the complete corresponding machine-readable source
4718 code, which must be distributed under the terms of Sections 1 and 2 above
4719 on a medium customarily used for software interchange; or,
4721 b) Accompany it with a written offer, valid for at least three years, to
4722 give any third party, for a charge no more than your cost of physically
4723 performing source distribution, a complete machine-readable copy of the
4724 corresponding source code, to be distributed under the terms of Sections 1
4725 and 2 above on a medium customarily used for software interchange; or,
4727 c) Accompany it with the information you received as to the offer to
4728 distribute corresponding source code. (This alternative is allowed only for
4729 noncommercial distribution and only if you received the program in object
4730 code or executable form with such an offer, in accord with Subsection b
4733 The source code for a work means the preferred form of the work for making
4734 modifications to it. For an executable work, complete source code means all
4735 the source code for all modules it contains, plus any associated interface
4736 definition files, plus the scripts used to control compilation and
4737 installation of the executable. However, as a special exception, the source
4738 code distributed need not include anything that is normally distributed (in
4739 either source or binary form) with the major components (compiler, kernel,
4740 and so on) of the operating system on which the executable runs, unless that
4741 component itself accompanies the executable.
4743 If distribution of executable or object code is made by offering access to
4744 copy from a designated place, then offering equivalent access to copy the
4745 source code from the same place counts as distribution of the source code,
4746 even though third parties are not compelled to copy the source along with the
4749 4. You may not copy, modify, sublicense, or distribute the Program except as
4750 expressly provided under this License. Any attempt otherwise to copy, modify,
4751 sublicense or distribute the Program is void, and will automatically
4752 terminate your rights under this License. However, parties who have received
4753 copies, or rights, from you under this License will not have their licenses
4754 terminated so long as such parties remain in full compliance.
4756 5. You are not required to accept this License, since you have not signed it.
4757 However, nothing else grants you permission to modify or distribute the
4758 Program or its derivative works. These actions are prohibited by law if you
4759 do not accept this License. Therefore, by modifying or distributing the
4760 Program (or any work based on the Program), you indicate your acceptance of
4761 this License to do so, and all its terms and conditions for copying,
4762 distributing or modifying the Program or works based on it.
4764 6. Each time you redistribute the Program (or any work based on the Program),
4765 the recipient automatically receives a license from the original licensor to
4766 copy, distribute or modify the Program subject to these terms and conditions.
4767 You may not impose any further restrictions on the recipients' exercise of
4768 the rights granted herein. You are not responsible for enforcing compliance
4769 by third parties to this License.
4771 7. If, as a consequence of a court judgment or allegation of patent
4772 infringement or for any other reason (not limited to patent issues),
4773 conditions are imposed on you (whether by court order, agreement or
4774 otherwise) that contradict the conditions of this License, they do not excuse
4775 you from the conditions of this License. If you cannot distribute so as to
4776 satisfy simultaneously your obligations under this License and any other
4777 pertinent obligations, then as a consequence you may not distribute the
4778 Program at all. For example, if a patent license would not permit
4779 royalty-free redistribution of the Program by all those who receive copies
4780 directly or indirectly through you, then the only way you could satisfy both
4781 it and this License would be to refrain entirely from distribution of the
4784 If any portion of this section is held invalid or unenforceable under any
4785 particular circumstance, the balance of the section is intended to apply and
4786 the section as a whole is intended to apply in other circumstances.
4788 It is not the purpose of this section to induce you to infringe any patents
4789 or other property right claims or to contest validity of any such claims;
4790 this section has the sole purpose of protecting the integrity of the free
4791 software distribution system, which is implemented by public license
4792 practices. Many people have made generous contributions to the wide range of
4793 software distributed through that system in reliance on consistent
4794 application of that system; it is up to the author/donor to decide if he or
4795 she is willing to distribute software through any other system and a licensee
4796 cannot impose that choice.
4798 This section is intended to make thoroughly clear what is believed to be a
4799 consequence of the rest of this License.
4801 8. If the distribution and/or use of the Program is restricted in certain
4802 countries either by patents or by copyrighted interfaces, the original
4803 copyright holder who places the Program under this License may add an
4804 explicit geographical distribution limitation excluding those countries, so
4805 that distribution is permitted only in or among countries not thus excluded.
4806 In such case, this License incorporates the limitation as if written in the
4807 body of this License.
4809 9. The Free Software Foundation may publish revised and/or new versions of
4810 the General Public License from time to time. Such new versions will be
4811 similar in spirit to the present version, but may differ in detail to address
4812 new problems or concerns.
4814 Each version is given a distinguishing version number. If the Program
4815 specifies a version number of this License which applies to it and "any later
4816 version", you have the option of following the terms and conditions either of
4817 that version or of any later version published by the Free Software
4818 Foundation. If the Program does not specify a version number of this License,
4819 you may choose any version ever published by the Free Software Foundation.
4821 10. If you wish to incorporate parts of the Program into other free programs
4822 whose distribution conditions are different, write to the author to ask for
4823 permission. For software which is copyrighted by the Free Software
4824 Foundation, write to the Free Software Foundation; we sometimes make
4825 exceptions for this. Our decision will be guided by the two goals of
4826 preserving the free status of all derivatives of our free software and of
4827 promoting the sharing and reuse of software generally.
4831 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
4832 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
4833 STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
4834 PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
4835 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
4836 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
4837 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
4838 YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
4840 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4841 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4842 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4843 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4844 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO
4845 LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
4846 THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4847 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4848 POSSIBILITY OF SUCH DAMAGES.
4850 END OF TERMS AND CONDITIONS
4851 ----------------------------------------------------------------------
4856 There are two separate mailing lists for nedit users, and one for developers.
4857 Users may post to the developer mailing list to report defects and communicate
4858 with the nedit developers. Remember that nedit is entirely a volunteer
4859 effort, so please ask questions first to the discussion list, and do your
4860 share to answer other users questions as well.
4864 General discussion, questions and answers among NEdit users and developers.
4866 announce@@nedit.org_
4868 A low-volume mailing list for announcing new versions.
4872 Communication among and with NEdit developers.
4873 Developers should also subscribe to the discuss list.
4875 To subscribe, send mail to <majordomo@@nedit.org> with one or more of the
4876 following in the body of the message:
4881 ----------------------------------------------------------------------
4886 3>Solutions to Common Problems
4888 For a much more comprehensive list of common problems and solutions, see the
4889 NEdit FAQ. The latest version of the FAQ can always be found on the NEdit
4892 http://www.nedit.org_.
4894 **P: No files are shown in the "Files" list in the Open... dialog.**
4896 S: When you use the "Filter" field, include the file specification or a
4897 complete directory specification, including the trailing "/" on Unix.
4898 (See Help in the Open... dialog).
4900 **P: Find Again and Replace Again don't continue in the same direction as the original Find or Replace.**
4902 S: Find Again and Replace Again don't use the direction of the original
4903 search. The Shift key controls the direction: Ctrl+G means forward,
4904 Shift+Ctrl+G means backward.
4906 **P: Preferences specified in the Preferences menu don't seem to get saved when I select Save Defaults.**
4908 S: NEdit has two kinds of preferences: 1) per-window preferences, in the
4909 Preferences menu, and 2) default settings for preferences in newly created
4910 windows, in the Default Settings sub-menu of the Preferences menu.
4911 Per-window preferences are not saved by Save Defaults, only Default
4914 **P: Columns and indentation don't line up.**
4916 S: NEdit is using a proportional width font. Set the font to a fixed style
4917 (see Preferences menu).
4919 **P: NEdit performs poorly on very large files.**
4921 S: Turn off Incremental Backup. With Incremental Backup on, NEdit
4922 periodically writes a full copy of the file to disk.
4924 **P: Commands added to the Shell Commands menu (Unix only) don't output anything until they are finished executing.**
4926 S: If the command output is directed to a dialog, or the input is from a
4927 selection, output is collected together and held until the command
4928 completes. De-select both of the options and the output will be shown
4929 incrementally as the command executes.
4931 **P: Dialogs don't automatically get keyboard focus when they pop up.**
4933 S: Most X Window managers allow you to choose between two categories of
4934 keyboard focus models: pointer focus, and explicit focus. Pointer focus
4935 means that as you move the mouse around the screen, the window under the
4936 mouse automatically gets the keyboard focus. NEdit users who use this
4937 focus model should set "Popups Under Pointer" in the Default Settings sub
4938 menu of the preferences menu in NEdit. Users with the explicit focus
4939 model, in some cases, may have problems with certain dialogs, such as Find
4940 and Replace. In MWM this is caused by the mwm resource startupKeyFocus
4941 being set to False (generally a bad choice for explicit focus users).
4942 NCDwm users should use the focus model "click" instead of "explicit",
4943 again, unless you have set it that way to correct specific problems, this
4944 is the appropriate setting for most explicit focus users.
4946 **P: The Backspace key doesn't work, or deletes forward rather than backward.**
4948 S: While this is an X/Motif binding problem, and should be solved outside of
4949 NEdit in the Motif virtual binding layer (or possibly xmodmap or
4950 translations), NEdit provides an out. If you set the resource:
4951 nedit.remapDeleteKey to True, NEdit will forcibly map the delete key to
4952 backspace. The default setting of this resource recently changed, so
4953 users who have been depending on this remapping will now have to set it
4954 explicitly (or fix their bindings).
4956 **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.**
4958 S: On many SunOS systems, you have to set up an nls directory before various
4959 inter-client communication features of Motif will function properly.
4960 There are instructions in README.sun in /pub/v5_0_2/individual/README.sun on
4961 ftp.nedit.org, as well as a tar file containing a complete nls
4962 directory: ftp://ftp.nedit.org/pub/v5_0_2/nls.tar.
4963 README.sun contains directions for setting up an nls directory, which
4964 is required by Motif for handling copy and paste to Motif text fields.
4968 Below is the list of known defects which affect NEdit. The defects your copy
4969 of NEdit will exhibit depend on which system you are running and with which
4970 Motif libraries it was built. Note that there are now Motif 1.2 and/or 2.0
4971 libraries available on ALL supported platforms, and as you can see below
4972 there are far fewer defects in Motif 1.2, so it is in your best interest to
4973 upgrade your system.
4978 Operations between rectangular selections on overlapping lines do nothing.
4981 None. These operations are very complicated and rarely used.
4984 Cut and Paste menu items fail, or possibly crash,
4985 for very large (multi-megabyte) selections.
4988 Use selection copy (middle mouse button click)
4989 for transferring larger quantities of data.
4990 Cut and Paste save the copied text in server
4991 memory, which is usually limited.
4995 Submit bugs through the web at:
4997 http://sf.net/tracker/?func=add&group_id=11005&atid=111005
4999 Please include the first few lines from Help > Version, which identifes
5000 NEdit's version and other system attributes important for diagnosing your
5003 The NEdit developers subscribe to both discuss@@nedit.org and
5004 develop@@nedit.org, either of which may be used for reporting defects. If
5005 you're not sure, or you think the report might be of interest to the general
5006 NEdit user community, send the report to discuss@@nedit.org_. If it's
5007 something obvious and boring, like we misspelled "anemometer" in the on-line
5008 help, send it to develop@@nedit.org_. If you don't want to subscribe to the
5009 Mailing_Lists_, please add a note to your mail about cc'ing you on responses.
5013 .. Hyperlinks for this document ==============================================
5015 .. _discuss@@nedit.org mailto:discuss@@nedit.org
5016 .. _announce@@nedit.org mailto:announce@@nedit.org
5017 .. _develop@@nedit.org mailto:develop@@nedit.org
5018 .. _http://www.nedit.org http://www.nedit.org
5019 .. _ctag_support #ctags
5020 .. _Alternation #alternation
5022 .. =============================================================================
5024 .. Below is what is used to guide the generation of 'C'-Motif menus.
5025 .. Indentation is SIGNIFICANT in the "Menu" directive lines below. It
5026 .. is used to determine under which menu element another item will belong.
5027 .. The number of spaces indented is not significant, but items to be placed
5028 .. in the same menu panel MUST line up at the same indent level.
5029 .. ALL nodes of this menu "tree" should have help name qualifiers.
5030 .. These are used to produce the internal lists used by NEdit help code.
5032 .. By default, the first character of the menu element will be used as a
5033 .. menu mneumonic key. To use another character in the menu element for this
5034 .. purpose, surround the character with underscores (eg. I w_a_nt 'a').
5036 .. The menu title MUST match the one found in the actual help text (sans
5037 .. special mneumonic key character marking). The help text title may include
5038 .. underlines (for spaces) when it is a hyperlink target.
5040 .. The Help-name is used to generate various data structure names. For
5041 .. instance, the 'start' help name will be used to generate the HelpTopic
5042 .. enumeration value HELP_START and the character array htxt_start which
5043 .. holds the actual help text used in the menu dialogs. Consequently, these
5044 .. names need to be unique and contain only the characters that a 'C'
5045 .. compiler can digest.
5047 .. Menu separator lines use a dash (-) character for the Menu Title. They
5048 .. should also have a unique Help-name.
5050 .. A numerical value following the Help-name (separated from the name by
5051 .. a comma and/or spaces) is part of a menu element hiding scheme implemented
5052 .. in buildHelpMenu (found in 'menu.c'). When the number matches the hideIt
5053 .. value found in the procedure, that element will effectively become invisible.
5054 .. This mechanism was created for particular menu features that are not
5055 .. available to all incarnations of NEdit (in this case, the VMS version).
5057 .. A "Help" directive is used for all other text used as NEdit help, but
5058 .. does not show up in the Help menu.
5060 .. Menu Title # Help-name
5061 .. ------------------------------------------------------------
5062 .. Menu: Getting Started # start
5063 .. Menu: Basic Operation # basicOp
5064 .. Menu: Selecting Text # select
5065 .. Menu: Finding and Replacing Text # search
5066 .. Menu: Cut and Paste # clipboard
5067 .. Menu: Using the Mouse # mouse
5068 .. Menu: Keyboard Shortcuts # keyboard
5069 .. Menu: S_h_ifting and Filling # fill
5070 .. Menu: F_i_le Format # format
5072 .. Menu: Features for Programming # features
5073 .. Menu: Programming with NEdit # programmer
5074 .. Menu: Tabs/Emulated Tabs # tabs
5075 .. Menu: Auto/Smart Indent # indent
5076 .. Menu: Syntax Highlighting # syntax
5077 .. Menu: Finding Declarations (ctags) # tags
5078 .. Menu: Calltips # calltips
5080 .. Menu: Regular Expressions # regex
5081 .. Menu: Basic Regular Expression Syntax # basicSyntax
5082 .. Menu: Metacharacters # escapeSequences
5083 .. Menu: Parenthetical Constructs # parenConstructs
5084 .. Menu: Advanced Topics # advancedTopics
5085 .. Menu: Example Regular Expressions # examples
5087 .. Menu: Macro/Shell Extensions # extensions
5088 .. Menu: Shell Commands and Filters # shell, 1
5089 .. Menu: Learn/Replay # learn
5090 .. Menu: Macro Language # macro_lang
5091 .. Menu: M_a_cro Subroutines # macro_subrs
5092 .. Menu: Action Routines # actions
5094 .. Menu: Customizing # customizing
5095 .. Menu: Customizing NEdit # customize
5096 .. Menu: Preferences # preferences
5097 .. Menu: X Resources # resources
5098 .. Menu: Key Binding # binding
5099 .. Menu: Highlighting Patterns # patterns
5100 .. Menu: Smart Indent Macros # smart_indent
5102 .. Menu: NEdit Command Line # command_line
5103 .. Menu: Client/Server Mode # server
5104 .. Menu: Cr_a_sh Recovery # recovery
5105 .. Menu: ---------------------------------- # separator1
5106 .. Menu: Version # version
5107 .. Menu: Distribution Policy # distribution
5108 .. Menu: Mailing _L_ists # mailing_list
5109 .. Menu: Problems/Defects # defects
5110 .. ------------------------------------------------------------
5111 .. Help: Tabs Dialog # tabs_dialog
5112 .. Help: Customize Window Title Dialog # custom_title_dialog