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:
1871 * The default place for the file is '$HOME/.nedit/autoload.nm',
1872 * if the variable $NEDIT_HOME is set in your environment it is located at
1873 '$NEDIT_HOME/autoload.nm',
1874 * if you are using old-style run control files (i.e. $HOME/.nedit is a regular
1875 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()**
2853 Moves the cursor to the beginning of the line.
2855 **beginning_of_selection()**
2856 Moves the cursor to the beginning of the selection
2857 without disturbing the selection.
2859 **copy_clipboard()**
2860 Copies the current selection to the clipboard.
2863 Copies the primary selection to the cursor.
2866 If a secondary selection exists, copies the secondary selection to
2867 the cursor. If no secondary selection exists, copies the primary selection
2868 to the pointer location.
2870 **copy_to_or_end_drag()**
2871 Completes either a secondary selection operation, or a
2872 primary drag. If the user is dragging the mouse to adjust a secondary
2873 selection, the selection is copied and either inserted at the cursor
2874 location, or, if pending-delete is on and a primary selection exists in the
2875 window, replaces the primary selection. If the user is dragging a block of
2876 text (primary selection), completes the drag operation and leaves the text at
2877 it's current location.
2880 Deletes the text in the primary selection and places it in
2884 Copies the primary selection to the cursor and deletes it at
2885 its original location.
2887 **delete_selection()**
2888 Deletes the contents of the primary selection.
2890 **delete_next_character( ["nobell"] )**
2891 If a primary selection exists, deletes its contents.
2892 Otherwise, deletes the character following the cursor.
2894 **delete_previous_character( ["nobell"] )**
2895 If a primary selection exists, deletes its
2896 contents. Otherwise, deletes the character before the cursor.
2898 **delete_next_word( ["nobell"] )**
2899 If a primary selection exists, deletes its contents.
2900 Otherwise, deletes the word following the cursor.
2902 **delete_previous_word( ["nobell"] )**
2903 If a primary selection exists, deletes its contents.
2904 Otherwise, deletes the word before the cursor.
2906 **delete_to_start_of_line( ["nobell"] )**
2907 If a primary selection exists, deletes its
2908 contents. Otherwise, deletes the characters between the cursor and the start
2911 **delete_to_end_of_line( ["nobell"] )**
2912 If a primary selection exists, deletes its contents.
2913 Otherwise, deletes the characters between the cursor and the end of the line.
2916 De-selects the primary selection.
2918 **end_of_file( ["scrollbar"] )**
2919 Moves the cursor to the end of the file.
2922 Moves the cursor to the end of the line.
2924 **end_of_selection()**
2925 Moves the cursor to the end of the selection without
2926 disturbing the selection.
2928 **exchange( ["nobell"] )**
2929 Exchange the primary and secondary selections.
2932 Attached mouse-movement events to begin a selection between
2933 the cursor and the mouse, or extend the primary selection to the mouse
2937 Completes a primary drag-selection operation.
2940 Begins a selection between the cursor and the mouse. A
2941 drag-selection operation can be started with either extend_start or
2944 **focus_pane( [relative-pane] | [positive-index] | [negative-index] )**
2945 Move the focus to the requested pane.
2946 Arguments can be specified in the form of a relative-pane
2947 ("first", "last", "next", "previous"), a positive-index
2948 (numbers greater than 0, 1 is the same as "first") or a
2949 negative-index (numbers less than 0, -1 is the same as "last").
2951 **forward_character()**
2952 Moves the cursor one character to the right.
2954 **forward_paragraph( ["nobell"] )**
2955 Moves the cursor to the beginning of the next paragraph.
2956 Paragraphs are defined as regions of text delimited by one or more blank
2959 **forward_word( ["tail"] ["nobell"] )**
2960 Moves the cursor to the beginning of the next word. Word
2961 delimiters are user-settable, and defined by the X resource wordDelimiters.
2962 If the "tail" argument is supplied the cursor will be moved to
2963 the end of the current word or the end of the next word, if the
2964 cursor is between words.
2967 Moves the cursor to the mouse pointer location, and prepares for
2968 a possible drag-selection operation (bound to extend_adjust), or multi-click
2969 operation (a further grab_focus action). If a second invocation of grab
2970 focus follows immediately, it selects a whole word, or a third, a whole line.
2972 **insert_string( "string" )**
2973 If pending delete is on and the cursor is inside the
2974 selection, replaces the selection with "string". Otherwise, inserts "string"
2975 at the cursor location.
2977 **key_select( "direction" [,"nobell"] )**
2978 Moves the cursor one character in "direction"
2979 ("left", "right", "up", or "down") and extends the selection. Same as
2980 forward/backward-character("extend"), or process-up/down("extend"), for
2981 compatibility with previous versions.
2983 **move-destination()**
2984 Moves the cursor to the pointer location without
2985 disturbing the selection. (This is an unusual way of working. We left it in
2986 for compatibility with previous versions, but if you actually use this
2987 capability, please send us some mail, otherwise it is likely to disappear in
2991 If a secondary selection exists, deletes the contents of the
2992 secondary selection and inserts it at the cursor, or if pending-delete is on
2993 and there is a primary selection, replaces the primary selection. If no
2994 secondary selection exists, moves the primary selection to the pointer
2995 location, deleting it from its original position.
2997 **move_to_or_end_drag()**
2998 Completes either a secondary selection operation, or a
2999 primary drag. If the user is dragging the mouse to adjust a secondary
3000 selection, the selection is deleted and either inserted at the cursor
3001 location, or, if pending-delete is on and a primary selection exists in the
3002 window, replaces the primary selection. If the user is dragging a block of
3003 text (primary selection), completes the drag operation and deletes the text
3004 from it's current location.
3007 Inserts a newline character. If Auto Indent is on, lines up the
3008 indentation of the cursor with the current line.
3010 **newline_and_indent()**
3011 Inserts a newline character and lines up the indentation
3012 of the cursor with the current line, regardless of the setting of Auto
3015 **newline_no_indent()**
3016 Inserts a newline character, without automatic
3017 indentation, regardless of the setting of Auto Indent.
3019 **next_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3020 Moves the cursor and scroll forward one page.
3021 The parameter "stutter" moves the cursor to the bottom of the display,
3022 unless it is already there, otherwise it will page down.
3023 The parameter "column" will maintain the preferred column while
3026 **page_left( ["scrollbar"] ["nobell"] )**
3027 Move the cursor and scroll left one page.
3029 **page_right( ["scrollbar"] ["nobell"] )**
3030 Move the cursor and scroll right one page.
3032 **paste_clipboard()**
3033 Insert the contents of the clipboard at the cursor, or if
3034 pending delete is on, replace the primary selection with the contents of the
3037 **previous_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )**
3038 Moves the cursor and scroll backward one page.
3039 The parameter "stutter" moves the cursor to the top of the display,
3040 unless it is already there, otherwise it will page up.
3041 The parameter "column" will maintain the preferred column while
3045 Same as secondary_or_drag_start for compatibility with previous versions.
3047 **process_cancel()**
3048 Cancels the current extend_adjust, secondary_adjust, or
3049 secondary_or_drag_adjust in progress.
3051 **process_down( ["nobell"] )**
3052 Moves the cursor down one line.
3054 **process_return()**
3055 Same as newline for compatibility with previous versions.
3057 **process_shift_down( ["nobell"] )**
3058 Same as process_down("extend") for compatibility with previous versions.
3060 **process_shift_up( ["nobell"] )**
3061 Same as process_up("extend") for compatibility with previous versions.
3064 If tab emulation is turned on, inserts an emulated tab,
3065 otherwise inserts a tab character.
3067 **process_up( ["nobell"] )**
3068 Moves the cursor up one line.
3070 **raise_window([relative-window] | [positive-index] | [negative-index])**
3071 Raise the current focused window to the front if no argument is supplied.
3072 Arguments can be specified in the form of a relative-window
3073 ("first", "last", "next", "previous"), a positive-index
3074 (numbers greater than 0, 1 is the same as "last") or a
3075 negative-index (numbers less than 0, -1 is the same as "first").
3077 **scroll_down(nLines)**
3078 Scroll the display down (towards the end of the file) by nLines.
3080 **scroll_left( nPixels )**
3081 Scroll the display left by nPixels.
3083 **scroll_right( nPixels )**
3084 Scroll the display right by nPixels.
3086 **scroll_up( nLines )**
3087 Scroll the display up (towards the beginning of the file) by nLines.
3089 **scroll_to_line( lineNum )**
3090 Scroll to position line number lineNum at the top of
3091 the pane. The first line of a file is line 1.
3093 **secondary_adjust()**
3094 Attached mouse-movement events to extend the secondary
3095 selection to the mouse position.
3097 **secondary_or_drag_adjust()**
3098 Attached mouse-movement events to extend the
3099 secondary selection, or reposition the primary text being dragged. Takes two
3100 optional arguments, "copy", and "overlay". "copy" leaves a copy of the
3101 dragged text at the site at which the drag began. "overlay" does the drag in
3102 overlay mode, meaning the dragged text is laid on top of the existing text,
3103 obscuring and ultimately deleting it when the drag is complete.
3105 **secondary_or_drag_start()**
3106 To be attached to a mouse down event. Begins drag
3107 selecting a secondary selection, or dragging the contents of the primary
3108 selection, depending on whether the mouse is pressed inside of an existing
3111 **secondary_start()**
3112 To be attached to a mouse down event. Begin drag selecting
3113 a secondary selection.
3116 Select the entire file.
3119 To be attached to a key-press event, inserts the character
3120 equivalent of the key pressed.
3122 ----------------------------------------------------------------------
3130 NEdit can be customized many different ways. The most important
3131 user-settable options are presented in the Preferences menu, including all
3132 options that users might need to change during an editing session. Options
3133 set in the Default Settings sub-menu of the Preferences menu can be preserved
3134 between sessions by selecting Save Defaults, which writes the changes to the
3135 preferences file. See the section titled "Preferences_" for more details.
3137 User defined commands can be added to NEdit's Shell, Macro, and window
3138 background menus. Dialogs for creating items in these menus can be found
3139 under Customize Menus in the Default Settings sub menu of the Preferences
3142 For users who depend on NEdit every day and want to tune every excruciating
3143 detail, there are also X resources for tuning a vast number of such details,
3144 down to the color of each individual button. See the section "X_Resources_"
3145 for more information, as well as a list of selected resources.
3147 The most common reason customizing your X resources for NEdit, however, is
3148 key binding. While limited key binding can be done through Preferences
3149 settings (Preferences -> Default Settings -> Customize Menus), you can really
3150 only add keys this way, and each key must have a corresponding menu item.
3151 Any significant changes to key binding should be made via the Translations
3152 resource and menu accelerator resources. The sections titled "Key_Binding_"
3153 and "X_Resources_" have more information.
3154 ----------------------------------------------------------------------
3159 The Preferences menu allows you to set options for both the current editing
3160 window, and default values for newly created windows and future NEdit
3161 sessions. Options in the Preferences menu itself (not in the Default
3162 Settings sub-menu) take effect immediately and refer to the current window
3163 only. Options in the Default Settings sub-menu provide initial settings for
3164 future windows created using the New or Open commands; options affecting all
3165 windows are also set here.
3166 Preferences set in the Default Settings sub-menu can be saved in a file that
3167 is automatically read by NEdit at startup time, by selecting Save Defaults.
3171 **Default Settings**
3172 Menu of initial settings for future windows. Generally the same as the
3173 options in the main part of the menu, but apply as defaults for future
3174 windows created during this NEdit session. These settings can be saved using
3175 the Save Defaults command below, to be loaded automatically each time NEdit
3179 Save the default options as set under Default Settings for future NEdit
3183 Show the full file name, line number, and length of the file being edited.
3185 **Incremental Search Line**
3186 Keep the incremental search bar (Search -> Find Incremental) permanently
3187 displayed at the top of the window.
3189 **Show Line Numbers**
3190 Display line numbers to the right of the text.
3193 Tells NEdit what language (if any) to assume, for selecting language-specific
3194 features such as highlight patterns and smart indent macros, and setting
3195 language specific preferences like word delimiters, tab emulation, and
3196 auto-indent. See Features for Programming -> Programming_with_NEdit_ for
3200 Setting Auto Indent "on" maintains a running indent (pressing the Return key
3201 will line up the cursor with the indent level of the previous line). If
3202 smart indent macros are available for the current language mode, smart indent
3203 can be selected and NEdit will attempt to guess proper language indentation
3204 for each new line. See Help -> Features for Programming -> Automatic Indent
3205 for more information.
3208 Choose between two styles of automatic wrapping or none. Auto Newline wrap,
3209 wraps text at word boundaries when the cursor reaches the right margin, by
3210 replacing the space or tab at the last word boundary with a newline
3211 character. Continuous Wrap wraps long lines which extend past the right
3212 margin. Continuous Wrap mode is typically used to produce files where
3213 newlines are omitted within paragraphs, to make text filling automatic (a
3214 kind of poor-man's word processor). Text of this style is common on Macs and
3215 PCs but is not necessarily supported very well under Unix (except in programs
3216 which deal with e-mail, for which it is often the format of choice).
3219 Set margin for Auto Newline Wrap, Continuous Wrap, and Fill Paragraph. Lines
3220 may, be wrapped at the right margin of the window, or the margin can be set
3221 at a specific column.
3224 Set the tab distance (number of characters between tab stops) for tab
3225 characters, and control tab emulation and use of tab characters in padding
3229 Change the font(s) used to display text (fonts for menus and dialogs must be
3230 set using X resources for the text area of the window). See below for more
3233 **Highlight Syntax**
3234 If NEdit recognizes the language being edited, and highlighting patterns are
3235 available for that language, use fonts and colors to enhance viewing of the
3236 file. (See Help -> Features for Programming -> Syntax Highlighting for more
3239 **Make Backup Copy**
3240 On Save, write a backup copy of the file as it existed before the Save
3241 command with the extension .bck (Unix only).
3243 **Incremental Backup**
3244 Periodically make a backup copy of the file being edited under the name
3245 `~filename` on Unix or `_filename` on VMS (see Crash_Recovery_).
3247 **Show Matching (..)**
3248 Momentarily highlight matching parenthesis, brackets, and braces, or the
3249 range between them, when one of these characters is typed, or when the
3250 insertion cursor is positioned after it. Delimiter only highlights the
3251 matching delimiter, while Range highlights the whole range of text between
3252 the matching delimiters.
3254 Optionally, the matching can make use of syntax information if syntax
3255 highlighting is enabled. Alternatively, the matching is purely character
3256 based. In general, syntax based matching results in fewer false matches.
3259 In overtype mode, new characters entered replace the characters in front of
3260 the insertion cursor, rather than being inserted before them.
3263 Lock the file against accidental modification. This temporarily prevents the
3264 file from being modified in this NEdit session. Note that this is different
3265 from setting the file protection.
3267 3>Preferences -> Default Settings Menu
3269 Options in the Preferences -> Default Settings menu have the same meaning as
3270 those in the top-level Preferences menu, except that they apply to future
3271 NEdit windows and future NEdit sessions if saved with the Save Defaults
3272 command. Additional options which appear in this menu are:
3275 Define language recognition information (for determining language mode from
3276 file name or content) and set language specific preferences.
3279 How to react to multiple tags for the same name. Tags are described in the
3280 section: Features for Programmers -> Finding Declarations (ctags). In Show
3281 All mode, all matching tags are displayed in a dialog. In Smart mode, if one
3282 of the matching tags is in the current window, that tag is chosen, without
3283 displaying the dialog.
3286 Add/remove items from the Shell, Macro, and window background menus (see
3289 **Customize Window Title**
3290 Opens a dialog where the information to be displayed in the windows's title
3291 field can be defined and tested. The dialog contains a Help button, providing
3292 further information about the options available.
3295 Options for controlling the behavior of Find and Replace commands:
3298 Presents search results in dialog form, asks before wrapping a
3299 search back around the beginning (or end) of the file
3300 (unless Beep On Search Wrap is turned on).
3303 Search and Replace operations wrap around the beginning (or end) of the file.
3305 ~Beep On Search Wrap~ -
3306 Beep when Search and Replace operations wrap around the beginning (or end) of
3307 the file (only if Wrap Around is turned on).
3310 Don't pop down Replace and Find boxes after searching.
3312 ~Default Search Style~ -
3313 Initial setting for search type in Find and Replace dialogs.
3315 ~Default Replace Scope~ -
3316 [THIS OPTION IS ONLY PRESENT WHEN NEDIT WAS COMPILED WITH THE
3317 -DREPLACE_SCOPE FLAG TO SELECT AN ALTERNATIVE REPLACE DIALOG LAYOUT.]
3319 Initial setting for the scope in the Replace/Find dialog, when a selection
3320 exists. It can be either "In Window", "In Selection", or "Smart". "Smart"
3321 results in "In Window" if the size of the selection is smaller than 1 line,
3322 and to "In Selection" otherwise.
3324 **Syntax Highlighting**
3325 Program and configure enhanced text display for new or supported languages
3326 (See Features for Programming -> Syntax_Highlighting_).
3328 **Append Line Feed on Save**
3329 Some UNIX tools expect that files end with a line feed. If this option is
3330 activated, NEdit will append one if required.
3332 **Sort Open Prev. Menu**
3333 Option to order the File -> Open Previous menu alphabetically, versus in
3334 order of last access.
3336 **Popups Under Pointer**
3337 Display pop-up dialogs centered on the current mouse position, as opposed to
3338 centered on the parent window. This generally speeds interaction, and is
3339 essential for users who users who set their window managers so keyboard focus
3342 **Modification Warnings**
3343 Pop up a warning dialog when files get changed external to NEdit.
3346 Ask before exiting when two or more files are open in an NEdit session.
3348 **Initial Window Size**
3349 Default size for new windows.
3353 The font used to display text in NEdit is set under Preferences -> Text Font
3354 (for the current window), or Preferences -> Default Settings Text Font (for
3355 future windows). These dialogs also allow you to set fonts for syntax
3356 highlighting. If you don't intend to use syntax highlighting, you can ignore
3357 most of the dialog, and just set the field labeled Primary Font.
3359 Unless you are absolutely certain about the types of files that you will be
3360 editing with NEdit, you should choose a fixed-spacing font. Many, if not
3361 most, plain-text files are written expecting to be viewed with fixed
3362 character spacing, and will look wrong with proportional spacing. NEdit's
3363 filling, wrapping, and rectangular operations will also work strangely if you
3364 choose a proportional font.
3366 Note that in the font browser (the dialog brought up by the Browse...
3367 button), the subset of fonts which are shown is narrowed depending on the
3368 characteristics already selected. It is therefore important to know that you
3369 can unselect characteristics from the lists by clicking on the selected items
3372 Fonts for syntax highlighting should ideally match the primary font in both
3373 height and spacing. A mismatch in spacing will result in similar distortions
3374 as choosing a proportional font: column alignment will sometimes look wrong,
3375 and rectangular operations, wrapping, and filling will behave strangely. A
3376 mismatch in height will cause windows to re-size themselves slightly when
3377 syntax highlighting is turned on or off, and increase the inter- line spacing
3378 of the text. Unfortunately, on some systems it is hard to find sets of fonts
3379 which match exactly in height.
3383 You can add or change items in the Shell, Macro, and window background menus
3384 under Preferences -> Default Settings -> Customize Menus. When you choose
3385 one of these, you will see a dialog with a list of the current
3386 user-configurable items from the menu on the left. To change an existing
3387 item, select it from the list, and its properties will appear in the
3388 remaining fields of the dialog, where you may change them. Selecting the
3389 item "New" from the list allows you to enter new items in the menu.
3391 Hopefully most of the characteristics are self explanatory, but here are a
3394 Accelerator keys are keyboard shortcuts which appear on the right hand side
3395 of the menus, and allow you avoid pulling down the menu and activate the
3396 command with a single keystroke. Enter accelerators by typing the keys
3397 exactly as you would to activate the command.
3399 Mnemonics are a single letter which should be part of the menu item name,
3400 which allow users to traverse and activate menu items by typing keys when the
3401 menu is pulled down.
3403 In the Shell Command field of the Shell Commands dialog, the % character
3404 expands to the name (including directory path) of the file in the window. To
3405 include a % character in the command, use %%.
3407 The Menu Entry field can contain special characters for constructing
3408 hierarchical sub-menus, and for making items which appear only in certain
3409 language modes. The right angle bracket character ">" creates a sub-menu.
3410 The name of the item itself should be the last element of the path formed
3411 from successive sub-menu names joined with ">". Menu panes are called in to
3412 existence simply by naming them as part of a Menu Entry name. To put several
3413 items in the same sub-menu, repeat the same hierarchical sequence for each.
3414 For example, in the Macro Commands dialog, two items with menu entries: a>b>c
3415 and a>b>d would create a single sub menu under the macro menu called "a",
3416 which would contain a single sub-menu, b, holding the actual items, c and d:
3423 To qualify a menu entry with a language mode, simply add an at-sign "@@" at
3424 the end of the menu command, followed (no space) by a language mode name. To
3425 make a menu item which appears in several language modes, append additional
3426 @@s and language mode names. For example, an item with the menu entry:
3428 Make C Prototypes@@C@@C++
3430 would appear only in C and C++ language modes, and:
3432 Make Class Template@@C++
3434 would appear only in C++ mode.
3436 Menu items with no qualification appear in all language modes.
3438 If a menu item is followed by the single language qualification "@@*", that
3439 item will appear only if there are no applicable language-specific items of
3440 the same name in the same submenu. For example, if you have the following
3441 three entries in the same menu:
3443 Make Prototypes@@C@@C++
3444 Make Prototypes@@Java
3447 The first will be available when the language mode is C or C++, the second
3448 when the language mode is Java, and for all other language modes (including
3449 the "Plain" non-language mode). If the entry:
3453 also exists, this will always appear, meaning that the menu will always have
3454 two "Make Prototypes" entries, whatever the language mode.
3456 3>The NEdit Preferences File
3458 The NEdit saved preferences file is an X resource file, and its contents can
3459 be moved into another X resource file (see X_Resources_). One reason for
3460 doing so would be to attach server specific preferences, such as a default
3461 font to a particular X server. Another reason for moving preferences into the
3462 X resource file would be to keep preferences menu options and resource
3463 settable options together in one place.
3464 Though the files are the same format, additional resources should not be added
3465 to the preference file since NEdit modifies this file by overwriting it
3466 completely. Note also that the contents of the preference file take
3467 precedence over the values of X resources.
3468 Using Save Defaults after moving the contents of your preference file to your
3469 .Xdefaults file will re-create the preference file, interfering with the
3470 options that you have moved.
3471 The location of NEdit's preferences file depends on your environment:
3472 * The default place for the file is '$HOME/.nedit/nedit.rc',
3473 * if the variable $NEDIT_HOME is set in your environment it is located at
3474 '$NEDIT_HOME/nedit.rc',
3475 * you may also use old-style run control files; in this case, the preferences
3476 are stored in $HOME/.nedit.
3477 (For VMS, the file is in '$NEDIT_HOME/nedit.rc' if $NEDIT_HOME is set, in
3478 'SYS$LOGIN:.nedit' otherwise.)
3480 3>Sharing Customizations with Other NEdit Users
3482 If you have written macro or shell menu commands, highlight patterns, or
3483 smart-indent macros that you want to share with other NEdit users, you can
3484 make a file which they can load into their NEdit environment.
3486 To load such a file, start NEdit with the command:
3488 nedit -import <file>
3490 In the new NEdit session, verify that the imported patterns or macros do what
3491 you want, then select Preferences -> Save Defaults. Saving incorporates the
3492 changes into the nedit preferences file, so the next time you run NEdit, you
3493 will not have to import the distribution file.
3495 Loading a customization file is automated, but creating one is not. To
3496 produce a file to be imported by other users, you must make a copy of your own
3497 NEdit configuration file, and edit it, by hand, to remove everything but the
3498 few items of interest to the recipient. Leave only the individual
3499 resource(s), and within those resources, only the particular macro, pattern,
3500 style, etc, that you wish to exchange.
3502 For example, to share a highlighting pattern set, you would include the
3503 patterns, any new styles you added, and language mode information only if the
3504 patterns are intended to support a new language rather than updating an
3505 existing one. For example:
3507 nedit.highlightPatterns:\
3509 Comment:"#":"$"::Comment::\n\
3510 Loop Header:"^[ \\t]*loop:":::Loop::\n\
3512 nedit.languageModes: My Language:.my::::::
3513 nedit.styles: Loop:blue:Bold
3515 Resources are in the format of X resource files, but the format of text
3516 within multiple-item resources like highlight patterns, language modes,
3517 macros, styles, etc., are private to NEdit. Each resource is a string which
3518 ends at the first newline character not escaped with \, so you must be
3519 careful about how you treat ends of lines. While you can generally just cut
3520 and paste indented sections, if something which was originally in the middle
3521 of a resource string is now at the end, you must remove the \ line
3522 continuation character(s) so it will not join the next line into the
3523 resource. Conversely, if something which was originally at the end of a
3524 resource is now in the middle, you'll have to add continuation character(s)
3525 to make sure that the resource string is properly continued from beginning to
3526 end, and possibly newline character(s) (\n) to make sure that it is properly
3527 separated from the next item.
3528 ----------------------------------------------------------------------
3533 NEdit has additional options to those provided in the Preferences menu which
3534 are set using X resources. Like most other X programs, NEdit can be
3535 customized to vastly unnecessary proportions, from initial window positions
3536 down to the font and shadow colors of each individual button (A complete
3537 discussion of how to do this is left to books on the X Windows System). Key
3538 binding (see "Key_Binding_" is one of the most useful of these resource
3541 X resources are usually specified in a file called .Xdefaults or .Xresources
3542 in your home directory (on VMS this is sys$login:decw$xdefaults.dat). On
3543 some systems, this file is read and its information attached to the X server
3544 (your screen) when you start X. On other systems, the .Xdefaults file is
3545 read each time you run an X program. When X resource values are attached to
3546 the X server, changes to the resource file are not available to application
3547 programs until you either run the xrdb program with the appropriate file as
3548 input, or re-start the X server.
3550 3>Selected X Resource Names
3552 The following are selected NEdit resource names and default values for NEdit
3553 options not settable via the Preferences menu (for preference resource names,
3554 see your NEdit preference file):
3556 **nedit.tagFile**: (not defined)
3558 This can be the name of a file, or multiple files separated by a colon (:)
3559 character, of the type produced by Exuberant Ctags or the Unix ctags
3560 command, which NEdit will load at startup time (see ctag_support_ ). The tag
3561 file provides a database from which NEdit can automatically open files
3562 containing the definition of a particular subroutine or data type.
3564 **nedit.alwaysCheckRelativeTagsSpecs: True**
3566 When this resource is set to True, and there are tag files specified (with
3567 the nedit.tagFile resource, see above) as relative paths, NEdit will evaluate
3568 these tag value paths whenever a file is opened. All accessible tag files
3569 will be loaded at this time. When this resource value is False, relative path
3570 tag specifications will only be evaluated at NEdit startup time.
3572 **nedit.shell**: /bin/csh
3574 (Unix systems only) The Unix shell (command interpreter) to use for executing
3575 commands from the Shell menu
3577 **nedit.wordDelimiters**: .,/\\`'!@@#%^&*()-=+{}[]":;<>?
3579 The characters, in addition to blanks and tabs, which mark the boundaries
3580 between words for the move-by-word (Ctrl+Arrow) and select-word (double
3581 click) commands. Note that this default value may be overridden by the
3582 setting in Preferences -> Default Settings -> Language Modes....
3584 **nedit.remapDeleteKey**: False
3586 Setting this resource to True forcibly maps the delete key to backspace. This
3587 can be helpful on systems where the bindings have become tangled, and in
3588 environments which mix systems with PC style keyboards and systems with DEC
3589 and Macintosh keyboards. Theoretically, these bindings should be made using
3590 the standard X/Motif mechanisms, outside of NEdit. In practice, some
3591 environments where users access several different systems remotely, can be
3592 very hard to configure. If you've given up and are using a backspace key
3593 halfway off the keyboard because you can't figure out the bindings, set this
3596 **nedit.typingHidesPointer**: False
3598 Setting this resource to True causes the mouse pointer to be hidden when you
3599 type in the text area. As soon as the mouse pointer is moved, it will
3600 reappear. This is useful to stop the mouse pointer from obscuring text.
3602 **nedit.overrideDefaultVirtualKeyBindings**: Auto
3604 Motif uses a virtual key binding mechanism that shares the bindings between
3605 different Motif applications. When a first Motif application is started, it
3606 installs some default virtual key bindings and any other Motif application
3607 that runs afterwards, simply reuses them. Obviously, if the first
3608 application installs an invalid set, all others applications may have
3611 In the past, NEdit has been the victim of invalid bindings installed by other
3612 applications several times. Through this resource, NEdit can be instructed
3613 to ignore the bindings installed by other applications, and use its own
3614 private bindings. By default, NEdit tries to detect invalid bindings
3615 and ignore them automatically (Auto). Optionally, NEdit can be told to
3616 always keep the installed bindings (Never), or to always override them
3619 **nedit.stdOpenDialog**: False
3621 Setting this resource to True restores the standard Motif style of Open
3622 dialog. NEdit file open dialogs are missing a text field at the bottom of
3623 the dialog, where the file name can be entered as a string. The field is
3624 removed in NEdit to encourage users to type file names in the list, a
3625 non-standard, but much faster method for finding files.
3627 **nedit.bgMenuButton**: @~Shift@~Ctrl@~Meta@~Alt<Btn3Down>
3629 Specification for mouse button / key combination to post the background menu
3630 (in the form of an X translation table event specification). The event
3631 specification should be as specific as possible, since it will override less
3632 specific translation table entries.
3634 **nedit.maxPrevOpenFiles**: 30
3636 Number of files listed in the Open Previous sub-menu of the File menu.
3637 Setting this to zero disables the Open Previous menu item and maintenance of
3638 the NEdit file history file.
3640 **nedit.printCommand**: (system specific)
3642 Command used by the print dialog to print a file, such as, lp, lpr, etc..
3643 The command must be capable of accepting input via stdin (standard input).
3645 **nedit.printCopiesOption**: (system specific)
3647 Option name used to specify multiple copies to the print command. If the
3648 option should be separated from its argument by a space, leave a trailing
3649 space. If blank, no "Number of Copies" item will appear in the print dialog.
3651 **nedit.printQueueOption**: (system specific)
3653 Option name used to specify a print queue to the print command. If the
3654 option should be separated from its argument by a space, leave a trailing
3655 space. If blank, no "Queue" item will appear in the print dialog.
3657 **nedit.printNameOption**: (system specific)
3659 Option name used to specify a job name to the print command. If the option
3660 should be separated from its argument by a space, leave a trailing space. If
3661 blank, no job or file name will be attached to the print job or banner page.
3663 **nedit.printHostOption**: (system specific)
3665 Option name used to specify a host name to the print command. If the option
3666 should be separated from its argument by a space, leave a trailing space. If
3667 blank, no "Host" item will appear in the print dialog.
3669 **nedit.printDefaultQueue**: (system specific)
3671 The name of the default print queue. Used only to display in the print
3672 dialog, and has no effect on printing.
3674 **nedit.visualID**: Best
3676 If your screen supports multiple visuals (color mapping models), this
3677 resource allows you to manually choose among them. The default value of
3678 "Best" chooses the deepest (most colors) visual available. Since NEdit does
3679 not depend on the specific characteristics of any given color model, Best
3680 probably IS the best choice for everyone, and the only reason for setting
3681 this resource would be to patch around some kind of X server problem. The
3682 resource may also be set to "Default", which chooses the screen's default
3683 visual (often a color-mapped, PseudoColor, visual for compatibility with
3684 older X applications). It may also be set to a numeric visual-id value (use
3685 xdpyinfo to see the list of visuals supported by your display), or a visual
3686 class name: PseudoColor, DirectColor, TrueColor, etc..
3688 **nedit.installColormap**: False
3690 Force the installation of a private colormap. If you have a humble 8-bit
3691 color display, and netscape is hogging all of the color cells, you may want
3692 to try turning this on. On most systems, this will result in colors flashing
3693 wildly when you switch between NEdit and other applications. But a few
3694 systems (SGI) have hardware support for multiple simultaneous colormaps, and
3695 applications with installed colormaps are well behaved.
3697 **nedit.findReplaceUsesSelection**: False
3699 Controls if the Find and Replace dialogs are automatically loaded with the
3700 contents of the primary selection.
3702 **nedit.stickyCaseSenseButton**: True
3704 Controls if the "Case Sensitive" buttons in the Find and Replace dialogs and
3705 the incremental search bar maintain a separate state for literal and regular
3706 expression searches. Moreover, when set to True, by default literal searches
3707 are case insensitive and regular expression searches are case sensitive. When
3708 set to False, the "Case Sensitive" buttons are independent of the "Regular
3711 **nedit.printDefaultHost**: (system specific)
3713 The node name of the default print host. Used only to display in the print
3714 dialog, and has no effect on printing.
3716 **nedit.multiClickTime**: (system specific)
3718 Maximum time in milliseconds allowed between mouse clicks within double and
3719 triple click actions.
3721 **nedit@*scrollBarPlacement**: BOTTOM_LEFT
3723 How scroll bars are placed in NEdit windows, as well as various lists and
3724 text fields in the program. Other choices are: BOTTOM_RIGHT, TOP_LEFT, or
3727 **nedit@*text.autoWrapPastedText**: False
3729 When Auto Newline Wrap is turned on, apply automatic wrapping (which
3730 normally only applies to typed text) to pasted text as well.
3732 **nedit@*text.heavyCursor**: False
3734 For monitors with poor resolution or users who have difficulty seeing the
3735 cursor, makes the cursor in the text editing area of the window heavier and
3738 **nedit@*text.foreground**: black
3740 Foreground color of the text editing area of the NEdit window.
3742 **nedit@*text.background**: white
3744 Background color of the text editing area of the NEdit window.
3746 **nedit@*text.selectForeground**: black
3748 Foreground (text) color for selections in the text editing area of the NEdit
3751 **nedit@*text.selectBackground**: gray80
3753 Color for selections in the text editing area of the NEdit window.
3755 **nedit@*text.highlightForeground**: white
3757 Foreground (text) color for highlights (parenthesis flashing) in the text
3758 editing area of the NEdit window.
3760 **nedit@*text.highlightBackground**: red
3762 Color for highlights (parenthesis flashing) in the text editing area of the
3765 **nedit@*text.cursorForeground**: black
3767 Color for text cursor in the text editing area of the NEdit window.
3769 **nedit@*text.lineNumForeground**: gray47
3771 Color for displaying line numbers in the NEdit window.
3773 **nedit@*text.blinkRate**: 500
3775 Blink rate of the text insertion cursor in milliseconds. Set to zero to stop
3778 **nedit@*text.Translations**:
3780 Modifies key bindings (see below).
3782 **nedit@*foreground**: black
3784 Default foreground color for menus, dialogs, scroll bars, etc..
3786 **nedit@*background**: #b3b3b3
3788 Default background color for menus, dialogs, scroll bars, etc..
3790 **nedit@*fontList**: helvetica medium 12 points
3792 Default font for menus, dialogs, scroll bars, etc..
3794 **nedit.helpFont**: helvetica medium 12 points
3796 Font used for displaying online help.
3798 **nedit.boldHelpFont**: helvetica bold 12 points
3800 Bold font for online help.
3802 **nedit.italicHelpFont**: helvetica italic 12 points
3804 Italic font for online help.
3806 **nedit.fixedHelpFont**: courier medium 12 points
3808 Fixed font for online help.
3810 **nedit.boldFixedHelpFont**: courier bold 12 points
3812 Fixed bold for online help.
3814 **nedit.italicFixedHelpFont**: courier italic 12 points
3816 Fixed italic font for online help.
3818 **nedit.h1HelpFont**: helvetica bold 14 points
3820 Font for level-1 titles in help text.
3822 **nedit.h2HelpFont**: helvetica bold italic 12 points
3824 Font for level-2 titles in help text.
3826 **nedit.h3HelpFont**: courier bold 12 points
3828 Font for level-3 titles in help text.
3830 **nedit.helpLinkFont**: helvetica medium 12 points
3832 Font for hyperlinks in the help text
3834 **nedit.helpLinkColor**: #009900
3836 Color for hyperlinks in the help text
3838 **nc.autoStart**: True
3840 Whether the nc program should automatically start an NEdit server (without
3841 prompting the user) if an appropriate server is not found.
3843 **nc.serverCommand**: nedit -server
3845 Command used by the nc program to start an NEdit server.
3847 ----------------------------------------------------------------------
3848 ~The following are Selected widget names (to which you may append~
3849 ~.background, .foreground, .fontList, etc., to change colors, fonts~
3850 ~ and other characteristics):~
3852 **nedit@*statsAreaForm**
3854 Statistics line and incremental search bar. To get consistent results across
3855 the entire stats line and the incremental search bar, use '*' rather than '.'
3856 to separate the resource name. For example, to set the foreground color of
3857 both components use:
3858 nedit*statsAreaForm*foreground
3860 nedit*statsAreaForm.foreground
3864 Top-of-window menu-bar.
3866 **nedit@*textHorScrollBar**
3868 Horizontal scroll bar.
3870 **nedit@*textVertScrollBar**
3872 Vertical scroll bar.
3877 ----------------------------------------------------------------------
3882 There are several ways to change key bindings in NEdit. The easiest way to
3883 add a new key binding in NEdit is to define a macro in Preferences -> Default
3884 Settings -> Customize Menus -> Macro Menu. However, if you want to change
3885 existing bindings or add a significant number of new key bindings you will
3886 need to do so via X resources.
3888 Before reading this section, you must understand how to set X resources (see
3889 the help section "X_Resources_"). Since setting X resources is tricky, it is
3890 also helpful when working on key-binding, to set some easier-to-verify
3891 resource at the same time, as a simple check that the NEdit program is
3892 actually seeing your changes. The appres program is also very helpful in
3893 checking that the resource settings that you make, actually reach the program
3894 for which they are intended in the correct form.
3896 3>Key Binding in General
3898 Keyboard commands are associated with editor action routines through two
3899 separate mechanisms in NEdit. Commands which appear in pull-down menus have
3900 individual resources designating a keyboard equivalent to the menu command,
3901 called an accelerator key. Commands which do not have an associated menu
3902 item are bound to keys via the X toolkit translation mechanism. The methods
3903 for changing these two kinds of bindings are quite different.
3905 3>Key Binding Via Translations
3907 The most general way to bind actions to keys in NEdit is to use the
3908 translation table associated with the text widget. To add a binding to Alt+Y
3909 to insert the string "Hi!", for example, add lines similar to the following
3910 to your X resource file:
3912 NEdit*text.Translations: #override \n\
3913 Alt<Key>y: insert_string("Hi!") \n
3915 The Help topic "Action_Routines_" lists the actions available to be bound.
3917 Translation tables map key and mouse presses, window operations, and other
3918 kinds of events, to actions. The syntax for translation tables is
3919 simplified here, so you may need to refer to a book on the X window system
3920 for more detailed information.
3922 Note that accelerator resources (discussed below) override translations, and
3923 that most Ctrl+letter and Alt+letter combinations are already bound to an
3924 accelerator key. To use one of these combinations from a translation table,
3925 therefore, you must first un-bind the original menu accelerator.
3927 A resource for changing a translation table consists of a keyword; #override,
3928 #augment, or #replace; followed by lines (separated by newline characters)
3929 pairing events with actions. Events begin with modifiers, like Ctrl, Shift,
3930 or Alt, followed by the event type in <>. BtnDown, Btn1Down, Btn2Down,
3931 Btn1Up, Key, KeyUp are valid event types. For key presses, the event type is
3932 followed by the name of the key. You can specify a combination of events,
3933 such as a sequence of key presses, by separating them with commas. The other
3934 half of the event/action pair is a set of actions. These are separated from
3935 the event specification by a colon and from each other by spaces. Actions
3936 are names followed by parentheses, optionally containing one or more
3937 parameters separated by comas.
3939 3>Changing Menu Accelerator Keys
3941 The menu shortcut keys shown at the right of NEdit menu items can also be
3942 changed via X resources. Each menu item has two resources associated with
3943 it, accelerator, the event to trigger the menu item; and acceleratorText, the
3944 string shown in the menu. The form of the accelerator resource is the same
3945 as events for translation table entries discussed above, though multiple keys
3946 and other subtleties are not allowed. The resource name for a menu is the
3947 title in lower case, followed by "Menu", the resource name of menu item is
3948 the name in lower case, run together, with words separated by caps, and all
3949 punctuation removed. For example, to change Cut to Ctrl+X, you would add the
3950 following to your .Xdefaults file:
3952 nedit*editMenu.cut.accelerator: Ctrl<Key>x
3953 nedit*editMenu.cut.acceleratorText: Ctrl+X
3955 Accelerator keys with optional shift key modifiers, like Find..., have an
3956 additional accelerator resource with Shift appended to the name. For
3959 nedit*searchMenu.find.acceleratorText: [Shift]Alt+F
3960 nedit*searchMenu.find.accelerator: Alt<Key>f
3961 nedit*searchMenu.findShift.accelerator: Shift Alt<Key>f
3962 ----------------------------------------------------------------------
3964 Highlighting Patterns
3965 ---------------------
3967 3>Writing Syntax Highlighting Patterns
3969 Patterns are the mechanism by which language syntax highlighting is
3970 implemented in NEdit (see Syntax_Highlighting_ under the heading of Features
3971 for Programming). To create syntax highlighting patterns for a new
3972 language, or to modify existing patterns, select "Recognition Patterns" from
3973 "Syntax Highlighting" sub-section of the "Default Settings" sub-menu of the
3976 First, a word of caution. As with regular expression matching in general, it
3977 is quite possible to write patterns which are so inefficient that they
3978 essentially lock up the editor as they recursively re-examine the entire
3979 contents of the file thousands of times. With the multiplicity of patterns,
3980 the possibility of a lock-up is significantly increased in syntax
3981 highlighting. When working on highlighting patterns, be sure to save your
3984 NEdit's syntax highlighting is unusual in that it works in real-time (as you
3985 type), and yet is completely programmable using standard regular expression
3986 notation. Other syntax highlighting editors usually fall either into the
3987 category of fully programmable but unable to keep up in real-time, or
3988 real-time but limited programmability. The additional burden that NEdit
3989 places on pattern writers in order to achieve this speed/flexibility mix, is
3990 to force them to state self-imposed limitations on the amount of context that
3991 patterns may examine when re-parsing after a change. While the "Pattern
3992 Context Requirements" heading is near the end of this section, it is not
3993 optional, and must be understood before making any any serious effort at
3996 In its simplest form, a highlight pattern consists of a regular expression to
3997 match, along with a style representing the font an color for displaying any
3998 text which matches that expression. To bold the word, "highlight", wherever
3999 it appears the text, the regular expression simply would be the word
4000 "highlight". The style (selected from the menu under the heading of
4001 "Highlight Style") determines how the text will be drawn. To bold the text,
4002 either select an existing style, such as "Keyword", which bolds text, or
4003 create a new style and select it under Highlight Style.
4005 The full range of regular expression capabilities can be applied in such a
4006 pattern, with the single caveat that the expression must conclusively match
4007 or not match, within the pre-defined context distance (as discussed below
4008 under Pattern Context Requirements).
4010 To match longer ranges of text, particularly any constructs which exceed the
4011 requested context, you must use a pattern which highlights text between a
4012 starting and ending regular expression match. To do so, select "Highlight
4013 text between starting and ending REs" under "Matching", and enter both a
4014 starting and ending regular expression. For example, to highlight everything
4015 between double quotes, you would enter a double quote character in both the
4016 starting and ending regular expression fields. Patterns with both a
4017 beginning and ending expression span all characters between the two
4018 expressions, including newlines.
4020 Again, the limitation for automatic parsing to operate properly is that both
4021 expressions must match within the context distance stated for the pattern
4024 With the ability to span large distances, comes the responsibility to recover
4025 when things go wrong. Remember that syntax highlighting is called upon to
4026 parse incorrect or incomplete syntax as often as correct syntax. To stop a
4027 pattern short of matching its end expression, you can specify an error
4028 expression, which stops the pattern from gobbling up more than it should.
4029 For example, if the text between double quotes shouldn't contain newlines,
4030 the error expression might be "$". As with both starting and ending
4031 expressions, error expressions must also match within the requested context
4034 4>Coloring Sub-Expressions
4036 It is also possible to color areas of text within a regular expression
4037 match. A pattern of this type associates a style with sub-expressions
4038 references of the parent pattern (as used in regular expression substitution
4039 patterns, see the NEdit Help menu item on Regular_Expressions_).
4040 Sub-expressions of both the starting and ending patterns may be colored. For
4041 example, if the parent pattern has a starting expression "\<", and end
4042 expression "\>", (for highlighting all of the text contained within angle
4043 brackets), a sub-pattern using "&" in both the starting and ending expression
4044 fields could color the brackets differently from the intervening text. A
4045 quick shortcut to typing in pattern names in the Parent Pattern field is to
4046 use the middle mouse button to drag them from the Patterns list.
4048 4>Hierarchical Patterns
4050 A hierarchical sub-pattern, is identical to a top level pattern, but is
4051 invoked only between the beginning and ending expression matches of its
4052 parent pattern. Like the sub-expression coloring patterns discussed above,
4053 it is associated with a parent pattern using the Parent Pattern field in the
4054 pattern specification. Pattern names can be dragged from the pattern list
4055 with the middle mouse button to the Parent Pattern field.
4057 After the start expression of the parent pattern matches, the syntax
4058 highlighting parser searches for either the parent's end pattern or a
4059 matching sub-pattern. When a sub-pattern matches, control is not returned to
4060 the parent pattern until the entire sub-pattern has been parsed, regardless
4061 of whether the parent's end pattern appears in the text matched by the
4064 The most common use for this capability is for coloring sub-structure of
4065 language constructs (smaller patterns embedded in larger patterns).
4066 Hierarchical patterns can also simplify parsing by having sub-patterns "hide"
4067 special syntax from parent patterns, such as special escape sequences or
4070 There is no depth limit in nesting hierarchical sub-patterns, but beyond the
4071 third level of nesting, automatic re-parsing will sometimes have to re-parse
4072 more than the requested context distance to guarantee a correct parse (which
4073 can slow down the maximum rate at which the user can type if large sections
4074 of text are matched only by deeply nested patterns).
4076 While this is obviously not a complete hierarchical language parser it is
4077 still useful in many text coloring situations. As a pattern writer, your
4078 goal is not to completely cover the language syntax, but to generate
4079 colorings that are useful to the programmer. Simpler patterns are usually
4080 more efficient and also more robust when applied to incorrect code.
4082 4>Deferred (Pass-2) Parsing
4084 NEdit does pattern matching for syntax highlighting in two passes. The first
4085 pass is applied to the entire file when syntax highlighting is first turned
4086 on, and to new ranges of text when they are initially read or pasted in. The
4087 second pass is applied only as needed when text is exposed (scrolled in to
4090 If you have a particularly complex set of patterns, and parsing is beginning
4091 to add a noticeable delay to opening files or operations which change large
4092 regions of text, you can defer some of that parsing from startup time, to
4093 when it is actually needed for viewing the text. Deferred parsing can only
4094 be used with single expression patterns, or begin/end patterns which match
4095 entirely within the requested context distance. To defer the parsing of a
4096 pattern to when the text is exposed, click on the Pass-2 pattern type button
4097 in the highlight patterns dialog.
4099 Sometimes a pattern can't be deferred, not because of context requirements,
4100 but because it must run concurrently with pass-1 (non-deferred) patterns. If
4101 they didn't run concurrently, a pass-1 pattern might incorrectly match some
4102 of the characters which would normally be hidden inside of a sequence matched
4103 by the deferred pattern. For example, C has character constants enclosed in
4104 single quotes. These typically do not cross line boundaries, meaning they
4105 can be parsed entirely within the context distance of the C pattern set and
4106 should be good candidates for deferred parsing. However, they can't be
4107 deferred because they can contain sequences of characters which can trigger
4108 pass-one patterns. Specifically, the sequence, '\"', contains a double quote
4109 character, which would be matched by the string pattern and interpreted as
4110 introducing a string.
4112 4>Pattern Context Requirements
4114 The context requirements of a pattern set state how much additional text
4115 around any change must be examined to guarantee that the patterns will match
4116 what they are intended to match. Context requirements are a promise by NEdit
4117 to the pattern writer, that the regular expressions in his/her patterns will
4118 be matched against at least <line context> lines and <character context>
4119 characters, around any modified text. Combining line and character
4120 requirements guarantee that both will be met.
4122 Automatic re-parsing happens on EVERY KEYSTROKE, so the amount of context
4123 which must be examined is very critical to typing efficiency. The more
4124 complicated your patterns, the more critical the context becomes. To cover
4125 all of the keywords in a typical language, without affecting the maximum rate
4126 at which users can enter text, you may be limited to just a few lines and/or
4127 a few hundred characters of context.
4129 The default context distance is 1 line, with no minimum character
4130 requirement. There are several benefits to sticking with this default. One
4131 is simply that it is easy to understand and to comply with. Regular
4132 expression notation is designed around single line matching. To span lines
4133 in a regular expression, you must explicitly mention the newline character
4134 "\n", and matches which are restricted to a single line are virtually immune
4135 to lock-ups. Also, if you can code your patterns to work within a single
4136 line of context, without an additional character-range context requirement,
4137 the parser can take advantage the fact that patterns don't cross line
4138 boundaries, and nearly double its efficiency over a one-line and 1-character
4139 context requirement. (In a single line context, you are allowed to match
4140 newlines, but only as the first and/or last character.)
4141 ----------------------------------------------------------------------
4146 Smart indent macros can be written for any language, but are usually more
4147 difficult to write than highlighting patterns. A good place to start, of
4148 course, is to look at the existing macros for C and C++.
4150 Smart indent macros for a language mode consist of standard NEdit macro
4151 language code attached to any or all of the following three activation
4152 conditions: 1) When smart indent is first turned on for a text window
4153 containing code of the language, 2) When a newline is typed and smart indent
4154 is expected, 3) after any character is typed. To attach macro code to any of
4155 these code "hooks", enter it in the appropriate section in the Preferences ->
4156 Default Settings -> Auto Indent -> Program Smart Indent dialog.
4158 Typically most of the code should go in the initialization section, because
4159 that is the appropriate place for subroutine definitions, and smart indent
4160 macros are complicated enough that you are not likely to want to write them
4161 as one monolithic run of code. You may also put code in the Common/Shared
4162 Initialization section (accessible through the button in the upper left
4163 corner of the dialog). Unfortunately, since the C/C++ macros also reside in
4164 the common/shared section, when you add code there, you run some risk of
4165 missing out on future upgrades to these macros, because your changes will
4166 override the built-in defaults.
4168 The newline macro is invoked after the user types a newline, but before the
4169 newline is entered in the buffer. It takes a single argument ($1) which is
4170 the position at which the newline will be inserted. It must return the
4171 number of characters of indentation the line should have, or -1. A return
4172 value of -1 means to do a standard auto-indent. You must supply a newline
4173 macro, but the code: "return -1" (auto-indent), or "return 0" (no indent) is
4176 The type-in macro takes two arguments. $1 is the insert position, and $2 is
4177 the character just inserted, and does not return a value. You can do just
4178 about anything here, but keep in mind that this macro is executed for every
4179 keystroke typed, so if you try to get too fancy, you may degrade performance.
4180 ----------------------------------------------------------------------
4185 .. ? help !!#ifndef VMS
4186 **nedit** [-**read**] [-**create**] [-**line** n | +n] [-**server**]
4187 [-**do** command] [-**tags** file] [-**tabs** n] [-**wrap**]
4188 [-**nowrap**] [-**autowrap**] [-**autoindent**] [-**noautoindent**]
4189 [-**autosave**] [-**noautosave**] [-**rows** n] [-**columns** n]
4190 [-**font** font] [-**lm** languagemode] [-**geometry** geometry]
4191 [-**iconic**] [-**noiconic**] [-**display** [host]:server[.screen]
4192 [-**xrm** resourcestring] [-**svrname** name] [-**import** file]
4193 [-**background** color] [-**foreground** color] [-**V**|-**version**]
4197 Open the file Read Only regardless of the actual file protection.
4200 Don't warn about file creation when a file doesn't exist.
4206 Designate this session as an NEdit server, for processing commands from the
4207 nc program. nc can be used to interface NEdit to code development
4208 environments, mailers, etc., or just as a quick way to open files from the
4209 shell command line without starting a new NEdit session.
4212 Execute an NEdit macro or action. On each file following the -do argument on
4213 the command line. -do is particularly useful from the nc program, where nc
4214 -do can remotely execute commands in an NEdit -server session.
4217 Load a file of directions for finding definitions of program subroutines and
4218 data objects. The file must be of the format gen- erated by Exuberant Ctags,
4219 or the standard Unix ctags command.
4222 Set tab stops every n characters.
4225 Wrap long lines at the right edge of the window rather than continuing them
4226 past it. (Continuous Wrap mode)
4228 **-autowrap, -noautowrap**
4229 Wrap long lines when the cursor reaches the right edge of the window by
4230 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4232 **-autoindent, -noautoindent**
4233 Maintain a running indent.
4235 **-autosave, -noautosave**
4236 Maintain a backup copy of the file being edited under the name '~filename'.
4239 Default height in characters for an editing window.
4242 Default width in characters for an editing window.
4244 **-font font (or -fn font)**
4245 Font for text being edited (Font for menus and dialogs can be set with -xrm
4248 **-lm languagemode**
4249 Initial language mode used for editing succeeding files.
4251 **-geometry geometry (or -g geometry)**
4252 The initial size and/or location of editor windows. The argument geometry
4255 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4257 where <width> and <height> are the desired width and height of the window,
4258 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4259 the window, + for top or left, - for bottom or right. -geometry can be
4260 specified for individual files on the command line.
4262 **-iconic, -noiconic**
4263 Initial window state for succeeding files.
4265 **-display [host]:server[.screen]**
4266 The name of the X server to use. host specifies the machine, server
4267 specifies the display server number, and screen specifies the screen number.
4268 host or screen can be omitted and default to the local machine, and screen 0.
4270 **-background color (or -bg color)**
4271 Background color. (background color for text can be set separately with
4272 -xrm "nedit*text.background: color").
4274 **-foreground color (or -fg color)**
4275 Foreground color. (foreground color for text can be set separately with -xrm
4276 "nedit*text.foreground: color").
4278 **-xrm resourcestring**
4279 Set the value of an X resource to override a default
4280 value (see "Customizing_NEdit_").
4283 When starting NEdit in server mode, name the server, such that it responds to
4284 requests only when nc is given a corresponding -svrname argument. By naming
4285 servers, you can run several simultaneously, and direct files and commands
4286 specifically to any one.
4289 Loads an additional preferences file on top of the existing defaults saved in
4290 your preferences file. To incorporate macros, language modes, and highlight
4291 patterns and styles written by other users, run NEdit with -import <file>,
4292 then re-save your preference file with Preferences -> Save Defaults.
4295 Prints out the NEdit version information. The -V option is synonymous.
4298 Treats all subsequent arguments as file names, even if they start with a
4299 dash. This is so NEdit can access files that begin with the dash character.
4304 .. This documentation for VMS NEdit usage should only appear in the
4305 .. generated help code, not in any of the printed documentation.
4306 .. Reasoning is that VMS usage is diminishing and there is a desire
4307 .. to not clutter up the printed documentation here.
4309 NEDIT [filespec[,...]]
4311 The following qualifiers are accepted:
4314 Open the file Read Only regardless of the actual file protection.
4317 Don't warn about file creation when a file doesn't exist.
4323 Designate this session as an NEdit server for processing commands from the nc
4324 program. The nc program can be used to interface NEdit to code development
4325 environments, mailers, etc., or just as a quick way to open files from the
4326 shell command line without starting a new NEdit session.
4329 Execute an NEdit action routine. on each file following the /do argument on
4330 the command line. /do is particularly useful from the nc program, where nc
4331 /do can remotely execute commands in an nedit /server session.
4334 Load a file of directions for finding definitions of program subroutines and
4335 data objects. The file must be of the format generated by the Unix ctags
4339 Wrap long lines at the right edge of the window rather than continuing them
4340 past it. (Continuous Wrap mode)
4342 **/autowrap, /noautowrap**
4343 Wrap long lines when the cursor reaches the right edge of the window by
4344 inserting newlines at word boundaries. (Auto Newline Wrap mode)
4346 **/autoindent, /noautoindent**
4347 Maintain a running indent.
4349 **/autosave, /noautosave**
4350 Maintain a backup copy of the file being edited under the name '_filename'.
4353 Default width in characters for an editing window.
4356 Default height in characters for an editing window.
4358 **/font=font (or /fn=font)**
4359 Font for text being edited (Font for menus and dialogs can be set with
4360 /xrm="*fontList:font").
4362 **/display [host]:server[.screen]**
4363 The name of the X server to use. host specifies the machine, server
4364 specifies the display server number, and screen specifies the screen number.
4365 host or screen can be omitted and default to the local machine, and screen 0.
4367 **/geometry=geometry (or /g=geometry)**
4368 The initial size and/or location of editor windows. The argument geometry
4371 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>]
4373 where <width> and <height> are the desired width and height of the window,
4374 and <xoffset> and <yoffset> are the distance from the edge of the screen to
4375 the window, + for top or left, - for bottom or right.
4377 **/background=color (or /bg=color)**
4379 Background color. (background color for text can be set separately with
4380 /xrm="nedit*text:background color").
4382 **/foreground=color (or /fg=color)**
4383 Foreground color. (foreground color for text can be set separately with
4384 /xrm="nedit*text:foreground color").
4386 **/xrm=resourcestring**
4387 Set the value of an X resource to override a default value
4388 (see Customizing NEdit).
4391 When starting nedit in server mode, name the server, such that it responds to
4392 requests only when nc is given a corresponding -svrname argument. By naming
4393 servers, you can run several simultaneously, and direct files and commands
4394 specifically to any one.
4397 Loads an additional preferences file on top of the existing defaults saved in
4398 your .nedit file. To incorporate macros, language modes, and highlight
4399 patterns and styles written by other users, run nedit with /import=<file>,
4400 then re-save your .nedit file with Preferences -> Save Defaults.
4402 Unix-style command lines (but not file names) are also acceptable:
4404 nedit -rows 20 -wrap file1.c file2.c
4408 nedit /rows=20/wrap file1.c, file2.c",
4411 ----------------------------------------------------------------------
4416 NEdit can be operated on its own, or as a two-part client/server
4417 application. Client/server mode is useful for integrating NEdit with
4418 software development environments, mailers, and other programs; or just as a
4419 quick way to open files from the shell command line without starting a new
4422 To run NEdit in server mode, type:
4426 NEdit can also be started in server mode via the Nedit Client (nc) program
4427 when no servers are available.
4429 The nc program, which is distributed along with NEdit,
4430 sends commands to an nedit server to open files, select lines, or execute
4431 editor actions. It accepts a limited set of the nedit command line options:
4432 -read, -create, -line (or +n), -do, and a list of file names. Listing a file
4433 on the nc command line means, open it if it is not already open and bring the
4434 window to the front. -read and -create affect only newly opened files, but
4435 -line and -do can also be used on files which are already open
4436 (See "NEdit_Command_Line_" for more information).
4438 In typical Unix style, arguments affect the files which follow them on the
4439 command line, for example:
4441 incorrect: nc file.c -line 25
4442 correct: nc -line 25 file.c
4444 -read, -create, and -line affect all of the files which follow them on the
4445 command line. The -do macro is executed only once, on the next file on the
4446 line. -do without a file following it on the command line, executes the
4447 macro on the first available window (presumably when you give a -do command
4448 without a corresponding file or window, you intend it to do something
4449 independent of the window in which it happens to execute).
4451 nc also accepts one command line option of its own, -noask (or -ask), which
4452 instructs it whether to automatically start a server if one is not
4453 available. This is also settable via the X resource, nc.autoStart
4454 (See "X_Resources_" section).
4456 Sometimes it is useful to have more than one NEdit server running, for
4457 example to keep mail and programming work separate. The option, -svrname, to
4458 both nedit and nc, allows you to start, and communicate with, separate named
4459 servers. A named server responds only to requests with the corresponding
4460 -svrname argument. If you use ClearCase and are within a ClearCase view, the
4461 server name will default to the name of the view (based on the value of the
4462 CLEARCASE_ROOT environment variable).
4464 Communication between nc and nedit is through the X display. So as long as X
4465 windows is set up and working properly, nc will work properly as well.
4466 nc uses the DISPLAY environment variable, the machine name and your user name
4467 to find the appropriate server, meaning, if you have several machines sharing
4468 a common file system, nc will not be able to find a server that is running on
4469 a machine with a different host name, even though it may be perfectly
4470 appropriate for editing a given file.
4472 The command which nc uses to start an nedit server is settable via the X
4473 resource nc.serverCommand, by default, "nedit -server".
4474 ----------------------------------------------------------------------
4479 If a system crash, network failure, X server crash, or program error should
4480 happen while you are editing a file, you can still recover most of your
4481 work. NEdit maintains a backup file which it updates periodically (every 8
4482 editing operations or 80 characters typed). This file has the same name
4483 as the file that you are editing, but with the character `~' (tilde) on Unix
4484 or `_' (underscore) on VMS prefixed to the name. To recover a file after a
4485 crash, simply rename the file to remove the tilde or underscore character,
4486 replacing the older version of the file. (Because several of the Unix shells
4487 consider the tilde to be a special character, you may have to prefix the
4488 character with a `\' (backslash) when you move or delete an NEdit backup
4491 Example, to recover the file called "help.c" on Unix type the command:
4495 A minor caveat, is that if the file you were editing was in MS DOS format,
4496 the backup file will be in Unix format, and you will need to open the backup
4497 file in NEdit and change the file format back to MS DOS via the Save As...
4498 dialog (or use the Unix unix2dos command outside of NEdit).
4499 ----------------------------------------------------------------------
4510 .. There is build time versioning information that is handled specially
4511 .. inside help.c for this section. It needs to have a '%s' string
4512 .. made available for it to appear in the on-line help.
4516 .. ======================================================================
4517 .. The policy for credit so far is this:
4519 .. You get "written by" credit if you have contributed significant
4520 .. code or effort to the project.
4522 .. You get a syntax/indent credit if your pattern is compiled into the
4524 .. ======================================================================
4526 NEdit was written by Mark Edel, Joy Kyriakopulos, Christopher Conrad,
4527 Jim Clark, Arnulfo Zepeda-Navratil, Suresh Ravoor, Tony Balinski, Max
4528 Vohlken, Yunliang Yu, Donna Reid, Arne Førlie, Eddy De Greef, Steve
4529 LoBasso, Alexander Mai, Scott Tringali, Thorsten Haude, and Steve Haehn.
4531 The regular expression matching routines used in NEdit are adapted (with
4532 permission) from original code written by Henry Spencer at the
4533 University of Toronto.
4535 Syntax highlighting patterns and smart indent macros were contributed by:
4536 Simon T. MacDonald, Maurice Leysens, Matt Majka, Alfred Smeenk,
4537 Alain Fargues, Christopher Conrad, Scott Markinson, Konrad Bernloehr,
4538 Ivan Herman, Patrice Venant, Christian Denat, Philippe Couton,
4539 Max Vohlken, Markus Schwarzenberg, Himanshu Gohel, Steven C. Kapp,
4540 Michael Turomsha, John Fieber, Chris Ross, Nathaniel Gray, Joachim Lous,
4541 Mike Duigou, Seak Teng-Fong, Joor Loohuis, Mark Jones,
4542 and Niek van den Berg.
4544 NEdit sources, executables, additional documentation, and contributed
4545 software are available from the NEdit web site at http://www.nedit.org_.
4547 This program is free software; you can redistribute it and/or
4548 modify it under the terms of the GNU General Public License
4549 as published by the Free Software Foundation; either version 2
4550 of the License, or (at your option) any later version.
4552 This program is distributed in the hope that it will be useful,
4553 but WITHOUT ANY WARRANTY; without even the implied warranty of
4554 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4555 GNU General Public License in the Help section "Distribution_Policy_"
4557 ----------------------------------------------------------------------
4562 GNU GENERAL PUBLIC LICENSE
4564 Version 2, June 1991
4566 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave,
4567 Cambridge, MA 02139, USA. Everyone is permitted to copy and distribute
4568 verbatim copies of this license document, but changing it is not allowed.
4572 The licenses for most software are designed to take away your freedom to
4573 share and change it. By contrast, the GNU General Public License is intended
4574 to guarantee your freedom to share and change free software--to make sure the
4575 software is free for all its users. This General Public License applies to
4576 most of the Free Software Foundation's software and to any other program
4577 whose authors commit to using it. (Some other Free Software Foundation
4578 software is covered by the GNU Library General Public License instead.) You
4579 can apply it to your programs, too.
4581 When we speak of free software, we are referring to freedom, not price. Our
4582 General Public Licenses are designed to make sure that you have the freedom
4583 to distribute copies of free software (and charge for this service if you
4584 wish), that you receive source code or can get it if you want it, that you
4585 can change the software or use pieces of it in new free programs; and that
4586 you know you can do these things.
4588 To protect your rights, we need to make restrictions that forbid anyone to
4589 deny you these rights or to ask you to surrender the rights. These
4590 restrictions translate to certain responsibilities for you if you distribute
4591 copies of the software, or if you modify it.
4593 For example, if you distribute copies of such a program, whether gratis or
4594 for a fee, you must give the recipients all the rights that you have. You
4595 must make sure that they, too, receive or can get the source code. And you
4596 must show them these terms so they know their rights.
4598 We protect your rights with two steps: (1) copyright the software, and (2)
4599 offer you this license which gives you legal permission to copy, distribute
4600 and/or modify the software.
4602 Also, for each author's protection and ours, we want to make certain that
4603 everyone understands that there is no warranty for this free software. If the
4604 software is modified by someone else and passed on, we want its recipients to
4605 know that what they have is not the original, so that any problems introduced
4606 by others will not reflect on the original authors' reputations.
4608 Finally, any free program is threatened constantly by software patents. We
4609 wish to avoid the danger that redistributors of a free program will
4610 individually obtain patent licenses, in effect making the program
4611 proprietary. To prevent this, we have made it clear that any patent must be
4612 licensed for everyone's free use or not licensed at all.
4614 The precise terms and conditions for copying, distribution and modification
4617 GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
4620 0. This License applies to any program or other work which contains a notice
4621 placed by the copyright holder saying it may be distributed under the terms
4622 of this General Public License. The "Program", below, refers to any such
4623 program or work, and a "work based on the Program" means either the Program
4624 or any derivative work under copyright law: that is to say, a work containing
4625 the Program or a portion of it, either verbatim or with modifications and/or
4626 translated into another language. (Hereinafter, translation is included
4627 without limitation in the term "modification".) Each licensee is addressed as
4630 Activities other than copying, distribution and modification are not covered
4631 by this License; they are outside its scope. The act of running the Program
4632 is not restricted, and the output from the Program is covered only if its
4633 contents constitute a work based on the Program (independent of having been
4634 made by running the Program). Whether that is true depends on what the
4637 1. You may copy and distribute verbatim copies of the Program's source code
4638 as you receive it, in any medium, provided that you conspicuously and
4639 appropriately publish on each copy an appropriate copyright notice and
4640 disclaimer of warranty; keep intact all the notices that refer to this
4641 License and to the absence of any warranty; and give any other recipients of
4642 the Program a copy of this License along with the Program.
4644 You may charge a fee for the physical act of transferring a copy, and you may
4645 at your option offer warranty protection in exchange for a fee.
4647 2. You may modify your copy or copies of the Program or any portion of it,
4648 thus forming a work based on the Program, and copy and distribute such
4649 modifications or work under the terms of Section 1 above, provided that you
4650 also meet all of these conditions:
4652 a) You must cause the modified files to carry prominent notices stating
4653 that you changed the files and the date of any change.
4655 b) You must cause any work that you distribute or publish, that in whole or
4656 in part contains or is derived from the Program or any part thereof, to be
4657 licensed as a whole at no charge to all third parties under the terms of
4660 c) If the modified program normally reads commands interactively when run,
4661 you must cause it, when started running for such interactive use in the
4662 most ordinary way, to print or display an announcement including an
4663 appropriate copyright notice and a notice that there is no warranty (or
4664 else, saying that you provide a warranty) and that users may redistribute
4665 the program under these conditions, and telling the user how to view a copy
4666 of this License. (Exception: if the Program itself is interactive but does
4667 not normally print such an announcement, your work based on the Program is
4668 not required to print an announcement.)
4670 These requirements apply to the modified work as a whole. If identifiable
4671 sections of that work are not derived from the Program, and can be reasonably
4672 considered independent and separate works in themselves, then this License,
4673 and its terms, do not apply to those sections when you distribute them as
4674 separate works. But when you distribute the same sections as part of a whole
4675 which is a work based on the Program, the distribution of the whole must be
4676 on the terms of this License, whose permissions for other licensees extend to
4677 the entire whole, and thus to each and every part regardless of who wrote it.
4679 Thus, it is not the intent of this section to claim rights or contest your
4680 rights to work written entirely by you; rather, the intent is to exercise the
4681 right to control the distribution of derivative or collective works based on
4684 In addition, mere aggregation of another work not based on the Program with
4685 the Program (or with a work based on the Program) on a volume of a storage or
4686 distribution medium does not bring the other work under the scope of this
4689 3. You may copy and distribute the Program (or a work based on it, under
4690 Section 2) in object code or executable form under the terms of Sections 1
4691 and 2 above provided that you also do one of the following:
4693 a) Accompany it with the complete corresponding machine-readable source
4694 code, which must be distributed under the terms of Sections 1 and 2 above
4695 on a medium customarily used for software interchange; or,
4697 b) Accompany it with a written offer, valid for at least three years, to
4698 give any third party, for a charge no more than your cost of physically
4699 performing source distribution, a complete machine-readable copy of the
4700 corresponding source code, to be distributed under the terms of Sections 1
4701 and 2 above on a medium customarily used for software interchange; or,
4703 c) Accompany it with the information you received as to the offer to
4704 distribute corresponding source code. (This alternative is allowed only for
4705 noncommercial distribution and only if you received the program in object
4706 code or executable form with such an offer, in accord with Subsection b
4709 The source code for a work means the preferred form of the work for making
4710 modifications to it. For an executable work, complete source code means all
4711 the source code for all modules it contains, plus any associated interface
4712 definition files, plus the scripts used to control compilation and
4713 installation of the executable. However, as a special exception, the source
4714 code distributed need not include anything that is normally distributed (in
4715 either source or binary form) with the major components (compiler, kernel,
4716 and so on) of the operating system on which the executable runs, unless that
4717 component itself accompanies the executable.
4719 If distribution of executable or object code is made by offering access to
4720 copy from a designated place, then offering equivalent access to copy the
4721 source code from the same place counts as distribution of the source code,
4722 even though third parties are not compelled to copy the source along with the
4725 4. You may not copy, modify, sublicense, or distribute the Program except as
4726 expressly provided under this License. Any attempt otherwise to copy, modify,
4727 sublicense or distribute the Program is void, and will automatically
4728 terminate your rights under this License. However, parties who have received
4729 copies, or rights, from you under this License will not have their licenses
4730 terminated so long as such parties remain in full compliance.
4732 5. You are not required to accept this License, since you have not signed it.
4733 However, nothing else grants you permission to modify or distribute the
4734 Program or its derivative works. These actions are prohibited by law if you
4735 do not accept this License. Therefore, by modifying or distributing the
4736 Program (or any work based on the Program), you indicate your acceptance of
4737 this License to do so, and all its terms and conditions for copying,
4738 distributing or modifying the Program or works based on it.
4740 6. Each time you redistribute the Program (or any work based on the Program),
4741 the recipient automatically receives a license from the original licensor to
4742 copy, distribute or modify the Program subject to these terms and conditions.
4743 You may not impose any further restrictions on the recipients' exercise of
4744 the rights granted herein. You are not responsible for enforcing compliance
4745 by third parties to this License.
4747 7. If, as a consequence of a court judgment or allegation of patent
4748 infringement or for any other reason (not limited to patent issues),
4749 conditions are imposed on you (whether by court order, agreement or
4750 otherwise) that contradict the conditions of this License, they do not excuse
4751 you from the conditions of this License. If you cannot distribute so as to
4752 satisfy simultaneously your obligations under this License and any other
4753 pertinent obligations, then as a consequence you may not distribute the
4754 Program at all. For example, if a patent license would not permit
4755 royalty-free redistribution of the Program by all those who receive copies
4756 directly or indirectly through you, then the only way you could satisfy both
4757 it and this License would be to refrain entirely from distribution of the
4760 If any portion of this section is held invalid or unenforceable under any
4761 particular circumstance, the balance of the section is intended to apply and
4762 the section as a whole is intended to apply in other circumstances.
4764 It is not the purpose of this section to induce you to infringe any patents
4765 or other property right claims or to contest validity of any such claims;
4766 this section has the sole purpose of protecting the integrity of the free
4767 software distribution system, which is implemented by public license
4768 practices. Many people have made generous contributions to the wide range of
4769 software distributed through that system in reliance on consistent
4770 application of that system; it is up to the author/donor to decide if he or
4771 she is willing to distribute software through any other system and a licensee
4772 cannot impose that choice.
4774 This section is intended to make thoroughly clear what is believed to be a
4775 consequence of the rest of this License.
4777 8. If the distribution and/or use of the Program is restricted in certain
4778 countries either by patents or by copyrighted interfaces, the original
4779 copyright holder who places the Program under this License may add an
4780 explicit geographical distribution limitation excluding those countries, so
4781 that distribution is permitted only in or among countries not thus excluded.
4782 In such case, this License incorporates the limitation as if written in the
4783 body of this License.
4785 9. The Free Software Foundation may publish revised and/or new versions of
4786 the General Public License from time to time. Such new versions will be
4787 similar in spirit to the present version, but may differ in detail to address
4788 new problems or concerns.
4790 Each version is given a distinguishing version number. If the Program
4791 specifies a version number of this License which applies to it and "any later
4792 version", you have the option of following the terms and conditions either of
4793 that version or of any later version published by the Free Software
4794 Foundation. If the Program does not specify a version number of this License,
4795 you may choose any version ever published by the Free Software Foundation.
4797 10. If you wish to incorporate parts of the Program into other free programs
4798 whose distribution conditions are different, write to the author to ask for
4799 permission. For software which is copyrighted by the Free Software
4800 Foundation, write to the Free Software Foundation; we sometimes make
4801 exceptions for this. Our decision will be guided by the two goals of
4802 preserving the free status of all derivatives of our free software and of
4803 promoting the sharing and reuse of software generally.
4807 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
4808 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
4809 STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
4810 PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
4811 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
4812 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
4813 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
4814 YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
4816 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4817 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4818 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4819 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4820 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO
4821 LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
4822 THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4823 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4824 POSSIBILITY OF SUCH DAMAGES.
4826 END OF TERMS AND CONDITIONS
4827 ----------------------------------------------------------------------
4832 There are two separate mailing lists for nedit users, and one for developers.
4833 Users may post to the developer mailing list to report defects and communicate
4834 with the nedit developers. Remember that nedit is entirely a volunteer
4835 effort, so please ask questions first to the discussion list, and do your
4836 share to answer other users questions as well.
4840 General discussion, questions and answers among NEdit users and developers.
4842 announce@@nedit.org_
4844 A low-volume mailing list for announcing new versions.
4848 Communication among and with NEdit developers.
4849 Developers should also subscribe to the discuss list.
4851 To subscribe, send mail to <majordomo@@nedit.org> with one or more of the
4852 following in the body of the message:
4857 ----------------------------------------------------------------------
4862 3>Solutions to Common Problems
4864 For a much more comprehensive list of common problems and solutions, see the
4865 NEdit FAQ. The latest version of the FAQ can always be found on the NEdit
4868 http://www.nedit.org_.
4870 **P: No files are shown in the "Files" list in the Open... dialog.**
4872 S: When you use the "Filter" field, include the file specification or a
4873 complete directory specification, including the trailing "/" on Unix.
4874 (See Help in the Open... dialog).
4876 **P: Find Again and Replace Again don't continue in the same direction as the original Find or Replace.**
4878 S: Find Again and Replace Again don't use the direction of the original
4879 search. The Shift key controls the direction: Ctrl+G means forward,
4880 Shift+Ctrl+G means backward.
4882 **P: Preferences specified in the Preferences menu don't seem to get saved when I select Save Defaults.**
4884 S: NEdit has two kinds of preferences: 1) per-window preferences, in the
4885 Preferences menu, and 2) default settings for preferences in newly created
4886 windows, in the Default Settings sub-menu of the Preferences menu.
4887 Per-window preferences are not saved by Save Defaults, only Default
4890 **P: Columns and indentation don't line up.**
4892 S: NEdit is using a proportional width font. Set the font to a fixed style
4893 (see Preferences menu).
4895 **P: NEdit performs poorly on very large files.**
4897 S: Turn off Incremental Backup. With Incremental Backup on, NEdit
4898 periodically writes a full copy of the file to disk.
4900 **P: Commands added to the Shell Commands menu (Unix only) don't output anything until they are finished executing.**
4902 S: If the command output is directed to a dialog, or the input is from a
4903 selection, output is collected together and held until the command
4904 completes. De-select both of the options and the output will be shown
4905 incrementally as the command executes.
4907 **P: Dialogs don't automatically get keyboard focus when they pop up.**
4909 S: Most X Window managers allow you to choose between two categories of
4910 keyboard focus models: pointer focus, and explicit focus. Pointer focus
4911 means that as you move the mouse around the screen, the window under the
4912 mouse automatically gets the keyboard focus. NEdit users who use this
4913 focus model should set "Popups Under Pointer" in the Default Settings sub
4914 menu of the preferences menu in NEdit. Users with the explicit focus
4915 model, in some cases, may have problems with certain dialogs, such as Find
4916 and Replace. In MWM this is caused by the mwm resource startupKeyFocus
4917 being set to False (generally a bad choice for explicit focus users).
4918 NCDwm users should use the focus model "click" instead of "explicit",
4919 again, unless you have set it that way to correct specific problems, this
4920 is the appropriate setting for most explicit focus users.
4922 **P: The Backspace key doesn't work, or deletes forward rather than backward.**
4924 S: While this is an X/Motif binding problem, and should be solved outside of
4925 NEdit in the Motif virtual binding layer (or possibly xmodmap or
4926 translations), NEdit provides an out. If you set the resource:
4927 nedit.remapDeleteKey to True, NEdit will forcibly map the delete key to
4928 backspace. The default setting of this resource recently changed, so
4929 users who have been depending on this remapping will now have to set it
4930 explicitly (or fix their bindings).
4932 **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.**
4934 S: On many SunOS systems, you have to set up an nls directory before various
4935 inter-client communication features of Motif will function properly.
4936 There are instructions in README.sun in /pub/v5_0_2/individual/README.sun on
4937 ftp.nedit.org, as well as a tar file containing a complete nls
4938 directory: ftp://ftp.nedit.org/pub/v5_0_2/nls.tar.
4939 README.sun contains directions for setting up an nls directory, which
4940 is required by Motif for handling copy and paste to Motif text fields.
4944 Below is the list of known defects which affect NEdit. The defects your copy
4945 of NEdit will exhibit depend on which system you are running and with which
4946 Motif libraries it was built. Note that there are now Motif 1.2 and/or 2.0
4947 libraries available on ALL supported platforms, and as you can see below
4948 there are far fewer defects in Motif 1.2, so it is in your best interest to
4949 upgrade your system.
4954 Operations between rectangular selections on overlapping lines do nothing.
4957 None. These operations are very complicated and rarely used.
4960 Cut and Paste menu items fail, or possibly crash,
4961 for very large (multi-megabyte) selections.
4964 Use selection copy (middle mouse button click)
4965 for transferring larger quantities of data.
4966 Cut and Paste save the copied text in server
4967 memory, which is usually limited.
4971 Submit bugs through the web at:
4973 http://sf.net/tracker/?func=add&group_id=11005&atid=111005
4975 Please include the first few lines from Help > Version, which identifes
4976 NEdit's version and other system attributes important for diagnosing your
4979 The NEdit developers subscribe to both discuss@@nedit.org and
4980 develop@@nedit.org, either of which may be used for reporting defects. If
4981 you're not sure, or you think the report might be of interest to the general
4982 NEdit user community, send the report to discuss@@nedit.org_. If it's
4983 something obvious and boring, like we misspelled "anemometer" in the on-line
4984 help, send it to develop@@nedit.org_. If you don't want to subscribe to the
4985 Mailing_Lists_, please add a note to your mail about cc'ing you on responses.
4989 .. Hyperlinks for this document ==============================================
4991 .. _discuss@@nedit.org mailto:discuss@@nedit.org
4992 .. _announce@@nedit.org mailto:announce@@nedit.org
4993 .. _develop@@nedit.org mailto:develop@@nedit.org
4994 .. _http://www.nedit.org http://www.nedit.org
4995 .. _ctag_support #ctags
4996 .. _Alternation #alternation
4998 .. =============================================================================
5000 .. Below is what is used to guide the generation of 'C'-Motif menus.
5001 .. Indentation is SIGNIFICANT in the "Menu" directive lines below. It
5002 .. is used to determine under which menu element another item will belong.
5003 .. The number of spaces indented is not significant, but items to be placed
5004 .. in the same menu panel MUST line up at the same indent level.
5005 .. ALL nodes of this menu "tree" should have help name qualifiers.
5006 .. These are used to produce the internal lists used by NEdit help code.
5008 .. By default, the first character of the menu element will be used as a
5009 .. menu mneumonic key. To use another character in the menu element for this
5010 .. purpose, surround the character with underscores (eg. I w_a_nt 'a').
5012 .. The menu title MUST match the one found in the actual help text (sans
5013 .. special mneumonic key character marking). The help text title may include
5014 .. underlines (for spaces) when it is a hyperlink target.
5016 .. The Help-name is used to generate various data structure names. For
5017 .. instance, the 'start' help name will be used to generate the HelpTopic
5018 .. enumeration value HELP_START and the character array htxt_start which
5019 .. holds the actual help text used in the menu dialogs. Consequently, these
5020 .. names need to be unique and contain only the characters that a 'C'
5021 .. compiler can digest.
5023 .. Menu separator lines use a dash (-) character for the Menu Title. They
5024 .. should also have a unique Help-name.
5026 .. A numerical value following the Help-name (separated from the name by
5027 .. a comma and/or spaces) is part of a menu element hiding scheme implemented
5028 .. in buildHelpMenu (found in 'menu.c'). When the number matches the hideIt
5029 .. value found in the procedure, that element will effectively become invisible.
5030 .. This mechanism was created for particular menu features that are not
5031 .. available to all incarnations of NEdit (in this case, the VMS version).
5033 .. A "Help" directive is used for all other text used as NEdit help, but
5034 .. does not show up in the Help menu.
5036 .. Menu Title # Help-name
5037 .. ------------------------------------------------------------
5038 .. Menu: Getting Started # start
5039 .. Menu: Basic Operation # basicOp
5040 .. Menu: Selecting Text # select
5041 .. Menu: Finding and Replacing Text # search
5042 .. Menu: Cut and Paste # clipboard
5043 .. Menu: Using the Mouse # mouse
5044 .. Menu: Keyboard Shortcuts # keyboard
5045 .. Menu: S_h_ifting and Filling # fill
5046 .. Menu: F_i_le Format # format
5048 .. Menu: Features for Programming # features
5049 .. Menu: Programming with NEdit # programmer
5050 .. Menu: Tabs/Emulated Tabs # tabs
5051 .. Menu: Auto/Smart Indent # indent
5052 .. Menu: Syntax Highlighting # syntax
5053 .. Menu: Finding Declarations (ctags) # tags
5054 .. Menu: Calltips # calltips
5056 .. Menu: Regular Expressions # regex
5057 .. Menu: Basic Regular Expression Syntax # basicSyntax
5058 .. Menu: Metacharacters # escapeSequences
5059 .. Menu: Parenthetical Constructs # parenConstructs
5060 .. Menu: Advanced Topics # advancedTopics
5061 .. Menu: Example Regular Expressions # examples
5063 .. Menu: Macro/Shell Extensions # extensions
5064 .. Menu: Shell Commands and Filters # shell, 1
5065 .. Menu: Learn/Replay # learn
5066 .. Menu: Macro Language # macro_lang
5067 .. Menu: M_a_cro Subroutines # macro_subrs
5068 .. Menu: Action Routines # actions
5070 .. Menu: Customizing # customizing
5071 .. Menu: Customizing NEdit # customize
5072 .. Menu: Preferences # preferences
5073 .. Menu: X Resources # resources
5074 .. Menu: Key Binding # binding
5075 .. Menu: Highlighting Patterns # patterns
5076 .. Menu: Smart Indent Macros # smart_indent
5078 .. Menu: NEdit Command Line # command_line
5079 .. Menu: Client/Server Mode # server
5080 .. Menu: Cr_a_sh Recovery # recovery
5081 .. Menu: ---------------------------------- # separator1
5082 .. Menu: Version # version
5083 .. Menu: Distribution Policy # distribution
5084 .. Menu: Mailing _L_ists # mailing_list
5085 .. Menu: Problems/Defects # defects
5086 .. ------------------------------------------------------------
5087 .. Help: Tabs Dialog # tabs_dialog
5088 .. Help: Customize Window Title Dialog # custom_title_dialog