UNIXworkcode

1 .. $Id: help.etx,v 1.111.2.2 2009/11/30 20:21:18 lebert Exp $ 2 .. NOTE: Remember to supply 'version' variable on setext command line. 3 .. For example, setext -m -v "version=XNEdit Version 6.0". 4 .. 5 .. The following are variable definitions for the various titles below 6 .. ---------------------------------------------------------------------------- 7 .. |>title=Nirvana Editor (XNEdit) Help Documentation<| 8 .. |>ttlMk==========================================<| 9 .. ---------------------------------------------------------------------------- 10 .. ? NEDITDOC~ 11 |>ttlMk<| 12 |>title<| 13 |>ttlMk<| 14 15 |>version<| |>Date<| 16 .. ~ NEDITDOC 17 18 .. ! NEDITDOC~ 19 |>title<| 20 |>ttlMk<| 21 22 .. ? html~ 23 .. 24 .. .. This table of contents is only for the HTML version of this document. 25 .. 26 Table of Contents 27 ----------------- 28 29 Getting_Started_ 30 31 Basic Operation Macro/Shell Extensions 32 Selecting_Text_ Shell_Commands_and_Filters_ 33 Finding_and_Replacing_Text_ Learn/Replay_ 34 Cut_and_Paste_ Macro_Language_ 35 Using_the_Mouse_ Macro_Subroutines_ 36 Keyboard_Shortcuts_ Highlighting_Information_ 37 Shifting_and_Filling_ Rangesets_ 38 Multi-cursor_Editing_ Action_Routines_ 39 Tabbed_Editing_ 40 File_Format_ Customizing 41 Customizing_XNEdit_ 42 Features for Programming Preferences_ 43 Programming_with_XNEdit_ X_Resources_ 44 Tab_Stops/Emulated_Tab_Stops_ Key_Binding_ 45 Auto/Smart_Indent_ Highlighting_Patterns_ 46 Syntax_Highlighting_ Smart_Indent_Macros_ 47 Finding_Declarations_(ctags)_ 48 Calltips_ XNEdit_Command_Line_ 49 Client/Server_Mode_ 50 Regular Expressions Crash_Recovery_ 51 Basic_Regular_Expression_Syntax_ Version_ 52 Metacharacters_ License_ 53 Parenthetical_Constructs_ Support_ 54 Advanced_Topics_ Problems/Defects_ 55 Example_Regular_Expressions_ 56 57 58 .. ~ html 59 Getting Started 60 --------------- 61 62 Welcome to XNEdit! 63 .. ~ NEDITDOC 64 .. .. What appears below will always print whether or not NEDITDOC is defined. 65 .. 66 67 XNEdit is a standard GUI (Graphical User Interface) style text editor for 68 programs and plain-text files. Users of Macintosh and MS Windows based text 69 editors should find XNEdit a familiar and comfortable environment. XNEdit 70 provides all of the standard menu, dialog, editing, and mouse support, as 71 well as all of the standard shortcuts to which the users of modern GUI based 72 environments are accustomed. For users of older style Unix editors, welcome 73 to the world of mouse-based editing! 74 75 .. ? NEDITDOC~ 76 .. XNEdit is freely distributed under the terms of the Gnu General Public 77 .. License. 78 79 .. .. This stuff will always be invisible, unless NEDITDOC is defined 80 .. 81 .. Installing XNEdit 82 .. ---------------- 83 .. 84 .. XNEdit is a single stand-alone executable file which can be installed by simply 85 .. copying the appropriate executable "xnedit" for your system. Both sources and 86 .. executables are available from https://www.unixwork.de/xnedit/. 87 .. The optional "xnc" (XNEdit Client) program is also available for users who want 88 .. to run xnedit in client/server mode. 89 .. 90 .. Getting Started 91 .. --------------- 92 .. ~ NEDITDOC 93 94 Help sections of interest to new users are listed under the "Basic Operation" 95 heading in the top-level Help menu: 96 97 Selecting_Text_ 98 Finding_and_Replacing_Text_ 99 Cut_and_Paste_ 100 Using_the_Mouse_ 101 Keyboard_Shortcuts_ 102 Shifting_and_Filling_ 103 104 Programmers should also read the introductory section under the "Features for 105 Programming" section: 106 107 Programming_with_XNEdit_ 108 109 If you get into trouble, the Undo command in the Edit menu can reverse any 110 modifications that you make. XNEdit does not change the file you are editing 111 until you tell it to Save. 112 113 3>Editing an Existing File 114 115 To open an existing file, choose Open... from the file menu. Select the file 116 that you want to open in the pop-up dialog that appears and click on OK. You 117 may open any number of files at the same time. Depending on your settings 118 (cf. "Tabbed_Editing_") each file can appear in its own editor window, or it 119 can appear under a tab in the same editor window. Using Open... rather than 120 re-typing the XNEdit command and running additional copies of XNEdit, will give 121 you quick access to all of the files you have open via the Windows menu, and 122 ensure that you don't accidentally open the same file twice. XNEdit has no 123 "main" window. It remains running as long as at least one editor window is 124 open. 125 126 3>Creating a New File 127 128 If you already have an empty (Untitled) window displayed, just begin typing 129 in the window. To create a new Untitled window, choose New Window or New Tab 130 from the File menu. To give the file a name and save its contents to the 131 disk, choose Save or Save As... from the File menu. 132 133 3>Backup Files 134 135 XNEdit maintains periodic backups of the file you are editing so that you can 136 recover the file in the event of a problem such as a system crash, network 137 failure, or X server crash. These files are saved under the name `~filename` 138 (on Unix) or `_filename` (on VMS), where filename is the name of the file you 139 were editing. If an XNEdit process is killed, some of these backup files may 140 remain in your directory. (To remove one of these files on Unix, you may 141 have to prefix the `~' (tilde) character with a (backslash) to prevent the 142 shell from interpreting it as a special character.) 143 144 3>Shortcuts 145 146 As you become more familiar with XNEdit, substitute the control and function 147 keys shown on the right side of the menus for pulling down menus with the 148 mouse. 149 150 Dialogs are also streamlined so you can enter information quickly and without 151 using the mouse*. To move the keyboard focus around a dialog, use the tab 152 and arrow keys. One of the buttons in a dialog is usually drawn with a 153 thick, indented, outline. This button can be activated by pressing Return or 154 Enter. The Cancel or Dismiss button can be activated by pressing escape. 155 For example, to replace the string "thing" with "things" type: 156 157 <ctrl-r>thing<tab>things<return> 158 159 To open a file named "whole_earth.c", type: 160 161 <ctrl-o>who<return> 162 163 (how much of the filename you need to type depends on the other files in the 164 directory). See the section called "Keyboard_Shortcuts_" for more details. 165 166 * Users who have set their keyboard focus mode to "pointer" should set 167 "Popups Under Pointer" in the Default Settings menu to avoid the additional 168 step of moving the mouse into the dialog. 169 ---------------------------------------------------------------------- 170 171 Basic Operation 172 =============== 173 174 Selecting Text 175 -------------- 176 177 XNEdit has two general types of selections, primary (highlighted text), and 178 secondary (underlined text). Selections can cover either a simple range of 179 text between two points in the file, or they can cover a rectangular area of 180 the file. Rectangular selections are only useful with non-proportional (fixed 181 spacing) fonts. 182 183 To select text for copying, deleting, or replacing, press the left mouse 184 button with the pointer at one end of the text you want to select, and drag 185 it to the other end. The text will become highlighted. To select a whole 186 word, double click (click twice quickly in succession). Double clicking and 187 then dragging the mouse will select a number of words. Similarly, you can 188 select a whole line or a number of lines by triple clicking or triple 189 clicking and dragging. Quadruple clicking selects the whole file. After 190 releasing the mouse button, you can still adjust a selection by holding down 191 the shift key and dragging on either end of the selection. To delete the 192 selected text, press delete or backspace. To replace it, begin typing. 193 194 To select a rectangle or column of text, hold the Ctrl key while dragging the 195 mouse. Rectangular selections can be used in any context that normal 196 selections can be used, including cutting and pasting, filling, shifting, 197 dragging, and searching. Operations on rectangular selections automatically 198 fill in tabs and spaces to maintain alignment of text within and to the right 199 of the selection. Note that the interpretation of rectangular selections by 200 Fill Paragraph is slightly different from that of other commands, the section 201 titled "Shifting_and_Filling_" has details. 202 203 The middle mouse button can be used to make an additional selection (called 204 the secondary selection). As soon as the button is released, the contents of 205 this selection will be copied to the insert position of the window where the 206 mouse was last clicked (the destination window). This position is marked by a 207 caret shaped cursor when the mouse is outside of the destination window. If 208 there is a (primary) selection, adjacent to the cursor in the window, the new 209 text will replace the selected text. Holding the shift key while making the 210 secondary selection will move the text, deleting it at the site of the 211 secondary selection, rather than copying it. 212 213 Selected text can also be dragged to a new location in the file using the 214 middle mouse button. Holding the shift key while dragging the text will copy 215 the selected text, leaving the original text in place. Holding the control 216 key will drag the text in overlay mode. 217 218 Normally, dragging moves text by removing it from the selected position at 219 the start of the drag, and inserting it at a new position relative to the 220 mouse. Dragging a block of text over existing characters, displaces the 221 characters to the end of the selection. In overlay mode, characters which are 222 occluded by blocks of text being dragged are simply removed. When dragging 223 non-rectangular selections, overlay mode also converts the selection to 224 rectangular form, allowing it to be dragged outside of the bounds of the 225 existing text. 226 227 The section "Using_the_Mouse_" summarizes the mouse commands for making primary 228 and secondary selections. Primary selections can also be made via keyboard 229 commands, see "Keyboard_Shortcuts_". 230 ---------------------------------------------------------------------- 231 232 Finding and Replacing Text 233 -------------------------- 234 235 The Search menu contains a number of commands for finding and replacing text. 236 237 The Find... and Replace... commands present dialogs for entering text for 238 searching and replacing. These dialogs also allow you to choose whether you 239 want the search to be sensitive to upper and lower case, or whether to use 240 the standard Unix pattern matching characters (regular expressions). 241 Searches begin at the current text insertion position. 242 243 Find Again and Replace Again repeat the last find or replace command without 244 prompting for search strings. To selectively replace text, use the two 245 commands in combination: Find Again, then Replace Again if the highlighted 246 string should be replaced, or Find Again again to go to the next string. 247 248 Find Selection searches for the text contained in the current primary 249 selection (see Selecting_Text_). The selected text does not have to be in the 250 current editor window, it may even be in another program. For example, if 251 the word dog appears somewhere in a window on your screen, and you want to 252 find it in the file you are editing, select the word dog by dragging the 253 mouse across it, switch to your XNEdit window and choose Find Selection from 254 the Search menu. 255 256 Find Incremental, which opens the interactive search bar, is yet another variation 257 on searching, where every character typed triggers a new search. After you've 258 completed the search string, the next occurrence in the buffer is found by hitting 259 the Return key, or by clicking on the icon to the left (magnifying glass). Holding 260 a Shift key down finds the previous occurrences. To the right there is a clear 261 button with an icon resembling "|<". Clicking on it empties the search text widget 262 without disturbing selections. A middle click on the clear button copies the 263 content of any existing selection into the search text widget and triggers a new 264 search. 265 266 3>Searching Backwards 267 268 Holding down the shift key while choosing any of the search or replace 269 commands from the menu (or using the keyboard shortcut), will search in the 270 reverse direction. Users who have set the search direction using the buttons 271 in the search dialog, may find it a bit confusing that Find Again and Replace 272 Again don't continue in the same direction as the original search (for 273 experienced users, consistency of the direction implied by the shift key is 274 more important). 275 276 3>Selective Replacement 277 278 To replace only some occurrences of a string within a file, choose Replace... 279 from the Search menu, enter the string to search for and the string to 280 substitute, and finish by pressing the Find button. When the first 281 occurrence is highlighted, use either Replace Again (^T) to replace it, or 282 Find Again (^G) to move to the next occurrence without replacing it, and 283 continue in such a manner through all occurrences of interest. 284 285 To replace all occurrences of a string within some range of text, select the 286 range (see Selecting_Text_), choose Replace... from the Search menu, type the 287 string to search for and the string to substitute, and press the "R. in 288 Selection" button in the dialog. Note that selecting text in the Replace... 289 dialog will unselect the text in the window. 290 291 3>Replacement in Multiple Documents 292 293 You can do the same replacement in more than one document at the same time. 294 To do that, enter the search and replacement string in the replacement dialog 295 as usual, then press the 'Multiple Documents...' button. XNEdit will open 296 another dialog where you can pick any document in which the replacement should 297 take place. Then press 'Replace' in this dialog to do the replacement. All 298 attributes (Regular Expression, Case, etc.) are used as selected in the main 299 dialog. 300 301 ---------------------------------------------------------------------- 302 303 Cut and Paste 304 ------------- 305 306 The easiest way to copy and move text around in your file or between windows, 307 is to use the clipboard, an imaginary area that temporarily stores text and 308 data. The Cut command removes the selected text (see Selecting_Text_) from 309 your file and places it in the clipboard. Once text is in the clipboard, the 310 Paste command will copy it to the insert position in the current window. For 311 example, to move some text from one place to another, select it by dragging 312 the mouse over it, choose Cut to remove it, click the pointer to move the 313 insert point where you want the text inserted, then choose Paste to insert 314 it. Copy copies text to the clipboard without deleting it from your file. 315 You can also use the clipboard to transfer text to and from other Motif 316 programs and X programs which make proper use of the clipboard. 317 318 There are many other methods for copying and moving text within XNEdit windows 319 and between XNEdit and other programs. The most common such method is 320 clicking the middle mouse button to copy the primary selection (to the 321 clicked position). Copying the selection by clicking the middle mouse button 322 in many cases is the only way to transfer data to and from many X programs. 323 Holding the Shift key while clicking the middle mouse button moves the text, 324 deleting it from its original position, rather than copying it. Other 325 methods for transferring text include secondary selections, primary selection 326 dragging, keyboard-based selection copying, and drag and drop. These are 327 described in detail in the sections: "Selecting_Text_", "Using_the_Mouse_", 328 and "Keyboard_Shortcuts_". 329 ---------------------------------------------------------------------- 330 331 Using the Mouse 332 --------------- 333 334 Mouse-based editing is what XNEdit is all about, and learning to use the more 335 advanced features like secondary selections and primary selection dragging 336 will be well worth your while. 337 338 If you don't have time to learn everything, you can get by adequately with 339 just the left mouse button: Clicking the left button moves the cursor. 340 Dragging with the left button makes a selection. Holding the shift key while 341 clicking extends the existing selection, or begins a selection between the 342 cursor and the mouse. Double or triple clicking selects a whole word or a 343 whole line. 344 345 This section will make more sense if you also read the section called, 346 "Selecting_Text_", which explains the terminology of selections, that is, 347 what is meant by primary, secondary, rectangular, etc. 348 349 350 3>Button and Modifier Key Summary 351 352 General meaning of mouse buttons and modifier keys: 353 354 4> Buttons 355 356 Button 1 (left) Cursor position and primary selection 357 358 Button 2 (middle) Secondary selections, and dragging and 359 copying the primary selection 360 361 Button 3 (right) Quick-access programmable menu and pan 362 scrolling 363 364 4> Modifier keys 365 366 Shift On primary selections, (left mouse button): 367 Extends selection to the mouse pointer 368 On secondary and copy operations, (middle): 369 Toggles between move and copy 370 371 Ctrl Makes selection rectangular or insertion 372 columnar 373 374 Alt* (on release) Exchange primary and secondary 375 selections. 376 377 378 3>Left Mouse Button 379 380 The left mouse button is used to position the cursor and to make primary 381 selections. 382 383 Click Moves the cursor 384 385 Double Click Selects a whole word 386 387 Triple Click Selects a whole line 388 389 Quad Click Selects the whole file 390 391 Shift Click Adjusts (extends or shrinks) the 392 selection, or if there is no existing 393 selection, begins a new selection 394 between the cursor and the mouse. 395 396 Ctrl+Shift+ Adjusts (extends or shrinks) the 397 Click selection rectangularly. 398 399 Drag Selects text between where the mouse 400 was pressed and where it was released. 401 402 Ctrl+Drag Selects rectangle between where the 403 mouse was pressed and where it was 404 released. 405 406 407 3>Right Mouse Button 408 409 The right mouse button posts a programmable menu for frequently used commands. 410 411 Click/Drag Pops up the background menu (programmed 412 from Preferences -> Default Settings -> 413 Customize Menus -> Window Background). 414 415 Ctrl+Drag Pan scrolling. Scrolls the window 416 both vertically and horizontally, as if 417 you had grabbed it with your mouse. 418 419 420 3>Middle Mouse Button 421 422 The middle mouse button is for making secondary selections, and copying and 423 dragging the primary selection. 424 425 Click Copies the primary selection to the 426 clicked position. 427 428 Shift+Click Moves the primary selection to the 429 clicked position, deleting it from its 430 original position. 431 432 Drag 1) Outside of the primary selection: 433 Begins a secondary selection. 434 2) Inside of the primary selection: 435 Moves the selection by dragging. 436 437 Ctrl+Drag 1) Outside of the primary selection: 438 Begins a rectangular secondary 439 selection. 440 2) Inside of the primary selection: 441 Drags the selection in overlay 442 mode (see below). 443 444 When the mouse button is released after creating a secondary selection: 445 446 No Modifiers If there is a primary selection, 447 replaces it with the secondary 448 selection. Otherwise, inserts the 449 secondary selection at the cursor 450 position. 451 452 Shift Move the secondary selection, deleting 453 it from its original position. If 454 there is a primary selection, the move 455 will replace the primary selection 456 with the secondary selection. 457 Otherwise, moves the secondary 458 selection to the cursor position. 459 460 Alt* Exchange the primary and secondary 461 selections. 462 463 464 While moving the primary selection by dragging with the middle mouse button: 465 466 Shift Leaves a copy of the original 467 selection in place rather than 468 removing it or blanking the area. 469 470 Ctrl Changes from insert mode to overlay 471 mode (see below). 472 473 Escape Cancels drag in progress. 474 475 Overlay Mode: Normally, dragging moves text by removing it from the selected 476 position at the start of the drag, and inserting it at a new position 477 relative to the mouse. When you drag a block of text over existing 478 characters, the existing characters are displaced to the end of the 479 selection. In overlay mode, characters which are occluded by blocks of text 480 being dragged are simply removed. When dragging non-rectangular selections, 481 overlay mode also converts the selection to rectangular form, allowing it to 482 be dragged outside of the bounds of the existing text. 483 484 Mouse buttons 4 and 5 are usually represented by a mouse wheel nowadays. 485 They are used to scroll up or down in the text window. 486 487 * The Alt key may be labeled Meta or Compose-Character on some keyboards. 488 Some window managers, including default configurations of mwm, bind 489 combinations of the Alt key and mouse buttons to window manager operations. 490 In XNEdit, Alt is only used on button release, so regardless of the window 491 manager bindings for Alt-modified mouse buttons, you can still do the 492 corresponding XNEdit operation by using the Alt key AFTER the initial mouse 493 press, so that Alt is held while you release the mouse button. If you find 494 this difficult or annoying, you can re-configure most window managers to skip 495 this binding, or you can re-configure XNEdit to use a different key 496 combination. 497 ---------------------------------------------------------------------- 498 499 Keyboard Shortcuts 500 ------------------ 501 502 Most of the keyboard shortcuts in XNEdit are shown on the right hand sides of 503 the pull-down menus. However, there are more which are not as obvious. These 504 include; dialog button shortcuts; menu and dialog mnemonics; labeled keyboard 505 keys, such as the arrows, page-up, page-down, and home; and optional Shift 506 modifiers on accelerator keys, like [Shift]Ctrl+F. 507 508 509 3>Menu Accelerators 510 511 Pressing the key combinations shown on the right of the menu items is a 512 shortcut for selecting the menu item with the mouse. Some items have the shift 513 key enclosed in brackets, such as [Shift]Ctrl+F. This indicates that the shift 514 key is optional. In search commands, including the shift key reverses the 515 direction of the search. In Shift commands, it makes the command shift the 516 selected text by a whole tab stop rather than by single characters. 517 518 519 3>Menu Mnemonics 520 521 Pressing the Alt key in combination with one of the underlined characters in 522 the menu bar pulls down that menu. Once the menu is pulled down, typing the 523 underlined characters in a menu item (without the Alt key) activates that 524 item. With a menu pulled down, you can also use the arrow keys to select menu 525 items, and the Space or Enter keys to activate them. 526 527 528 3>Keyboard Shortcuts within Dialogs 529 530 One button in a dialog is usually marked with a thick indented outline. 531 Pressing the Return or Enter key activates this button. 532 533 All dialogs have either a Cancel or Dismiss button. This button can be 534 activated by pressing the Escape (or Esc) key. 535 536 Pressing the tab key moves the keyboard focus to the next item in a dialog. 537 Within an associated group of buttons, the arrow keys move the focus among the 538 buttons. Shift+Tab moves backward through the items. 539 540 Most items in dialogs have an underline under one character in their name. 541 Pressing the Alt key along with this character, activates a button as if you 542 had pressed it with the mouse, or moves the keyboard focus to the associated 543 text field or list. 544 545 You can select items from a list by using the arrow keys to move the 546 selection and space to select. 547 548 In file selection dialogs, you can type the beginning characters of the file 549 name or directory in the list to select files 550 551 552 3>Labeled Function Keys 553 554 The labeled function keys on standard workstation and PC keyboards, like the 555 arrows, and page-up and page-down, are active in XNEdit, though not shown in the 556 pull-down menus. 557 558 Holding down the control key while pressing a named key extends the scope of 559 the action that it performs. For example, Home normally moves the insert 560 cursor the beginning of a line. Ctrl+Home moves it to the beginning of the 561 file. Backspace deletes one character, Ctrl+Backspace deletes one word. 562 563 Holding down the shift key while pressing a named key begins or extends a 564 selection. Combining the shift and control keys combines their actions. For 565 example, to select a word without using the mouse, position the cursor at the 566 beginning of the word and press Ctrl+Shift+RightArrow. The Alt key modifies 567 selection commands to make the selection rectangular. 568 569 Under X and Motif, there are several levels of translation between keyboard 570 keys and the actions they perform in a program. The "Customizing_XNEdit_", and 571 "X_Resources_" sections of the Help menu have more information on this subject. 572 Because of all of this configurability, and since keyboards and standards for 573 the meaning of some keys vary from machine to machine, the mappings may be 574 changed from the defaults listed below. 575 576 3>Modifier Keys (in general) 577 578 Ctrl Extends the scope of the action that the key 579 would otherwise perform. For example, Home 580 normally moves the insert cursor to the beginning 581 of a line. Ctrl+Home moves it to the beginning of 582 the file. Backspace deletes one character, Ctrl+ 583 Backspace deletes one word. 584 585 Shift Extends the selection to the cursor position. If 586 there's no selection, begins one between the old 587 and new cursor positions. 588 589 Alt When modifying a selection, makes the selection 590 rectangular. 591 592 (For the effects of modifier keys on mouse button presses, see the section 593 titled "Using_the_Mouse_") 594 595 3>All Keyboards 596 597 Escape Cancels operation in progress: menu 598 selection, drag, selection, etc. Also 599 equivalent to cancel button in dialogs. 600 601 Backspace Delete the character before the cursor 602 603 Ctrl+BS Delete the word before the cursor 604 605 Arrows -- 606 607 Left Move the cursor to the left one character 608 609 Ctrl+Left Move the cursor backward one word 610 (Word delimiters are settable, see 611 "Customizing_XNEdit_", and "X_Resources_") 612 613 Right Move the cursor to the right one character 614 615 Ctrl+Right Move the cursor forward one word 616 617 Up Move the cursor up one line 618 619 Ctrl+Up Move the cursor up one paragraph. 620 (Paragraphs are delimited by blank lines) 621 622 Down Move the cursor down one line. 623 624 Ctrl+Down Move the cursor down one paragraph. 625 626 Ctrl+Return Return with automatic indent, regardless 627 of the setting of Auto Indent. 628 629 Shift+Return Return without automatic indent, 630 regardless of the setting of Auto Indent. 631 632 Ctrl+Tab Insert an ASCII tab character, without 633 processing emulated tabs. 634 635 Alt+Ctrl+<c> Insert the control-code equivalent of 636 a key <c> 637 638 Ctrl+/ Select everything (same as Select 639 All menu item or ^A) 640 641 Ctrl+\ Unselect 642 643 Ctrl+U Delete to start of line 644 645 3>PC Standard Keyboard 646 647 Ctrl+Insert Copy the primary selection to the 648 clipboard (same as Copy menu item or ^C) 649 for compatibility with Motif standard key 650 binding 651 Shift+Ctrl+ 652 Insert Copy the primary selection to the cursor 653 location. 654 655 Delete Delete the character before the cursor. 656 (Can be configured to delete the character 657 after the cursor, see "Customizing_XNEdit_", 658 and "X_Resources_") 659 660 Ctrl+Delete Delete to end of line. 661 662 Shift+Delete Cut, remove the currently selected text 663 and place it in the clipboard. (same as 664 Cut menu item or ^X) for compatibility 665 with Motif standard key binding 666 Shift+Ctrl+ 667 Delete Cut the primary selection to the cursor 668 location. 669 670 Home Move the cursor to the beginning of the 671 line 672 673 Ctrl+Home Move the cursor to the beginning of the 674 file 675 676 End Move the cursor to the end of the line 677 678 Ctrl+End Move the cursor to the end of the file 679 680 PageUp Scroll and move the cursor up by one page. 681 682 PageDown Scroll and move the cursor down by one 683 page. 684 685 F10 Make the menu bar active for keyboard 686 input (Arrow Keys, Return, Escape, 687 and the Space Bar) 688 689 Alt+Home Switch to the previously active document. 690 691 Ctrl+PageUp Switch to the previous document. 692 693 Ctrl+PageDown Switch to the next document. 694 695 696 3>Specialty Keyboards 697 698 On machines with different styles of keyboards, generally, text editing 699 actions are properly matched to the labeled keys, such as Remove, 700 Next-screen, etc.. If you prefer different key bindings, see the section 701 titled "Key_Binding_" under the Customizing heading in the Help menu. 702 ---------------------------------------------------------------------- 703 704 Shifting and Filling 705 -------------------- 706 707 3>Shift Left, Shift Right 708 709 While shifting blocks of text is most important for programmers (See Features 710 for Programming), it is also useful for other tasks, such as creating 711 indented paragraphs. 712 713 To shift a block of text one tab stop to the right, select the text, then 714 choose Shift Right from the Edit menu. Note that the accelerator keys for 715 these menu items are Ctrl+9 and Ctrl+0, which correspond to the right and 716 left parenthesis on most keyboards. Remember them as adjusting the text in 717 the direction pointed to by the parenthesis character. Holding the Shift key 718 while selecting either Shift Left or Shift Right will shift the text by one 719 character. 720 721 It is also possible to shift blocks of text by selecting the text 722 rectangularly, and dragging it left or right (and up or down as well). Using 723 a rectangular selection also causes tabs within the selection to be 724 recalculated and substituted, such that the non-whitespace characters remain 725 stationary with respect to the selection. 726 727 728 3>Filling 729 730 Text filling using the Fill Paragraph command in the Edit menu is one of the 731 most important concepts in XNEdit. And it will be well worth your while to 732 understand how to use it properly. 733 734 In plain text files, unlike word-processor files, there is no way to tell 735 which lines are continuations of other lines, and which lines are meant to be 736 separate, because there is no distinction in meaning between newline 737 characters which separate lines in a paragraph, and ones which separate 738 paragraphs from other text. This makes it impossible for a text editor like 739 XNEdit to tell parts of the text which belong together as a paragraph from 740 carefully arranged individual lines. 741 742 In continuous wrap mode (Preferences -> Wrap -> Continuous), lines 743 automatically wrap and unwrap themselves to line up properly at the right 744 margin. In this mode, you simply omit the newlines within paragraphs and let 745 XNEdit make the line breaks as needed. Unfortunately, continuous wrap mode is 746 not appropriate in the majority of situations, because files with extremely 747 long lines are not common under Unix and may not be compatible with all 748 tools, and because you can't achieve effects like indented sections, columns, 749 or program comments, and still take advantage of the automatic wrapping. 750 751 Without continuous wrapping, paragraph filling is not entirely automatic. 752 Auto-Newline wrapping keeps paragraphs lined up as you type, but once 753 entered, XNEdit can no longer distinguish newlines which join wrapped text, 754 and newlines which must be preserved. Therefore, editing in the middle of a 755 paragraph will often leave the right margin messy and uneven. 756 757 Since XNEdit can't act automatically to keep your text lined up, you need to 758 tell it explicitly where to operate, and that is what Fill Paragraph is for. 759 It arranges lines to fill the space between two margins, wrapping the lines 760 neatly at word boundaries. Normally, the left margin for filling is inferred 761 from the text being filled. The first line of each paragraph is considered 762 special, and its left indentation is maintained separately from the remaining 763 lines (for leading indents, bullet points, numbered paragraphs, etc.). 764 Otherwise, the left margin is determined by the furthest left non-whitespace 765 character. The right margin is either the Wrap Margin, set in the 766 preferences menu (by default, the right edge of the window), or can also be 767 chosen on the fly by using a rectangular selection (see below). 768 769 There are three ways to use Fill Paragraph. The simplest is, while you are 770 typing text, and there is no selection, simply select Fill Paragraph (or type 771 Ctrl+J), and XNEdit will arrange the text in the paragraph adjacent to the 772 cursor. A paragraph, in this case, means an area of text delimited by blank 773 lines. 774 775 The second way to use Fill Paragraph is with a selection. If you select a 776 range of text and then chose Fill Paragraph, all of the text in the selection 777 will be filled. Again, continuous text between blank lines is interpreted as 778 paragraphs and filled individually, respecting leading indents and blank 779 lines. 780 781 The third, and most versatile, way to use Fill Paragraph is with a 782 rectangular selection. Fill Paragraph treats rectangular selections 783 differently from other commands. Instead of simply filling the text inside 784 the rectangular selection, XNEdit interprets the right edge of the selection 785 as the requested wrap margin. Text to the left of the selection is not 786 disturbed (the usual interpretation of a rectangular selection), but text to 787 the right of the selection is included in the operation and is pulled in to 788 the selected region. This method enables you to fill text to an arbitrary 789 right margin, without going back and forth to the wrap-margin dialog, as well 790 as to exclude text to the left of the selection such as comment bars or other 791 text columns. 792 ---------------------------------------------------------------------- 793 794 Multi-cursor_Editing 795 -------------------- 796 797 XNEdit supports multi-cursor editing, which allows doing the same text editing 798 operation at multiple positions simultaneously. 799 800 To add a new cursor, press and hold Ctrl and left-click on the desired 801 position of the new cursor. You can remove a specific cursor with 802 Ctrl + left click on the existing cursor. To return to the normal single 803 cursor operation, press Escape or do a left click without Ctrl to any text 804 position. 805 806 An alternative way to add cursors is Ctrl+Super+Up to add a cursor above 807 the most top cursor or Ctrl+Super+Down to add a cursor below the last 808 cursor. 809 810 Most operations like inserting text, moving cursors by character, word or 811 paragraph and undo/redo support multi-cursor editing. Text Selection and 812 pasting text as column is unsupported. 813 814 815 The following actions support multiple cursors: 816 817 **delete_next_character()** 818 **delete_previous_character()** 819 **delete_next_word()** 820 **delete_previous_word()** 821 **forward_character()** 822 **forward_paragraph()** 823 **forward_word()** 824 **backward_character()** 825 **backward_word()** 826 **backward_paragraph()** 827 **insert_string()** 828 **self_insert()** 829 **newline()** 830 **process_tab()** 831 **process_up()** 832 **process_down()** 833 **beginning_of_line()** 834 **end_of_line()** 835 836 Tabbed Editing 837 ---------------- 838 839 XNEdit is able to display files in distinct editor windows, or to display files 840 under tabs in the same editor window. The Options for controlling the tabbed 841 interface are found under Preferences -> Default Settings -> Tabbed Editing 842 (cf. "Preferences_", also "XNEdit_Command_Line_"). 843 844 Notice that you can re-group tabs at any time by detaching and attaching them, 845 or moving them, to other windows. This can be done using the Windows menu, or 846 using the context menu, which pops up when right clicking on a tab. 847 848 You can switch to a tab by simply clicking on it, or you can use the keyboard. 849 The default keybindings to switch tabs (which are Ctrl+PageUp/-Down and Alt+Home, 850 see "Keyboard_Shortcuts_") can be changed using the actions previous_document(), 851 next_document() and last_document(). 852 853 ---------------------------------------------------------------------- 854 855 File Format 856 ----------- 857 858 While plain-text is probably the simplest and most interchangeable file 859 format in the computer world, there is still variation in what plain-text 860 means from system to system. Plain-text files can differ in character set, 861 line termination, and wrapping. 862 863 While character set differences are the most obvious and pose the most 864 challenge to portability, they affect XNEdit only indirectly via the same font 865 and localization mechanisms common to all X applications. If your system is 866 set up properly, you will probably never see character-set related problems 867 in XNEdit. 868 869 The primary difference between an MS DOS format file and a Unix format file, 870 is how the lines are terminated. Unix uses a single newline character. MS 871 DOS uses a carriage-return and a newline. XNEdit can read and write both file 872 formats, but internally, it uses the single character Unix standard. XNEdit 873 auto-detects MS DOS format files based on the line termination at the start 874 of the file. Files are judged to be DOS format if all of the first five line 875 terminators, within a maximum range, are DOS-style. To change the format in 876 which XNEdit writes a file from DOS to Unix or visa versa, use the Save As... 877 command and check or un-check the MS DOS Format button. 878 879 Wrapping within text files can vary among individual users, as well as from 880 system to system. Both Windows and MacOS make frequent use of plain text 881 files with no implicit right margin. In these files, wrapping is determined 882 by the tool which displays them. Files of this style also exist on Unix 883 systems, despite the fact that they are not supported by all Unix utilities. 884 To display this kind of file properly in XNEdit, you have to select the wrap 885 style called Continuous. Wrapping modes are discussed in the sections: 886 Customizing -> Preferences, and Basic Operation -> Shifting and Filling. 887 888 The last and most minute of format differences is the terminating newline. 889 Some Unix compilers and utilities require a final terminating newline on all 890 files they read and fail in various ways on files which do not have it. Vi 891 and approximately half of Unix editors enforce the terminating newline on all 892 files that they write; Emacs does not enforce this rule. Users are divided 893 on which is best. XNEdit makes the final terminating newline optional 894 (Preferences -> Default Settings -> Terminate with Line Break on Save). 895 ---------------------------------------------------------------------- 896 897 Features for Programming 898 ======================== 899 900 Programming with XNEdit 901 ---------------------- 902 903 Though general in appearance, XNEdit has many features intended specifically 904 for programmers. Major programming-related topics are listed in separate 905 sections under the heading: "Features for Programming": Syntax_Highlighting_, 906 Tab_Stops/Emulated_Tab_Stops_, Finding_Declarations_(ctags)_, Calltips_, and 907 Auto/Smart_Indent_. Minor topics related to programming are discussed below: 908 909 3>Language Modes 910 911 When XNEdit initially reads a file, it attempts to determine whether the file 912 is in one of the computer languages that it knows about. Knowing what language 913 a file is written in allows XNEdit to assign highlight patterns and smart indent 914 macros, and to set language specific preferences like word delimiters, tab 915 emulation, and auto-indent. Language mode can be recognized from both the file 916 name and from the first 200 characters of content. Language mode recognition 917 and language-specific preferences are configured in: Preferences -> Default 918 Settings -> Language Modes.... 919 920 You can set the language mode manually for a window, by selecting it from the 921 menu: Preferences -> Language Modes. 922 923 3>Backlighting [EXPERIMENTAL] 924 925 XNEdit can be made to set the background color of particular classes of 926 characters to allow easy identification of those characters. This is 927 particularly useful if you need to be able to distinguish between tabs 928 and spaces in a file where the difference is important. The colors used 929 for backlighting are specified by a resource, "nedit*backlightCharTypes". 930 You can turn backlighting on and off through the 931 Preferences -> Apply Backlighting menu entry. 932 933 If you prefer to have backlighting turned on for all new windows, use 934 the Preferences -> Default Settings -> Apply Backlighting menu entry. 935 This settings can be saved along with other preferences using 936 Preferences -> Save Defaults. 937 938 **Important:** In future versions of XNEdit, the backlighting feature will be 939 extended and reworked such that it becomes easier to configure. The current 940 way of controlling it through a resource is generally considered to be below 941 XNEdit's usability standards. These future changes are likely to be 942 incompatible with the current format of the "nedit*backlightCharTypes" 943 resource, though. Therefore, it is expected that there will be no automatic 944 migration path for users who customize the resource. 945 946 3>Line Numbers 947 948 To find a particular line in a source file by line number, choose Goto Line 949 #... from the Search menu. You can also directly select the line number text 950 in the compiler message in the terminal emulator window (xterm, decterm, 951 winterm, etc.) where you ran the compiler, and choose Goto Selected from the 952 Search menu. 953 954 To find out the line number of a particular line in your file, turn on 955 Statistics Line in the Preferences menu and position the insertion point 956 anywhere on the line. The statistics line continuously updates the line number 957 of the line containing the cursor. 958 959 To go to a specific column on a given line, choose Goto Line #... from the 960 Search menu and enter a line number and a column number separated by a 961 comma. (e.g. Enter "100,12" for line 100 column 12.) If you want to go to 962 a column on the current line just leave out the line number. (e.g. Enter 963 ",45" to go the column 45 on the current line.) 964 965 3>Matching Parentheses 966 967 To help you inspect nested parentheses, brackets, braces, quotes, and other 968 characters, XNEdit has both an automatic parenthesis matching mode, and a Goto 969 Matching command. Automatic parenthesis matching is activated when you type, 970 or move the insertion cursor after a parenthesis, bracket, or brace. It 971 momentarily highlights either the opposite character ('Delimiter') or the 972 entire expression ('Range') when the opposite character is visible in the 973 window. To find a matching character anywhere in the file, select it or 974 position the cursor after it, and choose Goto Matching from the Search menu. 975 If the character matches itself, such as a quote or slash, select the first 976 character of the pair. XNEdit will match {, (, [, <, ", ', `, /, and \. 977 Holding the Shift key while typing the accelerator key (Shift+Ctrl+M, by 978 default), will select all of the text between the matching characters. 979 980 When syntax highlighting is enabled, the matching routines can optionally 981 make use of the syntax information for improved accuracy. In that case, 982 a brace inside a highlighted string will not match a brace inside a comment, 983 for instance. 984 985 3>Opening Included Files 986 987 The Open Selected command in the File menu understands the C preprocessor's 988 #include syntax, so selecting an #include line and invoking Open Selected will 989 generally find the file referred to, unless doing so depends on the settings of 990 compiler switches or other information not available to XNEdit. 991 992 3>Interface to Programming Tools 993 994 Integrated software development environments such as SGI's CaseVision and 995 Centerline Software's Code Center, can be interfaced directly with XNEdit via 996 the client server interface. These tools allow you to click directly on 997 compiler and runtime error messages and request XNEdit to open files, and select 998 lines of interest. The easiest method is usually to use the tool's interface 999 for character-based editors like vi, to invoke xnc, but programmatic interfaces 1000 can also be derived using the source code for xnc. 1001 1002 There are also some simple compile/review, grep, ctree, and ctags browsers 1003 available in the XNEdit contrib directory on ftp.nedit.org. 1004 ---------------------------------------------------------------------- 1005 1006 Tab Stops/Emulated Tab Stops 1007 ------------------ 1008 1009 3>Changing the Tab Stop Distance 1010 1011 Tab stops are important for programming in languages which use indentation to 1012 show nesting, as short-hand for producing white-space for leading indents. 1013 As a programmer, you have to decide how to use indentation, and how or whether 1014 tab characters map to your indentation scheme. 1015 1016 Ideally, tab characters map directly to the amount of indent that you use to 1017 distinguish nesting levels in your code. Unfortunately, the Unix standard 1018 for interpretation of tab characters is eight characters (probably dating 1019 back to mechanical capabilities of the original teletype), which is usually 1020 too coarse for a single indent. 1021 1022 Most text editors, XNEdit included, allow you to change the interpretation of 1023 the tab character, and many programmers take advantage of this, and set their 1024 tab stops to 3 or 4 characters to match their programming style. In XNEdit you 1025 set the hardware tab distance in Preferences -> Tab Stops... for the current 1026 window, or Preferences -> Default Settings -> Tab Stops... (general), or 1027 Preferences -> Default Settings -> Language Modes... (language-specific) to 1028 change the defaults for future windows. 1029 1030 Changing the meaning of the tab character makes programming much easier while 1031 you're in the editor, but can cause you headaches outside of the editor, 1032 because there is no way to pass along the tab setting as part of a plain-text 1033 file. All of the other tools which display, print, and otherwise process 1034 your source code have to be made aware of how the tab stops are set, and must 1035 be able to handle the change. Non-standard tab stops can also confuse other 1036 programmers, or make editing your code difficult for them if their text 1037 editors don't support changes in tab stop distance. 1038 1039 3>Emulated Tab Stops 1040 1041 An alternative to changing the interpretation of the tab character is tab stop 1042 emulation. In the Tab Stops... dialog(s), turning on Emulated Tabs causes the 1043 Tab key to insert the correct number of spaces and/or tabs to bring the cursor 1044 the next emulated tab stop, as if tabs were set at the emulated tab distance 1045 rather than the hardware tab distance. Backspacing immediately after entering 1046 an emulated tab will delete the fictitious tab as a unit, but as soon as you 1047 move the cursor away from the spot, XNEdit will forget that the collection of 1048 spaces and tabs is a tab, and will treat it as separate characters. To enter 1049 a real tab character with "Emulate Tabs" turned on, use Ctrl+Tab. 1050 1051 It is also possible to tell XNEdit not to insert ANY tab characters at all in 1052 the course of processing emulated tabs, and in shifting and rectangular 1053 insertion/deletion operations, for programmers who worry about the 1054 misinterpretation of tab characters on other systems. 1055 ---------------------------------------------------------------------- 1056 1057 .. ** NOTE ** 1058 .. 1059 .. The following Tabs Dialog and Customize Window Title Dialog sections 1060 .. should only appear in the online documentation, and not in any of 1061 .. the other possible forms. The rationale is that they are not directly 1062 .. obtained from the Help menu, but are buried in preference dialogs. 1063 .. 1064 .. ? help~ 1065 .. Tabs Dialog 1066 .. ----------- 1067 .. 1068 .. The Tabs dialog controls both the operation of the Tab key, and 1069 .. the interpretation of tab characters within a file. 1070 .. 1071 .. The first field, Tab Spacing, controls how XNEdit responds to 1072 .. tab characters in a file. On most Unix and VMS systems the 1073 .. conventional interpretation of a tab character is to advance the 1074 .. text position to the nearest multiple of eight characters (a tab 1075 .. spacing of 8). However, many programmers of C and other 1076 .. structured languages, when given the choice, prefer a tab 1077 .. spacing of 3 or 4 characters. Setting a three or four character 1078 .. hardware tab spacing is useful and convenient as long as your 1079 .. other software tools support it. Unfortunately, on Unix and VMS 1080 .. systems, system utilities, such as more, and printing software 1081 .. can't always properly display files with other than eight 1082 .. character tabs. 1083 .. 1084 .. Selecting "Emulate Tabs" will cause the Tab key to insert the 1085 .. correct number of spaces or tabs to reach the next tab stop, as 1086 .. if the tab spacing were set at the value in the "Emulated tab 1087 .. spacing" field. Backspacing immediately after entering an 1088 .. emulated tab will delete it as a unit, but as soon as you move 1089 .. the cursor away from the spot, XNEdit will forget that the 1090 .. collection of spaces and tabs is a tab, and will treat it as 1091 .. separate characters. To enter a real tab character with 1092 .. "Emulate Tabs" turned on, use Ctrl+Tab. 1093 .. 1094 .. In generating emulated tabs, and in Shift Left, Paste Column, 1095 .. and some rectangular selection operations, XNEdit inserts blank 1096 .. characters (spaces or tabs) to preserve the alignment of 1097 .. non-blank characters. The bottom toggle button in the Tabs 1098 .. dialog instructs XNEdit whether to insert tab characters as 1099 .. padding in such situations. Turning this off, will keep XNEdit 1100 .. from automatically inserting tabs. Some software developers 1101 .. prefer to keep their source code free of tabs to avoid its 1102 .. misinterpretation on systems with different tab character 1103 .. conventions. 1104 .. ---------------------------------------------------------------------- 1105 .. 1106 .. Customize Window Title Dialog 1107 .. ----------------------------- 1108 .. 1109 .. The Customize Window Title dialog allows you to customize 1110 .. and test the way information will be displayed in each window's 1111 .. title field. 1112 .. 1113 .. **Definition of the title** 1114 .. 1115 .. The upper half of the dialog can be used to select the various 1116 .. components that should be displayed in the title. The layout can be 1117 .. fine-tuned by editing the printf() like format string below the 1118 .. component buttons: additional characters can be entered, or the 1119 .. order can be changed. 1120 .. 1121 .. The following sequences are interpreted in the format string: 1122 .. 1123 .. %c ClearCase view tag (only relevant when XNEdit is 1124 .. used together with ClearCase) 1125 .. %[n]d directory, with one optional numeric digit n 1126 .. specifying the maximum number of trailing directory 1127 .. components to display. Skipped components are 1128 .. replaced by an ellipsis (...). 1129 .. %f file name, without the path name 1130 .. %h host name 1131 .. %s XNEdit server name (server mode only) 1132 .. %[*]S file status, either verbose (%S) or brief (%*S). 1133 .. In verbose mode the file status is spelled out: 1134 .. read-only, locked, and modified. In brief mode, 1135 .. abbreviations and an asterisk are used for the 1136 .. respective states: RO, LO, *. 1137 .. %u user name 1138 .. 1139 .. The format string and the component buttons are continously synchronized. 1140 .. 1141 .. The default format is: 1142 .. 1143 .. {%c} [%s] %f (%S) - %d 1144 .. 1145 .. The resulting title will only contain elements with 1146 .. a value. Hence, the title is compressed as follows: 1147 .. 1148 .. * Elements with no value are removed. 1149 .. * Empty parenthesis pairs i.e. (), [] or {}, or parenthesis pairs containing only space(s), are removed. 1150 .. * Sequences of spaces are replaced with one space. 1151 .. * Leading spaces and dashes are removed. 1152 .. * Trailing spaces and dashes are removed. 1153 .. 1154 .. If the server name and the ClearCase view tag are identical, only 1155 .. the first one specified in the format string will be displayed. 1156 .. 1157 .. **Previewing the settings** 1158 .. 1159 .. The lower part of the dialog can be used to test the selected title 1160 .. under various conditions. For some of the components that are selected 1161 .. for display, various states can be enforced on the preview. 1162 .. 1163 .. For instance, components that are not always active (such the 1164 .. XNEdit server name) can be turned on or off in the preview. 1165 .. 1166 .. ~ help 1167 1168 Auto/Smart Indent 1169 ----------------- 1170 1171 Programmers who use structured languages usually require some form of 1172 automatic indent, so that they don't have to continually re-type the 1173 sequences of tabs and/or spaces needed to maintain lengthy running indents. 1174 XNEdit therefore offers "smart" indent, in addition to the traditional 1175 automatic indent which simply lines up the cursor position with the previous 1176 line. 1177 1178 3>Smart Indent 1179 1180 Smart indent macros are only available by default for C and C++, and while 1181 these can easily be configured for different default indentation distances, 1182 they may not conform to everyone's exact C programming style. Smart indent 1183 is programmed in terms of macros in the XNEdit macro language which can be 1184 entered in: Preferences -> Default Settings -> Indent -> Program Smart 1185 Indent. Hooks are provided for intervening at the point that a newline is 1186 entered, either via the user pressing the Enter key, or through 1187 auto-wrapping; and for arbitrary type-in to act on specific characters typed. 1188 1189 To type a newline character without invoking smart-indent when operating in 1190 smart-indent mode, hold the Shift key while pressing the Return or Enter key. 1191 1192 3>Auto-Indent 1193 1194 With Indent set to Auto (the default), XNEdit keeps a running indent. When 1195 you press the Return or Enter key, spaces and tabs are inserted to line up 1196 the insert point under the start of the previous line. 1197 1198 Regardless of indent-mode, Ctrl+Return always does the automatic indent; 1199 Shift+Return always does a return without indent. 1200 1201 3>Block Indentation Adjustment 1202 1203 The Shift Left and Shift Right commands as well as rectangular dragging can 1204 be used to adjust the indentation for several lines at once. To shift a 1205 block of text one character to the right, select the text, then choose Shift 1206 Right from the Edit menu. Note that the accelerator keys for these menu 1207 items are Ctrl+9 and Ctrl+0, which correspond to the right and left 1208 parenthesis on most keyboards. Remember them as adjusting the text in the 1209 direction pointed to by the parenthesis character. Holding the Shift key 1210 while selecting either Shift Left or Shift Right will shift the text by one 1211 tab stop (or by one emulated tab stop if tab emulation is turned on). The 1212 help section "Shifting and Filling" under "Basic Operation" has details. 1213 ---------------------------------------------------------------------- 1214 1215 Syntax Highlighting 1216 ------------------- 1217 1218 Syntax Highlighting means using colors and fonts to help distinguish language 1219 elements in programming languages and other types of structured files. 1220 Programmers use syntax highlighting to understand code faster and better, and 1221 to spot many kinds of syntax errors more quickly. 1222 1223 To use syntax highlighting in XNEdit, select Highlight Syntax in the 1224 Preferences menu. If XNEdit recognizes the computer language that you are 1225 using, and highlighting rules (patterns) are available for that language, it 1226 will highlight your text, and maintain the highlighting, automatically, as 1227 you type. 1228 1229 If XNEdit doesn't correctly recognize the type of the file you are editing, 1230 you can manually select a language mode from Language Modes in the 1231 Preferences menu. You can also program the method that XNEdit uses to 1232 recognize language modes in Preferences -> Default Settings -> Language 1233 Modes.... 1234 1235 If no highlighting patterns are available for the language that you want to 1236 use, you can create new patterns relatively quickly. The Help section 1237 "Highlighting_Patterns_" under "Customizing", has details. 1238 1239 If you are satisfied with what XNEdit is highlighting, but would like it to 1240 use different colors or fonts, you can change these by selecting Preferences 1241 -> Default Settings -> Syntax Highlighting -> Text Drawing Styles. 1242 Highlighting patterns are connected with font and color information through a 1243 common set of styles so that colorings defined for one language will be 1244 similar across others, and patterns within the same language which are meant 1245 to appear identical can be changed in the same place. To understand which 1246 styles are used to highlight the language you are interested in, you may need 1247 to look at "Highlighting_Patterns_" section, as well. 1248 1249 Syntax highlighting is CPU intensive, and under some circumstances can affect 1250 XNEdit's responsiveness. If you have a particularly slow system, or work with 1251 very large files, you may not want to use it all of the time. Syntax 1252 highlighting introduces two kinds of delays. The first is an initial parsing 1253 delay, proportional to the size of the file. This delay is also incurred 1254 when pasting large sections of text, filtering text through shell commands, 1255 and other circumstances involving changes to large amounts of text. The 1256 second kind of delay happens when text which has not previously been visible 1257 is scrolled in to view. Depending on your system, and the highlight patterns 1258 you are using, this may or may not be noticeable. A typing delay is also 1259 possible, but unlikely if you are only using the built-in patterns. 1260 ---------------------------------------------------------------------- 1261 1262 Finding Declarations (ctags) 1263 ---------------------------- 1264 1265 XNEdit can process tags files generated using the Unix _ctags command or the 1266 Exuberant Ctags program. Ctags creates index files correlating names of 1267 functions and declarations with their locations in C, Fortran, or Pascal source 1268 code files. (See the ctags manual page for more information). Ctags produces a 1269 file called "tags" which can be loaded by XNEdit. XNEdit can manage any number 1270 of tags files simultaneously. Tag collisions are handled with a popup menu to 1271 let the user decide which tag to use. In 'Smart' mode XNEdit will automatically 1272 choose the desired tag based on the scope of the file or module. Once loaded, 1273 the information in the tags file enables XNEdit to go directly to the 1274 declaration of a highlighted function or data structure name with a single 1275 command. To load a tags file, select "Load Tags File" from the File menu and 1276 choose a tags file to load, or specify the name of the tags file on the XNEdit 1277 command line: 1278 1279 xnedit -tags tags 1280 1281 XNEdit can also be set to load a tags file automatically when it starts up. 1282 Setting the X resource nedit.tagFile to the name of a tag file tells XNEdit to 1283 look for that file at startup time (see "Customizing_XNEdit_"). The file name 1284 can be either a complete path name, in which case XNEdit will always load the 1285 same tags file, or a file name without a path or with a relative path, in 1286 which case XNEdit will load it starting from the current directory. The 1287 second option allows you to have different tags files for different projects, 1288 each automatically loaded depending on the directory you're in when you start 1289 XNEdit. Setting the name to "tags" is an obvious choice since this is the 1290 name that ctags uses. XNEdit normally evaluates relative path tag file 1291 specifications every time a file is opened. All accessible tag files are 1292 loaded at this time. To disable the automatic loading of tag files specified 1293 as relative paths, set the X resource nedit.alwaysCheckRelativeTagsSpecs to 1294 False. 1295 1296 To unload a tags file, select "Un-load Tags File" from the File menu and 1297 choose from the list of tags files. XNEdit will keep track of tags file updates 1298 by checking the timestamp on the files, and automatically update the tags 1299 cache. 1300 1301 To find the definition of a function or data structure once a tags file is 1302 loaded, select the name anywhere it appears in your program (see 1303 "Selecting_Text_") and choose "Find Definition" from the Search menu. 1304 ---------------------------------------------------------------------- 1305 1306 Calltips 1307 -------- 1308 1309 Calltips are little yellow boxes that pop up to remind you what the arguments 1310 and return type of a function are. More generally, they're a UI mechanism to 1311 present a small amount of crucial information in a prominent location. To 1312 display a calltip, select some text and choose "Show Calltip" from the Search 1313 menu. To kill a displayed calltip, hit Esc. 1314 1315 Calltips get their information from one of two places -- either a tags file (see 1316 "Finding_Declarations_(ctags)_") or a calltips file. First, any loaded calltips 1317 files are searched for a definition, and if nothing is found then the tags 1318 database is searched. If a tag is found that matches the highlighted text then 1319 a calltip is displayed with the first few lines of the definition -- usually 1320 enough to show you what the arguments of a function are. 1321 1322 You can load a calltips file by using choosing "Load Calltips File" from the 1323 File menu. You can unload a calltips file by selecting it from the 1324 "Unload Calltips File" submenu of the File menu. You can also choose one or 1325 more default calltips files to be loaded for each language mode using the 1326 "Default calltips file(s)" field of the Language Modes dialog. 1327 1328 The calltips file format is very simple. calltips files are organized in blocks 1329 separated by blank lines. The first line of the block is the key, which is the 1330 word that is matched when a calltip is requested. The rest of the block is 1331 displayed as the calltip. 1332 1333 Almost any text at all can appear in a calltip key or a calltip. There are no 1334 special characters that need to be escaped. The only issues to note are that 1335 trailing whitespace is ignored, and you cannot have a blank line inside a 1336 calltip. (Use a single period instead -- it'll be nearly invisible.) You should 1337 also avoid calltip keys that begin and end with '@*' characters, since those are 1338 used to mark special blocks. 1339 1340 There are five special block types--comment, include, language, alias, and 1341 version--which are distinguished by their first lines, "@* comment @*", 1342 "@* include @*", "@* language @*", "@* alias @*", and "@* version @*" respectively 1343 (without quotes). 1344 1345 Comment blocks are ignored when reading calltips files. 1346 1347 Include blocks specify additional calltips files to load, one per line. The ~ 1348 character can be used for your $HOME directory, but other shell shortcuts like 1349 @* and ? can't be used. Include blocks allow you to make a calltips file for your 1350 project that includes, say, the calltips files for C, Motif, and Xt. 1351 1352 Language blocks specify which language mode the calltips should be used with. 1353 When a calltip is requested it won't match tips from languages other than the 1354 current language mode. Language blocks only affect the tips listed after the 1355 block. 1356 1357 Alias blocks allow a calltip to have multiple keys. The first line of the block 1358 is the key for the calltip to be displayed, and the rest of the lines are 1359 additional keys, one per line, that should also show the calltip. 1360 1361 Version blocks are ignored for the time being. 1362 1363 You can use calltips in your own macros using the calltip() and kill_calltip() 1364 macro subroutines and the $calltip_ID macro variable. See the 1365 Macro_Subroutines_ section for details. 1366 ---------------------------------------------------------------------- 1367 1368 Regular Expressions 1369 =================== 1370 1371 Basic Regular Expression Syntax 1372 ------------------------------- 1373 1374 Regular expressions (regex's) are useful as a way to match inexact sequences 1375 of characters. They can be used in the `Find...' and `Replace...' search 1376 dialogs and are at the core of Color Syntax Highlighting patterns. To specify 1377 a regular expression in a search dialog, simply click on the `Regular 1378 Expression' radio button in the dialog. 1379 1380 A regex is a specification of a pattern to be matched in the searched text. 1381 This pattern consists of a sequence of tokens, each being able to match a 1382 single character or a sequence of characters in the text, or assert that a 1383 specific position within the text has been reached (the latter is called an 1384 anchor.) Tokens (also called atoms) can be modified by adding one of a number 1385 of special quantifier tokens immediately after the token. A quantifier token 1386 specifies how many times the previous token must be matched (see below.) 1387 1388 Tokens can be grouped together using one of a number of grouping constructs, 1389 the most common being plain parentheses. Tokens that are grouped in this way 1390 are also collectively considered to be a regex atom, since this new larger 1391 atom may also be modified by a quantifier. 1392 1393 A regex can also be organized into a list of alternatives by separating each 1394 alternative with pipe characters, `|'. This is called alternation. A match 1395 will be attempted for each alternative listed, in the order specified, until a 1396 match results or the list of alternatives is exhausted (see Alternation_ 1397 section below.) 1398 1399 3>The 'Any' Character 1400 1401 If a dot (`.') appears in a regex, it means to match any character exactly 1402 once. By default, dot will not match a newline character, but this behavior 1403 can be changed (see help topic Parenthetical_Constructs_, under the 1404 heading, Matching Newlines). 1405 1406 3>Character Classes 1407 1408 A character class, or range, matches exactly one character of text, but the 1409 candidates for matching are limited to those specified by the class. Classes 1410 come in two flavors as described below: 1411 1412 [...] Regular class, match only characters listed. 1413 [^...] Negated class, match only characters ~not~ listed. 1414 1415 As with the dot token, by default negated character classes do not match 1416 newline, but can be made to do so. 1417 1418 The characters that are considered special within a class specification are 1419 different than the rest of regex syntax as follows. If the first character in 1420 a class is the `]' character (second character if the first character is `^') 1421 it is a literal character and part of the class character set. This also 1422 applies if the first or last character is `-'. Outside of these rules, two 1423 characters separated by `-' form a character range which includes all the 1424 characters between the two characters as well. For example, `[^f-j]' is the 1425 same as `[^fghij]' and means to match any character that is not `f', `g', 1426 `h', `i', or `j'. 1427 1428 3>Anchors 1429 1430 Anchors are assertions that you are at a very specific position within the 1431 search text. XNEdit regular expressions support the following anchor tokens: 1432 1433 ^ Beginning of line 1434 $ End of line 1435 < Left word boundary 1436 > Right word boundary 1437 \B Not a word boundary 1438 1439 Note that the \B token ensures that neither the left nor the right character 1440 are delimiters, **or** that both left and right characters are delimiters. 1441 The left word anchor checks whether the previous character is a delimiter and 1442 the next character is not. The right word anchor works in a similar way. 1443 1444 Note that word delimiters are user-settable, and defined by the X resource 1445 wordDelimiters, cf. X_Resources_. 1446 1447 3>Quantifiers 1448 1449 Quantifiers specify how many times the previous regular expression atom may 1450 be matched in the search text. Some quantifiers can produce a large 1451 performance penalty, and can in some instances completely lock up XNEdit. To 1452 prevent this, avoid nested quantifiers, especially those of the maximal 1453 matching type (see below.) 1454 1455 The following quantifiers are maximal matching, or "greedy", in that they 1456 match as much text as possible (but don't exclude shorter matches if that 1457 is necessary to achieve an overall match). 1458 1459 * Match zero or more 1460 + Match one or more 1461 ? Match zero or one 1462 1463 The following quantifiers are minimal matching, or "lazy", in that they match 1464 as little text as possible (but don't exclude longer matches if that is 1465 necessary to achieve an overall match). 1466 1467 *? Match zero or more 1468 +? Match one or more 1469 ?? Match zero or one 1470 1471 One final quantifier is the counting quantifier, or brace quantifier. It 1472 takes the following basic form: 1473 1474 {min,max} Match from `min' to `max' times the 1475 previous regular expression atom. 1476 1477 If `min' is omitted, it is assumed to be zero. If `max' is omitted, it is 1478 assumed to be infinity. Whether specified or assumed, `min' must be less 1479 than or equal to `max'. Note that both `min' and `max' are limited to 1480 65535. If both are omitted, then the construct is the same as `*'. Note 1481 that `{,}' and `{}' are both valid brace constructs. A single number 1482 appearing without a comma, e.g. `{3}' is short for the `{min,min}' construct, 1483 or to match exactly `min' number of times. 1484 1485 The quantifiers `{1}' and `{1,1}' are accepted by the syntax, but are 1486 optimized away since they mean to match exactly once, which is redundant 1487 information. Also, for efficiency, certain combinations of `min' and `max' 1488 are converted to either `*', `+', or `?' as follows: 1489 1490 {} {,} {0,} * 1491 {1,} + 1492 {,1} {0,1} ? 1493 1494 Note that {0} and {0,0} are meaningless and will generate an error message at 1495 regular expression compile time. 1496 1497 Brace quantifiers can also be "lazy". For example {2,5}? would try to match 1498 2 times if possible, and will only match 3, 4, or 5 times if that is what is 1499 necessary to achieve an overall match. 1500 1501 3>Alternation 1502 1503 A series of alternative patterns to match can be specified by separating them 1504 with vertical pipes, `|'. An example of _alternation would be `a|be|sea'. 1505 This will match `a', or `be', or `sea'. Each alternative can be an 1506 arbitrarily complex regular expression. The alternatives are attempted in 1507 the order specified. An empty alternative can be specified if desired, e.g. 1508 `a|b|'. Since an empty alternative can match nothingness (the empty string), 1509 this guarantees that the expression will match. 1510 1511 3>Comments 1512 1513 Comments are of the form `(?#<comment text>)' and can be inserted anywhere 1514 and have no effect on the execution of the regular expression. They can be 1515 handy for documenting very complex regular expressions. Note that a comment 1516 begins with `(?#' and ends at the first occurrence of an ending parenthesis, 1517 or the end of the regular expression... period. Comments do not recognize 1518 any escape sequences. 1519 ---------------------------------------------------------------------- 1520 1521 Metacharacters 1522 -------------- 1523 1524 3>Escaping Metacharacters 1525 1526 In a regular expression (regex), most ordinary characters match themselves. 1527 For example, `ab%' would match anywhere `a' followed by `b' followed by `%' 1528 appeared in the text. Other characters don't match themselves, but are 1529 metacharacters. For example, backslash is a special metacharacter which 1530 'escapes' or changes the meaning of the character following it. Thus, to 1531 match a literal backslash would require a regular expression to have two 1532 backslashes in sequence. XNEdit provides the following escape sequences so 1533 that metacharacters that are used by the regex syntax can be specified as 1534 ordinary characters. 1535 1536 \( \) \- \[ \] \< \> \{ \} 1537 \. \| \^ \$ \* \+ \? \& \\ 1538 1539 3>Special Control Characters 1540 1541 There are some special characters that are difficult or impossible to type. 1542 Many of these characters can be constructed as a sort of metacharacter or 1543 sequence by preceding a literal character with a backslash. XNEdit recognizes 1544 the following special character sequences: 1545 1546 \a alert (bell) 1547 \b backspace 1548 \e ASCII escape character (***) 1549 \f form feed (new page) 1550 \n newline 1551 \r carriage return 1552 \t horizontal tab 1553 \v vertical tab 1554 1555 *** For environments that use the EBCDIC character set, 1556 when compiling XNEdit set the EBCDIC_CHARSET compiler 1557 symbol to get the EBCDIC equivalent escape 1558 character.) 1559 1560 3>Octal and Hex Escape Sequences 1561 1562 Any ASCII (or EBCDIC) character, except null, can be specified by using 1563 either an octal escape or a hexadecimal escape, each beginning with \0 or \x 1564 (or \X), respectively. For example, \052 and \X2A both specify the `*' 1565 character. Escapes for null (\00 or \x0) are not valid and will generate an 1566 error message. Also, any escape that exceeds \0377 or \xFF will either cause 1567 an error or have any additional character(s) interpreted literally. For 1568 example, \0777 will be interpreted as \077 (a `?' character) followed by `7' 1569 since \0777 is greater than \0377. 1570 1571 An invalid digit will also end an octal or hexadecimal escape. For example, 1572 \091 will cause an error since `9' is not within an octal escape's range of 1573 allowable digits (0-7) and truncation before the `9' yields \0 which is 1574 invalid. 1575 1576 3>Shortcut Escape Sequences 1577 1578 XNEdit defines some escape sequences that are handy shortcuts for commonly 1579 used character classes. 1580 1581 \d digits 0-9 1582 \l letters a-z, A-Z, and locale dependent letters 1583 \s whitespace \t, \r, \v, \f, and space 1584 \w word characters letters, digits, and underscore, `_' 1585 1586 \D, \L, \S, and \W are the same as the lowercase versions except that the 1587 resulting character class is negated. For example, \d is equivalent to 1588 `[0-9]', while \D is equivalent to `[^0-9]'. 1589 1590 These escape sequences can also be used within a character class. For 1591 example, `[\l_]' is the same as `[a-zA-Z@_]', extended with possible locale 1592 dependent letters. The escape sequences for special characters, and octal 1593 and hexadecimal escapes are also valid within a class. 1594 1595 3>Word Delimiter Tokens 1596 1597 Although not strictly a character class, the following escape sequences 1598 behave similarly to character classes: 1599 1600 \y Word delimiter character 1601 \Y Not a word delimiter character 1602 1603 The `\y' token matches any single character that is one of the characters 1604 that XNEdit recognizes as a word delimiter character, while the `\Y' token 1605 matches any character that is ~not~ a word delimiter character. Word 1606 delimiter characters are dynamic in nature, meaning that the user can change 1607 them through preference settings. For this reason, they must be handled 1608 differently by the regular expression engine. As a consequence of this, 1609 `\y' and `\Y' cannot be used within a character class specification. 1610 ---------------------------------------------------------------------- 1611 1612 Parenthetical Constructs 1613 ------------------------ 1614 1615 3>Capturing Parentheses 1616 1617 Capturing Parentheses are of the form `(<regex>)' and can be used to group 1618 arbitrarily complex regular expressions. Parentheses can be nested, but the 1619 total number of parentheses, nested or otherwise, is limited to 50 pairs. 1620 The text that is matched by the regular expression between a matched set of 1621 parentheses is captured and available for text substitutions and 1622 backreferences (see below.) Capturing parentheses carry a fairly high 1623 overhead both in terms of memory used and execution speed, especially if 1624 quantified by `*' or `+'. 1625 1626 3>Non-Capturing Parentheses 1627 1628 Non-Capturing Parentheses are of the form `(?:<regex>)' and facilitate 1629 grouping only and do not incur the overhead of normal capturing parentheses. 1630 They should not be counted when determining numbers for capturing parentheses 1631 which are used with backreferences and substitutions. Because of the limit 1632 on the number of capturing parentheses allowed in a regex, it is advisable to 1633 use non-capturing parentheses when possible. 1634 1635 3>Positive Look-Ahead 1636 1637 Positive look-ahead constructs are of the form `(?=<regex>)' and implement a 1638 zero width assertion of the enclosed regular expression. In other words, a 1639 match of the regular expression contained in the positive look-ahead 1640 construct is attempted. If it succeeds, control is passed to the next 1641 regular expression atom, but the text that was consumed by the positive 1642 look-ahead is first unmatched (backtracked) to the place in the text where 1643 the positive look-ahead was first encountered. 1644 1645 One application of positive look-ahead is the manual implementation of a 1646 first character discrimination optimization. You can include a positive 1647 look-ahead that contains a character class which lists every character that 1648 the following (potentially complex) regular expression could possibly start 1649 with. This will quickly filter out match attempts that cannot possibly 1650 succeed. 1651 1652 3>Negative Look-Ahead 1653 1654 Negative look-ahead takes the form `(?!<regex>)' and is exactly the same as 1655 positive look-ahead except that the enclosed regular expression must NOT 1656 match. This can be particularly useful when you have an expression that is 1657 general, and you want to exclude some special cases. Simply precede the 1658 general expression with a negative look-ahead that covers the special cases 1659 that need to be filtered out. 1660 1661 3>Positive Look-Behind 1662 1663 Positive look-behind constructs are of the form `(?<=<regex>)' and implement 1664 a zero width assertion of the enclosed regular expression in front of the 1665 current matching position. It is similar to a positive look-ahead assertion, 1666 except for the fact that the match is attempted on the text preceding the 1667 current position, possibly even in front of the start of the matching range 1668 of the entire regular expression. 1669 1670 A restriction on look-behind expressions is the fact that the expression 1671 must match a string of a bounded size. In other words, `*', `+', and `{n,}' 1672 quantifiers are not allowed inside the look-behind expression. Moreover, 1673 matching performance is sensitive to the difference between the upper and 1674 lower bound on the matching size. The smaller the difference, the better the 1675 performance. This is especially important for regular expressions used in 1676 highlight patterns. 1677 1678 Positive look-behind has similar applications as positive look-ahead. 1679 1680 3>Negative Look-Behind 1681 1682 Negative look-behind takes the form `(?<!<regex>)' and is exactly the same as 1683 positive look-behind except that the enclosed regular expression must 1684 ~not~ match. The same restrictions apply. 1685 1686 Note however, that performance is even more sensitive to the distance 1687 between the size boundaries: a negative look-behind must not match for 1688 **any** possible size, so the matching engine must check **every** size. 1689 1690 3>Case Sensitivity 1691 1692 There are two parenthetical constructs that control case sensitivity: 1693 1694 (?i<regex>) Case insensitive; `AbcD' and `aBCd' are 1695 equivalent. 1696 1697 (?I<regex>) Case sensitive; `AbcD' and `aBCd' are 1698 different. 1699 1700 Regular expressions are case sensitive by default, that is, `(?I<regex>)' is 1701 assumed. All regular expression token types respond appropriately to case 1702 insensitivity including character classes and backreferences. There is some 1703 extra overhead involved when case insensitivity is in effect, but only to the 1704 extent of converting each character compared to lower case. 1705 1706 3>Matching Newlines 1707 1708 XNEdit regular expressions by default handle the matching of newlines in a way 1709 that should seem natural for most editing tasks. There are situations, 1710 however, that require finer control over how newlines are matched by some 1711 regular expression tokens. 1712 1713 By default, XNEdit regular expressions will ~not~ match a newline character for 1714 the following regex tokens: dot (`.'); a negated character class (`[^...]'); 1715 and the following shortcuts for character classes: 1716 1717 `\d', `\D', `\l', `\L', `\s', `\S', `\w', `\W', `\Y' 1718 1719 The matching of newlines can be controlled for the `.' token, negated 1720 character classes, and the `\s' and `\S' shortcuts by using one of the 1721 following parenthetical constructs: 1722 1723 (?n<regex>) `.', `[^...]', `\s', `\S' match newlines 1724 1725 (?N<regex>) `.', `[^...]', `\s', `\S' don't match 1726 newlines 1727 1728 `(?N<regex>)' is the default behavior. 1729 1730 3>Notes on New Parenthetical Constructs 1731 1732 Except for plain parentheses, none of the parenthetical constructs capture 1733 text. If that is desired, the construct must be wrapped with capturing 1734 parentheses, e.g. `((?i<regex))'. 1735 1736 All parenthetical constructs can be nested as deeply as desired, except for 1737 capturing parentheses which have a limit of 50 sets of parentheses, 1738 regardless of nesting level. 1739 1740 3>Back References 1741 1742 Backreferences allow you to match text captured by a set of capturing 1743 parenthesis at some later position in your regular expression. A 1744 backreference is specified using a single backslash followed by a single 1745 digit from 1 to 9 (example: \3). Backreferences have similar syntax to 1746 substitutions (see below), but are different from substitutions in that they 1747 appear within the regular expression, not the substitution string. The number 1748 specified with a backreference identifies which set of text capturing 1749 parentheses the backreference is associated with. The text that was most 1750 recently captured by these parentheses is used by the backreference to 1751 attempt a match. As with substitutions, open parentheses are counted from 1752 left to right beginning with 1. So the backreference `\3' will try to match 1753 another occurrence of the text most recently matched by the third set of 1754 capturing parentheses. As an example, the regular expression `(\d)\1' could 1755 match `22', `33', or `00', but wouldn't match `19' or `01'. 1756 1757 A backreference must be associated with a parenthetical expression that is 1758 complete. The expression `(\w(\1))' contains an invalid backreference since 1759 the first set of parentheses are not complete at the point where the 1760 backreference appears. 1761 1762 3>Substitution 1763 1764 Substitution strings are used to replace text matched by a set of capturing 1765 parentheses. The substitution string is mostly interpreted as ordinary text 1766 except as follows. 1767 1768 The escape sequences described above for special characters, and octal and 1769 hexadecimal escapes are treated the same way by a substitution string. When 1770 the substitution string contains the `&' character, XNEdit will substitute the 1771 entire string that was matched by the `Find...' operation. Any of the first 1772 nine sub-expressions of the match string can also be inserted into the 1773 replacement string. This is done by inserting a `\' followed by a digit from 1774 1 to 9 that represents the string matched by a parenthesized expression 1775 within the regular expression. These expressions are numbered left-to-right 1776 in order of their opening parentheses. 1777 1778 The capitalization of text inserted by `&' or `\1', `\2', ... `\9' can be 1779 altered by preceding them with `\U', `\u', `\L', or `\l'. `\u' and `\l' 1780 change only the first character of the inserted entity, while `\U' and `\L' 1781 change the entire entity to upper or lower case, respectively. 1782 ---------------------------------------------------------------------- 1783 1784 Advanced Topics 1785 --------------- 1786 1787 3>Substitutions 1788 1789 Regular expression substitution can be used to program automatic editing 1790 operations. For example, the following are search and replace strings to find 1791 occurrences of the `C' language subroutine `get_x', reverse the first and 1792 second parameters, add a third parameter of NULL, and change the name to 1793 `new_get_x': 1794 1795 Search string: `get_x *\( *([^ ,]*), *([^\)]*)\)' 1796 Replace string: `new_get_x(\2, \1, NULL)' 1797 1798 3>Ambiguity 1799 1800 If a regular expression could match two different parts of the text, it will 1801 match the one which begins earliest. If both begin in the same place but 1802 match different lengths, or match the same length in different ways, life 1803 gets messier, as follows. 1804 1805 In general, the possibilities in a list of alternatives are considered in 1806 left-to-right order. The possibilities for `*', `+', and `?' are considered 1807 longest-first, nested constructs are considered from the outermost in, and 1808 concatenated constructs are considered leftmost-first. The match that will be 1809 chosen is the one that uses the earliest possibility in the first choice that 1810 has to be made. If there is more than one choice, the next will be made in 1811 the same manner (earliest possibility) subject to the decision on the first 1812 choice. And so forth. 1813 1814 For example, `(ab|a)b*c' could match `abc' in one of two ways. The first 1815 choice is between `ab' and `a'; since `ab' is earlier, and does lead to a 1816 successful overall match, it is chosen. Since the `b' is already spoken for, 1817 the `b*' must match its last possibility, the empty string, since it must 1818 respect the earlier choice. 1819 1820 In the particular case where no `|'s are present and there is only one `*', 1821 `+', or `?', the net effect is that the longest possible match will be 1822 chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that 1823 if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x', due 1824 to the begins-earliest rule. (In effect, the decision on where to start the 1825 match is the first choice to be made, hence subsequent choices must respect 1826 it even if this leads them to less-preferred alternatives.) 1827 1828 3>References 1829 1830 An excellent book on the care and feeding of regular expressions is 1831 1832 Mastering Regular Expressions, 3rd Edition 1833 Jeffrey E. F. Friedl 1834 August 2006, O'Reilly & Associates 1835 ISBN 0-596-52812-4 1836 1837 The first end second editions of this book are still useful for basic 1838 introduction to regexes and contain many useful tips and tricks. 1839 ---------------------------------------------------------------------- 1840 1841 Example Regular Expressions 1842 --------------------------- 1843 1844 The following are regular expression examples which will match: 1845 1846 * An entire line. 1847 ! ^.*$ 1848 1849 * Blank lines. 1850 ! ^$ 1851 1852 * Whitespace on a line. 1853 ! \s+ 1854 1855 * Whitespace across lines. 1856 ! (?n\s+) 1857 1858 * Whitespace that spans at least two lines. Note minimal matching `*?' quantifier. 1859 ! (?n\s*?\n\s*) 1860 1861 * IP address (not robust). 1862 ! (?:\d{1,3}(?:\.\d{1,3}){3}) 1863 1864 * Two character US Postal state abbreviations (includes territories). 1865 ! [ACDF-IK-PR-W][A-Z] 1866 1867 * Web addresses. 1868 ! (?:http://)?www\.\S+ 1869 1870 * Case insensitive double words across line breaks. 1871 ! (?i(?n<(\S+)\s+\1>)) 1872 1873 * Upper case words with possible punctuation. 1874 ! <[A-Z][^a-z\s]*> 1875 1876 ---------------------------------------------------------------------- 1877 1878 Macro/Shell Extensions 1879 ====================== 1880 1881 Shell Commands and Filters 1882 -------------------------- 1883 1884 The Shell menu (Unix versions only) allows you to execute Unix shell commands 1885 from within XNEdit. You can add items to the menu to extend XNEdit's command 1886 set or to incorporate custom automatic editing features using shell commands 1887 or editing languages like awk and sed. To add items to the menu, select 1888 Preferences -> Default Settings Customize Menus -> Shell Menu. XNEdit comes 1889 pre-configured with a few useful Unix commands like spell and sort, but we 1890 encourage you to add your own custom extensions. 1891 1892 Filter Selection... prompts you for a Unix command to use to process the 1893 currently selected text. The output from this command replaces the contents 1894 of the selection. 1895 1896 Execute Command... prompts you for a Unix command and replaces the current 1897 selection with the output of the command. If there is no selection, it 1898 deposits the output at the current insertion point. In the Shell Command 1899 field, the % character expands to the name (including directory path), and 1900 the # character expands to the current line number of the file in the window. 1901 To include a % or # character in the command, use %% or ##, respectively. 1902 1903 Execute Command Line uses the position of the cursor in the window to 1904 indicate a line to execute as a shell command line. The cursor may be 1905 positioned anywhere on the line. This command allows you to use an XNEdit 1906 window as an editable command window for saving output and saving commands 1907 for re-execution. Note that the same character expansions described above 1908 in Execute Command also occur with this command. 1909 1910 The X resource called nedit.shell (See "Customizing_XNEdit_") determines which 1911 Unix shell is used to execute commands. The default value for this resource 1912 is the user's login shell. 1913 ---------------------------------------------------------------------- 1914 1915 Input/Output Filters 1916 -------------------- 1917 1918 Input/Output Filters are filter commands executed when opening or saving 1919 files. 1920 1921 File Pattern: A glob pattern used to automatically select filters in the 1922 Open/Save File dialog. When a file that matches a file pattern is selected, 1923 the filter is automatically applied. 1924 1925 Default Extension: The default file extension is automatically added to a file 1926 name when a filter is selected in the "Save File As" dialog. 1927 1928 Input Filter Command: The command line executed when a filter is selected in 1929 the Open File dialog and the file is opened. The command receives the file 1930 content as input, and a document with the command's output is opened. 1931 1932 Output Filter Command: The command line executed when a file is saved and a 1933 filter was selected, either in the "Save File As" dialog or previously when 1934 the document was opened with a filter. The command receives the document 1935 content as input, and the output of the command is written to the file. 1936 ---------------------------------------------------------------------- 1937 1938 Learn/Replay 1939 ------------ 1940 1941 Selecting Learn Keystrokes from the Macro menu puts XNEdit in learn mode. In 1942 learn mode, keystrokes and menu commands are recorded, to be played back 1943 later, using the Replay Keystrokes command, or pasted into a macro in the 1944 Macro Commands dialog of the Default Settings menu in Preferences. 1945 1946 Note that only keyboard and menu commands are recorded, not mouse clicks or 1947 mouse movements since these have no absolute point of reference, such as 1948 cursor or selection position. When you do a mouse-based operation in learn 1949 mode, XNEdit will beep (repeatedly) to remind you that the operation was not 1950 recorded. 1951 1952 Learn mode is also the quickest and easiest method for writing macros. The 1953 dialog for creating macro commands contains a button labeled "Paste Learn / 1954 Replay Macro", which will deposit the last sequence learned into the body of 1955 the macro. 1956 1957 3>Repeating Actions and Learn/Replay Sequences 1958 1959 You can repeat the last (keyboard-based) command, or learn/replay sequence 1960 with the Repeat... command in the Macro menu. To repeat an action, first do 1961 the action (that is, insert a character, do a search, move the cursor), then 1962 select Repeat..., decide how or how many times you want it repeated, and 1963 click OK. For example, to move down 30 lines through a file, you could type: 1964 <Down Arrow> Ctrl+, 29 <Return>. To repeat a learn/replay sequence, first 1965 learn it, then select Repeat..., click on Learn/Replay and how you want it 1966 repeated, then click OK. 1967 1968 If the commands you are repeating advance the cursor through the file, you 1969 can also repeat them within a range of characters, or from the current cursor 1970 position to the end of the file. To iterate over a range of characters, use 1971 the primary selection (drag the left mouse button over the text) to mark the 1972 range you want to operate on, and select "In Selection" in the Repeat dialog. 1973 1974 When using In "Selection" or "To End" with a learned sequence, try to do 1975 cursor movement as the last step in the sequence, since testing of the cursor 1976 position is only done at the end of the sequence execution. If you do cursor 1977 movement first, for example searching for a particular word then doing a 1978 modification, the position of the cursor won't be checked until the sequence 1979 has potentially gone far beyond the end of your desired range. 1980 1981 It's easy for a repeated command to get out of hand, and you can easily 1982 generate an infinite loop by using range iteration on a command which doesn't 1983 progress. To cancel a repeating command in progress, type Ctrl+. (period), 1984 or select Cancel Macro from the Macro menu. 1985 ---------------------------------------------------------------------- 1986 1987 Macro Language 1988 -------------- 1989 1990 Macros can be called from Macro menu commands, window background menu 1991 commands, within the smart-indent framework, from the autoload macro file, 1992 cf. Preferences_, and from the command line. 1993 Macro menu and window background menu commands are defined under Preferences 1994 -> Default Settings -> Customize Menus. Help on creating items in these 1995 menus can be found in the section Preferences_. 1996 1997 XNEdit's macro language is a simple interpreter with integer arithmetic, 1998 dynamic strings, and C-style looping constructs (very similar to the 1999 procedural portion of the Unix awk program). From the macro language, you 2000 can call the same action routines which are bound to keyboard keys and menu 2001 items, as well additional subroutines for accessing and manipulating editor 2002 data, which are specific to the macro language (these are listed in the 2003 sections titled "Macro_Subroutines_", and "Action_Routines_"). 2004 2005 2006 3>Syntax 2007 2008 An XNEdit macro language program consists of a list of statements, each 2009 terminated by a newline. Groups of statements which are executed together 2010 conditionally, such as the body of a loop, are surrounded by curly braces 2011 "{}". 2012 2013 Blank lines and comments are also allowed. Comments begin with a "#" and end 2014 with a newline, and can appear either on a line by themselves, or at the end 2015 of a statement. 2016 2017 Statements which are too long to fit on a single line may be split across 2018 several lines, by placing a backslash "\" character at the end of each line 2019 to be continued. 2020 2021 2022 3>Data Types 2023 2024 The XNEdit macro language recognizes only three data types, dynamic character 2025 strings, integer values and associative arrays. In general strings and 2026 integers can be used interchangeably. If a string represents an integer 2027 value, it can be used as an integer. Integers can be compared and 2028 concatenated with strings. Arrays may contain integers, strings, or arrays. 2029 Arrays are stored key/value pairs. Keys are always stored as strings. 2030 2031 4>Integer Constants 2032 2033 Integers are non-fractional numbers in the range of -2147483647 to 2034 2147483647. Integer constants must be in decimal. For example: 2035 2036 a = -1 2037 b = 1000 2038 2039 4>Character String Constants 2040 2041 Character string constants are enclosed in double quotes. For example: 2042 2043 a = "a string" 2044 dialog("Hi there!", "OK") 2045 2046 Strings may also include C-language style escape sequences: 2047 2048 \\ Backslash \t Tab \f Form feed 2049 \" Double quote \b Backspace \a Alert 2050 \n Newline \r Carriage return \v Vertical tab 2051 2052 Also allowed is the escape control character sequence: 2053 2054 \e Escape (ASCII or EBCDIC, 2055 depending on XNEdit compilation settings) 2056 2057 For example, to send output to the terminal from which XNEdit was started, a 2058 newline character is necessary because, like printf, t_print requires 2059 explicit newlines, and also buffers its output on a per-line basis: 2060 2061 t_print("a = " a "\n") 2062 2063 Other characters can be expressed as backslash-escape sequences in macro 2064 strings. The format is the same as for regular expressions, described in the 2065 paragraphs headed "Octal and Hex Escape Sequences" of the section 2066 "Metacharacters_", except that an octal escape sequence can start with any 2067 octal digit, not just 0, so the single character string "\0033" is the same 2068 as "\33", "\x1B" and "\e" (for an ASCII version of XNEdit). 2069 2070 Note that if you want to define a regular expression in a macro string, 2071 you need to "double-up" the backslashes for the metacharacters with 2072 special meaning in regular expressions. For example, the expression 2073 2074 (?N(\s|/\*(?n(?:(?!\*/).)*)\*/|//.*\n|\n)+) 2075 2076 which matches whitespace or C/C++/Java-style comments, should be written as 2077 a macro string as 2078 2079 "(?N(\\s|/\\*(?n(?:(?!\\*/).)*)\\*/|//.*\n|\n)+)" 2080 2081 (The "\n"s towards the end add literal newline characters to the string. The 2082 regular expression interpretation treats the newlines as themselves. It can 2083 also interpret the sequence "\\n" as a newline, although the macro string here 2084 would then contain a literal backslash followed by a lowercase `N'.) 2085 2086 2087 3>Variables 2088 2089 Variable names must begin either with a letter (local variables), or a $ 2090 (global variables). Beyond the first character, variables may also contain 2091 numbers and underscores `_'. Variables are called in to existence just by 2092 setting them (no explicit declarations are necessary). 2093 2094 Local variables are limited in scope to the subroutine (or menu item 2095 definition) in which they appear. Global variables are accessible from all 2096 routines, and their values persist beyond the call which created them, until 2097 reset. 2098 2099 4>Built-in Variables 2100 2101 XNEdit has a number of permanently defined variables, which are used to access 2102 global editor information and information about the window in which the 2103 macro is executing. These are listed along with the built in functions in 2104 the section titled "Macro_Subroutines_". 2105 2106 2107 3>Functions and Subroutines 2108 2109 The syntax of a function or subroutine call is: 2110 2111 function_name(arg1, arg2, ...) 2112 2113 where arg1, arg2, etc. represent the argument values which are passed to 2114 the routine being called. A function or subroutine call can be on a line by 2115 itself, as above, or if it returns a value, can be invoked within a character 2116 or numeric expression: 2117 2118 a = fn1(b, c) + fn2(d) 2119 dialog("fn3 says: " fn3()) 2120 2121 Arguments are passed by value. This means that you cannot return values via 2122 the argument list, only through the function value or indirectly through 2123 agreed-upon global variables. 2124 2125 4>Built-in Functions 2126 2127 XNEdit has a wide range of built in functions which can be called from the 2128 macro language. These routines are divided into two classes, macro-language 2129 functions, and editor action routines. Editor action routines are more 2130 flexible, in that they may be called either from the macro language, or bound 2131 directly to keys via translation tables. They are also limited, however, in 2132 that they cannot return values. Macro language routines can return values, 2133 but cannot be bound to keys in translation tables. 2134 2135 Nearly all of the built-in subroutines operate on an implied window, which is 2136 initially the window from which the macro was started. To manipulate the 2137 contents of other windows, use the focus_window subroutine to change the 2138 focus to the ones you wish to modify. focus_window can also be used to 2139 iterate over all of the currently open windows, using the special keyword 2140 names, "last" and "next". 2141 2142 For backwards compatibility, hyphenated action routine names are allowed, and 2143 most of the existing action routines names which contain underscores have an 2144 equivalent version containing hyphens ('-') instead of underscores. Use of 2145 these names is discouraged. The macro parser resolves the ambiguity between 2146 '-' as the subtraction/negation operator, and - as part of an action routine 2147 name by assuming subtraction unless the symbol specifically matches an action 2148 routine name. 2149 2150 4>User Defined Functions 2151 2152 Users can define their own macro subroutines, using the define keyword: 2153 2154 define subroutine_name { 2155 < body of subroutine > 2156 } 2157 2158 Subroutine definitions cannot appear within other definitions, nor within 2159 macro menu item definitions. They can only appear in (macro) files, such as 2160 the autoload macro file, cf. Preferences_. Macro files can be loaded with 2161 File -> Load Macro File or with the load_macro_file() action. 2162 2163 The arguments with which a user-defined subroutine or function was invoked, 2164 are presented as $1, $2, ... , $9 or $args[expr], where expr can be evaluated 2165 to an integer from 1 to the number of arguments. The number of arguments can 2166 be read from $n_args or $args[]. The array $args[expr] is the only way to 2167 access arguments beyond the first 9. 2168 2169 To return a value from a subroutine, and/or to exit from the subroutine 2170 before the end of the subroutine body, use the return statement: 2171 2172 return <value to return> 2173 2174 2175 3>Operators and Expressions 2176 2177 Operators have the same meaning and precedence that they do in C, except for 2178 ^, which raises a number to a power (y^x means y to the x power), rather than 2179 bitwise exclusive OR. The table below lists operators in decreasing order of 2180 precedence. 2181 2182 Operators Associativity 2183 () 2184 ^ right to left 2185 - ! ++ -- (unary) 2186 * / % left to right 2187 + - left to right 2188 > >= < <= == != left to right 2189 & left to right 2190 | left to right 2191 && left to right 2192 || left to right 2193 (concatenation) left to right 2194 = += -= *= /= %=, &= |= right to left 2195 2196 The order in which operands are evaluated in an expression is undefined, 2197 except for && and ||, which like C, evaluate operands left to right, but stop 2198 when further evaluation would no longer change the result. 2199 2200 4>Numerical Operators 2201 2202 The numeric operators supported by the XNEdit macro language are listed below: 2203 2204 + addition 2205 - subtraction or negation 2206 * multiplication 2207 / division 2208 % modulo 2209 ^ power 2210 & bitwise and 2211 | bitwise or 2212 2213 Increment (++) and decrement (--) operators can also be appended or prepended 2214 to variables within an expression. Prepended increment/decrement operators 2215 act before the variable is evaluated. Appended increment/decrement operators 2216 act after the variable is evaluated. 2217 2218 4>Logical and Comparison Operators 2219 2220 Logical operations produce a result of 0 (for false) or 1 (for true). In a 2221 logical operation, any non-zero value is recognized to mean true. The 2222 logical and comparison operators allowed in the XNEdit macro language are 2223 listed below: 2224 2225 && logical and 2226 || logical or 2227 ! not 2228 > greater 2229 < less 2230 >= greater or equal 2231 <= less or equal 2232 == equal (integers and/or strings) 2233 != not equal (integers and/or strings) 2234 2235 4>Character String Operators 2236 2237 The "operator" for concatenating two strings is the absence of an operator. 2238 Adjoining character strings with no operator in between means concatenation: 2239 2240 d = a b "string" c 2241 t_print("the value of a is: " a) 2242 2243 Comparison between character strings is done with the == and != operators, 2244 (as with integers). There are a number of useful built-in routines for 2245 working with character strings, which are listed in the section called 2246 "Macro_Subroutines_". 2247 2248 4>Arrays and Array Operators 2249 2250 Arrays may contain either strings, integers, or other arrays. Arrays are 2251 associative, which means that they relate two pieces of information, the key 2252 and the value. The key is always a string; if you use an integer it is 2253 converted to a string. 2254 2255 To determine if a given key is in an array, use the 'in' keyword. 2256 2257 if ("6" in x) 2258 <body> 2259 2260 If the left side of the in keyword is an array, the result is true if every 2261 key in the left array is in the right array. Array values are not compared. 2262 2263 To iterate through all the keys of an array use the 'for' looping construct. 2264 Keys are not guaranteed in any particular order: 2265 2266 for (aKey in x) 2267 <body> 2268 2269 Elements can be removed from an array using the delete command: 2270 2271 delete x[3] # deletes element with key 3 2272 delete x[] # deletes all elements 2273 2274 The number of elements in an array can be determined by referencing the 2275 array with no indices: 2276 2277 dialog("array x has " x[] " elements", "OK") 2278 2279 Arrays can be combined with some operators. All the following operators only 2280 compare the keys of the arrays. 2281 2282 result = x + y (Merge arrays) 2283 2284 The 'result' is a new array containing keys from both x and y. If 2285 duplicates are present values from y are used. 2286 2287 result = x - y (Remove keys) 2288 2289 The 'result' is a new array containing all keys from x that are not in y. 2290 2291 result = x & y (Common keys) 2292 2293 The 'result' is a new array containing all keys which are in both x and y. 2294 The values from y are used. 2295 2296 result = x | y (Unique keys) 2297 2298 The 'result' is a new array containing keys which exist in either x or y, 2299 but not both. 2300 2301 When duplicate keys are encountered using the + and & operators, the values 2302 from the array on the right side of the operators are used for the result. 2303 All of the above operators are array only, meaning both the left and right 2304 sides of the operator must be arrays. The results are also arrays. 2305 2306 Array keys can also contain multiple dimensions: 2307 2308 x[1, 1, 1] = "string" 2309 2310 These are used in the expected way, e.g.: 2311 2312 for (i = 1; i < 3; i++) 2313 { 2314 for (j = 1; j < 3; j++) 2315 { 2316 x[i, j] = k++ 2317 } 2318 } 2319 2320 gives the following array: 2321 2322 x[1, 1] = 0 2323 x[1, 2] = 1 2324 x[2, 1] = 2 2325 x[2, 2] = 3 2326 2327 Internally all indices are part of one string, separated by the string 2328 $sub_sep (ASCII 0x1c, 'FS'). The first key in the above example is in 2329 fact: 2330 2331 ["1" $sub_sep "1"] 2332 2333 If you need to extract one of the keys, you can use split(), using 2334 $sub_sep as the separator. 2335 2336 You can also check for the existence of multi-dimensional array by 2337 looking for $sub_sep in the key. 2338 2339 Last, you need $sub_sep if you want to use the 'in' keyword. 2340 2341 if ((1,2) in myArray) 2342 {..} 2343 2344 doesn't work, but 2345 2346 if (("1" $sub_sep "2") in myArray) 2347 {..} 2348 2349 does work. 2350 2351 3>Looping and Conditionals 2352 2353 XNEdit supports looping constructs: for and while, and conditional statements: 2354 if and else, with essentially the same syntax as C: 2355 2356 for (<init>, ...; <condition>; <increment>, ...) <body> 2357 2358 while (<condition>) <body> 2359 2360 if (<condition>) <body> 2361 2362 if (<condition>) <body> else <body> 2363 2364 <body>, as in C, can be a single statement, or a list of statements enclosed 2365 in curly braces ({}). <condition> is an expression which must evaluate to 2366 true for the statements in <body> to be executed. for loops may also contain 2367 initialization statements, <init>, executed once at the beginning of the 2368 loop, and increment/decrement statements (or any arbitrary statement), which 2369 are executed at the end of the loop, before the condition is evaluated again. 2370 2371 Examples: 2372 2373 for (i=0; i<100; i++) 2374 j = i * 2 2375 2376 for (i=0, j=20; i<20; i++, j--) { 2377 k = i * j 2378 t_print(i, j, k) 2379 } 2380 2381 while (k > 0) 2382 { 2383 k = k - 1 2384 t_print(k) 2385 } 2386 2387 for (;;) { 2388 if (i-- < 1) 2389 break 2390 } 2391 2392 Loops may contain break and continue statements. A **break** statement 2393 causes an exit from the innermost loop, a **continue** statement transfers 2394 control to the end of the loop. 2395 ---------------------------------------------------------------------- 2396 2397 Macro Subroutines 2398 ----------------- 2399 2400 3>Built in Variables 2401 2402 These variables are read-only and cannot be changed by direct assignment. 2403 2404 **$1**, **$2**, **$3**, **$4**, **$5**, **$6**, **$7**, **$8**, **$9** 2405 **$args**[~expr~] 2406 **$n_args** 2407 Argument information. The first 9 arguments (if there are that many) can 2408 be referenced as read-only values using the shorthand form. All arguments 2409 can be accessed as values in the **$args** array, using a numeric index 2410 starting at 1. The total number of arguments received by a function is 2411 given by **$n_args** or **$args[]**. 2412 2413 **$active_pane** 2414 Index of the current pane. 2415 2416 **$auto_indent** 2417 Contains the current preference for auto indent. 2418 Can be "off", "on", or "smart". 2419 2420 **$calltip_ID** 2421 Equals the ID of the currently displayed calltip, or 0 if no calltip is 2422 being displayed. 2423 2424 **$cursor** 2425 Position of the cursor in the current window. 2426 2427 **$column** 2428 Column number of the cursor position in the current window. 2429 2430 **$display_width** 2431 Width of the current pane in pixels. 2432 2433 **$em_tab_dist** 2434 If tab stop emulation is turned on in the Tab Stops... 2435 dialog of the Preferences menu, the value is the 2436 distance between emulated tab stops. If tab 2437 emulation is turned off, the value is 0. 2438 2439 **$empty_array** 2440 An array with no elements. This can be used to initialize 2441 an array to an empty state. 2442 2443 **$file_format** 2444 Current newline format that the file will be saved with. Can 2445 be "unix", "dos" or "macintosh". 2446 2447 **$file_name** 2448 Name of the file being edited in the current 2449 window, stripped of directory component. 2450 2451 **$file_path** 2452 Directory component of file being edited in the current window. 2453 2454 **$font_name** 2455 Contains the current plain text font name. 2456 2457 **$font_name_bold** 2458 Contains the current bold text font name. 2459 2460 **$font_name_bold_italic** 2461 Contains the current bold-italic text font name. 2462 2463 **$font_name_italic** 2464 Contains the current italic text font name. 2465 2466 **$highlight_syntax** 2467 Whether syntax highlighting is turned on. 2468 2469 **$incremental_backup** 2470 Contains 1 if incremental auto saving is on, otherwise 0. 2471 2472 **$incremental_search_line** 2473 Has a value of 1 if the preference is 2474 selected to always show the incremental search line, otherwise 0. 2475 2476 **$language_mode** 2477 Name of language mode set in the current window. 2478 2479 **$line** 2480 Line number of the cursor position in the current window. 2481 2482 **$locked** 2483 True if the file has been locked by the user. 2484 2485 **$make_backup_copy** 2486 Has a value of 1 if original file is kept in a 2487 backup file on save, otherwise 0. 2488 2489 **$max_font_width** 2490 The maximum font width of all the active styles. 2491 Syntax highlighting styles are only considered if syntax highlighting 2492 is turned on. 2493 2494 **$min_font_width** 2495 The minimum font width of all the active styles. 2496 Syntax highlighting styles are only considered if syntax highlighting 2497 is turned on. 2498 2499 **$modified** 2500 True if the file in the current window has 2501 been modified and the modifications have not 2502 yet been saved. 2503 2504 **$VERSION** 2505 Returns XNEdit's version number ('5006' for XNEdit 5.6). 2506 2507 **$n_display_lines** 2508 The number of lines visible in the currently active pane. 2509 2510 **$n_panes** 2511 The number of panes in the current window. 2512 2513 **$overtype_mode** 2514 True if in Overtype mode. 2515 2516 **$read_only** 2517 True if the file is read only. 2518 2519 **$selection_start, $selection_end** 2520 Beginning and ending positions of the 2521 primary selection in the current window, or 2522 -1 if there is no text selected in the current window. 2523 2524 **$selection_left, $selection_right** 2525 Left and right character offsets of the rectangular (primary) selection in 2526 the current window, or -1 if there is no selection or it is not rectangular. 2527 2528 **$server_name** 2529 Name of the current XNEdit server. 2530 2531 **$show_line_numbers** 2532 Whether line numbers are shown next to the text. 2533 2534 **$show_matching** 2535 Contains the current preference for showing matching pairs, 2536 such as "[]" and "{}" pairs. Can be "off", "delimiter", or "range". 2537 2538 **$match_syntax_based** 2539 Whether pair matching should use syntax information, if available. 2540 2541 **$statistics_line** 2542 Has a value of 1 if the statistics line is shown, otherwise 0. 2543 2544 **$sub_sep** 2545 Contains the value of the array sub-script separation string. 2546 2547 **$tab_dist** 2548 The distance between tab stops for a 2549 hardware tab character, as set in the 2550 Tab Stops... dialog of the Preferences menu. 2551 2552 **$text_length** 2553 The length of the text in the current document. 2554 2555 **$top_line** 2556 The line number of the top line of the currently active pane. 2557 2558 **$use_tabs** 2559 Whether the user is allowing the XNEdit to insert tab characters to maintain 2560 spacing in tab emulation and rectangular dragging operations. (The setting of 2561 the "Use tab characters in padding and emulated tabs" button in the 2562 Tab Stops... dialog of the Preferences menu.) 2563 2564 **$wrap_margin** 2565 The right margin in the current window for text wrapping and filling. 2566 2567 **$wrap_text** 2568 The current wrap text mode. Values are "none", "auto" or "continuous". 2569 2570 ..Disabled for 5.4 release. 2571 ..**$backlight_string** 2572 .. The current value of the window's backlighting specification. This is empty 2573 .. if backlighting is turned off. It can be changed through calls to the 2574 .. built-in macro function set_backlight_string(). 2575 2576 2577 3>Built-in Subroutines 2578 2579 **append_file( string, filename )** 2580 Appends a string to a named file. Returns 1 on successful write, or 0 if 2581 unsuccessful. 2582 2583 **beep()** 2584 Ring the bell. 2585 2586 **calltip( "text_or_key" [, pos [, mode or position_modifier, ...]] )** 2587 Pops up a calltip. <pos> is an optional position in the buffer where the tip 2588 will be displayed. Passing -1 for <pos> is equivalent to not specifying a 2589 position, and it guarantees that the tip will appear on-screen somewhere even 2590 if the cursor is not. The upper-left corner of the calltip will appear below 2591 where the cursor would appear if it were at this position. 2592 2593 <mode> is one of "tipText" (default), "tipKey", or "tagKey". "tipText" 2594 displays the text as-is, "tagKey" uses it as the key to look up a tag, then 2595 converts the tag to a calltip, and "tipKey" uses it as the key to look up a 2596 calltip, then falls back to "tagKey" behavior if that fails. You'll usually 2597 use "tipKey" or "tipText". 2598 2599 Finally, you can modify the placement of the calltip relative to the cursor 2600 position (or <pos>) with one or more of these optional position modifiers: 2601 "center" aligns the center of the calltip with the position. "right" aligns 2602 the right edge of the calltip with the position. ("center" and "right" may 2603 not both be used.) "above" places the calltip above the position. "strict" 2604 does not allow the calltip to move from its position in order to avoid going 2605 off-screen or obscuring the cursor. 2606 2607 Returns the ID of the calltip if it was found and/or displayed correctly, 2608 0 otherwise. 2609 2610 **clipboard_to_string()** 2611 Returns the contents of the clipboard as a macro string. Returns empty 2612 string on error. 2613 2614 **dialog( message, btn_1_label, btn_2_label, ... )** 2615 Pop up a dialog for querying and presenting information to the user. First 2616 argument is a string to show in the message area of the dialog. 2617 Additional optional arguments represent labels for buttons to appear along 2618 the bottom of the dialog. Returns the number of the button pressed (the 2619 first button is number 1), or 0 if the user closed the dialog via the window 2620 close box. 2621 2622 **filename_dialog( [title[, mode[, defaultPath[, filter[, defaultName]]]]] )** 2623 Presents a file selection dialog with the given title to the user that 2624 prompts for a new or existing file. 2625 2626 Options are: ~title~ will be the title of the dialog, defaults to "Choose 2627 file". If ~mode~ is set to "exist" (default), the "New File Name"TextField 2628 of the FSB will be unmanaged. If "new", the TextField will be managed. 2629 ~defaultPath~ is the default path to use. Default (or "") will use the 2630 active document's directory. ~filter~ is the file glob which determines 2631 which files to display. Is set to "*" if filter is "" and by default. 2632 ~defaultName~ is the default filename that is filled in automatically. 2633 (**Note** that the default_filename argument does not work on all Motif 2634 implementations.) 2635 2636 Returns "" if the user cancelled the dialog, otherwise returns the 2637 fully-qualified path, including the filename. 2638 2639 **focus_window( window_name )** 2640 Sets the window on which subsequent macro commands operate. window_name can 2641 be either a fully qualified file name, or a relative filename (which will 2642 be completed from XNEdit's working directory) or one of "last" for the last 2643 window created, or "next" for the next window in the chain from the currently 2644 focused window (the first window being the one returned from calling 2645 focus_window("last"). Returns the name of the newly-focused window, or an 2646 empty string if the requested window was not found. 2647 2648 **get_character( position )** 2649 Returns the single character at the position 2650 indicated by the first argument to the routine from the current window. 2651 2652 **get_range( start, end )** 2653 Returns the text between a starting and ending position from the current 2654 window. 2655 2656 **get_selection()** 2657 Returns a string containing the text currently selected by the primary 2658 selection either from the current window (no keyword), or from anywhere on 2659 the screen (keyword "any"). 2660 2661 **getenv( name )** 2662 Gets the value of an environment variable. 2663 2664 **kill_calltip( [calltip_ID] )** 2665 Kills any calltip that is being displayed in the window in which the macro is 2666 running. If there is no displayed calltip this does nothing. If a calltip 2667 ID is supplied then the calltip is killed only if its ID is calltip_ID. 2668 2669 **length( string )** 2670 Returns the length of a string 2671 2672 **list_dialog( message, text, btn_1_label, btn_2_label, ... )** 2673 Pop up a dialog for prompting the user to choose a line from the given text 2674 string. The first argument is a message string to be used as a title for the 2675 fixed text describing the list. The second string provides the list data: 2676 this is a text string in which list entries are separated by newline 2677 characters. Additional optional arguments represent labels for 2678 buttons to appear along the bottom of the dialog. Returns the line of text 2679 selected by the user as the function value (without any newline separator) or 2680 the empty string if none was selected, and number of the button pressed (the 2681 first button is number 1), in $list_dialog_button. If the user closes the 2682 dialog via the window close box, the function returns the empty string, and 2683 $list_dialog_button returns 0. 2684 2685 **max( n1, n2, ... )** 2686 Returns the maximum value of all of its arguments 2687 2688 **min( n1, n2, ... )** 2689 Returns the minimum value of all of its arguments 2690 2691 **read_file( filename )** 2692 Reads the contents of a text file into a string. On success, returns 1 in 2693 $read_status, and the contents of the file as a string in the subroutine 2694 return value. On failure, returns the empty string "" and an 0 $read_status. 2695 2696 **replace_in_string( string, search_for, replace_with [, type, "copy"] )** 2697 Replaces all occurrences of a search string in a string with a replacement 2698 string. Arguments are 1: string to search in, 2: string to search for, 3: 2699 replacement string. There are two optional arguments. One is a search type, 2700 either "literal", "case", "word", "caseWord", "regex", or "regexNoCase". 2701 The default search type is "literal". If the optional "copy" argument is 2702 specified, a copy of the input string is returned when no replacements were 2703 performed. By default an empty string ("") will be returned in this case. 2704 Returns a new string with all of the replacements done. 2705 2706 **replace_range( start, end, string )** 2707 Replaces all the text between two positions in the current window. If the 2708 cursor position is between start and end it will be set to start. 2709 2710 **replace_selection( string )** 2711 Replaces the primary-selection selected text in the current window. 2712 2713 **replace_substring( string, start, end, replace_with )** 2714 Replacing a substring between two positions in a string within another string. 2715 2716 **revert_to_saved()** 2717 Reloads the file, discarding all changes done to the document by the user 2718 since the last save. 2719 2720 **search( search_for, start [, search_type, wrap, direction] )** 2721 Searches silently in a window without dialogs, beeps, or changes to the 2722 selection. Arguments are: 1: string to search for, 2: starting position. 2723 Optional arguments may include the strings: "wrap" to make the search wrap 2724 around the beginning or end of the string, "backward" or "forward" to change 2725 the search direction ("forward" is the default), "literal", "case", "word", 2726 "caseWord", "regex", or "regexNoCase" to change the search type (default is 2727 "literal"). Returns the starting position of the match, or -1 if nothing 2728 matched. Also returns the ending position of the match in $search_end. 2729 2730 **search_string( string, search_for, start [, search_type, direction] )** 2731 Built-in macro subroutine for searching a string. Arguments are 1: string to 2732 search in, 2: string to search for, 3: starting position. Optional arguments 2733 may include the strings: "wrap" to make the search wrap around the beginning 2734 or end of the string, "backward" or "forward" to change the search direction 2735 ("forward" is the default), "literal", "case", "word", "caseWord", "regex", 2736 or "regexNoCase" to change the search type (default is "literal"). Returns 2737 the starting position of the match, or -1 if nothing matched. Also returns 2738 the ending position of the match in $search_end. 2739 2740 **select( start, end )** 2741 Selects (with the primary selection) text in the current buffer between a 2742 starting and ending position. 2743 2744 **select_rectangle( start, end, left, right )** 2745 Selects a rectangular area of text between a starting and ending position, 2746 and confined horizontally to characters displayed between positions "left", 2747 and "right". 2748 2749 ..Disabled for 5.4 release. 2750 ..**set_backlight_string( [string] )** 2751 .. Applies the given string, which should be in the format of the 2752 .. nedit*backlightCharTypes X resource, to the current text window, turning on 2753 .. backlighting. If the value of the string passed is "default", or if no 2754 .. parameter is passed, the nedit.backlightCharTypes X resource's own value will 2755 .. be used. If the empty string, "", is passed, backlighting will be turned 2756 .. off. 2757 2758 **set_cursor_pos( position )** 2759 Set the cursor position for the current window. 2760 2761 **shell_command( command, input_string )** 2762 Executes a shell command, feeding it input from input_string. On completion, 2763 output from the command is returned as the function value, and the command's 2764 exit status is returned in the global variable $shell_cmd_status. 2765 2766 **split(string, separation_string [, search_type])** 2767 Splits a string using the separator specified. Optionally the search_type 2768 argument can specify how the separation_string is interpreted. The default 2769 is "literal". The returned value is an array with keys beginning at 0. 2770 2771 **string_dialog( message, btn_1_label, btn_2_label, ... )** 2772 Pops up a dialog prompting the user to enter information. The first argument 2773 is a string to show in the message area of the dialog. Additional 2774 optional arguments represent labels for buttons to appear along the bottom of 2775 the dialog. Returns the string entered by the user as the function value, 2776 and number of the button pressed (the first button is number 1), in 2777 $string_dialog_button. If the user closes the dialog via the window close 2778 box, the function returns the empty string, and $string_dialog_button returns 2779 0. 2780 2781 **string_compare(string1, string2 [, consider-case])** 2782 Compare two strings and return 0 if they are equal, -1 if string1 is less 2783 than string2 or 1 if string1 is greater than string2. The values for the 2784 optional consider-case argument is either "case" or "nocase". The default 2785 is to do a case sensitive comparison. 2786 2787 **string_to_clipboard( string )** 2788 Copy the contents of a macro string to the clipboard. 2789 2790 **substring( string, start [, end] )** 2791 Returns the portion of a string between a start and end position (with the 2792 position of the beginning of the string being 0). If end is missing, the 2793 position of the end of the string is used. If either of the positions are 2794 negative, they are treated as relative to the end of the string. A position 2795 specified either before the start of the string or after the end of the string 2796 is repositioned to the nearest valid string position. If the start position 2797 is beyond the end position, the empty string is returned. 2798 2799 **t_print( string1, string2, ... )** 2800 Writes strings to the terminal (stdout) from which XNEdit was started. 2801 2802 **tolower( string )** 2803 Return an all lower-case version of string. 2804 2805 **toupper( string )** 2806 Return an all upper-case version of string. 2807 2808 **valid_number( string )** 2809 Returns 1 if the string can be converted to a number without error 2810 following the same rules that the implicit conversion would. Otherwise 0. 2811 2812 **write_file( string, filename )** 2813 Writes a string (parameter 1) to a file named in parameter 2. Returns 1 on 2814 successful write, or 0 if unsuccessful. 2815 2816 2817 3>Deprecated Functions 2818 2819 Some functions are included only for supporting legacy macros. You should not 2820 use any of these functions in any new macro you write. Among these are all 2821 action routines with hyphens in their names; use underscores instead 2822 ('find-dialog' -> 'find_dialog'). 2823 2824 **match()** 2825 **DEPRECATED** Use select_to_matching() instead. 2826 2827 ---------------------------------------------------------------------- 2828 2829 Rangesets 2830 ---------- 2831 2832 Rangesets are a tool of the macro language to tag parts, or ranges, of the 2833 text, which shall be viewed as a group. A range is merely a contiguous range 2834 of characters between a start and an end position in the document, and a set 2835 of ranges belonging together is called a rangeset. So, a rangeset is nothing 2836 but an in general non-contiguous part of the text. 2837 2838 Rangesets can be assigned a background color to make them visible: characters 2839 within all ranges of a rangeset will have the background color of the 2840 rangeset. (If more than one rangeset includes a given character, its 2841 background color will be that of the most recently created rangeset which has 2842 a color defined.) 2843 2844 Applications of rangesets are for example: 2845 2846 * Showing differences between two versions of a file. Then, one rangeset would be those parts of the current file that are not in the prior version. 2847 * Highlighting all occurrences of a particular pattern, e.g. showing all the strings 'foobar' in the file. 2848 * Highlighting spelling mistakes found by a spell-checker. 2849 2850 Rangesets are manipulated only through macro routines. Rangesets must be 2851 created first using the rangeset_create() function, which will return an 2852 identifier for the newly-created (empty) rangeset. This identifier is then 2853 passed to the other rangeset functions to manipulate the rangeset. For 2854 example, ranges are added to a rangeset with the rangeset_add() function. 2855 2856 Notice that the ranges inside a rangeset do not have a particular identity. 2857 Only, they are given a (dynamically changing) numeric index, counting from 1, 2858 in the order of appearance in the text buffer. The ranges are adjusted when 2859 modifications are made to the text buffer: they shift around when characters 2860 are added or deleted staying with the original strings of characters. 2861 However, ranges within a set will coalesce if the characters between them are 2862 removed, or a new range is added to the set which bridges or overlaps 2863 others. For more on this, see "How rangesets change with modifications". 2864 2865 There is a limit to the number of rangesets which can exist at any time - 2866 currently up to 63 in each document. Care should be taken to destroy any 2867 rangesets which are no longer needed, by using the rangeset_destroy() 2868 function, if this limit is attained. 2869 2870 Rangesets can be named: this is useful for macros which need a fixed 2871 identification for rangesets which are used for the same purpose in different 2872 documents. Although a new rangeset's number is arbitrary, its name can be 2873 fixed. This is done using the rangeset_set_name() function. Note that 2874 rangeset names within a particular document may not be unique. For this 2875 reason, the rangeset_get_by_name() function returns an array of identifiers, 2876 which will be empty if the name has not been associated with a rangeset. 2877 2878 4>How rangesets change with modifications 2879 2880 When changes are made to the document text, ranges within each set are altered 2881 with it, according to their behavioral mode. If changes are made outside of 2882 the ranges in a rangeset, each range simply maintains its size and adjusts its 2883 position to match the changes. When text within a range is deleted, the 2884 range's length is reduced by the same amount. When changes involving new text 2885 are made within a range of the set, or to one of the extremities of a range, 2886 different behaviours may be desirable. The rangeset_set_mode() function allows 2887 these modes to be chosen. 2888 2889 Note that the precise behaviour of these modes may change in future versions 2890 of XNEdit. 2891 2892 The available modes are: 2893 2894 **maintain** or **ins_del** - 2895 Both these modes have the same behaviour. New text added at the front of a 2896 range in a set is not added to the range; new text added within the range or 2897 at the end extends the range. Replacement overlapping an extremity of the 2898 set acts as if the new text were added first, then the old text deleted. 2899 This causes curtailment at the front of the range, extension at the end. 2900 Replacement of the full text of the range removes the range from the set. 2901 The default behaviour for a newly created rangeset is **maintain**. 2902 2903 **del_ins** - 2904 New text added at the front or end of a range in a set is not added to the 2905 range; new text added within the range extends the range. Replacement 2906 overlapping an extremity of the set acts as if the old text were deleted 2907 first, then the new text added. This causes curtailment at either end. 2908 Replacement of the full text of the range removes the range from the set. 2909 2910 **include** - 2911 New text added at the front or end of a range in a set extends the range, as 2912 does new text added within the range. Replacement overlapping an extremity 2913 of the set acts as if the new text were added first, then the old text 2914 deleted. This causes curtailment at the front of the range, extension at 2915 the end. Replacement of the full text of the range adds the new text to the 2916 range if the start position of the replacement is at the range's start 2917 point. 2918 2919 **exclude** - 2920 New text added at the front or end of a range in a set does not extend the 2921 range; new text added within the range extends the range. Replacement 2922 overlapping an extremity causes curtailment of the range. Replacement of 2923 the full text of the range removes the range from the set. 2924 2925 **break** - 2926 New text added at the front or end of a range in a set does not extend the 2927 range; new text added within the range will split the range. Replacement 2928 overlapping an extremity causes curtailment of the range. Replacement of 2929 the full text of the range removes the range from the set. 2930 2931 4>Notes 2932 2933 A rangeset is manipulated ~only~ through macro routines. Rangesets 2934 can easily become very large, and may exceed the capacity of the running 2935 process. Coloring relies on proper color names or specifications (such as 2936 the "#rrggbb" hexadecimal digit strings), and appropriate hardware support. If 2937 an invalid color name is given, the default background color is used instead. 2938 Behaviours set using rangeset_set_mode() are subject to change in future 2939 versions. 2940 2941 3>Rangeset read-only variables 2942 2943 **$rangeset_list** 2944 array of active rangeset identifiers, with integer keys starting at 0, 2945 in the order the rangesets were defined. 2946 2947 3>Rangeset functions 2948 2949 **rangeset_create()** 2950 **rangeset_create( n )** 2951 Creates one or more new rangesets. The first form creates a single range 2952 set and returns its identifier; if there are no rangesets available it 2953 returns 0. The second form creates n new rangesets, and returns an array 2954 of the rangeset identifiers with keys beginning at 0. If the requested 2955 number of rangesets is not available it returns an empty array. 2956 2957 **rangeset_destroy( r )** 2958 **rangeset_destroy( array )** 2959 Deletes all information about a rangeset or a number of rangesets. The 2960 first form destroys the rangeset identified by r. The second form should 2961 be passed an array of rangeset identifiers with keys beginning at 0 (i.e. 2962 the same form of array returned by rangeset_create(n); it destroys all the 2963 rangesets appearing in the array. If any of the rangesets do not exist, 2964 the function continues without errors. Does not return a value. 2965 2966 **rangeset_add( r )** 2967 **rangeset_add( r, start, end )** 2968 **rangeset_add( r, r0 )** 2969 Adds to the rangeset r. The first form adds the range identified by the 2970 current primary selection to the rangeset, unless the selection is 2971 rectangular. The second form adds the range defined by the start and end 2972 positions given. The third form adds all ranges in the rangeset r0 to the 2973 rangeset r, and returns 0. 2974 2975 Returns the index of the newly-added range within the rangeset. 2976 2977 **rangeset_subtract( r, [start, end] )** 2978 **rangeset_subtract( r, r0 )** 2979 Removes from the rangeset r. The first form removes the range identified by 2980 the current primary selection from the rangeset, unless start and end are 2981 defined, in which case the range they define is removed. The second form 2982 removes all ranges in the rangeset r0 from the rangeset r. Does not return 2983 a value. 2984 2985 **rangeset_invert( r )** 2986 Changes the rangeset r so that it contains all ranges not in r. Does not 2987 return a value. 2988 2989 **rangeset_get_by_name( name )** 2990 Returns an array of active rangeset identifiers, with integer keys starting at 0, 2991 whose name matches name. 2992 2993 **rangeset_info( r )** 2994 Returns an array containing information about the rangeset r. The array 2995 has the following keys: **defined** (whether a rangeset with identifier 2996 r is defined), **count** (the number of ranges in the rangeset), **color** 2997 (the current background color of the rangeset, an empty string if the 2998 rangeset has no color), **name** (the user supplied name of the rangeset, 2999 an empty string if the rangeset has no name), and **mode** (the name of the 3000 modify-response mode of the rangeset). 3001 3002 **rangeset_range( r, [index] )** 3003 Returns details of a specific range in the rangeset r. The range is 3004 specified by index, which should be between 1 and n (inclusive), where 3005 n is the number of ranges in the rangeset. The return value is an array 3006 containing the keys **start** (the start position of the range) and **end** 3007 (the end position of the range). If index is not supplied, the region 3008 returned is the span of the entire rangeset (the region starting at the 3009 start of the first range and ending at the end of the last). If index 3010 is outside the correct range of values, the function returns an empty array. 3011 3012 **rangeset_includes( r, pos )** 3013 Returns the index of the range in rangeset r which includes pos; returns 3014 0 if pos is not contained in any of the ranges of r. This can also be used 3015 as a simple true/false function which returns true if pos is contained in 3016 the rangeset. 3017 3018 **rangeset_set_color( r, color )** 3019 Attempts to apply the color as a background color to the ranges of r. If 3020 color is at empty string, removes the coloring of r. No check is made 3021 regarding the validity of color: if the color is invalid (a bad name, 3022 or not supported by the hardware) this has unpredictable effects. 3023 3024 **rangeset_set_name( r, name )** 3025 Apply the name to the rangeset r. 3026 3027 **rangeset_set_mode( r, type )** 3028 Changes the behaviour of the rangeset r when modifications to the text 3029 buffer occur. type can be one of the following: "maintain" (the default), 3030 "break", "include", "exclude", "ins_del" or "del_ins". (These modes are 3031 described above.) 3032 3033 Highlighting Information 3034 ------------------------ 3035 3036 The user can interrogate the current window to determine the color 3037 highlighting used on a particular piece of text. The following functions 3038 provide information on the highlighting pattern against which text at a 3039 particular position has been matched, its style, color and font attributes 3040 (whether the font is supposed to be bold and/or italic). 3041 3042 These macro functions permit macro writers to generate formatted output which 3043 allows XNEdit highlighting to be reproduced. This is suitable for the 3044 generation of HTML or Postscript output, for example. 3045 3046 Note that if any of the functions is used while in Plain mode or while syntax 3047 highlighting is off, the behaviour is undefined. 3048 3049 **get_pattern_by_name( pattern_name )** 3050 Returns an array containing the pattern attributes for pattern 'pattern_name'. 3051 The elements in this array are: 3052 3053 * **style** -- Highlight style name 3054 3055 If 'pattern_name' is invalid, an empty array is returned. 3056 3057 **get_pattern_at_pos( pos )** 3058 Returns an array containing the pattern attributes of the character at 3059 position 'pos'. The elements in this array are: 3060 3061 * **pattern** -- Highlight pattern name 3062 * **style** -- Highlight style name 3063 * **extent** -- The length in the text which uses the same highlighting pattern 3064 3065 The 'extent' value is measured from position 'pos' going right/down (forward 3066 in the file) only. 3067 3068 If 'pos' is invalid, an empty array is returned. 3069 3070 **get_style_by_name( style_name )** 3071 Returns an array containing the style attributes for style 'style_name'. 3072 The elements in this array are: 3073 3074 * **bold** -- '1' if style is bold, '0' otherwise 3075 * **italic** -- '1' if style is italic, '0' otherwise 3076 * **color** -- Name of the style's color 3077 * **background** -- Name of the background color, if any 3078 3079 The colors use the names specified in the color definitions for the style. 3080 These will either be names matching those the X server recognises, or RGB 3081 (red/green/blue) specifications. 3082 3083 If 'style_name' is invalid, an empty array is returned. 3084 3085 **get_style_at_pos( pos )** 3086 Returns an array containing the style attributes of the character at 3087 position 'pos'. The elements in this array are: 3088 3089 * **style** -- Name of the highlight style 3090 * **bold** -- '1' if style is bold, '0' otherwise 3091 * **italic** -- '1' if style is italic, '0' otherwise 3092 * **color** -- Name of the style's color 3093 * **rgb** -- Color's RGB values ('#rrggbb') 3094 * **background** -- Name of the background color, if any 3095 * **back_rgb** -- Background color's RGB values ('#rrggbb') 3096 * **extent** -- The length in the text which uses the same highlight style 3097 3098 The colors use the names specified in the color definitions for the style. 3099 These will either be names matching those the X server recognises, or RGB 3100 specifications. The values for 'rgb' and 'back_rgb' contain the actual color 3101 values allocated by the X server for the window. If the X server cannot 3102 allocate the specified (named) color exactly, the RGB values in these 3103 entries may not match the specified ones. 3104 3105 The 'extent' value is measured from position 'pos' going right/down (forward 3106 in the file) only. 3107 3108 If 'pos' is invalid, an empty array is returned. 3109 3110 ---------------------------------------------------------------------- 3111 3112 Action Routines 3113 --------------- 3114 3115 All of the editing capabilities of XNEdit are represented as a special type of 3116 subroutine, called an action routine, which can be invoked from both macros 3117 and translation table entries (see "Key_Binding_" in the 3118 Customizing section of the Help menu). 3119 3120 3121 3>Actions Representing Menu Commands 3122 3123 File Menu Search Menu 3124 ----------------------- ------------------------- 3125 new() find() 3126 open() find_dialog() 3127 open_dialog() find_again() 3128 open_selected() find_selection() 3129 close() replace() 3130 save() replace_dialog() 3131 save_as() replace_all() 3132 save_as_dialog() replace_in_selection() 3133 revert_to_saved_dialog() replace_again() 3134 include_file() goto_line_number() 3135 include_file_dialog() goto_line_number_dialog() 3136 load_macro_file() goto_selected() 3137 load_macro_file_dialog() mark() 3138 load_tags_file() mark_dialog() 3139 load_tags_file_dialog() goto_mark() 3140 unload_tags_file() goto_mark_dialog() 3141 load_tips_file() goto_matching() 3142 load_tips_file_dialog() select_to_matching() 3143 unload_tips_file() find_definition() 3144 print() show_tip() 3145 print_selection() 3146 exit() Shell Menu 3147 ------------------------- 3148 Edit Menu filter_selection_dialog() 3149 ----------------------- filter_selection() 3150 undo() execute_command() 3151 redo() execute_command_dialog() 3152 delete() execute_command_line() 3153 select_all() shell_menu_command() 3154 shift_left() 3155 shift_left_by_tab() Macro Menu 3156 shift_right() ------------------------- 3157 shift_right_by_tab() macro_menu_command() 3158 uppercase() repeat_macro() 3159 lowercase() repeat_dialog() 3160 fill_paragraph() 3161 control_code_dialog() Windows Menu 3162 ------------------------- 3163 split_pane() 3164 close_pane() 3165 detach_document() 3166 move_document_dialog() 3167 3168 3169 An action representing a menu command is usually named the same as its 3170 corresponding menu item except that all punctuation is removed, all letters 3171 are changed to lower case, and spaces are replaced with underscores. To 3172 present a dialog to ask the user for input, use the actions with the 3173 `_dialog` suffix. Actions without the `_dialog` suffix take the information 3174 from the routine's arguments (see below). 3175 3176 3>Menu Action Routine Arguments 3177 3178 Arguments are text strings enclosed in quotes. Below are the menu action 3179 routines which take arguments. Optional arguments are enclosed in []. 3180 3181 **new**( ["tab" | "window" | "prefs" | "opposite"] ) 3182 3183 **close**( ["prompt" | "save" | "nosave"] ) 3184 3185 **execute_command**( shell-command ) 3186 3187 **filter_selection**( shell-command ) 3188 3189 **find**( search-string [, ~search-direction~] [, ~search-type~] 3190 [, ~search-wrap~] ) 3191 3192 **find_again**( [~search-direction~] [, ~search-wrap~] ) 3193 3194 **find_definition**( [tag-name] ) 3195 3196 **find_dialog**( [~search-direction~] [, ~search-type~] 3197 [, ~keep-dialog~] ) 3198 3199 **find_selection**( [~search-direction~] [, ~search-wrap~] 3200 [, ~non-regex-search-type~] ) 3201 3202 **goto_line_number**( [~line-number~] [, ~column-number~] ) 3203 3204 **goto_mark**( ~mark-letter~ ) 3205 3206 **include_file**( ~filename~ ) 3207 3208 **load_tags_file**( ~filename~ ) 3209 3210 **macro_menu_command**( ~macro-menu-item-name~ ) 3211 3212 **mark**( ~mark-letter~ ) 3213 3214 **open**( ~filename~ ) 3215 3216 **replace**( search-string, replace-string, 3217 [, ~search-direction~] [, ~search-type~] [, ~search-wrap~] ) 3218 3219 **replace_again**( [~search-direction~] [, ~search-wrap~] ) 3220 3221 **replace_all**( search-string, replace-string [, ~search-type~] ) 3222 3223 **replace_dialog**( [~search-direction~] [, ~search-type~] 3224 [, ~keep-dialog~] ) 3225 3226 **replace_in_selection**( search-string, 3227 replace-string [, ~search-type~] ) 3228 3229 **save_as**( ~filename~ ) 3230 3231 **shell_menu_command**( ~shell-menu-item-name~ ) 3232 3233 **unload_tags_file**( ~filename~ ) 3234 3235 **----------- Some notes on argument types above -----------** 3236 3237 ~Arguments to new()~ 3238 "tab": Open a new tab 3239 "window": Open a new window 3240 "prefs": Follow the user's tab/window 3241 preference 3242 "opposite": Opposite of user's tab/window 3243 preference 3244 Default behaviour is "prefs". 3245 3246 ~filename~ Path names are relative to the directory from 3247 which XNEdit was started. Shell interpreted 3248 wildcards and `~' are not expanded. 3249 3250 ~keep-dialog~ Either "keep" or "nokeep". 3251 3252 ~mark-letter~ The mark command limits users to single letters. Inside 3253 of macros, single digits are allowed as marks. These 3254 won't interfere with marks set by the user. 3255 3256 ~macro-menu-item-name~ 3257 Name of the command exactly as specified in 3258 the Macro Menu dialogs. 3259 3260 ~non-regex-search-type~ 3261 Either "literal", "case", "word", or 3262 "caseWord". 3263 3264 ~search-direction~ 3265 Either "forward" or "backward". 3266 3267 ~search-type~ Either "literal", "case", "word", 3268 "caseWord", "regex", or "regexNoCase". 3269 3270 ~search-wrap~ Either "wrap" or "nowrap". 3271 3272 ~shell-menu-item-name~ 3273 Name of the command exactly as specified in 3274 the Shell Menu dialogs. 3275 3276 3>Window Preferences Actions 3277 3278 **set_auto_indent( "off" | "on" | "smart" )** 3279 Set auto indent mode for the current window. 3280 3281 **set_em_tab_dist( em-tab-distance )** 3282 Set the emulated tab size. An em-tab-distance value of 3283 0 or less translates to no emulated tabs. Em-tab-distance must 3284 be smaller than 1000. 3285 3286 **set_fonts( font-name, italic-font-name, bold-font-name, bold-italic-font-name )** 3287 Set all the fonts used for the current window. 3288 3289 **set_highlight_syntax( [0 | 1] )** 3290 Set syntax highlighting mode for the current window. 3291 A value of 0 turns it off and a value of 1 turns it on. 3292 If no parameters are supplied the option is toggled. 3293 3294 **set_incremental_backup( [0 | 1] )** 3295 Set incremental backup mode for the current window. 3296 A value of 0 turns it off and a value of 1 turns it on. 3297 If no parameters are supplied the option is toggled. 3298 3299 **set_incremental_search_line( [0 | 1] )** 3300 Show or hide the incremental search line for the current window. 3301 A value of 0 turns it off and a value of 1 turns it on. 3302 If no parameters are supplied the option is toggled. 3303 3304 **set_language_mode( language-mode )** 3305 Set the language mode for the current window. If the language mode is 3306 "" or unrecognized, it will be set to Plain. 3307 3308 **set_locked( [0 | 1] )** 3309 This only affects the locked status of a file, not its read-only 3310 status. Permissions are ~not~ changed. 3311 A value of 0 turns it off and a value of 1 turns it on. 3312 If no parameters are supplied the option is toggled. 3313 3314 **set_make_backup_copy( [0 | 1] )** 3315 Set whether backup copies are made during saves for the current window. 3316 A value of 0 turns it off and a value of 1 turns it on. 3317 If no parameters are supplied the option is toggled. 3318 3319 **set_overtype_mode( [0 | 1] )** 3320 Set overtype mode for the current window. 3321 A value of 0 turns it off and a value of 1 turns it on. 3322 If no parameters are supplied the option is toggled. 3323 3324 **set_show_line_numbers( [0 | 1] )** 3325 Show or hide line numbers for the current window. 3326 A value of 0 turns it off and a value of 1 turns it on. 3327 If no parameters are supplied the option is toggled. 3328 3329 **set_show_matching( "off" | "delimiter" | "range" )** 3330 Set show matching (...) mode for the current window. 3331 3332 **set_match_syntax_based( [0 | 1] )** 3333 Set whether matching should be syntax based for the current window. 3334 3335 **set_statistics_line( [0 | 1] )** 3336 Show or hide the statistics line for the current window. 3337 A value of 0 turns it off and a value of 1 turns it on. 3338 If no parameters are supplied the option is toggled. 3339 3340 **set_tab_dist( tab-distance )** 3341 Set the size of hardware tab spacing. Tab-distance must 3342 be a value greater than 0 and no greater than 20. 3343 3344 **set_use_tabs( [0 | 1] )** 3345 Set whether tab characters are used for the current window. A value of 0 3346 turns it off (using space characters instead) and a value of 1 turns it on. 3347 If no parameters are supplied the option is toggled. 3348 3349 **set_wrap_margin( wrap-width )** 3350 Set the wrap width for text wrapping of the current window. A value 3351 of 0 means to wrap at window width. 3352 3353 **set_wrap_text( "none" | "auto" | "continuous" )** 3354 Set wrap text mode for the current window. 3355 3356 3>Keyboard-Only Actions 3357 3358 In addition to the arguments listed in the call descriptions below, any 3359 routine involving cursor movement can take the argument "extend", meaning, 3360 adjust the primary selection to the new cursor position. Routines which take 3361 the "extend" argument as well as mouse dragging operations for both primary 3362 and secondary selections can take the optional keyword "rect", meaning, make 3363 the selection rectangular. Any routine that accepts the "scrollbar" argument 3364 will move the display but not the cursor or selection. Routines that accept 3365 the "nobell" argument will fail silently without beeping, when that argument 3366 is supplied. 3367 3368 **backward_character( ["nobell"] )** 3369 Moves the cursor one character to the left. 3370 3371 **backward_paragraph(["nobell"] )** 3372 Moves the cursor to the beginning of the paragraph, or 3373 if the cursor is already at the beginning of a paragraph, moves the cursor to 3374 the beginning of the previous paragraph. Paragraphs are defined as regions 3375 of text delimited by one or more blank lines. 3376 3377 **backward_word( ["nobell"] )** 3378 Moves the cursor to the beginning of a word, or, if the 3379 cursor is already at the beginning of a word, moves the cursor to the 3380 beginning of the previous word. Word delimiters are user-settable, and 3381 defined by the X resource wordDelimiters. 3382 3383 **beginning_of_file( ["scrollbar"] )** 3384 Moves the cursor to the beginning of the file. 3385 3386 **beginning_of_line( ["absolute"] )** 3387 Moves the cursor to the beginning of the line. If 3388 "absolute" is given, always moves to the absolute beginning of line, 3389 regardless of the text wrapping mode. 3390 3391 **beginning_of_selection()** 3392 Moves the cursor to the beginning of the selection 3393 without disturbing the selection. 3394 3395 **copy_clipboard()** 3396 Copies the current selection to the clipboard. 3397 3398 **copy_primary()** 3399 Copies the primary selection to the cursor. 3400 3401 **copy_to()** 3402 If a secondary selection exists, copies the secondary selection to 3403 the cursor. If no secondary selection exists, copies the primary selection 3404 to the pointer location. 3405 3406 **copy_to_or_end_drag()** 3407 Completes either a secondary selection operation, or a 3408 primary drag. If the user is dragging the mouse to adjust a secondary 3409 selection, the selection is copied and either inserted at the cursor 3410 location, or, if pending-delete is on and a primary selection exists in the 3411 window, replaces the primary selection. If the user is dragging a block of 3412 text (primary selection), completes the drag operation and leaves the text at 3413 its current location. 3414 3415 **cut_clipboard()** 3416 Deletes the text in the primary selection and places it in 3417 the clipboard. 3418 3419 **cut_primary()** 3420 Copies the primary selection to the cursor and deletes it at 3421 its original location. 3422 3423 **delete_selection()** 3424 Deletes the contents of the primary selection. 3425 3426 **delete_next_character( ["nobell"] )** 3427 If a primary selection exists, deletes its contents. 3428 Otherwise, deletes the character following the cursor. 3429 3430 **delete_previous_character( ["nobell"] )** 3431 If a primary selection exists, deletes its 3432 contents. Otherwise, deletes the character before the cursor. 3433 3434 **delete_next_word( ["nobell"] )** 3435 If a primary selection exists, deletes its contents. 3436 Otherwise, deletes the word following the cursor. 3437 3438 **delete_previous_word( ["nobell"] )** 3439 If a primary selection exists, deletes its contents. 3440 Otherwise, deletes the word before the cursor. 3441 3442 **delete_to_start_of_line( ["nobell", "wrap"] )** 3443 If a primary selection exists, deletes its contents. Otherwise, deletes the 3444 characters between the cursor and the start of the line. If "wrap" is 3445 given, deletes to the previous wrap point or beginning of line, whichever 3446 is closest. 3447 3448 **delete_to_end_of_line( ["nobell", "absolute"] )** 3449 If a primary selection exists, deletes its contents. 3450 Otherwise, deletes the characters between the cursor and the end of the line. 3451 If "absolute" is given, always deletes to the absolute end of line, regardless 3452 of the text wrapping mode. 3453 3454 **deselect_all()** 3455 De-selects the primary selection. 3456 3457 **end_of_file( ["scrollbar"] )** 3458 Moves the cursor to the end of the file. 3459 3460 **end_of_line( ["absolute"] )** 3461 Moves the cursor to the end of the line. If 3462 "absolute" is given, always moves to the absolute end of line, regardless 3463 of the text wrapping mode. 3464 3465 **end_of_selection()** 3466 Moves the cursor to the end of the selection without 3467 disturbing the selection. 3468 3469 **exchange( ["nobell"] )** 3470 Exchange the primary and secondary selections. 3471 3472 **extend_adjust()** 3473 Attached mouse-movement events to begin a selection between 3474 the cursor and the mouse, or extend the primary selection to the mouse 3475 position. 3476 3477 **extend_end()** 3478 Completes a primary drag-selection operation. 3479 3480 **extend_start()** 3481 Begins a selection between the cursor and the mouse. A 3482 drag-selection operation can be started with either extend_start or 3483 grab_focus. 3484 3485 **focus_pane( [relative-pane] | [positive-index] | [negative-index] )** 3486 Move the focus to the requested pane. 3487 Arguments can be specified in the form of a relative-pane 3488 ("first", "last", "next", "previous"), a positive-index 3489 (numbers greater than 0, 1 is the same as "first") or a 3490 negative-index (numbers less than 0, -1 is the same as "last"). 3491 3492 **forward_character()** 3493 Moves the cursor one character to the right. 3494 3495 **forward_paragraph( ["nobell"] )** 3496 Moves the cursor to the beginning of the next paragraph. 3497 Paragraphs are defined as regions of text delimited by one or more blank 3498 lines. 3499 3500 **forward_word( ["tail"] ["nobell"] )** 3501 Moves the cursor to the beginning of the next word. Word 3502 delimiters are user-settable, and defined by the X resource wordDelimiters. 3503 If the "tail" argument is supplied the cursor will be moved to 3504 the end of the current word or the end of the next word, if the 3505 cursor is between words. 3506 3507 **grab_focus()** 3508 Moves the cursor to the mouse pointer location, and prepares for 3509 a possible drag-selection operation (bound to extend_adjust), or multi-click 3510 operation (a further grab_focus action). If a second invocation of grab 3511 focus follows immediately, it selects a whole word, or a third, a whole line. 3512 3513 **insert_string( "string" )** 3514 If pending delete is on and the cursor is inside the 3515 selection, replaces the selection with "string". Otherwise, inserts "string" 3516 at the cursor location. 3517 3518 **key_select( "direction" [,"nobell"] )** 3519 Moves the cursor one character in "direction" 3520 ("left", "right", "up", or "down") and extends the selection. Same as 3521 forward/backward-character("extend"), or process-up/down("extend"), for 3522 compatibility with previous versions. 3523 3524 **move-destination()** 3525 Moves the cursor to the pointer location without 3526 disturbing the selection. (This is an unusual way of working. We left it in 3527 for compatibility with previous versions, but if you actually use this 3528 capability, please send us some mail, otherwise it is likely to disappear in 3529 the future. 3530 3531 **move_to()** 3532 If a secondary selection exists, deletes the contents of the 3533 secondary selection and inserts it at the cursor, or if pending-delete is on 3534 and there is a primary selection, replaces the primary selection. If no 3535 secondary selection exists, moves the primary selection to the pointer 3536 location, deleting it from its original position. 3537 3538 **move_to_or_end_drag()** 3539 Completes either a secondary selection operation, or a 3540 primary drag. If the user is dragging the mouse to adjust a secondary 3541 selection, the selection is deleted and either inserted at the cursor 3542 location, or, if pending-delete is on and a primary selection exists in the 3543 window, replaces the primary selection. If the user is dragging a block of 3544 text (primary selection), completes the drag operation and deletes the text 3545 from its current location. 3546 3547 **newline()** 3548 Inserts a newline character. If Auto Indent is on, lines up the 3549 indentation of the cursor with the current line. 3550 3551 **newline_and_indent()** 3552 Inserts a newline character and lines up the indentation 3553 of the cursor with the current line, regardless of the setting of Auto 3554 Indent. 3555 3556 **newline_no_indent()** 3557 Inserts a newline character, without automatic 3558 indentation, regardless of the setting of Auto Indent. 3559 3560 **next_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )** 3561 Moves the cursor and scroll forward one page. 3562 The parameter "stutter" moves the cursor to the bottom of the display, 3563 unless it is already there, otherwise it will page down. 3564 The parameter "column" will maintain the preferred column while 3565 moving the cursor. 3566 3567 **page_left( ["scrollbar"] ["nobell"] )** 3568 Move the cursor and scroll left one page. 3569 3570 **page_right( ["scrollbar"] ["nobell"] )** 3571 Move the cursor and scroll right one page. 3572 3573 **paste_clipboard()** 3574 Insert the contents of the clipboard at the cursor, or if 3575 pending delete is on, replace the primary selection with the contents of the 3576 clipboard. 3577 3578 **previous_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )** 3579 Moves the cursor and scroll backward one page. 3580 The parameter "stutter" moves the cursor to the top of the display, 3581 unless it is already there, otherwise it will page up. 3582 The parameter "column" will maintain the preferred column while 3583 moving the cursor. 3584 3585 **process_bdrag()** 3586 Same as secondary_or_drag_start for compatibility with previous versions. 3587 3588 **process_cancel()** 3589 Cancels the current extend_adjust, secondary_adjust, or 3590 secondary_or_drag_adjust in progress. 3591 3592 **process_down( ["nobell", "absolute"] )** 3593 Moves the cursor down one line. If "absolute" is given, always moves to the 3594 next line in the text buffer, regardless of wrapping. 3595 3596 **process_return()** 3597 Same as newline for compatibility with previous versions. 3598 3599 **process_shift_down( ["nobell", "absolute"] )** 3600 Same as process_down("extend") for compatibility with previous versions. 3601 3602 **process_shift_up( ["nobell", "absolute"] )** 3603 Same as process_up("extend") for compatibility with previous versions. 3604 3605 **process_tab()** 3606 If tab emulation is turned on, inserts an emulated tab, 3607 otherwise inserts a tab character. 3608 3609 **process_up( ["nobell", "absolute"] )** 3610 Moves the cursor up one line. If "absolute" is given, always moves to the 3611 previous line in the text buffer, regardless of wrapping. 3612 3613 **raise_window([relative-window] | [positive-index] | [negative-index] [, "focus" | "nofocus"])** 3614 Raise the current focused window to the front if no argument is supplied. 3615 Arguments can be specified in the form of a relative-window 3616 ("first", "last", "next", "previous"), a positive-index 3617 (numbers greater than 0, 1 is the same as "last") or a 3618 negative-index (numbers less than 0, -1 is the same as "first"). 3619 3620 Moreover, it can be specified whether or not the raised window should 3621 request the X input focus. By default, it depends on the setting of the 3622 nedit.focusOnRaise resource (see the section "X_Resources_") whether or not 3623 the input focus is requested. 3624 3625 **scroll_down( nUnits, ["lines" | "pages"] )** 3626 Scroll the display down (towards the end of the file) by a given 3627 number of units, units being lines or pages. Default units are lines. 3628 3629 **scroll_left( nPixels )** 3630 Scroll the display left by nPixels. 3631 3632 **scroll_right( nPixels )** 3633 Scroll the display right by nPixels. 3634 3635 **scroll_up( nUnits, ["lines" | "pages"] )** 3636 Scroll the display up (towards the beginning of the file) by a given 3637 number of units, units being lines or pages. Default units are lines. 3638 3639 **scroll_to_line( lineNum )** 3640 Scroll to position line number lineNum at the top of 3641 the pane. The first line of a file is line 1. 3642 3643 **secondary_adjust()** 3644 Attached mouse-movement events to extend the secondary 3645 selection to the mouse position. 3646 3647 **secondary_or_drag_adjust()** 3648 Attached mouse-movement events to extend the 3649 secondary selection, or reposition the primary text being dragged. Takes two 3650 optional arguments, "copy", and "overlay". "copy" leaves a copy of the 3651 dragged text at the site at which the drag began. "overlay" does the drag in 3652 overlay mode, meaning the dragged text is laid on top of the existing text, 3653 obscuring and ultimately deleting it when the drag is complete. 3654 3655 **secondary_or_drag_start()** 3656 To be attached to a mouse down event. Begins drag 3657 selecting a secondary selection, or dragging the contents of the primary 3658 selection, depending on whether the mouse is pressed inside of an existing 3659 primary selection. 3660 3661 **secondary_start()** 3662 To be attached to a mouse down event. Begin drag selecting 3663 a secondary selection. 3664 3665 **select_all()** 3666 Select the entire file. 3667 3668 **self_insert()** 3669 To be attached to a key-press event, inserts the character 3670 equivalent of the key pressed. 3671 3672 ---------------------------------------------------------------------- 3673 3674 Customizing 3675 =========== 3676 3677 Customizing XNEdit 3678 ----------------- 3679 3680 XNEdit can be customized in many different ways. The most important 3681 user-settable options are presented in the Preferences menu, including all 3682 options that users might need to change during an editing session. Options 3683 set in the Default Settings sub-menu of the Preferences menu can be preserved 3684 between sessions by selecting Save Defaults, which writes the changes to the 3685 preferences file. See the section titled "Preferences_" for more details. 3686 3687 User defined commands can be added to XNEdit's Shell, Macro, and window 3688 background menus. Dialogs for creating items in these menus can be found 3689 under Customize Menus in the Default Settings sub menu of the Preferences 3690 menu. 3691 3692 For users who depend on XNEdit every day and want to tune every excruciating 3693 detail, there are also X resources for tuning a vast number of such details, 3694 down to the color of each individual button. See the section "X_Resources_" 3695 for more information, as well as a list of selected resources. 3696 3697 The most common reason for customizing your X resources for XNEdit, however, is 3698 key binding. While limited key binding can be done through Preferences 3699 settings (Preferences -> Default Settings -> Customize Menus), you can really 3700 only add keys this way, and each key must have a corresponding menu item. 3701 Any significant changes to key binding should be made via the Translations 3702 resource and menu accelerator resources. The sections titled "Key_Binding_" 3703 and "X_Resources_" have more information. 3704 ---------------------------------------------------------------------- 3705 3706 Preferences 3707 ----------- 3708 3709 The Preferences menu allows you to set options for both the current editing 3710 window, and default values for newly created windows and future XNEdit 3711 sessions. Options in the Preferences menu itself (not in the Default 3712 Settings sub-menu) take effect immediately and refer to the current window 3713 only. Options in the Default Settings sub-menu provide initial settings for 3714 future windows created using the New or Open commands; options affecting all 3715 windows are also set here. 3716 3717 Preferences set in the Default Settings sub-menu are saved in a file that 3718 XNEdit reads at startup time, cf. Autoload_Files_, by selecting Save Defaults. 3719 3720 3>Preferences Menu 3721 3722 **Default Settings** 3723 Menu of initial settings for future windows. Generally the same as the 3724 options in the main part of the menu, but apply as defaults for future 3725 windows created during this XNEdit session. These settings can be saved using 3726 the Save Defaults command below, to be loaded automatically each time XNEdit 3727 is started. 3728 3729 **Save Defaults** 3730 Save the default options as set under Default Settings for future XNEdit 3731 sessions. 3732 3733 **Statistics Line** 3734 Show the full file name, line number, and length of the file being edited. 3735 3736 **Incremental Search Line** 3737 Keep the incremental search bar (Search -> Find Incremental) permanently 3738 displayed at the top of the window. 3739 3740 **Show Line Numbers** 3741 Display line numbers to the right of the text. 3742 3743 **Language Mode** 3744 Tells XNEdit what language (if any) to assume, for selecting language-specific 3745 features such as highlight patterns and smart indent macros, and setting 3746 language specific preferences like word delimiters, tab emulation, and 3747 auto-indent. See Programming_with_XNEdit_ for more information. 3748 3749 **Auto Indent** 3750 Setting Auto Indent "on" maintains a running indent (pressing the Return key 3751 will line up the cursor with the indent level of the previous line). If 3752 smart indent macros are available for the current language mode, smart indent 3753 can be selected and XNEdit will attempt to guess proper language indentation 3754 for each new line, cf. Auto/Smart_Indent_. 3755 3756 **Wrap** 3757 Choose between two styles of automatic wrapping or none. Auto Newline wrap, 3758 wraps text at word boundaries when the cursor reaches the right margin, by 3759 replacing the space or tab at the last word boundary with a newline 3760 character. Continuous Wrap wraps long lines which extend past the right 3761 margin. Continuous Wrap mode is typically used to produce files where 3762 newlines are omitted within paragraphs, to make text filling automatic (a 3763 kind of poor-man's word processor). Text of this style is common on Macs and 3764 PCs but is not necessarily supported very well under Unix (except in programs 3765 which deal with e-mail, for which it is often the format of choice). 3766 3767 **Wrap Margin** 3768 Set margin for Auto Newline Wrap, Continuous Wrap, and Fill Paragraph. Lines 3769 may, be wrapped at the right margin of the window, or the margin can be set 3770 at a specific column. 3771 3772 **Tab Stops** 3773 Set the tab distance (number of characters between tab stops) for tab 3774 characters, and control tab emulation and use of tab characters in padding 3775 and emulated tabs. 3776 3777 **Text Font...** 3778 Change the font(s) used to display text (fonts for menus and dialogs must be 3779 set using X resources for the text area of the window). See below for more 3780 information. 3781 3782 **Highlight Syntax** 3783 If XNEdit recognizes the language being edited, and highlighting patterns are 3784 available for that language, use fonts and colors to enhance viewing of the 3785 file. (See Syntax_Highlighting_ for more information.) 3786 3787 **Make Backup Copy** 3788 On Save, write a backup copy of the file as it existed before the Save 3789 command with the extension .bck (Unix only). 3790 3791 **Incremental Backup** 3792 Periodically make a backup copy of the file being edited under the name 3793 `~filename` on Unix or `_filename` on VMS (see Crash_Recovery_). 3794 3795 **Show Matching (..)** 3796 Momentarily highlight matching parenthesis, brackets, and braces, or the 3797 range between them, when one of these characters is typed, or when the 3798 insertion cursor is positioned after it. Delimiter only highlights the 3799 matching delimiter, while Range highlights the whole range of text between 3800 the matching delimiters. 3801 3802 Optionally, the matching can make use of syntax information if syntax 3803 highlighting is enabled. Alternatively, the matching is purely character 3804 based. In general, syntax based matching results in fewer false matches. 3805 3806 **Overtype** 3807 In overtype mode, new characters entered replace the characters in front of 3808 the insertion cursor, rather than being inserted before them. 3809 3810 **Read Only** 3811 Lock the file against accidental modification. This temporarily prevents the 3812 file from being modified in this XNEdit session. Note that this is different 3813 from setting the file protection. 3814 3815 3>Preferences -> Default Settings Menu 3816 3817 Options in the Preferences -> Default Settings menu have the same meaning as 3818 those in the top-level Preferences menu, except that they apply to future 3819 XNEdit windows and future XNEdit sessions if saved with the Save Defaults 3820 command. Additional options which appear in this menu are: 3821 3822 **Language Modes** 3823 Define language recognition information (for determining language mode from 3824 file name or content) and set language specific preferences. 3825 3826 **Tag Collisions** 3827 How to react to multiple tags for the same name. Tags are described in the 3828 section: Finding_Declarations_(ctags)_. In Show All mode, all matching tags 3829 are displayed in a dialog. In Smart mode, if one of the matching tags is in 3830 the current window, that tag is chosen, without displaying the dialog. 3831 3832 **Command Shell...** 3833 Set the shell used to run programs from the shell_command() macro function 3834 and from the Shell menu. This defaults to the user's login shell. 3835 3836 **Colors...** 3837 Change the colors used to display text. The "Matching (..)" fields change the 3838 colors that matching parens, brackets and braces are flashed when the "Show 3839 Matching (..)" option is enabled. Note that the foreground colors for plain 3840 text, selected text, and matching paren flashing only apply when syntax 3841 highlighting is disabled. When syntax highlighting is enabled, text (even 3842 text that appears plain) will always be colored according to its highlighting 3843 style. (For information on changing syntax highlighting styles and matching 3844 patterns use see Syntax_Highlighting_.) 3845 3846 **Customize Menus** 3847 Add/remove items from the Shell, Macro, and window background menus (see 3848 below). 3849 3850 **Customize Window Title** 3851 Opens a dialog where the information to be displayed in the window's title 3852 field can be defined and tested. The dialog contains a Help button, providing 3853 further information about the options available. 3854 3855 **Searching** 3856 Options for controlling the behavior of Find and Replace commands: 3857 3858 ~Verbose~ - 3859 Presents search results in dialog form, asks before wrapping a 3860 search back around the beginning (or end) of the file 3861 (unless Beep On Search Wrap is turned on). 3862 3863 ~Wrap Around~ - 3864 Search and Replace operations wrap around the beginning (or end) of the file. 3865 3866 ~Beep On Search Wrap~ - 3867 Beep when Search and Replace operations wrap around the beginning (or end) of 3868 the file (only if Wrap Around is turned on). 3869 3870 ~Keep Dialogs Up~ - 3871 Don't pop down Replace and Find boxes after searching. 3872 3873 ~Default Search Style~ - 3874 Initial setting for search type in Find and Replace dialogs. 3875 3876 ~Default Replace Scope~ - 3877 [THIS OPTION IS ONLY PRESENT WHEN NEDIT WAS COMPILED WITH THE 3878 -DREPLACE_SCOPE FLAG TO SELECT AN ALTERNATIVE REPLACE DIALOG LAYOUT.] 3879 3880 Initial setting for the scope in the Replace/Find dialog, when a selection 3881 exists. It can be either "In Window", "In Selection", or "Smart". "Smart" 3882 results in "In Window" if the size of the selection is smaller than 1 line, 3883 and to "In Selection" otherwise. 3884 3885 **Syntax Highlighting** 3886 Program and configure enhanced text display for new or supported languages. 3887 (See Syntax_Highlighting_.) 3888 3889 **Tabbed Editing** 3890 Options for controlling the tabbed interface: 3891 3892 ~Open File in New Tab~ - 3893 Open files in new tabs, else open files in new windows. 3894 3895 ~Show Tab Bar~ - 3896 Show/Hide the tab bar. 3897 3898 ~Hide Tab Bar when only one Document is open~ 3899 3900 ~Next/Prev Tabs Across Windows~ - 3901 Suppose there are two windows with three tabs in the first window and two tabs in 3902 the second window. Enabling this option, if you are on the third tab in the 3903 first window, hitting Ctrl+PageDown would switch to the first tab in the second 3904 window (instead of switching to the first tab in the first window). 3905 3906 ~Sort Tabs Alphabetically~ 3907 3908 **Show Tooltips** 3909 Show file name and path in a tooltip when moving the mouse pointer over a tab. 3910 (See Tabbed_Editing_.) 3911 3912 **Terminate with Line Break on Save** 3913 Some UNIX tools expect that files end with a line feed. If this option is 3914 activated, XNEdit will append one if required. 3915 3916 **Sort Open Prev. Menu** 3917 Option to order the File -> Open Previous menu alphabetically, versus in 3918 order of last access. 3919 3920 **Popups Under Pointer** 3921 Display pop-up dialogs centered on the current mouse position, as opposed to 3922 centered on the parent window. This generally speeds interaction, and is 3923 essential for users who set their window managers so keyboard focus 3924 follows the mouse. 3925 3926 **Auto-Scroll Near Window Top/Bottom** 3927 When this option is enabled the window will automatically scroll when the 3928 cursor comes 4 lines from the top or bottom of the window (except at the 3929 beginning of the file). The number of lines can be customized with the 3930 nedit.autoScrollVPadding resource. 3931 3932 **Warnings** 3933 Options for controlling the popping up of warning dialogs: 3934 3935 ~File Modified Externally~ - 3936 Pop up a warning dialog when files get changed external to XNEdit. 3937 3938 ~Check Modified File Contents~ - 3939 If external file modification warnings are requested, also check the file 3940 contents iso. only the modification date. 3941 3942 ~On Exit~ - 3943 Ask before exiting when two or more files are open in an XNEdit session 3944 or before closing a window with two or more tabs. 3945 3946 **Initial Window Size** 3947 Default size for new windows. 3948 3949 3>Changing Font(s) 3950 3951 The font used to display text in XNEdit is set under Preferences -> Text Font 3952 (for the current window), or Preferences -> Default Settings Text Font (for 3953 future windows). These dialogs also allow you to set fonts for syntax 3954 highlighting. If you don't intend to use syntax highlighting, you can ignore 3955 most of the dialog, and just set the field labeled Primary Font. 3956 3957 Unless you are absolutely certain about the types of files that you will be 3958 editing with XNEdit, you should choose a fixed-spacing font. Many, if not 3959 most, plain-text files are written expecting to be viewed with fixed 3960 character spacing, and will look wrong with proportional spacing. XNEdit's 3961 filling, wrapping, and rectangular operations will also work strangely if you 3962 choose a proportional font. 3963 3964 Note that in the font browser (the dialog brought up by the Browse... 3965 button), the subset of fonts which are shown is narrowed depending on the 3966 characteristics already selected. It is therefore important to know that you 3967 can unselect characteristics from the lists by clicking on the selected items 3968 a second time. 3969 3970 Fonts for syntax highlighting should ideally match the primary font in both 3971 height and spacing. A mismatch in spacing will result in similar distortions 3972 as choosing a proportional font: column alignment will sometimes look wrong, 3973 and rectangular operations, wrapping, and filling will behave strangely. A 3974 mismatch in height will cause windows to re-size themselves slightly when 3975 syntax highlighting is turned on or off, and increase the inter-line spacing 3976 of the text. Unfortunately, on some systems it is hard to find sets of fonts 3977 which match exactly in height. 3978 3979 3>Customizing Menus 3980 3981 You can add or change items in the Shell, Macro, and window background menus 3982 under Preferences -> Default Settings -> Customize Menus. When you choose 3983 one of these, you will see a dialog with a list of the current 3984 user-configurable items from the menu on the left. To change an existing 3985 item, select it from the list, and its properties will appear in the 3986 remaining fields of the dialog, where you may change them. Selecting the 3987 item "New" from the list allows you to enter new items in the menu. 3988 3989 Hopefully most of the characteristics are self explanatory, but here are a 3990 few things to note: 3991 3992 Accelerator keys are keyboard shortcuts which appear on the right hand side 3993 of the menus, and allow you avoid pulling down the menu and activate the 3994 command with a single keystroke. Enter accelerators by typing the keys 3995 exactly as you would to activate the command. 3996 3997 Mnemonics are a single letter which should be part of the menu item name, 3998 which allow users to traverse and activate menu items by typing keys when the 3999 menu is pulled down. 4000 4001 In the Shell Command field of the Shell Commands dialog, the % character 4002 expands to the name (including directory path) of the file in the window. To 4003 include a % character in the command, use %%. 4004 4005 The Menu Entry field can contain special characters for constructing 4006 hierarchical sub-menus, and for making items which appear only in certain 4007 language modes. The right angle bracket character ">" creates a sub-menu. 4008 The name of the item itself should be the last element of the path formed 4009 from successive sub-menu names joined with ">". Menu panes are called in to 4010 existence simply by naming them as part of a Menu Entry name. To put several 4011 items in the same sub-menu, repeat the same hierarchical sequence for each. 4012 For example, in the Macro Commands dialog, two items with menu entries: a>b>c 4013 and a>b>d would create a single sub menu under the macro menu called "a", 4014 which would contain a single sub-menu, b, holding the actual items, c and d: 4015 4016 +---++---++---+ 4017 |a >||b >||c | 4018 +---++---+|d | 4019 +---+ 4020 4021 To qualify a menu entry with a language mode, simply add an at-sign "@@" at 4022 the end of the menu command, followed (no space) by a language mode name. To 4023 make a menu item which appears in several language modes, append additional 4024 @@s and language mode names. For example, an item with the menu entry: 4025 4026 Make C Prototypes@@C@@C++ 4027 4028 would appear only in C and C++ language modes, and: 4029 4030 Make Class Template@@C++ 4031 4032 would appear only in C++ mode. 4033 4034 Menu items with no qualification appear in all language modes. 4035 4036 If a menu item is followed by the single language qualification "@@*", that 4037 item will appear only if there are no applicable language-specific items of 4038 the same name in the same submenu. For example, if you have the following 4039 three entries in the same menu: 4040 4041 Make Prototypes@@C@@C++ 4042 Make Prototypes@@Java 4043 Make Prototypes@@* 4044 4045 The first will be available when the language mode is C or C++, the second 4046 when the language mode is Java, and for all other language modes (including 4047 the "Plain" non-language mode). If the entry: 4048 4049 Make Prototypes 4050 4051 also exists, this will always appear, meaning that the menu will always have 4052 two "Make Prototypes" entries, whatever the language mode. 4053 4054 3>The XNEdit Autoload Files 4055 4056 At startup time, XNEdit _automatically reads the preferences file 4057 `nedit.rc', the autoload macro file `autoload.nm', and the history data base 4058 `nedit.history'. The preferences file contains saved preferences (menu 4059 settings) in the format of an X resource file. The autoload macro file is a 4060 macro file containing macro commands and definitions that XNEdit will 4061 execute at startup. (XNEdit doesn't create this file automatically.) 4062 Moreover, XNEdit saves a list of the recently opened files, which appear under 4063 the Open Previous menu, in the history data base. 4064 4065 By default the location of these files is '$HOME/.xnedit/'. A different 4066 directory can be given by letting the environment variable NEDIT_HOME 4067 point to it. 4068 4069 Notice that XNEdit still supports the older names for these files, which are 4070 `$HOME/.nedit', `$HOME/.neditmacro', and `$HOME/.neditdb', respectively. This 4071 old naming scheme will be used if XNEdit detects that `$HOME/.nedit' is a 4072 regular file and NEDIT_HOME isn't set. 4073 4074 (For VMS, the location of these files is '$NEDIT_HOME/' if NEDIT_HOME is set, 4075 and 'SYS$LOGIN:' otherwise.) 4076 4077 The contents of the preferences file can be moved into another X resource 4078 file (see X_Resources_). One reason for doing so would be to attach server 4079 specific preferences, such as a default font, to a particular X server. 4080 Another reason for moving preferences into an X resource file would be to 4081 keep preferences menu options and X resource settable options together in 4082 one place. Though the files are the same format, additional resources 4083 should not be added to the preferences file, since XNEdit modifies that file 4084 by overwriting it completely. Note also that the contents of the 4085 preferences file takes precedence over the values in an X resource file. 4086 Using Save Defaults after moving the contents of your preferences file to 4087 your .Xdefaults file will re-create the preferences file, interfering with 4088 the options that you have moved. 4089 4090 4091 4092 3>Sharing Customizations with Other XNEdit Users 4093 4094 If you have written macro or shell menu commands, highlight patterns, or 4095 smart-indent macros that you want to share with other XNEdit users, you can 4096 make a file which they can load into their XNEdit environment. 4097 4098 To load such a file, start XNEdit with the command: 4099 4100 xnedit -import <file> 4101 4102 In the new XNEdit session, verify that the imported patterns or macros do what 4103 you want, then select Preferences -> Save Defaults. Saving incorporates the 4104 changes into the XNEdit preferences file, so the next time you run XNEdit, you 4105 will not have to import the distribution file. 4106 4107 Loading a customization file is automated, but creating one is not. To 4108 produce a file to be imported by other users, you must make a copy of your own 4109 preferences file, and edit it, by hand, to remove everything but the 4110 few items of interest to the recipient. Leave only the individual 4111 resource(s), and within those resources, only the particular macro, pattern, 4112 style, etc, that you wish to exchange. 4113 4114 For example, to share a highlighting pattern set, you would include the 4115 patterns, any new styles you added, and language mode information only if the 4116 patterns are intended to support a new language rather than updating an 4117 existing one. For example: 4118 4119 nedit.highlightPatterns:\ 4120 My Language:1:0{\n\ 4121 Comment:"#":"$"::Comment::\n\ 4122 Loop Header:"^[ \\t]*loop:":::Loop::\n\ 4123 } 4124 nedit.languageModes: My Language:.my:::::: 4125 nedit.styles: Loop:blue:Bold 4126 4127 Resources are in the format of X resource files, but the format of text 4128 within multiple-item resources like highlight patterns, language modes, 4129 macros, styles, etc., are private to XNEdit. Each resource is a string which 4130 ends at the first newline character not escaped with \, so you must be 4131 careful about how you treat ends of lines. While you can generally just cut 4132 and paste indented sections, if something which was originally in the middle 4133 of a resource string is now at the end, you must remove the \ line 4134 continuation character(s) so it will not join the next line into the 4135 resource. Conversely, if something which was originally at the end of a 4136 resource is now in the middle, you'll have to add continuation character(s) 4137 to make sure that the resource string is properly continued from beginning to 4138 end, and possibly newline character(s) (\n) to make sure that it is properly 4139 separated from the next item. 4140 ---------------------------------------------------------------------- 4141 4142 X Resources 4143 ----------- 4144 4145 XNEdit has additional options to those provided in the Preferences menu which 4146 are set using X resources. Like most other X programs, XNEdit can be 4147 customized to vastly unnecessary proportions, from initial window positions 4148 down to the font and shadow colors of each individual button (A complete 4149 discussion of how to do this is left to books on the X Window System). Key 4150 binding (see "Key_Binding_" is one of the most useful of these resource 4151 settable options. 4152 4153 X resources are usually specified in a file called .Xdefaults or .Xresources 4154 in your home directory (on VMS this is sys$login:decw$xdefaults.dat). On 4155 some systems, this file is read and its information attached to the X server 4156 (your screen) when you start X. On other systems, the .Xdefaults file is 4157 read each time you run an X program. When X resource values are attached to 4158 the X server, changes to the resource file are not available to application 4159 programs until you either run the xrdb program with the appropriate file as 4160 input, or re-start the X server. 4161 4162 3>Selected X Resource Names 4163 4164 The following are selected XNEdit resource names and default values for XNEdit 4165 options not settable via the Preferences menu (for preference resource names, 4166 see your XNEdit preference file): 4167 4168 **nedit.tagFile**: (not defined) 4169 4170 This can be the name of a file, or multiple files separated by a colon (:) 4171 character, of the type produced by Exuberant Ctags or the Unix ctags 4172 command, which XNEdit will load at startup time (see ctags_support_). The tag 4173 file provides a database from which XNEdit can automatically open files 4174 containing the definition of a particular subroutine or data type. 4175 4176 **nedit.alwaysCheckRelativeTagsSpecs: True** 4177 4178 When this resource is set to True, and there are tag files specified (with 4179 the nedit.tagFile resource, see above) as relative paths, XNEdit will evaluate 4180 these tag value paths whenever a file is opened. All accessible tag files 4181 will be loaded at this time. When this resource value is False, relative path 4182 tag specifications will only be evaluated at XNEdit startup time. 4183 4184 **nedit.wordDelimiters**: .,/\\`'!@@#%^&*()-=+{}[]":;<>? 4185 4186 The set of characters which mark the boundaries between words. In addition 4187 to these, spaces, tabs, and newlines are always word boundaries. 4188 4189 These boundaries take effect for the move-by-word (Ctrl+Arrow) and 4190 select-word (double click) commands, and for doing regex searches using the 4191 \B, < and > tokens. 4192 4193 Note that this default value may be overridden by the setting in 4194 Preferences -> Default Settings -> Language Modes.... 4195 4196 **nedit.remapDeleteKey**: False 4197 4198 Setting this resource to True forcibly maps the delete key to backspace. This 4199 can be helpful on systems where the bindings have become tangled, and in 4200 environments which mix systems with PC style keyboards and systems with DEC 4201 and Macintosh keyboards. Theoretically, these bindings should be made using 4202 the standard X/Motif mechanisms, outside of XNEdit. In practice, some 4203 environments where users access several different systems remotely, can be 4204 very hard to configure. If you've given up and are using a backspace key 4205 halfway off the keyboard because you can't figure out the bindings, set this 4206 to True. 4207 4208 **nedit.typingHidesPointer**: False 4209 4210 Setting this resource to True causes the mouse pointer to be hidden when you 4211 type in the text area. As soon as the mouse pointer is moved, it will 4212 reappear. This is useful to stop the mouse pointer from obscuring text. 4213 4214 **nedit.overrideDefaultVirtualKeyBindings**: Auto 4215 4216 Motif uses a virtual key binding mechanism that shares the bindings between 4217 different Motif applications. When a first Motif application is started, it 4218 installs some default virtual key bindings and any other Motif application 4219 that runs afterwards, simply reuses them. Obviously, if the first 4220 application installs an invalid set, all others applications may have 4221 problems. 4222 4223 In the past, XNEdit has been the victim of invalid bindings installed by other 4224 applications several times. Through this resource, XNEdit can be instructed 4225 to ignore the bindings installed by other applications, and use its own 4226 private bindings. By default, XNEdit tries to detect invalid bindings 4227 and ignore them automatically (Auto). Optionally, XNEdit can be told to 4228 always keep the installed bindings (Never), or to always override them 4229 (Always). 4230 4231 **nedit.stdOpenDialog**: False 4232 4233 Setting this resource to True restores the standard Motif style of Open 4234 dialog. XNEdit file open dialogs are missing a text field at the bottom of 4235 the dialog, where the file name can be entered as a string. The field is 4236 removed in XNEdit to encourage users to type file names in the list, a 4237 non-standard, but much faster method for finding files. 4238 4239 **nedit.bgMenuButton**: @~Shift@~Ctrl@~Meta@~Alt<Btn3Down> 4240 4241 Specification for mouse button / key combination to post the background menu 4242 (in the form of an X translation table event specification). The event 4243 specification should be as specific as possible, since it will override less 4244 specific translation table entries. 4245 4246 **nedit.maxPrevOpenFiles**: 30 4247 4248 Number of files listed in the Open Previous sub-menu of the File menu. 4249 Setting this to zero disables the Open Previous menu item and maintenance of 4250 the XNEdit file history file. 4251 4252 **nedit.printCommand**: (system specific) 4253 4254 Command used by the print dialog to print a file, such as, lp, lpr, etc.. 4255 The command must be capable of accepting input via stdin (standard input). 4256 4257 **nedit.printCopiesOption**: (system specific) 4258 4259 Option name used to specify multiple copies to the print command. If the 4260 option should be separated from its argument by a space, leave a trailing 4261 space. If blank, no "Number of Copies" item will appear in the print dialog. 4262 4263 **nedit.printQueueOption**: (system specific) 4264 4265 Option name used to specify a print queue to the print command. If the 4266 option should be separated from its argument by a space, leave a trailing 4267 space. If blank, no "Queue" item will appear in the print dialog. 4268 4269 **nedit.printNameOption**: (system specific) 4270 4271 Option name used to specify a job name to the print command. If the option 4272 should be separated from its argument by a space, leave a trailing space. If 4273 blank, no job or file name will be attached to the print job or banner page. 4274 4275 **nedit.printHostOption**: (system specific) 4276 4277 Option name used to specify a host name to the print command. If the option 4278 should be separated from its argument by a space, leave a trailing space. If 4279 blank, no "Host" item will appear in the print dialog. 4280 4281 **nedit.printDefaultQueue**: (system specific) 4282 4283 The name of the default print queue. Used only to display in the print 4284 dialog, and has no effect on printing. 4285 4286 **nedit.printDefaultHost**: (system specific) 4287 4288 The node name of the default print host. Used only to display in the print 4289 dialog, and has no effect on printing. 4290 4291 **nedit.visualID**: Best 4292 4293 If your screen supports multiple visuals (color mapping models), this 4294 resource allows you to manually choose among them. The default value of 4295 "Best" chooses the deepest (most colors) visual available. Since XNEdit does 4296 not depend on the specific characteristics of any given color model, Best 4297 probably IS the best choice for everyone, and the only reason for setting 4298 this resource would be to patch around some kind of X server problem. The 4299 resource may also be set to "Default", which chooses the screen's default 4300 visual (often a color-mapped, PseudoColor, visual for compatibility with 4301 older X applications). It may also be set to a numeric visual-id value (use 4302 xdpyinfo to see the list of visuals supported by your display), or a visual 4303 class name: PseudoColor, DirectColor, TrueColor, etc.. 4304 4305 If you are running under a themed environment (like KDE or CDE) that places 4306 its colors in a shallow visual, and you'd rather have that color scheme 4307 instead of more colors available, then you may need set the visual to 4308 "Default" so that XNEdit doesn't choose one with more colors. (The reason 4309 for this is: if the "best" visual is not the server's default, then XNEdit 4310 cannot use the colors provided by your environment. XNEdit will fall back to 4311 its own default color scheme.) 4312 4313 **nedit.installColormap**: False 4314 4315 Force the installation of a private colormap. If you have a humble 8-bit 4316 color display, and netscape is hogging all of the color cells, you may want 4317 to try turning this on. On most systems, this will result in colors flashing 4318 wildly when you switch between XNEdit and other applications. But a few 4319 systems (SGI) have hardware support for multiple simultaneous colormaps, and 4320 applications with installed colormaps are well behaved. 4321 4322 **nedit.findReplaceUsesSelection**: False 4323 4324 Controls if the Find and Replace dialogs are automatically loaded with the 4325 contents of the primary selection. 4326 4327 **nedit.stickyCaseSenseButton**: True 4328 4329 Controls if the "Case Sensitive" buttons in the Find and Replace dialogs and 4330 the incremental search bar maintain a separate state for literal and regular 4331 expression searches. Moreover, when set to True, by default literal searches 4332 are case insensitive and regular expression searches are case sensitive. When 4333 set to False, the "Case Sensitive" buttons are independent of the "Regular 4334 Expression" toggle. 4335 4336 **nedit.multiClickTime**: (system specific) 4337 4338 Maximum time in milliseconds allowed between mouse clicks within double and 4339 triple click actions. 4340 4341 **nedit.undoModifiesSelection**: True 4342 4343 By default, XNEdit selects any text inserted or changed through a undo/redo 4344 action. Set this resource to False if you don't want your selection to be 4345 touched. 4346 4347 **nedit@*scrollBarPlacement**: BOTTOM_RIGHT 4348 4349 How scroll bars are placed in XNEdit windows, as well as various lists and 4350 text fields in the program. Other choices are: BOTTOM_LEFT, TOP_LEFT, or 4351 TOP_RIGHT. 4352 4353 **nedit@*text.autoWrapPastedText**: False 4354 4355 When Auto Newline Wrap is turned on, apply automatic wrapping (which 4356 normally only applies to typed text) to pasted text as well. 4357 4358 **nedit@*text.heavyCursor**: False 4359 4360 For monitors with poor resolution or users who have difficulty seeing the 4361 cursor, makes the cursor in the text editing area of the window heavier and 4362 darker. 4363 4364 **nedit.autoScrollVPadding**: 4 4365 4366 Number of lines to keep the cursor away from the top or bottom line of the 4367 window when the "Auto-Scroll Near Window Top/Bottom" feature is enabled. 4368 Keyboard operations that would cause the cursor to get closer than 4369 this distance cause the window to scroll up or down instead, except at the 4370 beginning of the file. Mouse operations are not affected. 4371 4372 **nedit@*text.blinkRate**: 500 4373 4374 Blink rate of the text insertion cursor in milliseconds. Set to zero to stop 4375 blinking. 4376 4377 **nedit@*text.Translations**: 4378 4379 Modifies key bindings (see "Key_Binding_"). 4380 4381 **nedit@*foreground**: black 4382 4383 Default foreground color for menus, dialogs, scroll bars, etc.. 4384 4385 **nedit@*background**: #b3b3b3 4386 4387 Default background color for menus, dialogs, scroll bars, etc.. 4388 4389 **nedit@*calltipForeground**: black 4390 4391 Foreground color for calltips 4392 4393 **nedit@*calltipBackground**: LemonChiffon1 4394 4395 Background color for calltips 4396 4397 **nedit@*XmLFolder.inactiveForeground**: #666 4398 4399 Foreground color for inactive tabs. 4400 4401 **nedit@*fontList**: helvetica medium 12 points 4402 4403 Default font for menus, dialogs, scroll bars, etc.. 4404 4405 **nedit.helpFont**: helvetica medium 12 points 4406 4407 Font used for displaying online help. 4408 4409 **nedit.boldHelpFont**: helvetica bold 12 points 4410 4411 Bold font for online help. 4412 4413 **nedit.italicHelpFont**: helvetica italic 12 points 4414 4415 Italic font for online help. 4416 4417 **nedit.fixedHelpFont**: courier medium 12 points 4418 4419 Fixed font for online help. 4420 4421 **nedit.boldFixedHelpFont**: courier bold 12 points 4422 4423 Fixed bold for online help. 4424 4425 **nedit.italicFixedHelpFont**: courier italic 12 points 4426 4427 Fixed italic font for online help. 4428 4429 **nedit.h1HelpFont**: helvetica bold 14 points 4430 4431 Font for level-1 titles in help text. 4432 4433 **nedit.h2HelpFont**: helvetica bold italic 12 points 4434 4435 Font for level-2 titles in help text. 4436 4437 **nedit.h3HelpFont**: courier bold 12 points 4438 4439 Font for level-3 titles in help text. 4440 4441 **nedit.helpLinkFont**: helvetica medium 12 points 4442 4443 Font for hyperlinks in the help text 4444 4445 **nedit.helpLinkColor**: #009900 4446 4447 Color for hyperlinks in the help text 4448 4449 **nedit.backlightCharTypes**: 0-8,10-31,127:red;9:#dedede;32,160-255:#f0f0f0;128-159:orange 4450 4451 **NOTE: backlighting is ~experimental~** (see "Programming_with_XNEdit_"). 4452 4453 A string specifying character classes as ranges of ASCII values followed by 4454 the color to be used as their background colors. The format is: 4455 4456 low[-high]{,low[-high]}:color{;low-high{,low[-high]}:color} 4457 4458 where low and high are ASCII values. 4459 4460 For example: 4461 32-255:#f0f0f0;1-31,127:red;128-159:orange;9-13:#e5e5e5 4462 4463 .. DISABLED for 5.4 4464 .. The macro built-in function set_backlight_string() allows these strings to be 4465 .. set for a particular window. 4466 4467 **nedit.focusOnRaise**: False 4468 4469 This resource determines whether new text windows and text windows that are 4470 raised, should also request the input focus. Conventionally, it is the task 4471 of the window manager to decide on which window gets the input focus. 4472 Therefore, XNEdit's default behaviour is not to request the input focus 4473 explicitly. 4474 4475 **nedit.forceOSConversion**: True 4476 4477 By default, XNEdit converts texts in DOS or Mac format to an internal 4478 format using simple newlines as line dividers. This is sometimes not 4479 wanted by the user and can be prevented by setting this resource to 4480 False. 4481 4482 Note: Setting this to False would supress newlines in Mac files entirely, 4483 leaving the control character <cr> where every line feed would be. Mac OS 4484 X uses Unix files and is not affected. 4485 4486 Note: Setting this to False while the option 'Terminate with Line Break 4487 on Save' is active could lead to file corruption. 4488 4489 **nedit.truncSubstitution**: Fail 4490 4491 XNEdit has a fixed limit on substitution result string length. This 4492 resource modifies the behaviour if this limit is exceeded. Possible 4493 values are ~Silent~ (will silently fail the operation), ~Fail~ (will fail 4494 the operation and pop up a dialog informing the user), ~Warn~ (pops up a 4495 dialog warning the user, offering to cancel the operation) and ~Ignore~ 4496 (will silently conclude the operation). 4497 4498 **WARNING**: Setting this to 'Ignore' will destroy data without warning! 4499 4500 **nedit.honorSymlinks**: True 4501 4502 If set to True, XNEdit will open a requested file on disk even if it is a 4503 symlink pointing to a file already opened in another window. If set to false, 4504 XNEdit will try to detect these cases and just pop up the already opened 4505 document. 4506 4507 **nc.autoStart**: True 4508 4509 Whether the xnc program should automatically start an XNEdit server (without 4510 prompting the user) if an appropriate server is not found. 4511 4512 **nc.serverCommand**: xnedit -server 4513 4514 Command used by the xnc program to start an XNEdit server. 4515 4516 **nc.timeOut**: 10 4517 4518 Basic time-out period used in communication with an XNEdit server (seconds). 4519 4520 ---------------------------------------------------------------------- 4521 ~The following are Selected widget names (to which you may append~ 4522 ~.background, .foreground, .fontList, etc., to change colors, fonts~ 4523 ~ and other characteristics):~ 4524 4525 **nedit@*statsAreaForm** 4526 4527 Statistics line and incremental search bar. To get consistent results across 4528 the entire stats line and the incremental search bar, use '*' rather than '.' 4529 to separate the resource name. For example, to set the foreground color of 4530 both components use: 4531 nedit*statsAreaForm*foreground 4532 instead of: 4533 nedit*statsAreaForm.foreground 4534 4535 **nedit@*menuBar** 4536 4537 Top-of-window menu-bar. 4538 4539 **nedit@*textHorScrollBar** 4540 4541 Horizontal scroll bar. 4542 4543 **nedit@*textVertScrollBar** 4544 4545 Vertical scroll bar. 4546 ---------------------------------------------------------------------- 4547 4548 Key Binding 4549 ----------- 4550 4551 There are several ways to change key bindings in XNEdit. The easiest way to 4552 add a new key binding in XNEdit is to define a macro in Preferences -> Default 4553 Settings -> Customize Menus -> Macro Menu. However, if you want to change 4554 existing bindings or add a significant number of new key bindings you will 4555 need to do so via X resources. 4556 4557 Before reading this section, you must understand how to set X resources (see 4558 the help section "X_Resources_"). Since setting X resources is tricky, it is 4559 also helpful when working on key-binding, to set some easier-to-verify 4560 resource at the same time, as a simple check that the XNEdit program is 4561 actually seeing your changes. The appres program is also very helpful in 4562 checking that the resource settings that you make, actually reach the program 4563 for which they are intended in the correct form. 4564 4565 3>Key Binding in General 4566 4567 Keyboard commands are associated with editor action routines through two 4568 separate mechanisms in XNEdit. Commands which appear in pull-down menus have 4569 individual resources designating a keyboard equivalent to the menu command, 4570 called an accelerator key. Commands which do not have an associated menu 4571 item are bound to keys via the X toolkit translation mechanism. The methods 4572 for changing these two kinds of bindings are quite different. 4573 4574 3>Key Binding Via Translations 4575 4576 The most general way to bind actions to keys in XNEdit is to use the 4577 translation table associated with the text widget. To add a binding to Alt+Y 4578 to insert the string "Hi!", for example, add lines similar to the following 4579 to your X resource file: 4580 4581 XNEdit*text.Translations: #override \n\ 4582 Alt<Key>y: insert_string("Hi!") \n 4583 4584 The Help topic "Action_Routines_" lists the actions available to be bound. 4585 4586 Translation tables map key and mouse presses, window operations, and other 4587 kinds of events, to actions. The syntax for translation tables is 4588 simplified here, so you may need to refer to a book on the X window system 4589 for more detailed information. 4590 4591 Note that accelerator resources (discussed below) override translations, and 4592 that most Ctrl+letter and Alt+letter combinations are already bound to an 4593 accelerator key. To use one of these combinations from a translation table, 4594 therefore, you must first un-bind the original menu accelerator. 4595 4596 A resource for changing a translation table consists of a keyword; #override, 4597 #augment, or #replace; followed by lines (separated by newline characters) 4598 pairing events with actions. Events begin with modifiers, like Ctrl, Shift, 4599 or Alt, followed by the event type in <>. BtnDown, Btn1Down, Btn2Down, 4600 Btn1Up, Key, KeyUp are valid event types. For key presses, the event type is 4601 followed by the name of the key. You can specify a combination of events, 4602 such as a sequence of key presses, by separating them with commas. The other 4603 half of the event/action pair is a set of actions. These are separated from 4604 the event specification by a colon and from each other by spaces. Actions 4605 are names followed by parentheses, optionally containing one or more 4606 parameters separated by comas. 4607 4608 3>Changing Menu Accelerator Keys 4609 4610 The menu shortcut keys shown at the right of XNEdit menu items can also be 4611 changed via X resources. Each menu item has two resources associated with 4612 it, accelerator, the event to trigger the menu item; and acceleratorText, the 4613 string shown in the menu. The form of the accelerator resource is the same 4614 as events for translation table entries discussed above, though multiple keys 4615 and other subtleties are not allowed. The resource name for a menu is the 4616 title in lower case, followed by "Menu", the resource name of menu item is 4617 the name in lower case, run together, with words separated by caps, and all 4618 punctuation removed. For example, to change Cut to Ctrl+X, you would add the 4619 following to your .Xdefaults file: 4620 4621 nedit*editMenu.cut.accelerator: Ctrl<Key>x 4622 nedit*editMenu.cut.acceleratorText: Ctrl+X 4623 4624 Accelerator keys with optional shift key modifiers, like Find..., have an 4625 additional accelerator resource with Shift appended to the name. For 4626 example: 4627 4628 nedit*searchMenu.find.acceleratorText: [Shift]Alt+F 4629 nedit*searchMenu.find.accelerator: Alt<Key>f 4630 nedit*searchMenu.findShift.accelerator: Shift Alt<Key>f 4631 ---------------------------------------------------------------------- 4632 4633 Highlighting Patterns 4634 --------------------- 4635 4636 3>Writing Syntax Highlighting Patterns 4637 4638 Patterns are the mechanism by which language syntax highlighting is 4639 implemented in XNEdit (see Syntax_Highlighting_ under the heading of Features 4640 for Programming). To create syntax highlighting patterns for a new 4641 language, or to modify existing patterns, select "Recognition Patterns" from 4642 "Syntax Highlighting" sub-section of the "Default Settings" sub-menu of the 4643 "Preferences" menu. 4644 4645 First, a word of caution. As with regular expression matching in general, it 4646 is quite possible to write patterns which are so inefficient that they 4647 essentially lock up the editor as they recursively re-examine the entire 4648 contents of the file thousands of times. With the multiplicity of patterns, 4649 the possibility of a lock-up is significantly increased in syntax 4650 highlighting. When working on highlighting patterns, be sure to save your 4651 work frequently. 4652 4653 XNEdit's syntax highlighting is unusual in that it works in real-time (as you 4654 type), and yet is completely programmable using standard regular expression 4655 notation. Other syntax highlighting editors usually fall either into the 4656 category of fully programmable but unable to keep up in real-time, or 4657 real-time but limited programmability. The additional burden that XNEdit 4658 places on pattern writers in order to achieve this speed/flexibility mix, is 4659 to force them to state self-imposed limitations on the amount of context that 4660 patterns may examine when re-parsing after a change. While the "Pattern 4661 Context Requirements" heading is near the end of this section, it is not 4662 optional, and must be understood before making any serious effort at 4663 pattern writing. 4664 4665 In its simplest form, a highlight pattern consists of a regular expression to 4666 match, along with a style representing the font an color for displaying any 4667 text which matches that expression. To bold the word, "highlight", wherever 4668 it appears the text, the regular expression simply would be the word 4669 "highlight". The style (selected from the menu under the heading of 4670 "Highlight Style") determines how the text will be drawn. To bold the text, 4671 either select an existing style, such as "Keyword", which bolds text, or 4672 create a new style and select it under Highlight Style. 4673 4674 The full range of regular expression capabilities can be applied in such a 4675 pattern, with the single caveat that the expression must conclusively match 4676 or not match, within the pre-defined context distance (as discussed below 4677 under Pattern Context Requirements). 4678 4679 To match longer ranges of text, particularly any constructs which exceed the 4680 requested context, you must use a pattern which highlights text between a 4681 starting and ending regular expression match. To do so, select "Highlight 4682 text between starting and ending REs" under "Matching", and enter both a 4683 starting and ending regular expression. For example, to highlight everything 4684 between double quotes, you would enter a double quote character in both the 4685 starting and ending regular expression fields. Patterns with both a 4686 beginning and ending expression span all characters between the two 4687 expressions, including newlines. 4688 4689 Again, the limitation for automatic parsing to operate properly is that both 4690 expressions must match within the context distance stated for the pattern 4691 set. 4692 4693 With the ability to span large distances, comes the responsibility to recover 4694 when things go wrong. Remember that syntax highlighting is called upon to 4695 parse incorrect or incomplete syntax as often as correct syntax. To stop a 4696 pattern short of matching its end expression, you can specify an error 4697 expression, which stops the pattern from gobbling up more than it should. 4698 For example, if the text between double quotes shouldn't contain newlines, 4699 the error expression might be "$". As with both starting and ending 4700 expressions, error expressions must also match within the requested context 4701 distance. 4702 4703 4>Coloring Sub-Expressions 4704 4705 It is also possible to color areas of text within a regular expression 4706 match. A pattern of this type associates a style with sub-expressions 4707 references of the parent pattern (as used in regular expression substitution 4708 patterns, see the XNEdit Help menu item on Regular_Expressions_). 4709 Sub-expressions of both the starting and ending patterns may be colored. For 4710 example, if the parent pattern has a starting expression "\<", and end 4711 expression "\>", (for highlighting all of the text contained within angle 4712 brackets), a sub-pattern using "&" in both the starting and ending expression 4713 fields could color the brackets differently from the intervening text. A 4714 quick shortcut to typing in pattern names in the Parent Pattern field is to 4715 use the middle mouse button to drag them from the Patterns list. 4716 4717 In some cases, there can be interference between coloring sub-patterns and 4718 hierarchical sub-patterns (discussed next). How this is resolved, is 4719 explained below. 4720 4721 4>Hierarchical Patterns 4722 4723 A hierarchical sub-pattern, is identical to a top level pattern, but is 4724 invoked only between the starting and ending expression matches of its 4725 parent pattern or, in case the parent pattern consists of a single 4726 expression, inside the text area matching that expression. Like the 4727 sub-expression coloring patterns discussed above, it is associated with a 4728 parent pattern using the Parent Pattern field in the pattern specification. 4729 Pattern names can be dragged from the pattern list with the middle mouse 4730 button to the Parent Pattern field. 4731 4732 The matching behaviour for sub-patterns is slightly different, depending on 4733 whether the parent pattern consists of a single expression or has both a 4734 starting and an ending expression. 4735 4736 In case the parent pattern consists of a single expression, and the syntax 4737 highlighting parser finds a match for that expression, sub-patterns are 4738 matched between the start and the end of the parent match. Sub-patterns 4739 cannot extend beyond the boundaries of the parent's match nor can they 4740 affect those boundaries (the latter can happen for starting/ending parent 4741 patterns, see below). Note that sub-patterns can ~peek~ beyond the 4742 parent's matching boundaries by means of look-ahead or look-behind 4743 expressions. 4744 4745 In case the parent pattern is a starting/ending style pattern, after the 4746 start expression of the parent pattern matches, the syntax highlighting 4747 parser searches for either the parent's end pattern or a matching 4748 sub-pattern. When a sub-pattern matches, control is not returned to the 4749 parent pattern until the entire sub-pattern has been parsed, regardless of 4750 whether the parent's end pattern appears in the text matched by the 4751 sub-pattern. In this way, matching of the parent's ending pattern can be 4752 postponed, in contrast to the case where the parent pattern consists of a 4753 single expression. Note that, in this case, parsing of sub-patterns starts 4754 **after** the match of the parent pattern's starting expression, also in 4755 contrast to the single-expression case. 4756 4757 The most common use for this capability is for coloring sub-structure of 4758 language constructs (smaller patterns embedded in larger patterns). 4759 Hierarchical patterns can also simplify parsing by having sub-patterns "hide" 4760 special syntax from parent patterns, such as special escape sequences or 4761 internal comments. 4762 4763 There is no depth limit in nesting hierarchical sub-patterns, but beyond the 4764 third level of nesting, automatic re-parsing will sometimes have to re-parse 4765 more than the requested context distance to guarantee a correct parse (which 4766 can slow down the maximum rate at which the user can type if large sections 4767 of text are matched only by deeply nested patterns). 4768 4769 While this is obviously not a complete hierarchical language parser it is 4770 still useful in many text coloring situations. As a pattern writer, your 4771 goal is not to completely cover the language syntax, but to generate 4772 colorings that are useful to the programmer. Simpler patterns are usually 4773 more efficient and also more robust when applied to incorrect code. 4774 4775 Note that in case of a single-expression parent pattern, there is a 4776 potential for conflicts between coloring-only sub-patterns and hierarchical 4777 sub-patterns (which cannot happen for starting/ending type of patterns, 4778 because sub-patterns are matched **between** the starting and ending pattern 4779 (not included)). Due to the different nature of these two kinds of 4780 sub-patterns, it is technically infeasible to follow the standard matching 4781 precedence rules, where a sub-pattern has precedence over the sub-patterns 4782 following it. Instead, coloring-only sub-patterns are always colored last, 4783 ie., they may override the coloring for overlapping sibling sub-patterns in 4784 the overlapping parts of the matches. 4785 4786 4>Deferred (Pass-2) Parsing 4787 4788 XNEdit does pattern matching for syntax highlighting in two passes. The first 4789 pass is applied to the entire file when syntax highlighting is first turned 4790 on, and to new ranges of text when they are initially read or pasted in. The 4791 second pass is applied only as needed when text is exposed (scrolled in to 4792 view). 4793 4794 If you have a particularly complex set of patterns, and parsing is beginning 4795 to add a noticeable delay to opening files or operations which change large 4796 regions of text, you can defer some of that parsing from startup time, to 4797 when it is actually needed for viewing the text. Deferred parsing can only 4798 be used with single expression patterns, or begin/end patterns which match 4799 entirely within the requested context distance. To defer the parsing of a 4800 pattern to when the text is exposed, click on the Pass-2 pattern type button 4801 in the highlight patterns dialog. 4802 4803 Sometimes a pattern can't be deferred, not because of context requirements, 4804 but because it must run concurrently with pass-1 (non-deferred) patterns. If 4805 they didn't run concurrently, a pass-1 pattern might incorrectly match some 4806 of the characters which would normally be hidden inside of a sequence matched 4807 by the deferred pattern. For example, C has character constants enclosed in 4808 single quotes. These typically do not cross line boundaries, meaning they 4809 can be parsed entirely within the context distance of the C pattern set and 4810 should be good candidates for deferred parsing. However, they can't be 4811 deferred because they can contain sequences of characters which can trigger 4812 pass-one patterns. Specifically, the sequence, '\"', contains a double quote 4813 character, which would be matched by the string pattern and interpreted as 4814 introducing a string. 4815 4816 4>Pattern Context Requirements 4817 4818 The context requirements of a pattern set state how much additional text 4819 around any change must be examined to guarantee that the patterns will match 4820 what they are intended to match. Context requirements are a promise by XNEdit 4821 to the pattern writer, that the regular expressions in his/her patterns will 4822 be matched against at least <line context> lines and <character context> 4823 characters, around any modified text. Combining line and character 4824 requirements guarantee that both will be met. 4825 4826 Automatic re-parsing happens on EVERY KEYSTROKE, so the amount of context 4827 which must be examined is very critical to typing efficiency. The more 4828 complicated your patterns, the more critical the context becomes. To cover 4829 all of the keywords in a typical language, without affecting the maximum rate 4830 at which users can enter text, you may be limited to just a few lines and/or 4831 a few hundred characters of context. 4832 4833 The default context distance is 1 line, with no minimum character 4834 requirement. There are several benefits to sticking with this default. One 4835 is simply that it is easy to understand and to comply with. Regular 4836 expression notation is designed around single line matching. To span lines 4837 in a regular expression, you must explicitly mention the newline character 4838 "\n", and matches which are restricted to a single line are virtually immune 4839 to lock-ups. Also, if you can code your patterns to work within a single 4840 line of context, without an additional character-range context requirement, 4841 the parser can take advantage the fact that patterns don't cross line 4842 boundaries, and nearly double its efficiency over a one-line and 1-character 4843 context requirement. (In a single line context, you are allowed to match 4844 newlines, but only as the first and/or last character.) 4845 ---------------------------------------------------------------------- 4846 4847 Smart Indent Macros 4848 ------------------- 4849 4850 Smart indent macros can be written for any language, but are usually more 4851 difficult to write than highlighting patterns. A good place to start, of 4852 course, is to look at the existing macros for C and C++. 4853 4854 Smart indent macros for a language mode consist of standard XNEdit macro 4855 language code attached to any or all of the following three activation 4856 conditions: 1) When smart indent is first turned on for a text window 4857 containing code of the language, 2) When a newline is typed and smart indent 4858 is expected, 3) after any character is typed. To attach macro code to any of 4859 these code "hooks", enter it in the appropriate section in the Preferences -> 4860 Default Settings -> Auto Indent -> Program Smart Indent dialog. 4861 4862 Typically most of the code should go in the initialization section, because 4863 that is the appropriate place for subroutine definitions, and smart indent 4864 macros are complicated enough that you are not likely to want to write them 4865 as one monolithic run of code. You may also put code in the Common/Shared 4866 Initialization section (accessible through the button in the upper left 4867 corner of the dialog). Unfortunately, since the C/C++ macros also reside in 4868 the common/shared section, when you add code there, you run some risk of 4869 missing out on future upgrades to these macros, because your changes will 4870 override the built-in defaults. 4871 4872 The newline macro is invoked after the user types a newline, but before the 4873 newline is entered in the buffer. It takes a single argument ($1) which is 4874 the position at which the newline will be inserted. It must return the 4875 number of characters of indentation the line should have, or -1. A return 4876 value of -1 means to do a standard auto-indent. You must supply a newline 4877 macro, but the code: "return -1" (auto-indent), or "return 0" (no indent) is 4878 sufficient. 4879 4880 The type-in macro takes two arguments. $1 is the insert position, and $2 is 4881 the character just typed, and does not return a value. It also is invoked 4882 before the character is inserted into the buffer. You can do just about 4883 anything here, but keep in mind that this macro is executed for every 4884 keystroke typed, so if you try to get too fancy, you may degrade performance. 4885 ---------------------------------------------------------------------- 4886 4887 XNEdit Command Line 4888 ------------------ 4889 4890 .. ? help !!#ifndef VMS 4891 **xnedit** [-**read**] [-**create**] [-**line** n | +n] [-**server**] 4892 [-**do** command] [-**tags** file] [-**tabs** n] [-**wrap**] 4893 [-**nowrap**] [-**autowrap**] [-**autoindent**] [-**noautoindent**] 4894 [-**autosave**] [-**noautosave**] [-**rows** n] [-**columns** n] 4895 [-**font** font] [-**lm** languagemode] [-**geometry** geometry] 4896 [-**iconic**] [-**noiconic**] [-**display** [host]:server[.screen] 4897 [-**xrm** resourcestring] [-**svrname** name] [-**import** file] 4898 [-**background** color] [-**foreground** color] [-**h**|-**help**] 4899 [-**tabbed**] [-**untabbed**] [-**group**] [-**V**|-**version**] 4900 [-bgrun] [--] [file...] 4901 4902 **-read** 4903 Open the file Read Only regardless of the actual file protection. 4904 4905 **-create** 4906 Don't warn about file creation when a file doesn't exist. 4907 4908 **-line n (or +n)** 4909 Go to line number n in the file following this switch. 4910 4911 **-server** 4912 Designate this session as an XNEdit server, for processing commands from the 4913 xnc program. xnc can be used to interface XNEdit to code development 4914 environments, mailers, etc., or just as a quick way to open files from the 4915 shell command line without starting a new XNEdit session. 4916 4917 **-do command** 4918 Execute an XNEdit macro or action on the file following the -do argument on 4919 the command line. -do is particularly useful from the xnc program, where 4920 xnc -do can remotely execute commands in an XNEdit -server session. 4921 4922 **-tags file** 4923 Load a file of directions for finding definitions of program subroutines and 4924 data objects. The file must be of the format generated by Exuberant Ctags, 4925 or the standard Unix ctags command. 4926 4927 **-tabs n** 4928 Set tab stops every n characters. 4929 4930 **-wrap, -nowrap** 4931 Wrap long lines at the right edge of the window rather than continuing them 4932 past it. (Continuous Wrap mode) 4933 4934 **-autowrap, -noautowrap** 4935 Wrap long lines when the cursor reaches the right edge of the window by 4936 inserting newlines at word boundaries. (Auto Newline Wrap mode) 4937 4938 **-autoindent, -noautoindent** 4939 Maintain a running indent. 4940 4941 **-autosave, -noautosave** 4942 Maintain a backup copy of the file being edited under the name '~filename'. 4943 4944 **-rows n** 4945 Default height in characters for an editing window. 4946 4947 **-columns n** 4948 Default width in characters for an editing window. 4949 4950 **-font font (or -fn font)** 4951 Font for text being edited (Font for menus and dialogs can be set with -xrm 4952 "*fontList:font"). 4953 4954 **-lm languagemode** 4955 Initial language mode used for editing succeeding files. 4956 4957 **-geometry geometry (or -g geometry)** 4958 The initial size and/or location of editor windows. The argument geometry 4959 has the form: 4960 4961 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>] 4962 4963 where <width> and <height> are the desired width and height of the window, 4964 and <xoffset> and <yoffset> are the distance from the edge of the screen to 4965 the window, + for top or left, - for bottom or right. -geometry can be 4966 specified for individual files on the command line. 4967 4968 **-iconic, -noiconic** 4969 Initial window state for succeeding files. 4970 4971 **-display [host]:server[.screen]** 4972 The name of the X server to use. host specifies the machine, server 4973 specifies the display server number, and screen specifies the screen number. 4974 host or screen can be omitted and default to the local machine, and screen 0. 4975 4976 **-background color (or -bg color)** 4977 User interface background color. (Background color for text can be set 4978 separately with -xrm "nedit.textBgColor: color" or using the Preferences -> 4979 Colors dialog). 4980 4981 **-foreground color (or -fg color)** 4982 User interface foreground color. (Foreground color for text can be set 4983 separately with -xrm "nedit.textFgColor: color" or using the Preferences 4984 -> Colors dialog). 4985 4986 **-tabbed** 4987 Open all subsequent files in new tabs. Resets -group option. 4988 4989 **-untabbed** 4990 Open all subsequent files in new windows. Resets -group option. Note 4991 that this only works on subsequent files in this command and does not put 4992 XNEdit in tab-less mode; for that you can use the command 4993 nedit -xrm "nedit.openInTab: False" -xrm "nedit.tabBarHideOne: True" 4994 This will affect your default settings for the session, and will be saved 4995 if Preferences->Save Defaults... is used, which may not be desired. 4996 4997 **-group** 4998 Open all subsequent files as tabs in a new window. 4999 5000 **-xrm resourcestring** 5001 Set the value of an X resource to override a default 5002 value (see "Customizing_XNEdit_"). 5003 5004 **-svrname name** 5005 When starting XNEdit in server mode, name the server, such that it responds to 5006 requests only when xnc is given a corresponding -svrname argument. By naming 5007 servers, you can run several simultaneously, and direct files and commands 5008 specifically to any one. Specifying a non-empty name automatically designates 5009 this session as an XNEdit server, as though -server were specified. 5010 5011 **-import file** 5012 Loads an additional preferences file on top of the existing defaults saved in 5013 your preferences file. To incorporate macros, language modes, and highlight 5014 patterns and styles written by other users, run XNEdit with -import <file>, 5015 then re-save your preferences file with Preferences -> Save Defaults. 5016 5017 **-bgrun** 5018 Run xnedit in a background process 5019 5020 **-version** 5021 Prints out the XNEdit version information. The -V option is synonymous. 5022 5023 **-help** 5024 Prints out the XNEdit command line help. The -h option is synonymous. 5025 5026 **--** 5027 Treats all subsequent arguments as file names, even if they start with a 5028 dash. This is so XNEdit can access files that begin with the dash character. 5029 5030 .. ? help~ 5031 !!#else 5032 .. 5033 .. This documentation for VMS XNEdit usage should only appear in the 5034 .. generated help code, not in any of the printed documentation. 5035 .. Reasoning is that VMS usage is diminishing and there is a desire 5036 .. to not clutter up the printed documentation here. 5037 .. 5038 NEDIT [filespec[,...]] 5039 5040 The following qualifiers are accepted: 5041 5042 **/read** 5043 Open the file Read Only regardless of the actual file protection. 5044 5045 **/create** 5046 Don't warn about file creation when a file doesn't exist. 5047 5048 **/line=n** 5049 Go to line #n 5050 5051 **/server** 5052 Designate this session as an XNEdit server for processing commands from the xnc 5053 program. The xnc program can be used to interface XNEdit to code development 5054 environments, mailers, etc., or just as a quick way to open files from the 5055 shell command line without starting a new XNEdit session. 5056 5057 **/do=command** 5058 Execute an XNEdit action routine. on each file following the /do argument on 5059 the command line. /do is particularly useful from the xnc program, where xnc 5060 /do can remotely execute commands in an xnedit /server session. 5061 5062 **/tags=file** 5063 Load a file of directions for finding definitions of program subroutines and 5064 data objects. The file must be of the format generated by the Unix ctags 5065 command. 5066 5067 **/wrap, /nowrap** 5068 Wrap long lines at the right edge of the window rather than continuing them 5069 past it. (Continuous Wrap mode) 5070 5071 **/autowrap, /noautowrap** 5072 Wrap long lines when the cursor reaches the right edge of the window by 5073 inserting newlines at word boundaries. (Auto Newline Wrap mode) 5074 5075 **/autoindent, /noautoindent** 5076 Maintain a running indent. 5077 5078 **/autosave, /noautosave** 5079 Maintain a backup copy of the file being edited under the name '_filename'. 5080 5081 **/rows=n** 5082 Default width in characters for an editing window. 5083 5084 **/columns=n** 5085 Default height in characters for an editing window. 5086 5087 **/font=font (or /fn=font)** 5088 Font for text being edited (Font for menus and dialogs can be set with 5089 /xrm="*fontList:font"). 5090 5091 **/display [host]:server[.screen]** 5092 The name of the X server to use. host specifies the machine, server 5093 specifies the display server number, and screen specifies the screen number. 5094 host or screen can be omitted and default to the local machine, and screen 0. 5095 5096 **/geometry=geometry (or /g=geometry)** 5097 The initial size and/or location of editor windows. The argument geometry 5098 has the form: 5099 5100 [<width>x<height>][+|-][<xoffset>[+|-]<yoffset>] 5101 5102 where <width> and <height> are the desired width and height of the window, 5103 and <xoffset> and <yoffset> are the distance from the edge of the screen to 5104 the window, + for top or left, - for bottom or right. 5105 5106 **/background=color (or /bg=color)** 5107 5108 Background color. (background color for text can be set separately with 5109 /xrm="nedit:textBgColor color" or using the Preferences -> 5110 Colors dialog). 5111 5112 **/foreground=color (or /fg=color)** 5113 Foreground color. (foreground color for text can be set separately with 5114 /xrm="nedit:textFgColor color" or using the Preferences -> 5115 Colors dialog). 5116 5117 **/tabbed** 5118 Open all subsequent files in new tabs. Resets /group option. 5119 5120 **/untabbed** 5121 Open all subsequent files in new windows. Resets /group option. 5122 5123 **/group** 5124 Open all subsequent files as tabs in a new window. 5125 5126 **/xrm=resourcestring** 5127 Set the value of an X resource to override a default value 5128 (see Customizing XNEdit). 5129 5130 **/svrname=name** 5131 When starting xnedit in server mode, name the server, such that it responds to 5132 requests only when xnc is given a corresponding -svrname argument. By naming 5133 servers, you can run several simultaneously, and direct files and commands 5134 specifically to any one. 5135 5136 **/import=file** 5137 Loads an additional preferences file on top of the existing defaults saved in 5138 your .nedit file. To incorporate macros, language modes, and highlight 5139 patterns and styles written by other users, run nedit with /import=<file>, 5140 then re-save your .nedit file with Preferences -> Save Defaults. 5141 5142 Unix-style command lines (but not file names) are also acceptable: 5143 5144 nedit -rows 20 -wrap file1.c file2.c 5145 5146 is equivalent to: 5147 5148 nedit /rows=20/wrap file1.c, file2.c", 5149 !!#endif /* VMS */ 5150 .. ~ help 5151 ---------------------------------------------------------------------- 5152 5153 Client/Server Mode 5154 ------------------ 5155 5156 XNEdit can be operated on its own, or as a two-part client/server 5157 application. Client/server mode is useful for integrating XNEdit with 5158 software development environments, mailers, and other programs; or just as a 5159 quick way to open files from the shell command line without starting a new 5160 XNEdit session. 5161 5162 To run XNEdit in server mode, type: 5163 5164 xnedit -server 5165 5166 XNEdit can also be started in server mode via the XNEdit Client program 5167 (**xnc**) when no servers are available. 5168 5169 The xnc program, which is distributed along with XNEdit, sends commands to 5170 an XNEdit server to open files or execute editor actions. It can also be 5171 used on files that are already opened. 5172 5173 Listing a file on the xnc command line means: Open it if it is not already 5174 open and bring the window to the front. 5175 5176 5177 xnc supports the following command line options: 5178 5179 **xnc** [**-read**] [**-create**] 5180 [**-line** n | **+**n] [**-do** command] [**-lm** languagemode] 5181 [**-svrname** name] [**-svrcmd** command] 5182 [**-ask**] [**-noask**] [**-timeout** seconds] 5183 [**-geometry** geometry | **-g** geometry] [**-icon** | **-iconic**] 5184 [-**tabbed**] [-**untabbed**] [-**group**] [**-wait**] 5185 [**-V** | **-version**] 5186 [**-xrm** resourcestring] [**-display** [host]:server[.screen]] 5187 [**-**-] [file...] 5188 5189 **-read** 5190 Open the file read-only regardless of its actual permissions. There is no 5191 effect if the file is already open. 5192 5193 **-create** 5194 Don't warn about file creation when a file doesn't exist. 5195 5196 **-line** n, **+**n 5197 Go to line number n. This will also affect files which are already open. 5198 5199 **-do** command 5200 Execute an XNEdit macro or action on the file following the -do argument 5201 on the command line. 5202 5203 If you use this command without a filename, xnc would randomly choose one 5204 window to focus and execute the macro in. 5205 5206 **-lm** languagemode 5207 Initial language mode used. 5208 5209 **-svrname** name 5210 Explicitly instructs xnc which server to connect to, an instance of 5211 xnedit(1) with a corresponding -svrname argument. By naming servers, you 5212 can run several simultaneously, and direct files and commands 5213 specifically to any one. 5214 5215 **-svrcmd** command 5216 The command which xnc uses to start an XNEdit server. It is also settable 5217 via the X resource `nc.serverCommand' (see X_Resources_). Defaults to 5218 "xnedit -server". 5219 5220 **-ask**, **-noask** 5221 Instructs xnc to automatically start a server if one is not available. This 5222 overrides the X resource `nc.autoStart' (see X_Resources_). 5223 5224 **-timeout** seconds 5225 Basic time-out period used in communication with an XNEdit server. The 5226 default is 10 seconds. Also settable via the X resource `nc.timeOut'. 5227 5228 Under rare conditions (such as a slow connection), it may be necessary to 5229 increase the time-out period. In most cases, the default is fine. 5230 5231 **-geometry** geometry, **-g** geometry 5232 The initial size and/or location of editor windows. See 5233 XNEdit_Command_Line_ for details. 5234 5235 **-icon**, **-iconic** 5236 Initial window state. 5237 5238 **-tabbed** 5239 Open all subsequent files in new tabs. Resets -group option. 5240 5241 **-untabbed** 5242 Open all subsequent files in new windows. Resets -group option. 5243 5244 **-group** 5245 Open all subsequent files as tabs in a new window. 5246 5247 **-wait** 5248 Instructs xnc not to return to the shell until all files given are closed. 5249 5250 Normally, xnc returns once the files given in its command line are opened 5251 by the server. When this option is given, xnc returns only after the last 5252 file given in this call is closed. 5253 5254 Note that this option affects all files in the command line, not only the 5255 ones following this option. 5256 5257 Note that xnc will wait for all files given in the command line, even if 5258 the files were already opened. 5259 5260 **-version**, **-V** 5261 Prints xnc's version and build information. 5262 5263 **-xrm** resourcestring 5264 Contains the resourcestring passed to a newly started server. This option 5265 has no effect if the server is already started. 5266 5267 **-display** [<host>]:<server>[.<screen>] 5268 The name of the X server to use. See XNEdit_Command_Line_ for details. 5269 5270 5271 4>Command Line Arguments 5272 5273 In typical Unix style, arguments affect the files which follow them on the 5274 command line, for example: 5275 5276 incorrect: xnc file.c -line 25 5277 correct: xnc -line 25 file.c 5278 5279 -read, -create, and -line affect all of the files which follow them on the 5280 command line. 5281 5282 The -do macro is executed only once, on the next file on the line. -do 5283 without a file following it on the command line, executes the macro on the 5284 first available window (presumably when you give a -do command without a 5285 corresponding file or window, you intend it to do something independent of 5286 the window in which it happens to execute). 5287 5288 The -wait option affects all files named in the command line. 5289 5290 4>Multiple Servers 5291 5292 Sometimes it is useful to have more than one XNEdit server running, for 5293 example to keep mail and programming work separate. The option, -svrname, to 5294 both xnedit and xnc, allows you to start, and communicate with, separate named 5295 servers. A named server responds only to requests with the corresponding 5296 -svrname argument. If you use ClearCase and are within a ClearCase view, the 5297 server name will default to the name of the view (based on the value of the 5298 CLEARCASE_ROOT environment variable). 5299 5300 4>Communication 5301 5302 Communication between xnc and xnedit is done through the X display. So as long 5303 as the X Window System is set up and working properly, xnc will work properly 5304 as well. xnc uses the DISPLAY environment variable, the machine name and your 5305 user name to find the appropriate server, meaning, if you have several 5306 machines sharing a common file system, xnc will not be able to find a server 5307 that is running on a machine with a different host name, even though it may 5308 be perfectly appropriate for editing a given file. 5309 5310 The command which xnc uses to start an xnedit server is settable via the X 5311 resource nc.serverCommand, by default, "xnedit -server". 5312 ---------------------------------------------------------------------- 5313 5314 Crash Recovery 5315 -------------- 5316 5317 If a system crash, network failure, X server crash, or program error should 5318 happen while you are editing a file, you can still recover most of your 5319 work. XNEdit maintains a backup file which it updates periodically (every 8 5320 editing operations or 80 characters typed). This file has the same name 5321 as the file that you are editing, but with the character `~' (tilde) on Unix 5322 or `_' (underscore) on VMS prefixed to the name. To recover a file after a 5323 crash, simply rename the file to remove the tilde or underscore character, 5324 replacing the older version of the file. (Because several of the Unix shells 5325 consider the tilde to be a special character, you may have to prefix the 5326 character with a `\' (backslash) when you move or delete an XNEdit backup 5327 file.) 5328 5329 Example, to recover the file called "help.c" on Unix type the command: 5330 5331 mv \~help.c help.c 5332 5333 A minor caveat, is that if the file you were editing was in MS DOS format, 5334 the backup file will be in Unix format, and you will need to open the backup 5335 file in XNEdit and change the file format back to MS DOS via the Save As... 5336 dialog (or use the Unix unix2dos command outside of XNEdit). 5337 ---------------------------------------------------------------------- 5338 5339 Version 5340 ------- 5341 .. ! help~ 5342 5343 |>version<| 5344 |>date<| 5345 5346 .. ~ help 5347 .. 5348 .. There is build time versioning information that is handled specially 5349 .. inside help.c for this section. It needs to have a '%s' string 5350 .. made available for it to appear in the on-line help. 5351 .. 5352 .. ? help %s 5353 .. 5354 .. ====================================================================== 5355 .. The policy for credit so far is this: 5356 .. 5357 .. You get "written by" credit if you have CVS commit privileges, and you 5358 .. participated in the current release. 5359 .. 5360 .. You will be "retired" once we realize you haven't been around for a 5361 .. while... please come back someday and be active again! 5362 .. 5363 .. The order is alphabetical, not political or time-ordered. The list 5364 .. of patch authors is too large to include here, and we probably won't 5365 .. get it right unless they are diligent about adding credits to the 5366 .. contributed files. 5367 .. 5368 .. You get a syntax/indent credit if your pattern is compiled into the 5369 .. binary. 5370 .. ====================================================================== 5371 5372 XNEdit is based on NEdit 5.7 and developed by Olaf Wintermann. 5373 5374 NEdit developers: Tony Balinski, Arne Førlie, Nathaniel Gray, Eddy De 5375 Greef, Thorsten Haude, Andrew Hood, Scott Tringali, TK Soh, Mark Edel, 5376 Joy Kyriakopulos, Christopher Conrad, Jim Clark, Arnulfo Zepeda-Navratil, 5377 Suresh Ravoor, Max Vohlken, Yunliang Yu, Donna Reid, Steve Haehn, 5378 Steve LoBasso and Alexander Mai. 5379 5380 Additional NEdit patches by: Fredrik Jönsson, Per Grahn. 5381 5382 XNEdit contributions: Laszlo Ersek, Mike Becker, Peter Mühlenpfordt, 5383 Valerio Messina and Jack Zeal. 5384 5385 The regular expression matching routines used in XNEdit are adapted (with 5386 permission) from original code written by Henry Spencer at the 5387 University of Toronto. 5388 5389 The Microline widgets are inherited from the Mozilla project. 5390 5391 Syntax highlighting patterns and smart indent macros were contributed by: 5392 Simon T. MacDonald, Maurice Leysens, Matt Majka, Alfred Smeenk, 5393 Alain Fargues, Christopher Conrad, Scott Markinson, Konrad Bernloehr, 5394 Ivan Herman, Patrice Venant, Christian Denat, Philippe Couton, 5395 Max Vohlken, Markus Schwarzenberg, Himanshu Gohel, Steven C. Kapp, 5396 Michael Turomsha, John Fieber, Chris Ross, Nathaniel Gray, Joachim Lous, 5397 Mike Duigou, Seak Teng-Fong, Joor Loohuis, Mark Jones and 5398 Niek van den Berg. 5399 5400 XNEdit sources, executables, additional documentation, and contributed 5401 software are available from the XNEdit web site at 5402 https://www.unixwork.de/xnedit/. 5403 5404 This program is free software; you can redistribute it and/or 5405 modify it under the terms of the GNU General Public License 5406 as published by the Free Software Foundation; either version 2 5407 of the License, or (at your option) any later version. 5408 5409 In addition, as a special exception to the GNU GPL, the copyright holders 5410 give permission to link the code of this program with the Motif and Open 5411 Motif libraries (or with modified versions of these that use the same 5412 license), and distribute linked combinations including the two. You must 5413 obey the GNU General Public License in all respects for all of the code 5414 used other than linking with Motif/Open Motif. If you modify this file, 5415 you may extend this exception to your version of the file, but you are 5416 not obligated to do so. If you do not wish to do so, delete this 5417 exception statement from your version. 5418 5419 This program is distributed in the hope that it will be useful, 5420 but WITHOUT ANY WARRANTY; without even the implied warranty of 5421 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 5422 section on the License_ for more details. 5423 ---------------------------------------------------------------------- 5424 5425 License 5426 ------------------- 5427 5428 NEdit License 5429 5430 GNU GENERAL PUBLIC LICENSE 5431 5432 Version 2, June 1991 5433 5434 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 675 Mass Ave, 5435 Cambridge, MA 02139, USA. Everyone is permitted to copy and distribute verbatim 5436 copies of this license document, but changing it is not allowed. 5437 5438 Preamble 5439 5440 The licenses for most software are designed to take away your freedom to share 5441 and change it. By contrast, the GNU General Public License is intended to 5442 guarantee your freedom to share and change free software--to make sure the 5443 software is free for all its users. This General Public License applies to most 5444 of the Free Software Foundation's software and to any other program whose 5445 authors commit to using it. (Some other Free Software Foundation software is 5446 covered by the GNU Library General Public License instead.) You can apply it to 5447 your programs, too. 5448 5449 When we speak of free software, we are referring to freedom, not price. Our 5450 General Public Licenses are designed to make sure that you have the freedom to 5451 distribute copies of free software (and charge for this service if you wish), 5452 that you receive source code or can get it if you want it, that you can change 5453 the software or use pieces of it in new free programs; and that you know you 5454 can do these things. 5455 5456 To protect your rights, we need to make restrictions that forbid anyone to deny 5457 you these rights or to ask you to surrender the rights. These restrictions 5458 translate to certain responsibilities for you if you distribute copies of the 5459 software, or if you modify it. 5460 5461 For example, if you distribute copies of such a program, whether gratis or for 5462 a fee, you must give the recipients all the rights that you have. You must make 5463 sure that they, too, receive or can get the source code. And you must show them 5464 these terms so they know their rights. 5465 5466 We protect your rights with two steps: (1) copyright the software, and (2) 5467 offer you this license which gives you legal permission to copy, distribute 5468 and/or modify the software. 5469 5470 Also, for each author's protection and ours, we want to make certain that 5471 everyone understands that there is no warranty for this free software. If the 5472 software is modified by someone else and passed on, we want its recipients to 5473 know that what they have is not the original, so that any problems introduced 5474 by others will not reflect on the original authors' reputations. 5475 5476 Finally, any free program is threatened constantly by software patents. We wish 5477 to avoid the danger that redistributors of a free program will individually 5478 obtain patent licenses, in effect making the program proprietary. To prevent 5479 this, we have made it clear that any patent must be licensed for everyone's 5480 free use or not licensed at all. 5481 5482 The precise terms and conditions for copying, distribution and modification 5483 follow. 5484 5485 GNU GENERAL PUBLIC LICENSE 5486 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 5487 5488 0. This License applies to any program or other work which contains a notice 5489 placed by the copyright holder saying it may be distributed under the terms of 5490 this General Public License. The "Program", below, refers to any such program 5491 or work, and a "work based on the Program" means either the Program or any 5492 derivative work under copyright law: that is to say, a work containing the 5493 Program or a portion of it, either verbatim or with modifications and/or 5494 translated into another language. (Hereinafter, translation is included without 5495 limitation in the term "modification".) Each licensee is addressed as "you". 5496 5497 Activities other than copying, distribution and modification are not covered by 5498 this License; they are outside its scope. The act of running the Program is not 5499 restricted, and the output from the Program is covered only if its contents 5500 constitute a work based on the Program (independent of having been made by 5501 running the Program). Whether that is true depends on what the Program does. 5502 5503 1. You may copy and distribute verbatim copies of the Program's source code as 5504 you receive it, in any medium, provided that you conspicuously and 5505 appropriately publish on each copy an appropriate copyright notice and 5506 disclaimer of warranty; keep intact all the notices that refer to this License 5507 and to the absence of any warranty; and give any other recipients of the 5508 Program a copy of this License along with the Program. 5509 5510 You may charge a fee for the physical act of transferring a copy, and you may 5511 at your option offer warranty protection in exchange for a fee. 5512 5513 2. You may modify your copy or copies of the Program or any portion of it, thus 5514 forming a work based on the Program, and copy and distribute such modifications 5515 or work under the terms of Section 1 above, provided that you also meet all of 5516 these conditions: 5517 5518 a) You must cause the modified files to carry prominent notices stating that 5519 you changed the files and the date of any change. 5520 5521 b) You must cause any work that you distribute or publish, that in whole or in 5522 part contains or is derived from the Program or any part thereof, to be 5523 licensed as a whole at no charge to all third parties under the terms of this 5524 License. 5525 5526 c) If the modified program normally reads commands interactively when run, you 5527 must cause it, when started running for such interactive use in the most 5528 ordinary way, to print or display an announcement including an appropriate 5529 copyright notice and a notice that there is no warranty (or else, saying that 5530 you provide a warranty) and that users may redistribute the program under these 5531 conditions, and telling the user how to view a copy of this License. 5532 (Exception: if the Program itself is interactive but does not normally print 5533 such an announcement, your work based on the Program is not required to print 5534 an announcement.) 5535 5536 These requirements apply to the modified work as a whole. If identifiable 5537 sections of that work are not derived from the Program, and can be reasonably 5538 considered independent and separate works in themselves, then this License, and 5539 its terms, do not apply to those sections when you distribute them as separate 5540 works. But when you distribute the same sections as part of a whole which is a 5541 work based on the Program, the distribution of the whole must be on the terms 5542 of this License, whose permissions for other licensees extend to the entire 5543 whole, and thus to each and every part regardless of who wrote it. 5544 5545 Thus, it is not the intent of this section to claim rights or contest your 5546 rights to work written entirely by you; rather, the intent is to exercise the 5547 right to control the distribution of derivative or collective works based on 5548 the Program. 5549 5550 In addition, mere aggregation of another work not based on the Program with the 5551 Program (or with a work based on the Program) on a volume of a storage or 5552 distribution medium does not bring the other work under the scope of this 5553 License. 5554 5555 3. You may copy and distribute the Program (or a work based on it, under 5556 Section 2) in object code or executable form under the terms of Sections 1 and 5557 2 above provided that you also do one of the following: 5558 5559 a) Accompany it with the complete corresponding machine-readable source code, 5560 which must be distributed under the terms of Sections 1 and 2 above on a medium 5561 customarily used for software interchange; or, 5562 5563 b) Accompany it with a written offer, valid for at least three years, to give 5564 any third party, for a charge no more than your cost of physically performing 5565 source distribution, a complete machine-readable copy of the corresponding 5566 source code, to be distributed under the terms of Sections 1 and 2 above on a 5567 medium customarily used for software interchange; or, 5568 5569 c) Accompany it with the information you received as to the offer to distribute 5570 corresponding source code. (This alternative is allowed only for noncommercial 5571 distribution and only if you received the program in object code or executable 5572 form with such an offer, in accord with Subsection b above.) 5573 5574 The source code for a work means the preferred form of the work for making 5575 modifications to it. For an executable work, complete source code means all the 5576 source code for all modules it contains, plus any associated interface 5577 definition files, plus the scripts used to control compilation and installation 5578 of the executable. However, as a special exception, the source code distributed 5579 need not include anything that is normally distributed (in either source or 5580 binary form) with the major components (compiler, kernel, and so on) of the 5581 operating system on which the executable runs, unless that component itself 5582 accompanies the executable. 5583 5584 If distribution of executable or object code is made by offering access to copy 5585 from a designated place, then offering equivalent access to copy the source 5586 code from the same place counts as distribution of the source code, even though 5587 third parties are not compelled to copy the source along with the object code. 5588 5589 4. You may not copy, modify, sublicense, or distribute the Program except as 5590 expressly provided under this License. Any attempt otherwise to copy, modify, 5591 sublicense or distribute the Program is void, and will automatically terminate 5592 your rights under this License. However, parties who have received copies, or 5593 rights, from you under this License will not have their licenses terminated so 5594 long as such parties remain in full compliance. 5595 5596 5. You are not required to accept this License, since you have not signed it. 5597 However, nothing else grants you permission to modify or distribute the Program 5598 or its derivative works. These actions are prohibited by law if you do not 5599 accept this License. Therefore, by modifying or distributing the Program (or 5600 any work based on the Program), you indicate your acceptance of this License to 5601 do so, and all its terms and conditions for copying, distributing or modifying 5602 the Program or works based on it. 5603 5604 6. Each time you redistribute the Program (or any work based on the Program), 5605 the recipient automatically receives a license from the original licensor to 5606 copy, distribute or modify the Program subject to these terms and conditions. 5607 You may not impose any further restrictions on the recipients' exercise of the 5608 rights granted herein. You are not responsible for enforcing compliance by 5609 third parties to this License. 5610 5611 7. If, as a consequence of a court judgment or allegation of patent 5612 infringement or for any other reason (not limited to patent issues), conditions 5613 are imposed on you (whether by court order, agreement or otherwise) that 5614 contradict the conditions of this License, they do not excuse you from the 5615 conditions of this License. If you cannot distribute so as to satisfy 5616 simultaneously your obligations under this License and any other pertinent 5617 obligations, then as a consequence you may not distribute the Program at all. 5618 For example, if a patent license would not permit royalty-free redistribution 5619 of the Program by all those who receive copies directly or indirectly through 5620 you, then the only way you could satisfy both it and this License would be to 5621 refrain entirely from distribution of the Program. 5622 5623 If any portion of this section is held invalid or unenforceable under any 5624 particular circumstance, the balance of the section is intended to apply and 5625 the section as a whole is intended to apply in other circumstances. 5626 5627 It is not the purpose of this section to induce you to infringe any patents or 5628 other property right claims or to contest validity of any such claims; this 5629 section has the sole purpose of protecting the integrity of the free software 5630 distribution system, which is implemented by public license practices. Many 5631 people have made generous contributions to the wide range of software 5632 distributed through that system in reliance on consistent application of that 5633 system; it is up to the author/donor to decide if he or she is willing to 5634 distribute software through any other system and a licensee cannot impose that 5635 choice. 5636 5637 This section is intended to make thoroughly clear what is believed to be a 5638 consequence of the rest of this License. 5639 5640 8. If the distribution and/or use of the Program is restricted in certain 5641 countries either by patents or by copyrighted interfaces, the original 5642 copyright holder who places the Program under this License may add an explicit 5643 geographical distribution limitation excluding those countries, so that 5644 distribution is permitted only in or among countries not thus excluded. In such 5645 case, this License incorporates the limitation as if written in the body of 5646 this License. 5647 5648 9. The Free Software Foundation may publish revised and/or new versions of the 5649 General Public License from time to time. Such new versions will be similar in 5650 spirit to the present version, but may differ in detail to address new problems 5651 or concerns. 5652 5653 Each version is given a distinguishing version number. If the Program specifies 5654 a version number of this License which applies to it and "any later version", 5655 you have the option of following the terms and conditions either of that 5656 version or of any later version published by the Free Software Foundation. If 5657 the Program does not specify a version number of this License, you may choose 5658 any version ever published by the Free Software Foundation. 5659 5660 10. If you wish to incorporate parts of the Program into other free programs 5661 whose distribution conditions are different, write to the author to ask for 5662 permission. For software which is copyrighted by the Free Software Foundation, 5663 write to the Free Software Foundation; we sometimes make exceptions for this. 5664 Our decision will be guided by the two goals of preserving the free status of 5665 all derivatives of our free software and of promoting the sharing and reuse of 5666 software generally. 5667 5668 NO WARRANTY 5669 5670 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR 5671 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE 5672 STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE 5673 PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 5674 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 5675 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND 5676 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, 5677 YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 5678 5679 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL 5680 ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE 5681 THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 5682 GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE 5683 OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR 5684 DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR 5685 A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH 5686 HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 5687 5688 END OF TERMS AND CONDITIONS 5689 5690 Addition 5691 5692 In addition, as a special exception to the GNU GPL, the copyright holders give 5693 permission to link the code of this program with the Motif and Open Motif 5694 libraries (or with modified versions of these that use the same license), and 5695 distribute linked combinations including the two. You must obey the GNU General 5696 Public License in all respects for all of the code used other than linking with 5697 Motif/Open Motif. If you modify this file, you may extend this exception to your 5698 version of the file, but you are not obligated to do so. If you do not wish to 5699 do so, delete this exception statement from your version. 5700 5701 5702 Additional XNEdit LICENSE 5703 5704 Copyright 2019 Olaf Wintermann 5705 5706 Permission is hereby granted, free of charge, to any person obtaining a copy 5707 of this software and associated documentation files (the "Software"), to deal 5708 in the Software without restriction, including without limitation the rights 5709 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 5710 copies of the Software, and to permit persons to whom the Software is 5711 furnished to do so, subject to the following conditions: 5712 5713 The above copyright notice and this permission notice shall be included in all 5714 copies or substantial portions of the Software. 5715 5716 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 5717 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 5718 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 5719 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 5720 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 5721 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 5722 SOFTWARE. 5723 5724 5725 5726 OCaml Syntax Highlighting 5727 5728 Copyright (C) 2021, Red Hat, Inc. 5729 GPL-2.0-only 5730 5731 5732 EditorConfig glob matching 5733 5734 Copyright 2024 Mike Becker - All rights reserved. 5735 5736 Redistribution and use in source and binary forms, with or without 5737 modification, are permitted provided that the following conditions are met: 5738 5739 1. Redistributions of source code must retain the above copyright 5740 notice, this list of conditions and the following disclaimer. 5741 5742 2. Redistributions in binary form must reproduce the above copyright 5743 notice, this list of conditions and the following disclaimer in the 5744 documentation and/or other materials provided with the distribution. 5745 5746 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 5747 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 5748 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 5749 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 5750 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 5751 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 5752 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 5753 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 5754 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 5755 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 5756 POSSIBILITY OF SUCH DAMAGE. 5757 5758 5759 Support 5760 ------------- 5761 5762 For questions or general discussions, please refer to the forum at SourceForge: 5763 5764 https://sourceforge.net/p/xnedit/discussion/general/ 5765 5766 Bug reports and feature requests can be done at at GitHub or SourceForge. 5767 5768 https://github.com/unixwork/xnedit/issues 5769 5770 https://sourceforge.net/projects/xnedit/ 5771 5772 5773 Problems/Defects 5774 ---------------- 5775 5776 3>Solutions to Common Problems 5777 5778 For a much more comprehensive list of common problems and solutions, see the 5779 XNEdit FAQ. The latest version of the FAQ can always be found on the XNEdit 5780 web site at: 5781 5782 https://www.unixwork.de/xnedit/_. 5783 5784 **P: No files are shown in the "Files" list in the Open... dialog.** 5785 5786 S: When you use the "Filter" field, include the file specification or a 5787 complete directory specification, including the trailing "/" on Unix. 5788 (See Help in the Open... dialog). 5789 5790 **P: Find Again and Replace Again don't continue in the same direction as the original Find or Replace.** 5791 5792 S: Find Again and Replace Again don't use the direction of the original 5793 search. The Shift key controls the direction: Ctrl+G means forward, 5794 Shift+Ctrl+G means backward. 5795 5796 **P: Preferences specified in the Preferences menu don't seem to get saved when I select Save Defaults.** 5797 5798 S: XNEdit has two kinds of preferences: 1) per-window preferences, in the 5799 Preferences menu, and 2) default settings for preferences in newly created 5800 windows, in the Default Settings sub-menu of the Preferences menu. 5801 Per-window preferences are not saved by Save Defaults, only Default 5802 Settings. 5803 5804 **P: Columns and indentation don't line up.** 5805 5806 S: XNEdit is using a proportional width font. Set the font to a fixed style 5807 (see Preferences menu). 5808 5809 **P: XNEdit performs poorly on very large files.** 5810 5811 S: Turn off Incremental Backup. With Incremental Backup on, XNEdit 5812 periodically writes a full copy of the file to disk. 5813 5814 **P: Commands added to the Shell Commands menu (Unix only) don't output anything until they are finished executing.** 5815 5816 S: If the command output is directed to a dialog, or the input is from a 5817 selection, output is collected together and held until the command 5818 completes. De-select both of the options and the output will be shown 5819 incrementally as the command executes. 5820 5821 **P: Dialogs don't automatically get keyboard focus when they pop up.** 5822 5823 S: Most X Window managers allow you to choose between two categories of 5824 keyboard focus models: pointer focus, and explicit focus. Pointer focus 5825 means that as you move the mouse around the screen, the window under the 5826 mouse automatically gets the keyboard focus. XNEdit users who use this 5827 focus model should set "Popups Under Pointer" in the Default Settings sub 5828 menu of the preferences menu in XNEdit. Users with the explicit focus 5829 model, in some cases, may have problems with certain dialogs, such as Find 5830 and Replace. In MWM this is caused by the mwm resource startupKeyFocus 5831 being set to False (generally a bad choice for explicit focus users). 5832 NCDwm users should use the focus model "click" instead of "explicit", 5833 again, unless you have set it that way to correct specific problems, this 5834 is the appropriate setting for most explicit focus users. 5835 5836 **P: The Backspace key doesn't work, or deletes forward rather than backward.** 5837 5838 S: While this is an X/Motif binding problem, and should be solved outside of 5839 XNEdit in the Motif virtual binding layer (or possibly xmodmap or 5840 translations), XNEdit provides an out. If you set the resource: 5841 nedit.remapDeleteKey to True, XNEdit will forcibly map the delete key to 5842 backspace. The default setting of this resource recently changed, so 5843 users who have been depending on this remapping will now have to set it 5844 explicitly (or fix their bindings). 5845 5846 **P: XNEdit crashes when I try to paste text in to a text field in a dialog (like Find or Replace) on my SunOS system.** 5847 5848 S: On many SunOS systems, you have to set up an nls directory before various 5849 inter-client communication features of Motif will function properly. 5850 There are instructions in README.sun in /pub/v5_0_2/individual/README.sun on 5851 ftp.nedit.org, as well as a tar file containing a complete nls 5852 directory: ftp://ftp.nedit.org/pub/v5_0_2/nls.tar. 5853 README.sun contains directions for setting up an nls directory, which 5854 is required by Motif for handling copy and paste to Motif text fields. 5855 5856 3>Known Defects 5857 5858 Below is the list of known defects which affect XNEdit. The defects your copy 5859 of XNEdit will exhibit depend on which system you are running and with which 5860 Motif libraries it was built. Note that there are now Motif 1.2 and/or 2.0 5861 libraries available on ALL supported platforms, and as you can see below 5862 there are far fewer defects in Motif 1.2, so it is in your best interest to 5863 upgrade your system. 5864 5865 4>All Versions 5866 5867 **DEFECT** 5868 Operations between rectangular selections on overlapping lines do nothing. 5869 5870 ~Work Around~ 5871 None. These operations are very complicated and rarely used. 5872 5873 **DEFECT** 5874 Cut and Paste menu items fail, or possibly crash, 5875 for very large (multi-megabyte) selections. 5876 5877 ~Work Around~ 5878 Use selection copy (middle mouse button click) 5879 for transferring larger quantities of data. 5880 Cut and Paste save the copied text in server 5881 memory, which is usually limited. 5882 5883 3>Reporting Defects 5884 5885 Submit bugs through the web at: 5886 5887 https://sourceforge.net/p/xnedit/_list/tickets 5888 5889 https://github.com/unixwork/xnedit/issues 5890 5891 Please include the first few lines from Help > Version, which identifies 5892 XNEdit's version and other system attributes important for diagnosing your 5893 problem. 5894 5895 $$ 5896 5897 .. Hyperlinks for this document ============================================== 5898 5899 .. _https://www.unixwork.de/xnedit/ https://www.unixwork.de/xnedit/ 5900 .. _ctags_support #ctags 5901 .. _Alternation #alternation 5902 .. _Autoload_Files #automatically 5903 5904 .. ============================================================================= 5905 5906 .. Below is what is used to guide the generation of 'C'-Motif menus. 5907 .. Indentation is SIGNIFICANT in the "Menu" directive lines below. It 5908 .. is used to determine under which menu element another item will belong. 5909 .. The number of spaces indented is not significant, but items to be placed 5910 .. in the same menu panel MUST line up at the same indent level. 5911 .. ALL nodes of this menu "tree" should have help name qualifiers. 5912 .. These are used to produce the internal lists used by XNEdit help code. 5913 5914 .. By default, the first character of the menu element will be used as a 5915 .. menu mneumonic key. To use another character in the menu element for this 5916 .. purpose, surround the character with underscores (eg. I w_a_nt 'a'). 5917 5918 .. The menu title MUST match the one found in the actual help text (sans 5919 .. special mneumonic key character marking). The help text title may include 5920 .. underlines (for spaces) when it is a hyperlink target. 5921 5922 .. The Help-name is used to generate various data structure names. For 5923 .. instance, the 'start' help name will be used to generate the HelpTopic 5924 .. enumeration value HELP_START and the character array htxt_start which 5925 .. holds the actual help text used in the menu dialogs. Consequently, these 5926 .. names need to be unique and contain only the characters that a 'C' 5927 .. compiler can digest. 5928 5929 .. Menu separator lines use a dash (-) character for the Menu Title. They 5930 .. should also have a unique Help-name. 5931 5932 .. A numerical value following the Help-name (separated from the name by 5933 .. a comma and/or spaces) is part of a menu element hiding scheme implemented 5934 .. in buildHelpMenu (found in 'menu.c'). When the number matches the hideIt 5935 .. value found in the procedure, that element will effectively become invisible. 5936 .. This mechanism was created for particular menu features that are not 5937 .. available to all incarnations of XNEdit (in this case, the VMS version). 5938 5939 .. A "Help" directive is used for all other text used as XNEdit help, but 5940 .. does not show up in the Help menu. 5941 5942 .. Menu Title # Help-name 5943 .. ------------------------------------------------------------ 5944 .. Menu: Getting Started # start 5945 .. Menu: Basic Operation # basicOp 5946 .. Menu: Selecting Text # select 5947 .. Menu: Finding and Replacing Text # search 5948 .. Menu: Cut and Paste # clipboard 5949 .. Menu: Using the Mouse # mouse 5950 .. Menu: Keyboard Shortcuts # keyboard 5951 .. Menu: Multi-cursor Editing # multicursor 5952 .. Menu: S_h_ifting and Filling # fill 5953 .. Menu: Tabbed Editing # interface 5954 .. Menu: F_i_le Format # format 5955 5956 .. Menu: Features for Programming # features 5957 .. Menu: Programming with XNEdit # programmer 5958 .. Menu: Tab Stops/Emulated Tab Stops # tabs 5959 .. Menu: Auto/Smart Indent # indent 5960 .. Menu: Syntax Highlighting # syntax 5961 .. Menu: Finding Declarations (ctags) # tags 5962 .. Menu: Calltips # calltips 5963 5964 .. Menu: Regular Expressions # regex 5965 .. Menu: Basic Regular Expression Syntax # basicSyntax 5966 .. Menu: Metacharacters # escapeSequences 5967 .. Menu: Parenthetical Constructs # parenConstructs 5968 .. Menu: Advanced Topics # advancedTopics 5969 .. Menu: Example Regular Expressions # examples 5970 5971 .. Menu: Macro/Shell Extensions # extensions 5972 .. Menu: Shell Commands and Filters # shell, 1 5973 .. Menu: Input/Output Filters # filters 5974 .. Menu: Learn/Replay # learn 5975 .. Menu: Macro Language # macro_lang 5976 .. Menu: M_a_cro Subroutines # macro_subrs 5977 .. Menu: Rangesets # rangeset 5978 .. Menu: Highlighting Information # hiliteInfo 5979 .. Menu: Action Routines # actions 5980 5981 .. Menu: Customizing # customizing 5982 .. Menu: Customizing XNEdit # customize 5983 .. Menu: Preferences # preferences 5984 .. Menu: X Resources # resources 5985 .. Menu: Key Binding # binding 5986 .. Menu: Highlighting Patterns # patterns 5987 .. Menu: Smart Indent Macros # smart_indent 5988 5989 .. Menu: XNEdit Command Line # command_line 5990 .. Menu: Client/Server Mode # server 5991 .. Menu: Cr_a_sh Recovery # recovery 5992 .. Menu: ---------------------------------- # separator1 5993 .. Menu: Version # version 5994 .. Menu: License # distribution 5995 .. Menu: Support # support 5996 .. Menu: Problems/Defects # defects 5997 .. ------------------------------------------------------------ 5998 .. Help: Tabs Dialog # tabs_dialog 5999 .. Help: Customize Window Title Dialog # custom_title_dialog 6000