1This is Info file ../info/emacs, produced by Makeinfo-1.54 from the 2input file emacs.texi. 3 4 5File: emacs, Node: Diary, Next: Appointments, Prev: Other Calendars, Up: Calendar/Diary 6 7The Diary 8========= 9 10 The Emacs diary keeps track of appointments or other events on a 11daily basis, in conjunction with the calendar. To use the diary 12feature, you must first create a "diary file" containing a list of 13events and their dates. Then Emacs can automatically pick out and 14display the events for today, for the immediate future, or for any 15specified date. 16 17 By default, Emacs uses `~/diary' as the diary file. This is the 18same file that the `calendar' utility uses. A sample `~/diary' file is: 19 20 12/22/1988 Twentieth wedding anniversary!! 21 &1/1. Happy New Year! 22 10/22 Ruth's birthday. 23 * 21, *: Payday 24 Tuesday--weekly meeting with grad students at 10am 25 Supowit, Shen, Bitner, and Kapoor to attend. 26 1/13/89 Friday the thirteenth!! 27 &thu 4pm squash game with Lloyd. 28 mar 16 Dad's birthday 29 April 15, 1989 Income tax due. 30 &* 15 time cards due. 31 32 Although you probably will start by creating a diary manually, Emacs 33provides a number of commands to let you view, add, and change diary 34entries. 35 36* Menu: 37 38* Diary Commands:: Viewing diary entries and associated calendar dates. 39* Format of Diary File:: Entering events in your diary. 40* Date Formats:: Various ways you can specify dates. 41* Adding to Diary:: Commands to create diary entries. 42* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. 43 44 45File: emacs, Node: Diary Commands, Next: Format of Diary File, Up: Diary 46 47Commands Displaying Diary Entries 48--------------------------------- 49 50 Once you have created a `~/diary' file, you can view it from within 51the calendar. You can also view today's events outside of Calendar 52mode. 53 54`d' 55 Display any diary entries for the selected date 56 (`view-diary-entries'). 57 58`Mouse-2 Diary' 59 Display any diary entries for the date you click on. 60 61`s' 62 Display entire diary file (`show-all-diary-entries'). 63 64`m' 65 Mark all visible dates that have diary entries 66 (`mark-diary-entries'). 67 68`u' 69 Unmark calendar window (`calendar-unmark'). 70 71`M-x print-diary-entries' 72 Print hard copy of the diary display as it appears. 73 74`M-x diary' 75 Display any diary entries for today's date. 76 77 Displaying the diary entries with `d' shows in a separate window the 78diary entries for the selected date in the calendar. The mode line of 79the new window shows the date of the diary entries and any holidays 80that fall on that date. 81 82 If you specify a numeric argument with `d', it shows all the diary 83entries for that many successive days. Thus, `2 d' displays all the 84entries for the selected date and for the following day. 85 86 Another way to display the diary entries for a date is to click 87`Mouse-2' on the date, and then choose `Diary' from the menu that 88appears. 89 90 To get a broader view of which days are mentioned in the diary, use 91the `m' command. This displays the dates that have diary entries fall 92in a different face (or places a `+' after these dates, if display with 93multiple faces is not available). The command applies both to the 94currently visible months and to other months that subsequently become 95visible by scrolling. To turn marking off and erase the current marks, 96type `u', which also turns off holiday marks (*note Holidays::.). 97 98 To see the full diary file, rather than just some of the entries, use 99the `s' command. 100 101 Display of selected diary entries uses the selective display feature 102to hide entries that don't apply. This is the same feature that Outline 103mode uses to show part of an outline (*note Outline Mode::.). The diary 104buffer as you see it is an illusion, so simply printing the buffer does 105not print what you see on your screen. 106 107 There is a special command to print hard copy of the diary buffer 108*as it appears*; this command is `M-x print-diary-entries'. It sends 109the data directly to the printer. You can customize it like 110`lpr-region' (*note Hardcopy::.). 111 112 The command `M-x diary' displays the diary entries for the current 113date, independently of the calendar display, and optionally for the next 114few days as well; the variable `number-of-diary-entries' specifies how 115many days to include. *Note Calendar/Diary Options: 116(elisp)Calendar/Diary Options. 117 118 If you put `(diary)' in your `.emacs' file, this automatically 119displays a window with the day's diary entries, when you enter Emacs. 120The mode line of the displayed window shows the date and any holidays 121that fall on that date. 122 123 124File: emacs, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary 125 126The Diary File 127-------------- 128 129 Your "diary file" is a file that records events associated with 130particular dates. The name of the diary file is specified by the 131variable `diary-file'; `~/diary' is the default. You can use the same 132file for the `calendar' utility program, since its formats are a subset 133of the ones allowed by the Emacs diary facilities. 134 135 Each entry in the diary file describes one event and consists of one 136or more lines. An entry always begins with a date specification at the 137left margin. The rest of the entry is simply text to describe the 138event. If the entry has more than one line, then the lines after the 139first must begin with whitespace to indicate they continue a previous 140entry. Lines that do not begin with valid dates and do not continue a 141preceding entry are ignored. 142 143 You can inhibit the marking of certain diary entries in the calendar 144window; to do this, insert an ampersand (`&') at the beginning of the 145entry, before the date. This has no effect on display of the entry in 146the diary window; it affects only marks on dates in the calendar 147window. Nonmarking entries are especially useful for generic entries 148that would otherwise mark many different dates. 149 150 If the first line of a diary entry consists only of the date or day 151name with no following blanks or punctuation, then the diary window 152display doesn't include that line; only the continuation lines appear. 153For example: 154 155 02/11/1989 156 Bill B. visits Princeton today 157 2pm Cognitive Studies Committee meeting 158 2:30-5:30 Liz at Lawrenceville 159 4:00pm Dentist appt 160 7:30pm Dinner at George's 161 8:00-10:00pm concert 162 163appears in the diary window without the date line at the beginning. 164This style of entry looks neater when you display just a single day's 165entries, but can cause confusion if you ask for more than one day's 166entries. 167 168 You can edit the diary entries as they appear in the window, but it 169is important to remember that the buffer displayed contains the *entire* 170diary file, with portions of it concealed from view. This means, for 171instance, that the `C-f' (`forward-char') command can put point at what 172appears to be the end of the line, but what is in reality the middle of 173some concealed line. 174 175 *Be careful when editing the diary entries!* Inserting additional 176lines or adding/deleting characters in the middle of a visible line 177cannot cause problems, but editing at the end of a line may not do what 178you expect. Deleting a line may delete other invisible entries that 179follow it. Before editing the diary, it is best to display the entire 180file with `s' (`show-all-diary-entries'). 181 182 183File: emacs, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary 184 185Date Formats 186------------ 187 188 Here are some sample diary entries, illustrating different ways of 189formatting a date. The examples all show dates in American order 190(month, day, year), but Calendar mode supports European order (day, 191month, year) as an option. 192 193 4/20/93 Switch-over to new tabulation system 194 apr. 25 Start tabulating annual results 195 4/30 Results for April are due 196 */25 Monthly cycle finishes 197 Friday Don't leave without backing up files 198 199 The first entry appears only once, on April 20, 1993. The second and 200third appear every year on the specified dates, and the fourth uses a 201wildcard (asterisk) for the month, so it appears on the 25th of every 202month. The final entry appears every week on Friday. 203 204 You can use just numbers to express a date, as in `MONTH/DAY' or 205`MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date 206itself, MONTH and DAY are numbers of one or two digits. YEAR is a 207number and may be abbreviated to the last two digits; that is, you can 208use `11/12/1989' or `11/12/89'. 209 210 Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY, 211YEAR', where the month's name can be spelled in full or abbreviated to 212three characters (with or without a period). Case is not significant. 213 214 A date may be "generic", or partially unspecified. Then the entry 215applies to all dates that match the specification. If the date does not 216contain a year, it is generic and applies to any year. Alternatively, 217MONTH, DAY, or YEAR can be a `*'; this matches any month, day, or year, 218respectively. Thus, a diary entry `3/*/*' matches any day in March of 219any year; so does `march *'. 220 221 If you prefer the European style of writing dates--in which the day 222comes before the month--type `M-x european-calendar' while in the 223calendar, or set the variable `european-calendar-style' to `t' *before* 224using any calendar or diary command. This mode interprets all dates in 225the diary in the European manner, and also uses European style for 226displaying diary dates. (Note that there is no comma after the 227MONTHNAME in the European style.) To go back to the (default) American 228style of writing dates, type `M-x american-calendar'. 229 230 You can use the name of a day of the week as a generic date which 231applies to any date falling on that day of the week. You can abbreviate 232the day of the week to three letters (with or without a period) or spell 233it in full; case is not significant. 234 235 236File: emacs, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary 237 238Commands to Add to the Diary 239---------------------------- 240 241 While in the calendar, there are several commands to create diary 242entries: 243 244`i d' 245 Add a diary entry for the selected date (`insert-diary-entry'). 246 247`i w' 248 Add a diary entry for the selected day of the week 249 (`insert-weekly-diary-entry'). 250 251`i m' 252 Add a diary entry for the selected day of the month 253 (`insert-monthly-diary-entry'). 254 255`i y' 256 Add a diary entry for the selected day of the year 257 (`insert-yearly-diary-entry'). 258 259 You can make a diary entry for a specific date by selecting that date 260in the calendar window and typing the `i d' command. This command 261displays the end of your diary file in another window and inserts the 262date; you can then type the rest of the diary entry. 263 264 If you want to make a diary entry that applies to a specific day of 265the week, select that day of the week (any occurrence will do) and type 266`i w'. This inserts the day-of-week as a generic date; you can then 267type the rest of the diary entry. 268 269 You can make a monthly diary entry in the same fashion. Select the 270day of the month, use the `i m' command, and type rest of the entry. 271Similarly, you can insert a yearly diary entry with the `i y' command. 272 273 All of the above commands make marking diary entries. If you want 274the diary entry to be nonmarking, give a prefix argument to the command. 275For example, `C-u i w' makes a nonmarking, weekly diary entry. 276 277 When you modify the diary file, be sure to save the file before 278exiting Emacs. 279 280 281File: emacs, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary 282 283Special Diary Entries 284--------------------- 285 286 In addition to entries based on calendar dates, your diary file can 287contain "special entries" for regular events such as anniversaries. 288These entries are based on Lisp expressions (sexps) that Emacs evaluates 289as it scans the diary file. Instead of a date, a special entry contains 290`%%' followed by a Lisp expression which must begin and end with 291parentheses. The Lisp expression determines which dates the entry 292applies to. 293 294 Calendar mode provides commands to insert certain commonly used 295special entries: 296 297`i a' 298 Add an anniversary diary entry for the selected date 299 (`insert-anniversary-diary-entry'). 300 301`i b' 302 Add a block diary entry for the current region 303 (`insert-block-diary-entry'). 304 305`i c' 306 Add a cyclic diary entry starting at the date 307 (`insert-cyclic-diary-entry'). 308 309 If you want to make a diary entry that applies to the anniversary of 310a specific date, move point to that date and use the `i a' command. 311This displays the end of your diary file in another window and inserts 312the anniversary description; you can then type the rest of the diary 313entry. The entry looks like this: 314 315 %%(diary-anniversary 10 31 1948) Arthur's birthday 316 317This entry applies to October 31 in any year after 1948; `10 31 1948' 318specifies the date. (If you are using the European calendar style, the 319month and day are interchanged.) The reason this expression requires a 320beginning year is that advanced diary functions can use it to calculate 321the number of elapsed years. 322 323 You can make a diary entry for a block of dates by setting the mark 324at the date at one end of the block, moving point to the date at the 325other end of the block, and using the `i b' command. This command 326causes the end of your diary file to be displayed in another window and 327the block description to be inserted; you can then type the diary 328entry. Here is a block diary entry that applies to all dates from June 32924, 1990 through July 10, 1990: 330 331 %%(diary-block 6 24 1990 7 10 1990) Vacation 332 333The `6 24 1990' indicates the starting date and the `7 10 1990' 334indicates the stopping date. (Again, if you are using the European 335calendar style, the month and day are interchanged.) 336 337 "Cyclic" diary entries repeat after a fixed interval of days. To 338create one, select the starting date and use the `i c' command. The 339command prompts for the length of interval, then inserts the entry. It 340looks like this: 341 342 %%(diary-cyclic 50 3 1 1990) Renew medication 343 344which applies to March 1, 1990 and every 50th day following; `3 1 1990' 345specifies the starting date. (If you are using the European calendar 346style, the month and day are interchanged.) 347 348 All three of the these commands make marking diary entries. If you 349want the diary entry to be nonmarking, give a numeric argument to the 350command. For example, `C-u i a' makes a nonmarking anniversary diary 351entry. 352 353 Marking sexp diary entries in the calendar is *extremely* 354time-consuming, since every date visible in the calendar window must be 355individually checked. So it's a good idea to make sexp diary entries 356nonmarking (with `&') when possible. 357 358 Another sophisticated kind of sexp entry, a "floating" diary entry, 359specifies a regularly-occurring event by offsets specified in days, 360weeks, and months. It is comparable to a crontab entry interpreted by 361the `cron' utility. Here is a nonmarking, floating diary entry that 362applies to the last Thursday in November: 363 364 &%%(diary-float 11 4 -1) American Thanksgiving 365 366The 11 specifies November (the eleventh month), the 4 specifies Thursday 367(the fourth day of the week, where Sunday is numbered zero), and the -1 368specifies "last" (1 would mean "first", 2 would mean "second", -2 would 369mean "second-to-last", and so on). The month can be a single month or 370a list of months. Thus you could change the 11 above to `'(1 2 3)' and 371have the entry apply to the last Thursday of January, February, and 372March. If the month is `t', the entry applies to all months of the 373year. 374 375 Most generally, special diary entries can perform arbitrary 376computations to determine when they apply. *Note Sexp Diary Entries: 377(elisp)Sexp Diary Entries. 378 379 380File: emacs, Node: Appointments, Next: Daylight Savings, Prev: Diary, Up: Calendar/Diary 381 382Appointments 383============ 384 385 If you have a diary entry for an appointment, and that diary entry 386begins with a recognizable time of day, Emacs can warn you, several 387minutes beforehand, that that appointment is pending. Emacs alerts you 388to the appointment by displaying a message in the mode line. 389 390 To enable appointment notification, you must enable the time display 391feature of Emacs, `M-x display-time' (*note Mode Line::.). You must 392also add the function `appt-make-list' to the `diary-hook', like this: 393 394 (add-hook 'diary-hook 'appt-make-list) 395 396 With these preparations done, when you display the diary (either with 397the `d' command in the calendar window or with the `M-x diary' 398command), it sets up an appointment list of all the diary entries found 399with recognizable times of day, and reminds you just before each of 400them. 401 402 For example, if the diary file contains these lines: 403 404 Monday 405 9:30am Coffee break 406 12:00pm Lunch 407 408Then on Mondays, after you have displayed the diary, you will be 409reminded at 9:20am about your coffee break and at 11:50am about lunch. 410 411 Diary entries can have the time in the conventional American style, 412or in "military" style. You need not be consistent; your diary file can 413have a mixture of the two styles. 414 415 Emacs updates the appointments list automatically just after 416midnight. This also displays the next days' diary entries in the diary 417buffer, unless you set `appt-display-diary' to `nil'. 418 419 You can also use the appointment notification facility like an alarm 420clock. The command `M-x appt-add' adds entries to the appointment list 421without affecting your diary file. You delete entries from the 422appointment list with `M-x appt-delete'. 423 424 You can turn off the appointment notification feature at any time by 425setting `appt-issue-message' to `nil'. 426 427 428File: emacs, Node: Daylight Savings, Prev: Appointments, Up: Calendar/Diary 429 430Daylight Savings Time 431===================== 432 433 Emacs understands the difference between standard time and daylight 434savings time--the times given for sunrise, sunset, solstices, 435equinoxes, and the phases of the moon take that into account. The rules 436for daylight savings time vary from place to place and have also varied 437historically from year to year. To do the job properly, Emacs needs to 438know which rules to use. 439 440 Some operating systems keep track of the rules that apply to the 441place where you are; on these systems, Emacs gets the information it 442needs from the system automatically. If some or all of this 443information is missing, Emacs fills in the gaps with the rules 444currently used in Cambridge, Massachusetts. If the resulting rules are 445not what you want, you can tell Emacs the rules to use by setting 446certain variables. 447 448 These values should be Lisp expressions that refer to the variable 449`year', and evaluate to the Gregorian date on which daylight savings 450time starts or (respectively) ends, in the form of a list `(MONTH DAY 451YEAR)'. The values should be `nil' if your area does not use daylight 452savings time. 453 454 Emacs uses these expressions to determine the starting date of 455daylight savings time for the holiday list and for correcting times of 456day in the solar and lunar calculations. 457 458 The values for Cambridge, Massachusetts are as follows: 459 460 (calendar-nth-named-day 1 0 4 year) 461 (calendar-nth-named-day -1 0 10 year) 462 463i.e. the first 0th day (Sunday) of the fourth month (April) in the year 464specified by `year', and the last Sunday of the tenth month (October) 465of that year. If daylight savings time were changed to start on 466October 1, you would set `calendar-daylight-savings-starts' to this: 467 468 (list 10 1 year) 469 470 If there is no daylight savings time at your location, or if you want 471all times in standard time, set `calendar-daylight-savings-starts' and 472`calendar-daylight-savings-ends' to `nil'. 473 474 This variable specifies the difference between daylight savings time 475and standard time, measured in minutes. The value for Cambridge is 60. 476 477 These variables specify is the number of minutes after midnight 478local time when the transition to and from daylight savings time should 479occur. For Cambridge, both variables' values are 120. 480 481 482File: emacs, Node: GNUS, Next: Sorting, Prev: Calendar/Diary, Up: Top 483 484GNUS 485==== 486 487 GNUS is an Emacs subsystem for reading and responding to netnews. 488You can use GNUS to browse through news groups, look at summaries of 489articles in specific group, and read articles of interest. You can 490respond to authors or write replies to all the readers of a news group. 491 492 This section introduces GNUS and describes several basic features. 493Full documentation will appear elsewhere. 494 495 To start GNUS, type `M-x gnus RET'. 496 497* Menu: 498 499* Buffers of GNUS:: The Newsgroups, Summary and Article buffers. 500* GNUS Startup:: What you should know about starting GNUS. 501* Summary of GNUS:: A short description of the basic GNUS commands. 502 503 504File: emacs, Node: Buffers of GNUS, Next: GNUS Startup, Up: GNUS 505 506GNUS's Three Buffers 507-------------------- 508 509 GNUS creates and uses three Emacs buffers, each with its own 510particular purpose and its own major mode. 511 512 The "Newsgroup buffer" contains a list of newsgroups. This is the 513first buffer that GNUS displays when it starts up. Normally the list 514contains only the newsgroups to which you subscribe (which are listed in 515your `.newsrc' file) and which contain unread articles. Use this 516buffer to select a specific newsgroup. 517 518 The "Summary buffer" lists the articles in a single newsgroup, 519including their subjects, their numbers, and who posted them. GNUS 520creates a Summary buffer for a newsgroup when you select the group in 521the Newsgroup buffer. Use this buffer to select an article, and to move 522around in an article. 523 524 The "Article buffer" displays the text of an article. You rarely 525need to select this buffer because you can read the text while keeping 526the Summary buffer selected. 527 528 529File: emacs, Node: GNUS Startup, Next: Summary of GNUS, Prev: Buffers of GNUS, Up: GNUS 530 531When GNUS Starts Up 532------------------- 533 534 At startup, GNUS reads your `.newsrc' news initialization file and 535attempts to communicate with the local news server, which is a 536repository of news articles. The news server need not be the same 537computer you are logged in on. 538 539 If you start GNUS and connect to the server, but do not see any 540newsgroups listed in the Newsgroup buffer, type `L' to get a listing of 541all the newsgroups. Then type `u' to unsubscribe from particular 542newsgroups. (Move the cursor using `n' and `p' or the usual Emacs 543commands.) 544 545 When you quit GNUS with `q', it automatically records in your 546`.newsrc' initialization file the subscribed or unsubscribed status of 547all newsgroups, except for groups you have "killed". (You do not need 548to edit this file yourself, but you may.) When new newsgroups come 549into existence, GNUS adds them automatically. 550 551 552File: emacs, Node: Summary of GNUS, Prev: GNUS Startup, Up: GNUS 553 554Summary of GNUS Commands 555------------------------ 556 557 Reading news is a two step process: 558 559 1. Choose a newsgroup in the Newsgroup buffer. 560 561 2. Select articles from the Summary buffer. Each article selected is 562 displayed in the Article buffer in a large window, below the 563 Summary buffer in its small window. 564 565 Each buffer has commands particular to it, but commands that do the 566same things have similar keybindings. Here are commands for the 567Newsgroup and Summary buffers: 568 569`z' 570 In the Newsgroup buffer, suspend GNUS. You can return to GNUS 571 later by selecting the Newsgroup buffer and typing `g' to get 572 newly arrived articles. 573 574`q' 575 In the Newsgroup buffer, update your `.newsrc' initialization file 576 and quit GNUS. 577 578 In the Summary buffer, exit the current newsgroup and return to the 579 Newsgroup buffer. Thus, typing `q' twice quits GNUS. 580 581`L' 582 In the Newsgroup buffer, list all the newsgroups available on your 583 news server. This may be a long list! 584 585`l' 586 In the Newsgroup buffer, list only the newsgroups to which you 587 subscribe and which contain unread articles. 588 589`u' 590 In the Newsgroup buffer, unsubscribe from (or subscribe to) the 591 newsgroup listed in the line that point is on. When you quit GNUS 592 by typing `q', GNUS lists your subscribed-to newsgroups in your 593 `.newsrc' file. The next time you start GNUS, you see only the 594 newsgroups listed in your `.newsrc' file. 595 596`C-k' 597 In the Newsgroup buffer, "kill" the current line's newsgroup--don't 598 show it in the Newsgroup buffer from now on. This affects future 599 GNUS sessions as well as the present session. 600 601 When you quit GNUS by typing `q', GNUS writes information in the 602 file `.newsrc' describing all newsgroups except those you have 603 "killed." 604 605`SPC' 606 In the Newsgroup buffer, select the group on the line under the 607 cursor and display the first unread article in that group. 608 609 In the Summary buffer, 610 611 - Select the article on the line under the cursor if none is 612 selected. 613 614 - Scroll the text of the selected article (if there is one). 615 616 - Select the next unread article if at the end of the current 617 article. 618 619 Thus, you can move through all the articles by repeatedly typing 620 SPC. 621 622`DEL' 623 In the Newsgroup Buffer, move point to the previous newsgroup 624 containing unread articles. 625 626 In the Summary buffer, scroll the text of the article backwards. 627 628`n' 629 Move point to the next unread newsgroup, or select the next unread 630 article. 631 632`p' 633 Move point to the previous unread newsgroup, or select the previous 634 unread article. 635 636`C-n' 637`C-p' 638 Move point to the next or previous item, even if it is marked as 639 read. This does not select the article or newsgroup on that line. 640 641`s' 642 In the Summary buffer, do an incremental search of the current 643 text in the Article buffer, just as if you switched to the Article 644 buffer and typed `C-s'. 645 646`M-s REGEXP RET' 647 In the Summary buffer, search forward for articles containing a 648 match for REGEXP. 649 650`C-c C-s C-n' 651`C-c C-s C-s' 652`C-c C-s C-d' 653`C-c C-s C-a' 654 In the Summary buffer, sort the list of articles by number, 655 subject, date, or author. 656 657`C-M-n' 658`C-M-p' 659 In the Summary buffer, read the next or previous article with the 660 same subject as the current article. 661 662 663File: emacs, Node: Sorting, Next: Shell, Prev: GNUS, Up: Top 664 665Sorting Text 666============ 667 668 Emacs provides several commands for sorting text in the buffer. All 669operate on the contents of the region (the text between point and the 670mark). They divide the text of the region into many "sort records", 671identify a "sort key" for each record, and then reorder the records 672into the order determined by the sort keys. The records are ordered so 673that their keys are in alphabetical order, or, for numeric sorting, in 674numeric order. In alphabetic sorting, all upper case letters `A' 675through `Z' come before lower case `a', in accord with the ASCII 676character sequence. 677 678 The various sort commands differ in how they divide the text into 679sort records and in which part of each record is used as the sort key. 680Most of the commands make each line a separate sort record, but some 681commands use paragraphs or pages as sort records. Most of the sort 682commands use each entire sort record as its own sort key, but some use 683only a portion of the record as the sort key. 684 685`M-x sort-lines' 686 Divide the region into lines, and sort by comparing the entire 687 text of a line. A prefix argument means sort into descending 688 order. 689 690`M-x sort-paragraphs' 691 Divide the region into paragraphs, and sort by comparing the entire 692 text of a paragraph (except for leading blank lines). A prefix 693 argument means sort into descending order. 694 695`M-x sort-pages' 696 Divide the region into pages, and sort by comparing the entire 697 text of a page (except for leading blank lines). A prefix 698 argument means sort into descending order. 699 700`M-x sort-fields' 701 Divide the region into lines, and sort by comparing the contents of 702 one field in each line. Fields are defined as separated by 703 whitespace, so the first run of consecutive non-whitespace 704 characters in a line constitutes field 1, the second such run 705 constitutes field 2, etc. 706 707 Specify which field to sort by with a numeric argument: 1 to sort 708 by field 1, etc. A negative argument means count fields from the 709 right instead of from the left; thus, minus 1 means sort by the 710 last field. If several lines have identical contents in the field 711 being sorted, they keep same relative order that they had in the 712 original buffer. 713 714`M-x sort-numeric-fields' 715 Like `M-x sort-fields' except the specified field is converted to 716 an integer for each line, and the numbers are compared. `10' 717 comes before `2' when considered as text, but after it when 718 considered as a number. A negative argument means count fields 719 from the right (from the end of the line). 720 721`M-x sort-columns' 722 Like `M-x sort-fields' except that the text within each line used 723 for comparison comes from a fixed range of columns. See below for 724 an explanation. 725 726`M-x reverse-region' 727 Reverse the order of the lines in the region. This is useful for 728 sorting into descending order by fields or columns, since those 729 sort commands do not have a feature for doing that. 730 731 For example, if the buffer contains this: 732 733 On systems where clash detection (locking of files being edited) is 734 implemented, Emacs also checks the first time you modify a buffer 735 whether the file has changed on disk since it was last visited or 736 saved. If it has, you are asked to confirm that you want to change 737 the buffer. 738 739then applying `M-x sort-lines' to the entire buffer produces this: 740 741 On systems where clash detection (locking of files being edited) is 742 implemented, Emacs also checks the first time you modify a buffer 743 saved. If it has, you are asked to confirm that you want to change 744 the buffer. 745 whether the file has changed on disk since it was last visited or 746 747where the upper case `O' sorts before all lower case letters. If you 748use `C-u 2 M-x sort-fields' instead, you get this: 749 750 implemented, Emacs also checks the first time you modify a buffer 751 saved. If it has, you are asked to confirm that you want to change 752 the buffer. 753 On systems where clash detection (locking of files being edited) is 754 whether the file has changed on disk since it was last visited or 755 756where the sort keys were `Emacs', `If', `buffer', `systems' and `the'. 757 758 `M-x sort-columns' requires more explanation. You specify the 759columns by putting point at one of the columns and the mark at the other 760column. Because this means you cannot put point or the mark at the 761beginning of the first line to sort, this command uses an unusual 762definition of `region': all of the line point is in is considered part 763of the region, and so is all of the line the mark is in. 764 765 For example, to sort a table by information found in columns 10 to 76615, you could put the mark on column 10 in the first line of the table, 767and point on column 15 in the last line of the table, and then run 768`sort-columns'. Equivalently, you could run it with the mark on column 76915 in the first line and point on column 10 in the last line. 770 771 This can be thought of as sorting the rectangle specified by point 772and the mark, except that the text on each line to the left or right of 773the rectangle moves along with the text inside the rectangle. *Note 774Rectangles::. 775 776 Many of the sort commands ignore case differences when comparing, if 777`sort-fold-case' is non-`nil'. 778 779 780File: emacs, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top 781 782Running Shell Commands from Emacs 783================================= 784 785 Emacs has commands for passing single command lines to inferior shell 786processes; it can also run a shell interactively with input and output 787to an Emacs buffer `*shell*'. 788 789`M-!' 790 Run a specified shell command line and display the output 791 (`shell-command'). 792 793`M-|' 794 Run a specified shell command line with region contents as input; 795 optionally replace the region with the output 796 (`shell-command-on-region'). 797 798`M-x shell' 799 Run a subshell with input and output through an Emacs buffer. You 800 can then give commands interactively. 801 802* Menu: 803 804* Single Shell:: How to run one shell command and return. 805* Interactive Shell:: Permanent shell taking input via Emacs. 806* Shell Mode:: Special Emacs commands used with permanent shell. 807* History: Shell History. Repeating previous commands in a shell buffer. 808* Options: Shell Options. Options for customizing Shell mode. 809* Remote Host:: Connecting to another computer. 810 811 812File: emacs, Node: Single Shell, Next: Interactive Shell, Up: Shell 813 814Single Shell Commands 815--------------------- 816 817 `M-!' (`shell-command') reads a line of text using the minibuffer 818executes it as a shell command in a subshell made just for this 819command. Standard input for the command comes from the null device. 820If the shell command produces any output, the output goes into an Emacs 821buffer named `*Shell Command Output*', which is displayed in another 822window but not selected. A numeric argument, as in `M-1 M-!', directs 823this command to insert any output into the current buffer. In that 824case, point is left before the output and the mark is set after the 825output. 826 827 If the shell command line ends in `&', it runs asynchronously. 828 829 `M-|' (`shell-command-on-region') is like `M-!' but passes the 830contents of the region as input to the shell command, instead of no 831input. If a numeric argument is used, meaning insert output in the 832current buffer, then the old region is deleted first and the output 833replaces it as the contents of the region. 834 835 Both `M-!' and `M-|' use `shell-file-name' to specify the shell to 836use. This variable is initialized based on your `SHELL' environment 837variable when Emacs is started. If the file name does not specify a 838directory, the directories in the list `exec-path' are searched; this 839list is initialized based on the environment variable `PATH' when Emacs 840is started. Your `.emacs' file can override either or both of these 841default initializations. 842 843 With `M-!' and `M-|', Emacs has to wait until the shell command 844completes. To stop waiting, type `C-g' to quit; that also kills the 845shell command. 846 847 848File: emacs, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell 849 850Interactive Inferior Shell 851-------------------------- 852 853 To run a subshell interactively, putting its typescript in an Emacs 854buffer, use `M-x shell'. This creates (or reuses) a buffer named 855`*shell*' and runs a subshell with input coming from and output going 856to that buffer. That is to say, any "terminal output" from the subshell 857goes into the buffer, advancing point, and any "terminal input" for the 858subshell comes from text in the buffer. To give input to the subshell, 859go to the end of the buffer and type the input, terminated by RET. 860 861 Emacs does not wait for the subshell to do anything. You can switch 862windows or buffers and edit them while the shell is waiting, or while 863it is running a command. Output from the subshell waits until Emacs 864has time to process it; this happens whenever Emacs is waiting for 865keyboard input or for time to elapse. 866 867 To make multiple subshells, rename the buffer `*shell*' to something 868different using `M-x rename-uniquely'. Then type `M-x shell' again to 869create a new buffer `*shell*' with its own subshell. If you rename 870this buffer as well, you can create a third one, and so on. All the 871subshells run independently and in parallel. 872 873 The file name used to load the subshell is the value of the variable 874`explicit-shell-file-name', if that is non-`nil'. Otherwise, the 875environment variable `ESHELL' is used, or the environment variable 876`SHELL' if there is no `ESHELL'. If the file name specified is 877relative, the directories in the list `exec-path' are searched (*note 878Single Shell Commands: Single Shell.). 879 880 As soon as the subshell is started, it is sent as input the contents 881of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME 882is the name of the file that the shell was loaded from. For example, 883if you use `bash', the file sent to it is `~/.emacs_bash'. 884 885 `cd', `pushd' and `popd' commands given to the inferior shell are 886watched by Emacs so it can keep the `*shell*' buffer's default 887directory the same as the shell's working directory. These commands 888are recognized syntactically by examining lines of input that are sent. 889If you use aliases for these commands, you can tell Emacs to recognize 890them also. For example, if the value of the variable 891`shell-pushd-regexp' matches the beginning of a shell command line, 892that line is regarded as a `pushd' command. Change this variable when 893you add aliases for `pushd'. Likewise, `shell-popd-regexp' and 894`shell-cd-regexp' are used to recognize commands with the meaning of 895`popd' and `cd'. These commands are recognized only at the beginning 896of a shell command line. 897 898 If Emacs gets an error while trying to handle what it believes is a 899`cd', `pushd' or `popd' command, it runs the hook 900`shell-set-directory-error-hook' (*note Hooks::.). 901 902 If Emacs does not properly track changes in the current directory of 903the subshell, use the command `M-x dirs' to ask the shell what its 904current directory is. This command works for shells that support the 905most common command syntax; it may not work for unusual shells. 906 907 908File: emacs, Node: Shell Mode, Next: Shell History, Prev: Interactive Shell, Up: Shell 909 910Shell Mode 911---------- 912 913 The shell buffer uses Shell mode, which defines several special keys 914attached to the `C-c' prefix. They are chosen to resemble the usual 915editing and job control characters present in shells that are not under 916Emacs, except that you must type `C-c' first. Here is a complete list 917of the special key bindings of Shell mode: 918 919`RET' 920 At end of buffer send line as input; otherwise, copy current line 921 to end of buffer and send it (`comint-send-input'). When a line is 922 copied, any text at the beginning of the line that matches the 923 variable `shell-prompt-pattern' is left out; this variable's value 924 should be a regexp string that matches the prompts that your shell 925 uses. 926 927`TAB' 928 Complete the command name or file name before point in the shell 929 buffer (`comint-dynamic-complete'). TAB also completes history 930 references (*note History References::.) and environment variable 931 names. 932 933 The variable `shell-completion-fignore' specifies a list of file 934 name extensions to ignore in Shell mode completion. The default 935 setting ignores file names ending in `~', `#' or `%'. Other 936 related Comint modes use the variable `comint-completion-fignore' 937 instead. 938 939`M-?' 940 Display temporarily a list of the possible completions of the file 941 name before point in the shell buffer 942 (`comint-dynamic-list-filename-completions'). 943 944`C-a' 945 Move to the beginning of the line, but after the prompt if any 946 (`comint-bol'). 947 948`C-d' 949 Either delete a character or send EOF 950 (`comint-delchar-or-maybe-eof'). Typed at the end of the shell 951 buffer, `C-d' sends EOF to the subshell. Typed at any other 952 position in the buffer, `C-d' deletes a character as usual. 953 954`C-c C-u' 955 Kill all text pending at end of buffer to be sent as input 956 (`comint-kill-input'). 957 958`C-c C-w' 959 Kill a word before point (`backward-kill-word'). 960 961`C-c C-c' 962 Interrupt the shell or its current subjob if any 963 (`comint-interrupt-subjob'). 964 965`C-c C-z' 966 Stop the shell or its current subjob if any (`comint-stop-subjob'). 967 968`C-c C-\' 969 Send quit signal to the shell or its current subjob if any 970 (`comint-quit-subjob'). 971 972`C-c C-o' 973 Kill the last batch of output from a shell command 974 (`comint-kill-output'). This is useful if a shell command spews 975 out lots of output that just gets in the way. 976 977`C-c C-r' 978`C-M-l' 979 Scroll to display the beginning of the last batch of output at the 980 top of the window; also move the cursor there 981 (`comint-show-output'). 982 983`C-c C-e' 984 Scroll to put the end of the buffer at the bottom of the window 985 (`comint-show-maximum-output'). 986 987`C-c C-f' 988 Move forward across one shell command, but not beyond the current 989 line (`shell-forward-command'). The variable 990 `shell-command-regexp' specifies how to recognize the end of a 991 command. 992 993`C-c C-b' 994 Move backward across one shell command, but not beyond the current 995 line (`shell-backward-command'). 996 997`M-x dirs' 998 Ask the shell what its current directory is, so that Emacs can 999 agree with the shell. 1000 1001`M-x send-invisible RET TEXT RET' 1002 Send TEXT as input to the shell, after reading it without echoing. 1003 This is useful when a shell command runs a program that asks for 1004 a password. 1005 1006 Alternatively, you can arrange for Emacs to notice password prompts 1007 and turn off echoing for them, as follows: 1008 1009 (add-hook `comint-output-filter-functions 1010 `comint-watch-for-password-prompt) 1011 1012`M-x comint-continue-subjob' 1013 Continue the shell process. This is useful if you accidentally 1014 suspend the shell process.(1) 1015 1016`M-x shell-strip-ctrl-m' 1017 Discard all control-m characters from the shell output. 1018 1019 Shell mode also customizes the paragraph commands so that only shell 1020promps start new paragraphs. Thus, a paragraph consists of an input 1021command plus the output that follows it in the buffer. 1022 1023 Shell mode is a derivative of Comint mode, a general purpose mode for 1024communicating with interactive subprocesses. Most of the features of 1025Shell mode actually come from Comint mode, as you can see from the 1026command names listed above. The specialization of Shell mode in 1027particular include the choice of regular expression for detecting 1028prompts, the directory tracking feature, and a few user commands. 1029 1030 Other Emacs features that use variants of Comint mode include GUD 1031(*note Debuggers::.) and `M-x run-lisp' (*note External Lisp::.). 1032 1033 You can use `M-x comint-run' to execute any program of your choice 1034in a subprocess using unmodified Comint mode--without the 1035specializations of Shell mode. 1036 1037 ---------- Footnotes ---------- 1038 1039 (1) You should not suspend the shell process. Suspending a subjob 1040of the shell is a completely different matter-that is normal practice, 1041but you must use the shell to continue the subjob; this command won't 1042do it. 1043 1044 1045File: emacs, Node: Shell History, Next: Shell Options, Prev: Shell Mode, Up: Shell 1046 1047Shell Command History 1048--------------------- 1049 1050 Shell buffers support three ways of repeating earlier commands. You 1051can use the same keys used in the minibuffer; these work much as they do 1052in the minibuffer, inserting text from prior commands while point 1053remains always at the end of the buffer. You can move through the 1054buffer to previous inputs in their original place, then resubmit them or 1055copy them to the end. Or you can use a `!'-style history reference. 1056 1057* Menu: 1058 1059* Ring: Shell Ring. Fetching commands from the history list. 1060* Copy: Shell History Copying. Moving to a command and then copying it. 1061* History References:: Expanding `!'-style history references. 1062 1063 1064File: emacs, Node: Shell Ring, Next: Shell History Copying, Up: Shell History 1065 1066Shell History Ring 1067.................. 1068 1069`M-p' 1070 Fetch the next earlier old shell command. 1071 1072`M-n' 1073 Fetch the next later old shell command. 1074 1075`M-r REGEXP RET' 1076`M-s REGEXP RET' 1077 Search backwards or forwards for old shell commands that match 1078 REGEXP. 1079 1080 Shell buffers provide a history of previously entered shell 1081commands. To reuse shell commands from the history, use the editing 1082commands `M-p', `M-n', `M-r' and `M-s'. These work just like the 1083minibuffer history commands except that they operate on the text at the 1084end of the shell buffer, where you would normally insert text to send 1085to the shell. 1086 1087 `M-p' fetches an earlier shell command to the end of the shell 1088buffer. Successive use of `M-p' fetches successively earlier shell 1089commands, each replacing any text that was already present as potential 1090shell input. `M-n' does likewise except that it finds successively 1091more recent shell commands from the buffer. 1092 1093 The history search commands `M-r' and `M-s' read a regular 1094expression and search through the history for a matching command. Aside 1095from the choice of which command to fetch, they work just like `M-p' 1096and `M-r'. If you enter an empty regexp, these commands reuse the same 1097regexp used last time. 1098 1099 When you find the previous input you want, you can resubmit it by 1100typing RET, or you can edit it first and then resubmit it if you wish. 1101 1102 These commands get the text of previous shell commands from a special 1103history list, not from the shell buffer itself. Thus, editing the shell 1104buffer, or even killing large parts of it, does not affect the history 1105that these commands access. 1106 1107 1108File: emacs, Node: Shell History Copying, Next: History References, Prev: Shell Ring, Up: Shell History 1109 1110Shell History Copying 1111..................... 1112 1113`C-c C-p' 1114 Move point to the previous prompt (`comint-previous-prompt'). 1115 1116`C-c C-n' 1117 Move point to the following prompt (`comint-next-prompt'). 1118 1119`C-c RET' 1120 Copy the input command which point is in, inserting the copy at 1121 the end of the buffer (`comint-copy-old-input'). This is useful 1122 if you move point back to a previous command. After you copy the 1123 command, you can submit the copy as input with RET. If you wish, 1124 you can edit the copy before resubmitting it. 1125 1126 Moving to a previous input and then copying it with `C-c RET' 1127produces the same results--the same buffer contents--that you would get 1128by using `M-p' enough times to fetch that previous input from the 1129history list. However, `C-c RET' copies the text from the buffer, 1130which can be different from what is in the history list (if you edit 1131the input in the buffer after it has been sent). 1132 1133 1134File: emacs, Node: History References, Prev: Shell History Copying, Up: Shell History 1135 1136Shell History References 1137........................ 1138 1139 Various shells including csh and bash support "history references" 1140that begin with `!' and `^'. Shell mode now understands this syntax. 1141If you insert a history reference and type TAB, this searches the input 1142history for a matching command, performs substitution if necessary, and 1143places the result in the buffer in place of the history reference. For 1144example, you can fetch the most recent command beginning with `mv' with 1145`! m v TAB'. You could then resubmit this command to the shell by 1146typing RET as usual. 1147 1148 History references take effect only following a shell prompt. The 1149variable `comint-prompt-regexp' specifies how to recognize a shell 1150prompt. 1151 1152