usr.bin/ee/ee.1

   1 .\"
   2 .\" $FreeBSD: src/usr.bin/ee/ee.1,v 1.8.2.6 2002/06/20 23:45:45 charnier Exp $
   3 .\"
   4 .Dd August 30, 1995
   5 .Dt EE 1
   6 .Os
   7 .Sh NAME
   8 .Nm ee
   9 .Nd easy editor
  10 .Sh SYNOPSIS
  11 .Nm
  12 .Op Fl  eih
  13 .Op +#
  14 .Op Ar
  15 .Nm ree
  16 .Op Fl eih
  17 .Op +#
  18 .Op Ar
  19 .Sh DESCRIPTION
  20 The
  21 .Nm
  22 utility
  23 is a simple screen oriented text editor.  It is always in text insertion
  24 mode unless there is a prompt at the bottom of the terminal, or a
  25 menu present (in a box in the middle of the terminal).  The
  26 .Nm ree
  27 utility is the same as
  28 .Nm ,
  29 but restricted to editing the named
  30 file (no file operations, or shell escapes are allowed).
  31 .Pp
  32 For
  33 .Nm
  34 to work properly, the environment variable
  35 .Ev TERM
  36 must be set to indicate the type of terminal being used.  For
  37 example, for an
  38 .Tn HP 700/92
  39 terminal, the
  40 .Ev TERM
  41 variable should be set to "70092".  See your System Administrator if
  42 you need more information.
  43 .Pp
  44 The following options are available:
  45 .Bl -tag -width indent
  46 .It Fl e
  47 Turn off expansion of tab character to spaces.
  48 .It Fl i
  49 Turn off display of information window at top of terminal.
  50 .It Fl h
  51 Turn off highlighting of borders of windows and menus (improves
  52 performance on some terminals).
  53 .It Sy +#
  54 Move the cursor to line '#' at startup.
  55 .El
  56 .Ss "Control keys"
  57 To do anything other than insert text, the user must use the control
  58 keys (the
  59 .Li Control
  60 key, represented by a "^",  pressed in conjunction with an
  61 alphabetic key, e.g., ^a) and function keys available on the keyboard
  62 (such as
  63 .Em "Next Page" ,
  64 .Em "Prev Page" ,
  65 arrow keys, etc.).
  66 .Pp
  67 Since not all terminals have function keys,
  68 .Nm
  69 has the basic cursor movement functions assigned to control keys as
  70 well as more intuitive keys on the keyboard when available.  For
  71 instance, to move the cursor up, the user can use the up arrow key,
  72 or
  73 .Em ^u .
  74 .Bl -tag -width indent
  75 .It ^a
  76 Prompt for the decimal value of a character to insert.
  77 .It ^b
  78 Move to the bottom of the text.
  79 .It ^c
  80 Get the prompt for a command.
  81 .It ^d
  82 Move the cursor down.
  83 .It ^e
  84 Prompt for the string to search for.
  85 .It ^f
  86 Undelete the last deleted character.
  87 .It ^g
  88 Move to the beginning of the line.
  89 .It ^h
  90 Backspace.
  91 .It ^i
  92 Tab.
  93 .It ^j
  94 Insert a newline.
  95 .It ^k
  96 Delete the character the cursor is sitting on.
  97 .It ^l
  98 Move the cursor left.
  99 .It ^m
 100 Insert a newline.
 101 .It ^n
 102 Move to the next page.
 103 .It ^o
 104 Move to the end of the line.
 105 .It ^p
 106 Move to the previous page.
 107 .It ^r
 108 Move the cursor to the right.
 109 .It ^t
 110 Move to the top of the text.
 111 .It ^u
 112 Move the cursor up.
 113 .It ^v
 114 Undelete the last deleted word.
 115 .It ^w
 116 Delete the word beginning at the cursor position.
 117 .It ^x
 118 Search.
 119 .It ^y
 120 Delete from the cursor position to the end of line.
 121 .It ^z
 122 Undelete the last deleted line.
 123 .It ^[ (ESC)
 124 Pop up menu.
 125 .El
 126 .Ss "EMACS keys mode"
 127 Since many shells provide an Emacs mode (for cursor movement and other editing
 128 operations), some bindings that may be more useful for people familiar with
 129 those bindings have been provided.  These are accessible via the
 130 .Em settings
 131 menu, or via the initialization file (see below).  The mappings are as follows:
 132 .Bl -tag -width indent
 133 .It ^a
 134 Move to the beginning of the line.
 135 .It ^b
 136 Back 1 character.
 137 .It ^c
 138 Command prompt.
 139 .It ^d
 140 Delete character the cursor is sitting on.
 141 .It ^e
 142 End of line.
 143 .It ^f
 144 Forward 1 character.
 145 .It ^g
 146 Go back 1 page.
 147 .It ^h
 148 Backspace.
 149 .It ^i
 150 Tab.
 151 .It ^j
 152 Undelete last deleted character.
 153 .It ^k
 154 Delete line.
 155 .It ^l
 156 Undelete last deleted line.
 157 .It ^m
 158 Insert a newline.
 159 .It ^n
 160 Move to the next line.
 161 .It ^o
 162 Prompt for the decimal value of a character to insert.
 163 .It ^p
 164 Previous line.
 165 .It ^r
 166 Restore last deleted word.
 167 .It ^t
 168 Move to the top of the text.
 169 .It ^u
 170 Move to the bottom of the text.
 171 .It ^v
 172 Move to the next page.
 173 .It ^w
 174 Delete the word beginning at the cursor position.
 175 .It ^y
 176 Prompt for the string to search for.
 177 .It ^z
 178 Next word.
 179 .It ^[ (ESC)
 180 Pop up menu.
 181 .El
 182 .Ss "Function Keys"
 183 .Bl -tag -width indent
 184 .It Next Page
 185 Move to the next page.
 186 .It Prev Page
 187 Move to the previous page.
 188 .It Delete Char
 189 Delete the character the cursor is on.
 190 .It Delete Line
 191 Delete from the cursor to the end of line.
 192 .It Insert line
 193 Insert a newline at the cursor position.
 194 .It Arrow keys
 195 Move the cursor in the direction indicated.
 196 .El
 197 .Ss Commands
 198 Some operations require more information than a single keystroke can
 199 provide.  For the most basic operations, there is a menu that can be
 200 obtained by pressing the
 201 .Tn ESC
 202 key.  The same operations, and more can be performed by obtaining the
 203 command prompt (^c) and typing in one of the commands below.
 204 .Bl -tag -width indent
 205 .It ! Ns Ar cmd
 206 Execute
 207 .Ar cmd
 208 in a shell.
 209 .It 0-9
 210 Move to the line indicated.
 211 .It case
 212 Make searches case sensitive.
 213 .It character
 214 Display the ASCII value of the character at the cursor.
 215 .It exit
 216 Save the edited text, and leave the editor.
 217 .It expand
 218 Expand tabs to spaces.
 219 .It file
 220 Print the name of the file.
 221 .It help
 222 Display help screen.
 223 .It line
 224 Display the current line number.
 225 .It nocase
 226 Make searches insensitive to case (the default).
 227 .It noexpand
 228 Don't expand tab to spaces when the TAB key is pressed.
 229 .It quit
 230 Leave the editor without saving changes.
 231 .It read Ar file
 232 Read the named
 233 .Ar file .
 234 .It write Ar file
 235 Write the text to the named
 236 .Ar file .
 237 .El
 238 .Ss "Menu Operations"
 239 Pop-up menus can be obtained by pressing the
 240 .Em escape
 241 key (or
 242 .Em ^[
 243 if no
 244 .Em escape
 245 key is present).  When in the menu, the escape key can be
 246 used to leave the menu without performing any operations.  Use the up and
 247 down arrow keys, or
 248 .Em ^u
 249 for moving up and
 250 .Em ^d
 251 for moving down to move to the desired items in the menu, then press
 252 .Em return
 253 to perform the indicated task.
 254 .Pp
 255 To the left of each menu item is a letter, which if the corresponding
 256 letter is pressed on the keyboard selects that menu entry.
 257 .Pp
 258 The main menu in
 259 .Nm
 260 is as follows:
 261 .Bl -tag -width indent
 262 .It leave editor
 263 If changes have been made, the user will get a menu prompting whether or
 264 not the changes should be saved.
 265 .It help
 266 Display a help screen, with all of the keyboard operations and commands.
 267 .It file operations
 268 Pop up a menu for selecting whether to read a file, write to a file, or
 269 save the current contents of the editor, as well as send the contents of
 270 the editor to a print command (see the section
 271 .Sx "Initializing ee from a file" ) .
 272 .It redraw screen
 273 Provide a means to repaint the screen if the screen has been corrupted.
 274 .It settings
 275 Show the current values of the operating modes, and right margin.  By
 276 pressing return when the cursor is on a particular item, the value can be
 277 changed.  To leave this menu, press the
 278 .Em escape
 279 key. (See
 280 .Sx Modes
 281 below.)
 282 .It search
 283 Pop up a menu in which the user may choose to enter a string to search
 284 for, or search for a string already entered.
 285 .It miscellaneous
 286 Pop up a menu that allows the user to format the current paragraph,
 287 execute a shell command, or check the spelling of the text in the editor.
 288 .El
 289 .Ss "Paragraph Formatting"
 290 Paragraphs are defined for
 291 .Nm
 292 by a block of text bounded by:
 293 .Bl -bullet -width indent
 294 .It
 295 Begin or end of file.
 296 .It
 297 Line with no characters, or only spaces and/or tabs.
 298 .It
 299 Line starting with a period ('.') or right angle bracket ('>').
 300 .El
 301 .Pp
 302 A paragraph may be formatted two ways:  explicitly by choosing the
 303 .Em format paragraph
 304 menu item, or by setting
 305 .Nm
 306 to automatically
 307 format paragraphs.  The automatic mode may be set via a menu, or via the
 308 initialization file.
 309 .Pp
 310 There are three states for text operation in
 311 .Nm :
 312 free-form, margins,
 313 and automatic formatting.
 314 .Pp
 315 "Free-form" is best used for things like programming.  There are no
 316 restrictions on the length of lines, and no formatting takes place.
 317 .Pp
 318 "Margins" allows the user to type in text without having to worry about going
 319 beyond the right margin (the right margin may be set in the
 320 .Em settings
 321 menu, the default is for the margin to be the right edge of the
 322 terminal).  This is the mode that allows the
 323 .Em format paragraph
 324 menu item to work.
 325 .Pp
 326 "Automatic formatting" provides word-processor-like behavior.  The user
 327 may type in text, while
 328 .Nm
 329 will make sure the entire paragraph fits
 330 within the width of the terminal every time the user inserts a space after
 331 typing or deleting text.  Margin observation must also be enabled in order for
 332 automatic formatting to occur.
 333 .Ss Modes
 334 Although
 335 .Nm
 336 is a 'modeless' editor (it is in text insertion mode all the
 337 time), there are modes in some of the things it does.  These include:
 338 .Bl -tag -width indent
 339 .It tab expansion
 340 Tabs may be inserted as a single tab character, or replaced with spaces.
 341 .It case sensitivity
 342 The search operation can be sensitive to whether characters are upper- or
 343 lower-case, or ignore case completely.
 344 .It margins observed
 345 Lines can either be truncated at the right margin, or extend on forever.
 346 .It auto paragraph formatting
 347 While typing in text, the editor can try to keep it looking reasonably well
 348 within the width of the screen.
 349 .It eightbit characters
 350 Toggle whether eight bit characters are displayed as their value in angle
 351 brackets (e.g. "<220>") or as a character.
 352 .It info window
 353 A window showing the keyboard operations that can be performed can be
 354 displayed or not.
 355 .It emacs keys
 356 Control keys may be given bindings similar to emacs, or not.
 357 .It 16 bit characters
 358 Toggles whether sixteen bit characters are handled as one 16-bit quantities or
 359 two 8-bit quantities.  This works primarily with the Chinese Big 5 code set.
 360 .El
 361 .Pp
 362 You may set these modes via the initialization file (see below), or with a
 363 menu (see above).
 364 .Ss "Spell Checking"
 365 There are two ways to have the spelling in the text checked from
 366 .Nm .
 367 One is by the traditional
 368 .Xr spell 1
 369 command, the other is with the
 370 optional
 371 .Xr ispell 1
 372 command.
 373 .Pp
 374 Using
 375 .Nm spell ,
 376 the words that are not recognized will be placed at the top
 377 of the file.  For the
 378 .Nm ispell
 379 option, the file is written to disk,
 380 then
 381 .Nm ispell
 382 run on the file, and the file read back in once
 383 .Nm ispell
 384 has completed making changes to the file.
 385 .Ss "Printing the contents of the editor"
 386 The user may select a menu item which prints the contents of the editor.
 387 The
 388 .Nm
 389 utility pipes the text in the editor to the command specified by the
 390 initialization command
 391 .Em printcommand
 392 (see the section
 393 .Sx Initializing ee from a file
 394 below).  The default is to send the contents to
 395 .Xr lp 1 .
 396 .Pp
 397 Whatever the user assigns to
 398 .Em printcommand
 399 must take input from
 400 standard input.  See your system administrator for more details.
 401 .Ss "Shell operations"
 402 Shell commands can be executed from within
 403 .Nm
 404 by selecting the
 405 .Em shell command
 406 item in the
 407 .Em miscellaneous
 408 menu, or by placing an exclamation mark ("!") before the command to
 409 execute at the
 410 .Em command:
 411 prompt.  Additionally, the user may direct the contents of the edit buffer
 412 out to a shell operation (via a pipe) by using the left angle bracket
 413 (">"), followed by a "!" and the shell command to execute.  The output of
 414 a shell operation can also be directed into the edit buffer by using a
 415 right angle bracket ("<") before the exclamation mark.  These can even be
 416 used together to send output to a shell operation and read back the
 417 results into the editor.  So, if the editor contained a list of words
 418 to be sorted, they could be sorted by typing the following at the command
 419 prompt:
 420 .Dl ><!sort
 421 This would send the contents of the editor to be piped into the
 422 .Xr sort 1
 423 utility and the result would be placed into the edit buffer at the current
 424 cursor location.  The old information would have to be deleted by the user.
 425 .Ss "Initializing ee from a file"
 426 Since different users have different preferences,
 427 .Nm
 428 allows some
 429 slight configurability.  There are three possible locations for an
 430 initialization file for
 431 .Nm :
 432 the file
 433 .Pa /usr/share/misc/init.ee ,
 434 the file
 435 .Pa .init.ee
 436 in the user's home directory, or the file
 437 .Pa .init.ee
 438 in the current directory (if different from the home
 439 directory).  This allows system administrators to set some preferences for
 440 the users on a system-wide basis (for example, the
 441 .Em print
 442 command),
 443 and the user to customize settings for particular directories (like one
 444 for correspondence, and a different directory for programming).
 445 .Pp
 446 The file
 447 .Pa /usr/share/misc/init.ee
 448 is read first, then
 449 .Pa $HOME/.init.ee ,
 450 then
 451 .Pa .init.ee ,
 452 with the settings specified by the
 453 most recent file read taking precedence.
 454 .Pp
 455 The following items may be entered in the initialization file:
 456 .Bl -tag -width indent
 457 .It case
 458 Set searches to be case sensitive.
 459 .It nocase
 460 Set searches to be insensitive to case (default).
 461 .It expand
 462 Cause
 463 .Nm
 464 to expand tabs to spaces (default).
 465 .It noexpand
 466 Cause
 467 .Nm
 468 to insert tabs as a single character.
 469 .It info
 470 A small information window is displayed at the top of the terminal
 471 (default).
 472 .It noinfo
 473 Turn off the display of the information window.
 474 .It margins
 475 Cause
 476 .Nm
 477 to truncate lines at the right margin when the
 478 cursor passes beyond the right margin as set by the user
 479 while text is being inserted
 480 (default).
 481 .It nomargins
 482 Allow lines to extend beyond the right margin.
 483 .It autoformat
 484 Cause
 485 .Nm
 486 to automatically try to format the current paragraph while
 487 text insertion is occurring.
 488 .It noautoformat
 489 Turn off automatic paragraph formatting (default).
 490 .It printcommand
 491 Allow the setting of the print command (default: "lp").
 492 .It rightmargin
 493 The user can select a value for the right margin (the first column on the
 494 screen is zero).
 495 .It highlight
 496 Turn on highlighting of border of information window and menus (default).
 497 .It nohighlight
 498 Turn off highlighting of border of information window and menus.
 499 .It eightbit
 500 Turn on display of eight bit characters.
 501 .It noeightbit
 502 Turn off display of eight bit characters (they are displayed as their decimal
 503 value inside angle brackets, e.g., "<220>").
 504 .It 16bit
 505 Turns on handling of 16-bit characters.
 506 .It no16bit
 507 Turns off handling of 16-bit characters.
 508 .It emacs
 509 Turns on emacs key bindings.
 510 .It noemacs
 511 Turns off emacs key bindings.
 512 .El
 513 .Ss "Save Editor Configuration"
 514 When using this entry from the
 515 .Em settings
 516 menu, the user may choose to save the current configuration of
 517 the editor (see
 518 .Sx Initializing ee from a file
 519 above) to a file named
 520 .Pa .init.ee
 521 in the current directory or the user's home directory.  If a file named
 522 .Pa .init.ee
 523 already exists, it will be renamed
 524 .Pa .init.ee.old .
 525 .Sh CAVEATS
 526 THIS MATERIAL IS PROVIDED "AS IS".  THERE ARE
 527 NO WARRANTIES OF ANY KIND WITH REGARD TO THIS
 528 MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE
 529 IMPLIED WARRANTIES OF MERCHANTABILITY AND
 530 FITNESS FOR A PARTICULAR PURPOSE.  Neither
 531 Hewlett-Packard nor Hugh Mahon shall be liable
 532 for errors contained herein, nor for
 533 incidental or consequential damages in
 534 connection with the furnishing, performance or
 535 use of this material.  Neither Hewlett-Packard
 536 nor Hugh Mahon assumes any responsibility for
 537 the use or reliability of this software or
 538 documentation.  This software and
 539 documentation is totally UNSUPPORTED.  There
 540 is no support contract available.  Hewlett-Packard
 541 has done NO Quality Assurance on ANY
 542 of the program or documentation.  You may find
 543 the quality of the materials inferior to
 544 supported materials.
 545 .Pp
 546 Always make a copy of files that cannot be easily reproduced before
 547 editing.  Save files early, and save often.
 548 .Ss "International Code Set Support"
 549 The
 550 .Nm
 551 utility supports single-byte character code sets (eight-bit clean), or the
 552 Chinese Big-5 code set.  (Other multi-byte code sets may function, but the
 553 reason Big-5 works is that a two-byte character also takes up two columns on
 554 the screen.)
 555 .Sh WARNINGS
 556 The automatic paragraph formatting operation
 557 may be too slow for slower systems.
 558 .Sh FILES
 559 .Bl -tag -width /usr/share/misc/init.ee -compact
 560 .It Pa /usr/share/misc/init.ee
 561 .It Pa $HOME/.init.ee
 562 .It Pa .init.ee
 563 .El
 564 .Sh SEE ALSO
 565 .Xr ispell 1 Pq Pa textproc/ispell ,
 566 .Xr lpr 1 ,
 567 .Xr spell 1 ,
 568 .Xr termcap 5 ,
 569 .Xr terminfo 5 ,
 570 .Xr environ 7
 571 .Sh AUTHORS
 572 The software
 573 .Nm
 574 was developed by
 575 .An Hugh Mahon .
 576 .Pp
 577 This software and documentation contains
 578 proprietary information which is protected by
 579 copyright.  All rights are reserved.
 580 .Pp
 581 Copyright (c) 1990, 1991, 1992, 1993, 1995, 1996 Hugh Mahon.