1This is Info file ../info/emacs, produced by Makeinfo-1.54 from the 2input file emacs.texi. 3 4 5File: emacs, Node: Dired Deletion, Next: Dired Visiting, Prev: Dired Commands, Up: Dired 6 7Deleting Files with Dired 8========================= 9 10 The primary use of Dired is to "flag" files for deletion and then 11delete the files previously flagged. 12 13`d' 14 Flag this file for deletion. 15 16`u' 17 Remove deletion flag on this line. 18 19`DEL' 20 Move point to previous line and remove the deletion flag on that 21 line. 22 23`x' 24 Delete the files that are flagged for deletion. 25 26`#' 27 Flag all auto-save files (files whose names start and end with `#') 28 for deletion (*note Auto Save::.). 29 30`~' 31 Flag all backup files (files whose names end with `~') for deletion 32 (*note Backup::.). 33 34`. (Period)' 35 Flag excess numeric backup files for deletion. The oldest and 36 newest few backup files of any one file are exempt; the middle 37 ones are flagged. 38 39`% d REGEXP RET' 40 Flag for deletion all files whose names match the regular 41 expression REGEXP (`dired-flag-files-regexp'). This is just like 42 `% m' except that it uses `D' instead of `*' to mark the files. 43 44 Only the non-directory part of the file name is used in matching. 45 Use `^' and `$' to anchor matches. Exclude subdirectories by 46 hiding them (*note Hiding Subdirectories::.). 47 48 You can flag a file for deletion by moving to the line describing the 49file and typing `d'. The deletion flag is visible as a `D' at the 50beginning of the line. This command moves point to the beginning of 51the next line, so that repeated `d' commands flag successive files. 52 53 The files are flagged for deletion rather than deleted immediately to 54reduce the danger of deleting a file accidentally. Until you direct 55Dired to expunge the flagged files, you can remove deletion flags using 56the commands `u' and DEL. `u' works just like `d', but removes flags 57rather than making flags. DEL moves upward, removing flags; it is like 58`u' with numeric argument automatically negated. 59 60 To delete the flagged files, type `x' (`dired-expunge'). This 61command first displays a list of all the file names flagged for 62deletion, and requests confirmation with `yes'. Once you confirm, `x' 63deletes all the flagged files, then deletes their lines from the text 64of the Dired buffer. The shortened Dired buffer remains selected. 65 66 If you answer `no' or quit with `C-g' when asked to confirm, you 67return immediately to Dired, with the deletion flags still present in 68the buffer, and no files actually deleted. 69 70 The `#', `~' and `.' commands flag many files for deletion, based on 71their file names. These commands are useful precisely because they do 72not actually delete any files; you can remove the deletion flags from 73any flagged files that you really wish to keep. 74 75 `#' flags for deletion all files whose names look like auto-save 76files (*note Auto Save::.)--that is, files whose names begin and end 77with `#'. `~' flags for deletion all files whose names say they are 78backup files (*note Backup::.)--that is, whose names end in `~'. 79 80 `.' (Period) flags just some of the backup files for deletion: all 81but the oldest few and newest few backups of any one file. Normally 82`dired-kept-versions' (*not* `kept-new-versions'; that applies only 83when saving) specifies the number of newest versions of each file to 84keep, and `kept-old-versions' specifies the number of oldest versions 85to keep. 86 87 Period with a positive numeric argument, as in `C-u 3 .', specifies 88the number of newest versions to keep, overriding 89`dired-kept-versions'. A negative numeric argument overrides 90`kept-old-versions', using minus the value of the argument to specify 91the number of oldest versions of each file to keep. 92 93 The `% d' command flags all files whose names match a specified 94regular expression (`dired-flag-files-regexp'). Only the non-directory 95part of the file name is used in matching. You can use `^' and `$' to 96anchor matches. You can exclude subdirectories by hiding them (*note 97Hiding Subdirectories::.). 98 99 100File: emacs, Node: Dired Visiting, Next: Marks vs Flags, Prev: Dired Deletion, Up: Dired 101 102Visiting Files in Dired 103======================= 104 105 There are several Dired commands for visiting or examining the files 106listed in the Dired buffer. All of them apply to the current line's 107file; if that file is really a directory, these commands invoke Dired on 108that subdirectory (using a separate Dired buffer). 109 110`f' 111 Visit the file described on the current line, like typing `C-x C-f' 112 and supplying that file name (`dired-find-file'). *Note 113 Visiting::. 114 115`o' 116 Like `f', but uses another window to display the file's buffer 117 (`dired-find-file-other-window'). The Dired buffer remains visible 118 in the first window. This is like using `C-x 4 C-f' to visit the 119 file. *Note Windows::. 120 121`C-o' 122 Visit the file described on the current line, and display the 123 buffer in another window, but do not select that window 124 (`dired-display-file'). 125 126`v' 127 View the file described on the current line, using `M-x view-file' 128 (`dired-view-file'). 129 130 Viewing a file is like visiting it, but is slanted toward moving 131 around in the file conveniently and does not allow changing the 132 file. *Note View File: Misc File Ops. 133 134 135File: emacs, Node: Marks vs Flags, Next: Operating on Files, Prev: Dired Visiting, Up: Dired 136 137Dired Marks vs. Flags 138===================== 139 140 Instead of flagging a file with `D', you can "mark" the file with 141some other character (usually `*'). Most Dired commands other than 142"expunge" (`x') operate on files marked with `*'. 143 144 Here are some commands for marking with `*' (and also for 145unmarking). (*Note Dired Deletion::, for commands to flag and unflag 146files.) 147 148`m' 149 Mark the current file with `*' (`dired-mark'). With a numeric 150 argument N, mark the next N files starting with the current file. 151 (If N is negative, mark the previous -N files.) 152 153`*' 154 Mark all executable files with `*' (`dired-mark-executables'). 155 With a prefix argument, unmark all those files. 156 157`@' 158 Mark all symbolic links with `*' (`dired-mark-symlinks'). With a 159 prefix argument, unmark all those files. 160 161`/' 162 Mark with `*' all files which are actually directories, except for 163 `.' and `..' (`dired-mark-directories'). With a prefix argument, 164 unmark all those files. 165 166`M-DEL MARKCHAR' 167 Remove all marks that use the character MARKCHAR 168 (`dired-unmark-all-files'). If you specify RET as MARKCHAR, this 169 command removes all marks, no matter what the marker character is. 170 171 With a numeric argument, this command queries about each marked 172 file, asking whether to remove its mark. You can answer `y' 173 meaning yes, `n' meaning no, `!' to remove the marks from the 174 remaining files without asking about them. 175 176`c OLD NEW' 177 Replace all marks that use the character OLD with marks that use 178 the character NEW (`dired-change-marks'). This command is the 179 only way to create or use marks other than `*' or `D'. The 180 arguments are single characters--do not use RET to terminate them. 181 182 You can use almost any character as a mark character by means of 183 this command, to distinguish various classes of files. If OLD is a 184 space (` '), then the command operates on all unmarked files; if 185 NEW is a space, then the command unmarks the files it acts on. 186 187 To illustrate the power of this command, here is how to put `*' 188 marks on all the files that are unmarked, while unmarking all 189 those that have `*' marks: 190 191 c * t c SPC * c t SPC 192 193`% m REGEXP RET' 194 Mark (with `*') all files whose names match the regular expression 195 REGEXP (`dired-mark-files-regexp'). 196 197 Only the non-directory part of the file name is used in matching. 198 Use `^' and `$' to anchor matches. Exclude subdirectories by 199 hiding them (*note Hiding Subdirectories::.). 200 201 202File: emacs, Node: Operating on Files, Next: Shell Commands in Dired, Prev: Marks vs Flags, Up: Dired 203 204Operating on Files 205================== 206 207 This section describes the basic Dired commands to operate on one 208file or several files. All of these commands are capital letters; all 209of them use the minibuffer, either to read an argument or to ask for 210confirmation, before they act. All use the following convention to 211decide which files to manipulate: 212 213 * If you give the command a numeric prefix argument N, it operates 214 on the next N files, starting with the current file. (If N is 215 negative, the command operates on the -N files preceding the 216 current line.) 217 218 * Otherwise, if some files are marked with `*', the command operates 219 on all those files. 220 221 * Otherwise, the command operates on the current file only. 222 223 Here are the commands that operate on files in this way: 224 225`C NEW RET' 226 Copy the specified files (`dired-do-copy'). The argument NEW is 227 the directory to copy into, or (if copying a single file) the new 228 name. 229 230 If `dired-copy-preserve-time' is non-`nil', then copying with this 231 command sets the modification time of the new file to be the same 232 as that of the old file. 233 234`R NEW RET' 235 Rename the specified files (`dired-do-rename'). The argument NEW 236 is the directory to rename into, or (if renaming a single file) 237 the new name. 238 239 Dired automatically changes the visited file name of buffers 240 associated with renamed files so that they refer to the new names. 241 242`H NEW RET' 243 Make hard links to the specified files (`dired-do-hardlink'). The 244 argument NEW is the directory to make the links in, or (if making 245 just one link) the name to give the link. 246 247`S NEW RET' 248 Make symbolic links to the specified files (`dired-do-symlink'). 249 The argument NEW is the directory to make the links in, or (if 250 making just one link) the name to give the link. 251 252`M MODESPEC RET' 253 Change the mode (also called "permission bits") of the specified 254 files (`dired-do-chmod'). This calls the `chmod' program, so 255 MODESPEC can be any argument that `chmod' can handle. 256 257`G NEWGROUP RET' 258 Change the group of the specified files to NEWGROUP 259 (`dired-do-chgrp'). 260 261`O NEWOWNER RET' 262 Change the owner of the specified files to NEWOWNER 263 (`dired-do-chown'). (On most systems, only the superuser can do 264 this.) 265 266 The variable `dired-chown-program' specifies the name of the 267 program to use to do the work (different systems put `chown' in 268 different places). 269 270`P COMMAND RET' 271 Print the specified files (`dired-do-print'). You must specify the 272 command to print them with, but the minibuffer starts out with a 273 suitable guess made using the variables `lpr-command' and 274 `lpr-switches' (the same variables that `lpr-file' uses; *note 275 Hardcopy::.). 276 277`Z' 278 Compress or uncompress the specified files (`dired-do-compress'). 279 If the file appears to be a compressed file, it is uncompressed; 280 otherwise, it is compressed. 281 282`L' 283 Load the specified Emacs Lisp files (`dired-do-load'). *Note Lisp 284 Libraries::. 285 286`B' 287 Byte compile the specified Emacs Lisp files 288 (`dired-do-byte-compile'). *Note Byte Compilation: (elisp)Byte 289 Compilation. 290 291 292File: emacs, Node: Shell Commands in Dired, Next: Transforming File Names, Prev: Operating on Files, Up: Dired 293 294Shell Commands in Dired 295======================= 296 297 The dired command `!' (`dired-do-shell-command') reads a shell 298command string in the minibuffer and runs the shell command on all the 299specified files. There are two ways of applying a shell command to 300multiple files: 301 302 * If you use `*' in the shell command, then it runs just once, with 303 the list of file names substituted for the `*'. The order of file 304 names is the order of appearance in the Dired buffer. 305 306 Thus, `! tar cf foo.tar * RET' runs `tar' on the entire list of 307 file names, putting them into one tar file `foo.tar'. 308 309 * If the command string doesn't contain `*', then it runs once *for 310 each file*, with the file name added at the end. 311 312 For example, `! uudecode RET' runs `uudecode' on each file. 313 314 What if you want to run the shell command once for each file but with 315the file name inserted in the middle? Or if you want to use the file 316names in a more complicated fashion? Use a shell loop. For example, 317this shell command would run `uuencode' on each of the specified files, 318writing the output into a corresponding `.uu' file: 319 320 for file in *; uuencode $file $file >$file.uu; done 321 322 The working directory for the shell command is the top level 323directory of the Dired buffer. 324 325 The `!' command does not attempt to update the Dired buffer to show 326new or modified files, because it doesn't really understand shell 327commands, and does not know what files the shell command changed. Use 328the `g' command to update the Dired buffer (*note Dired Updating::.). 329 330 331File: emacs, Node: Transforming File Names, Next: Comparison in Dired, Prev: Shell Commands in Dired, Up: Dired 332 333Transforming File Names in Dired 334================================ 335 336 Here are commands that alter file names in a systematic way: 337 338`% u' 339 Rename each of the selected files to an upper case name 340 (`dired-upcase'). If the old file names are `Foo' and `bar', the 341 new names are `FOO' and `BAR'. 342 343`% l' 344 Rename each of the selected files to a lower case name 345 (`dired-downcase'). If the old file names are `Foo' and `bar', 346 the new names are `foo' and `bar'. 347 348`% R FROM RET TO RET' 349`% C FROM RET TO RET' 350`% H FROM RET TO RET' 351`% S FROM RET TO RET' 352 These four commands rename, copy, make hard links and make soft 353 links, in each case computing the new name by regular expression 354 substitution from the name of the old file. 355 356 The four regular expression substitution commands effectively perform 357`query-replace-regexp' on the selected file names in the Dired buffer. 358They read two arguments: a regular expression FROM, and a substitution 359pattern TO. 360 361 The commands match each "old" file name against the regular 362expression FROM, and then replace the matching part with TO. You can 363use `\&' and `\DIGIT' in TO to refer to all or part of what the pattern 364matched in the old file name, as in `query-replace' (*note Query 365Replace::.). 366 367 For example, `% R ^.*$ RET x-\& RET' renames each selected file by 368prepending `x-' to its name. The inverse of this, removing `x-' from 369the front of each file name, is also possible: one method is `% R 370^x-\(.*\)$ RET \1 RET'; another is `% R ^x- RET RET'. (Use `^' and `$' 371to anchor matches that should span the whole filename.) 372 373 If the regular expression matches more than once in a file name, only 374the first match is replaced. 375 376 Normally, the replacement process does not consider the files' 377directory names; it operates on the file name within the directory. If 378you specify a prefix argument of zero, then replacement affects the 379entire absolute file name including directory name. 380 381 Often you will want to apply the command to all files matching the 382same REGEXP that you use in the command. To do this, mark those files 383with `% m REGEXP RET', then use the same regular expression in the 384command to operate on the files. To make this easier, the commands to 385operate use the last regular expression specified in a `%' command as a 386default. 387 388 389File: emacs, Node: Comparison in Dired, Next: Subdirectories in Dired, Prev: Transforming File Names, Up: Dired 390 391File Comparison with Dired 392========================== 393 394 Here are two Dired commands that compare specified files using 395`diff'. 396 397`=' 398 Compare the current file (the file at point) with another file 399 (the file at the mark) using the `diff' program (`dired-diff'). 400 The file at the mark is the first argument of `diff', and the file 401 at point is the second argument. 402 403`M-=' 404 Compare the current file with its latest backup file 405 (`dired-backup-diff'). If the current file is itself a backup, 406 compare it with the file it is a backup of; this way, you can 407 compare a file with any backup version of your choice. 408 409 The backup file is the first file given to `diff'. 410 411 412File: emacs, Node: Subdirectories in Dired, Next: Subdirectory Motion, Prev: Comparison in Dired, Up: Dired 413 414Subdirectories in Dired 415======================= 416 417 A Dired buffer displays just one directory in the normal case; but 418you can optionally include its subdirectories as well. 419 420 The simplest way to include multiple directories in one Dired buffer 421is to specify the options `-lR' for running `ls'. (If you give a 422numeric argument when you run Dired, then you can specify these options 423in the minibuffer.) That produces a recursive directory listing showing 424all subdirectories at all levels. 425 426 But usually all the subdirectories are too many; usually you will 427prefer to include specific subdirectories only. You can do this with 428the `i' command: 429 430`i' 431 Insert the contents of a subdirectory later in the buffer. 432 433 Use the `i' (`dired-maybe-insert-subdir') command on a line that 434 describes a file which is a directory. It inserts the contents of 435 that directory into the same Dired buffer, and moves there. 436 Inserted subdirectory contents follow the top-level directory of 437 the Dired buffer, just as they do in `ls -lR' output. 438 439 If the subdirectory's contents are already present in the buffer, 440 the `i' command just moves to it. 441 442 In either case, `i' sets the Emacs mark before moving, so `C-x 443 C-x' takes you back to the old position in the buffer (the line 444 describing that subdirectory). 445 446 Use the `l' command (`dired-do-redisplay') to update the 447 subdirectory's contents. Use `k' to delete the subdirectory. 448 *Note Dired Updating::. 449 450 451File: emacs, Node: Subdirectory Motion, Next: Hiding Subdirectories, Prev: Subdirectories in Dired, Up: Dired 452 453Moving Over Subdirectories 454========================== 455 456 When a Dired buffer lists subdirectories, you can use the page motion 457commands `C-x [' and `C-x ]' to move by entire directories. 458 459 The following commands move across, up and down in the tree of 460directories within one Dired buffer. They move to "directory header 461lines", which are the lines that give a directory's name, at the 462beginning of the directory's contents. 463 464`C-M-n' 465 Go to next subdirectory header line, regardless of level 466 (`dired-next-subdir'). 467 468`C-M-p' 469 Go to previous subdirectory header line, regardless of level 470 (`dired-prev-subdir'). 471 472`C-M-u' 473 Go up to the parent directory's header line (`dired-tree-up'). 474 475`C-M-d' 476 Go down in the directory tree, to the first subdirectory's header 477 line (`dired-tree-down'). 478 479 480File: emacs, Node: Hiding Subdirectories, Next: Dired Updating, Prev: Subdirectory Motion, Up: Dired 481 482Hiding Subdirectories 483===================== 484 485 "Hiding" a subdirectory means to make it invisible, except for its 486header line, via selective display (*note Selective Display::.). 487 488`$' 489 Hide or reveal the subdirectory that point is in, and move point 490 to the next subdirectory (`dired-hide-subdir'). A numeric 491 argument serves as a repeat count. 492 493`M-$' 494 Hide all subdirectories in this Dired buffer, leaving only their 495 header lines (`dired-hide-all'). Or, if any subdirectory is 496 currently hidden, make all subdirectories visible again. You can 497 use this command to get an overview in very deep directory trees 498 or to move quickly to subdirectories far away. 499 500 Ordinary Dired commands never consider files inside a hidden 501subdirectory. For example, the commands to operate on marked files 502ignore files in hidden directories even if they are marked. Thus you 503can use hiding to temporarily exclude subdirectories from operations 504without having to remove the markers. 505 506 The subdirectory hiding commands toggle; that is they unhide what was 507hidden and vice versa. 508 509 510File: emacs, Node: Dired Updating, Next: Dired and Find, Prev: Hiding Subdirectories, Up: Dired 511 512Updating the Dired Buffer 513========================= 514 515 This section describes commands to update the Dired buffer to reflect 516outside (non-Dired) changes in the directories and files, and to delete 517part of the Dired buffer. 518 519`g' 520 Update the entire contents of the Dired buffer (`revert-buffer'). 521 522`l' 523 Update the specified files (`dired-do-redisplay'). 524 525`k' 526 Delete the specified *file lines*--not the files, just the lines 527 (`dired-do-kill-lines'). 528 529`s' 530 Toggle between sorting by file name and sorting by date/time 531 (`dired-sort-toggle-or-edit'). 532 533`C-u s SWITCHES' 534 Refresh the Dired buffer using SWITCHES as 535 `dired-listing-switches'. 536 537 Type `g' (`revert-buffer') to update the contents of the Dired 538buffer, based on changes in the files and directories listed. This 539preserves all marks except for those on files that have vanished. 540Hidden subdirectories are updated but remain hidden. 541 542 To update only some of the files, type `l' (`dired-do-redisplay'). 543This command applies to the next N files, or to the marked files if 544any, or to the current file. Updating them means reading their current 545status from the file system and changing the buffer to reflect it 546properly. 547 548 If you use `l' on a subdirectory header line, it updates the 549contents of the corresponding subdirectory. 550 551 To delete the specified *file lines*--not the files, just the 552lines--type `k' (`dired-do-kill-lines'). This command applies to the 553next N files, or to the marked files if any, or to the current file. 554 555 If you kill the line for a file that is a directory, the directory's 556contents are also deleted from the buffer. Typing `C-u k' on the 557header line for a subdirectory is another way to delete a subdirectory 558from the Dired buffer. 559 560 The `g' command brings back any individual lines that you have 561killed in this way, but not subdirectories--you must use `i' to 562reinsert each subdirectory. 563 564 The files in a Dired buffers are normally in listed alphabetical 565order by file names. Alternatively Dired can sort them by date/time. 566The Dired command `s' (`dired-sort-toggle-or-edit') switches between 567these two sorting modes. 568 569 The mode line in a Dired buffer indicates which way it is currently 570sorted--by name, or by date. 571 572 `C-u s SWITCHES RET' lets you specify a new value for 573`dired-listing-switches'. 574 575 576File: emacs, Node: Dired and Find, Prev: Dired Updating, Up: Dired 577 578Dired and `find' 579================ 580 581 You can select a set of files for display in a Dired buffer more 582flexibly by using the `find' utility to choose the files. 583 584 To search for files with names matching a wildcard pattern use `M-x 585find-name-dired'. It reads arguments DIRECTORY and PATTERN, and 586chooses all the files in DIRECTORY or its subdirectories whose 587individual names match PATTERN. 588 589 The files thus chosen are displayed in a Dired buffer in which the 590ordinary Dired commands are available. 591 592 If you want to test the contents of files, rather than their names, 593use `M-x find-grep-dired'. This command reads two minibuffer 594arguments, DIRECTORY and REGEXP; it chooses all the files in DIRECTORY 595or its subdirectories that contain a match for REGEXP. It works by 596running the programs `find' and `grep'. 597 598 The most general command in this series is `M-x find-dired', which 599lets you specify any condition that `find' can test. It takes two 600minibuffer arguments, DIRECTORY and FIND-ARGS; it runs `find' in 601DIRECTORY, passing FIND-ARGS to tell `find' what condition to test. To 602use this command, you need to know how to use `find'. 603 604 605File: emacs, Node: Calendar/Diary, Next: GNUS, Prev: Dired, Up: Top 606 607The Calendar and the Diary 608************************** 609 610 Emacs provides the functions of a desk calendar, with a diary of 611planned or past events. To enter the calendar, type `M-x calendar'; 612this displays a three-month calendar centered on the current month, with 613point on the current date. If you use prefix argument as in `C-u M-x 614calendar', it prompts you for the month and year to be the center of 615the three-month calendar. The calendar uses its own buffer and the 616major mode is Calendar mode. 617 618 *Note Customizing the Calendar and Diary: (elisp)Calendar, for 619customization information about the calendar and diary. 620 621 To exit the calendar, type `q'. `Mouse-3' in the calendar brings up 622a menu of commonly used calendar features. 623 624* Menu: 625 626* Calendar Motion:: Moving through the calendar; selecting a date. 627* Scroll Calendar:: Bringing earlier or later months onto the screen. 628* Counting Days:: How many days are there between two dates? 629* General Calendar:: Exiting or recomputing the calendar. 630* Holidays:: Displaying dates of holidays. 631* Sunrise/Sunset:: Displaying local times of sunrise and sunset. 632* Lunar Phases:: Displaying phases of the moon. 633* Other Calendars:: Converting dates to other calendar systems. 634* Diary:: Displaying events from your diary. 635* Appointments:: Reminders when it's time to do something. 636* Daylight Savings:: How to specify when daylight savings time is active. 637 638 639File: emacs, Node: Calendar Motion, Next: Scroll Calendar, Up: Calendar/Diary 640 641Movement in the Calendar 642======================== 643 644 Calendar mode lets you move in logical units of time such as days, 645weeks, months, and years. If you move outside the three months 646originally displayed, the calendar display scrolls automatically through 647time. Moving to a date lets you view its holidays or diary entries, 648convert it to other calendars; moving longer time periods is useful 649simply to scroll the calendar. 650 651* Menu: 652 653* Calendar Unit Motion:: Moving by days, weeks, months, and years. 654* Move to Beginning or End:: Moving to start/end of weeks, months, and years. 655* Specified Dates:: Moving to the current date or another 656 specific date. 657 658 659File: emacs, Node: Calendar Unit Motion, Next: Move to Beginning or End, Up: Calendar Motion 660 661Motion by Integral Days, Weeks, Months, Years 662--------------------------------------------- 663 664 The commands for movement in the calendar buffer parallel the 665commands for movement in text. You can move forward and backward by 666days, weeks, months, and years. 667 668`C-f' 669 Move point one day forward (`calendar-forward-day'). 670 671`C-b' 672 Move point one day backward (`calendar-backward-day'). 673 674`C-n' 675 Move point one week forward (`calendar-forward-week'). 676 677`C-p' 678 Move point one week backward (`calendar-backward-week'). 679 680`M-}' 681 Move point one month forward (`calendar-forward-month'). 682 683`M-{' 684 Move point one month backward (`calendar-backward-month'). 685 686`C-x ]' 687 Move point one year forward (`calendar-forward-year'). 688 689`C-x [' 690 Move point one year backward (`calendar-forward-year'). 691 692 The day and week commands are natural analogues of the usual Emacs 693commands for moving by characters and by lines. Just as `C-n' usually 694moves to the same column in the following line, in Calendar mode it 695moves to the same day in the following week. And `C-p' moves to the 696same day in the previous week. 697 698 The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just 699as they normally are in other modes. 700 701 The commands for motion by months and years work like those for 702weeks, but move a larger distance. The month commands `M-}' and `M-{' 703move forward or backward by an entire month's time. The year commands 704`C-x ]' and `C-x [' move forward or backward a whole year. 705 706 The easiest way to remember these commands is to consider months and 707years analogous to paragraphs and pages of text, respectively. But the 708commands themselves are not quite analogous. The ordinary Emacs 709paragraph commands move to the beginning or end of a paragraph, whereas 710these month and year commands move by an entire month or an entire 711year, which usually involves skipping across the end of a month or year. 712 713 All these commands accept a numeric argument as a repeat count. For 714convenience, the digit keys and the minus sign specify numeric 715arguments in Calendar mode even without the Meta modifier. For example, 716`100 C-f' moves point 100 days forward from its present location. 717 718 719File: emacs, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion 720 721Beginning or End of Week, Month or Year 722--------------------------------------- 723 724 A week (or month, or year) is not just a quantity of days; we think 725of new weeks (months, years) as starting on particular days. So 726Calendar mode provides commands to move to the beginning or end of a 727week, month or year: 728 729`C-a' 730 Move point to beginning of week (`calendar-beginning-of-week'). 731 732`C-e' 733 Move point to end of week (`calendar-end-of-week'). 734 735`M-a' 736 Move point to beginning of month (`calendar-beginning-of-month'). 737 738`M-e' 739 Move point to end of month (`calendar-end-of-month'). 740 741`M-<' 742 Move point to beginning of year (`calendar-beginning-of-year'). 743 744`M->' 745 Move point to end of year (`calendar-end-of-year'). 746 747 These commands also take numeric arguments as repeat counts, with the 748repeat count indicating how many weeks, months, or years to move 749backward or forward. 750 751 By default, weeks begin on Sunday. To make them begin on Monday 752instead, set the variable `calendar-week-start-day' to 1. 753 754 755File: emacs, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion 756 757Particular Dates 758---------------- 759 760 Calendar mode provides commands for getting to a particular date 761specified absolutely. 762 763`g d' 764 Move point to specified date (`calendar-goto-date'). 765 766`o' 767 Center calendar around specified month (`calendar-other-month'). 768 769`.' 770 Move point to today's date (`calendar-current-month'). 771 772 `g d' (`calendar-goto-date') prompts for a year, a month, and a day 773of the month, and then moves to that date. Because the calendar 774includes all dates from the beginning of the current era, you must type 775the year in its entirety; that is, type `1990', not `90'. 776 777 `o' (`calendar-other-month') prompts for a month and year, then 778centers the three-month calendar around that month. 779 780 You can return to today's date with `.' (`calendar-current-month'). 781 782 783File: emacs, Node: Scroll Calendar, Next: Counting Days, Prev: Calendar Motion, Up: Calendar/Diary 784 785Scrolling in the Calendar 786========================= 787 788 The calendar display scrolls automatically through time when you 789move out of the visible portion. You can also scroll it manually. 790Imagine that the calendar window contains a long strip of paper with 791the months on it. Scrolling it means moving the strip so that new 792months become visible in the window. 793 794`C-x <' 795 Scroll calendar one month forward (`scroll-calendar-left'). 796 797`C-x >' 798 Scroll calendar one month backward (`scroll-calendar-right'). 799 800`C-v' 801`NEXT' 802 Scroll calendar three months forward 803 (`scroll-calendar-left-three-months'). 804 805`M-v' 806`PRIOR' 807 Scroll calendar three months backward 808 (`scroll-calendar-right-three-months'). 809 810`SPC' 811 Scroll the next window (`scroll-other-window'). 812 813 The most basic calendar scroll commands scroll by one month at a 814time. This means that there are two months of overlap between the 815display before the command and the display after. `C-x <' scrolls the 816calendar contents one month to the left; that is, it moves the display 817forward in time. `C-x >' scrolls the contents to the right, which 818moves backwards in time. 819 820 The commands `C-v' and `M-v' scroll the calendar by an entire 821"screenful"--three months--in analogy with the usual meaning of these 822commands. `C-v' makes later dates visible and `M-v' makes earlier 823dates visible. These commands take a numeric argument as a repeat 824count; in particular, since `C-u' (`universal-argument') multiplies the 825next command by four, typing `C-u C-v' scrolls the calendar forward by 826a year and typing `C-u M-v' scrolls the calendar backward by a year. 827 828 The function keys NEXT and PRIOR are equivalent to `C-v' and `M-v', 829just as they are in other modes. 830 831 In Calendar mode, you can use `SPC' (`scroll-other-window') to 832scroll the other window. This is handy when you display a list of 833holidays or diary entries in another window. 834 835 836File: emacs, Node: Counting Days, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary 837 838Counting Days 839============= 840 841`M-=' 842 Display the number of days in the current region 843 (`calendar-count-days-region'). 844 845 To determine the number of days in the region, type `M-=' 846(`calendar-count-days-region'). The numbers of days printed is 847*inclusive*; that is, it includes the days specified by mark and point. 848 849 850File: emacs, Node: General Calendar, Next: Holidays, Prev: Counting Days, Up: Calendar/Diary 851 852Miscellaneous Calendar Commands 853=============================== 854 855`p d' 856 Display day-in-year (`calendar-print-day-of-year'). 857 858`C-c C-l' 859 Regenerate the calendar window (`redraw-calendar'). 860 861`q' 862 Exit from calendar (`exit-calendar'). 863 864 To print the number of days elapsed since the start of the year, or 865the number of days remaining in the year, type the `p d' command 866(`calendar-print-day-of-year'). This displays both of those numbers in 867the echo area. The number of days elapsed includes the selected date. 868The number of days remaining does not include that date. 869 870 If the calendar window gets corrupted, type `C-c C-l' 871(`redraw-calendar') to redraw it. 872 873 To exit from the calendar, type `q' (`exit-calendar'). This buries 874all buffers related to the calendar and returns the window display to 875what it was when you entered the calendar. 876 877 878File: emacs, Node: Holidays, Next: Sunrise/Sunset, Prev: General Calendar, Up: Calendar/Diary 879 880Holidays 881======== 882 883 The Emacs calendar knows about all major and many minor holidays, 884and can display them. 885 886`h' 887 Display holidays for the selected date 888 (`calendar-cursor-holidays'). 889 890`Mouse-2 Holidays' 891 Display any diary entries for the date you click on. 892 893`x' 894 Mark holidays in the calendar window (`mark-calendar-holidays'). 895 896`u' 897 Unmark calendar window (`calendar-unmark'). 898 899`a' 900 List all holidays for the displayed three months in another window 901 (`list-calendar-holidays'). 902 903`M-x holidays' 904 List all holidays for three months around today's date in another 905 window. 906 907 To see if any holidays fall on a given date, position point on that 908date in the calendar window and use the `h' command. Alternatively, 909click on that date with `Mouse-2' and then choose `Holidays' from the 910menu that appears. Either operation displays the holidays for that 911date, in the echo area if they fit there, otherwise in a separate 912window. 913 914 To find the distribution of holidays for a wider period, use the `x' 915command. This displays the dates on which holidays fall in a different 916face (or places a `*' after these dates, if display with multiple faces 917is not available). The command applies both to the currently visible 918months and to other months that subsequently become visible by 919scrolling. To turn marking off and erase the current marks, type `u', 920which also erases any diary marks (*note Diary::.). 921 922 To get even more detailed information, use the `a' command, which 923displays a separate buffer containing a list of all holidays in the 924current three-month range. 925 926 The command `M-x holidays' displays the list of holidays for the 927current month and the preceding and succeeding months; this works even 928if you don't have a calendar window. If you want the list of holidays 929centered around a different month, use `C-u M-x holidays', which 930prompts for the month and year. 931 932 The holidays known to Emacs include American holidays and the major 933Christian, Jewish, and Islamic holidays; also the solstices and 934equinoxes. 935 936 The dates used by Emacs for holidays are based on *current 937practice*, not historical fact. Historically, for instance, the start 938of daylight savings time and even its existence have varied from year to 939year, but present American law mandates that daylight savings time 940begins on the first Sunday in April. In an American locale, Emacs 941always uses this definition, even though it is wrong for some prior 942years. 943 944 945File: emacs, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary 946 947Times of Sunrise and Sunset 948=========================== 949 950 Emacs can tell you, to within a minute or two, the times of sunrise 951and sunset for any date. 952 953`S' 954 Display times of sunrise and sunset for the selected date 955 (`calendar-sunrise-sunset'). 956 957`Mouse-2 Sunrise/sunset' 958 Display times of sunrise and sunset for the date you click on. 959 960`M-x sunrise-sunset' 961 Display times of sunrise and sunset for today's date. 962 963`C-u M-x sunrise-sunset' 964 Display times of sunrise and sunset for a specified date. 965 966 Within the calendar, to display the *local times* of sunrise and 967sunset in the echo area, move point to the date you want, and type `S'. 968Alternatively, click `Mouse-2' on the date, then choose 969`Sunrise/sunset' from the menu that appears. 970 971 The command `M-x sunrise-sunset' is available outside the calendar 972to print this information for today's date or a specified date. To 973specify a date other than today, use `C-u M-x sunrise-sunset', which 974prompts for the year, month, and day. 975 976 Because the times of sunrise and sunset depend on the location on 977earth, you need to tell Emacs your latitude, longitude, and location 978name before using these commands. Here is an example of what to set: 979 980 (setq calendar-latitude 40.1) 981 (setq calendar-longitude -88.2) 982 (setq calendar-location-name "Urbana, IL") 983 984Use one decimal place in the values of `calendar-latitude' and 985`calendar-longitude'. 986 987 Your time zone also affects the local time of sunrise and sunset. 988Emacs usually gets this information from the operating system, but if 989these values are not what you want (or if the operating system does not 990supply them), you must set them yourself. Here is an example: 991 992 (setq calendar-time-zone -360) 993 (setq calendar-standard-time-zone-name "CST") 994 (setq calendar-daylight-time-zone-name "CDT") 995 996The value of `calendar-time-zone' is the number of minutes difference 997between your local standard time and Coordinated Universal Time 998(Greenwich time). The values of `calendar-standard-time-zone-name' and 999`calendar-daylight-time-zone-name' are the abbreviations used in your 1000time zone. 1001 1002 Emacs displays the times of sunrise and sunset *corrected for 1003daylight savings time*. *Note Daylight Savings::, for how daylight 1004savings time is determined. 1005 1006 You can display the times of sunrise and sunset for any location and 1007any date with `C-u C-u M-x sunrise-sunset'. This asks you for a 1008longitude, latitude, number of minutes difference from Coordinated 1009Universal Time, and date, and then tells you the times of sunrise and 1010sunset for that location on that date. 1011 1012 1013File: emacs, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary 1014 1015Phases of the Moon 1016================== 1017 1018 Emacs can tell you the dates and times of the phases of the moon (new 1019moon, first quarter, full moon, last quarter). This feature is useful 1020for debugging problems that "depend on the phase of the moon." 1021 1022`M' 1023 Display the dates and times for all the quarters of the moon for 1024 the three-month period shown (`calendar-phases-of-moon'). 1025 1026`M-x phases-of-moon' 1027 Display dates and times of the quarters of the moon for three 1028 months around today's date. 1029 1030 Within the calendar, use the `M' command to display a separate 1031buffer of the phases of the moon for the current three-month range. The 1032dates and times listed are accurate to within a few minutes. 1033 1034 Outside the calendar, use the command `M-x phases-of-moon' to 1035display the list of the phases of the moon for the current month and the 1036preceding and succeeding months. For information about a different 1037month, use `C-u M-x phases-of-moon', which prompts for the month and 1038year. 1039 1040 The dates and times given for the phases of the moon are given in 1041local time (corrected for daylight savings, when appropriate); but if 1042the variable `calendar-time-zone' is void, Coordinated Universal Time 1043(the Greenwich time zone) is used. *Note Daylight Savings::. 1044 1045 1046File: emacs, Node: Other Calendars, Next: Diary, Prev: Lunar Phases, Up: Calendar/Diary 1047 1048Conversion To and From Other Calendars 1049====================================== 1050 1051 The Emacs calendar displayed is *always* the Gregorian calendar, 1052sometimes called the "new style" calendar, which is used in most of the 1053world today. However, this calendar did not exist before the sixteenth 1054century and was not widely used before the eighteenth century; it did 1055not fully displace the Julian calendar and gain universal acceptance 1056until the early twentieth century. The Emacs calendar can display any 1057month since January, year 1 of the current era, but the calendar 1058displayed is the Gregorian, even for a date at which the Gregorian 1059calendar did not exist. 1060 1061 While Emacs cannot display other calendars, it can convert dates to 1062and from several other calendars. 1063 1064* Menu: 1065 1066* Calendar Systems:: The calendars Emacs understands 1067 (aside from Gregorian). 1068* To Other Calendar:: Converting the selected date to various calendars. 1069* From Other Calendar:: Moving to a date specified in another calendar. 1070* Mayan Calendar:: Moving to a date specified in a Mayan calendar. 1071 1072 1073File: emacs, Node: Calendar Systems, Next: To Other Calendar, Up: Other Calendars 1074 1075Supported Calendar Systems 1076-------------------------- 1077 1078 The ISO commercial calendar is used largely in Europe. 1079 1080 The Julian calendar, named after Julius Caesar, was the one used in 1081Europe throughout medieval times, and in many countries up until the 1082nineteenth century. 1083 1084 Astronomers use a simple counting of days elapsed since noon, Monday, 1085January 1, 4713 B.C. on the Julian calendar. The number of days elapsed 1086is called the *Julian day number* or the *Astronomical day number*. 1087 1088 The Hebrew calendar is the one used to determine the dates of Jewish 1089holidays. Hebrew calendar dates begin and end at sunset. 1090 1091 The Islamic (Moslem) calendar is the one used to determine the dates 1092of Moslem holidays. There is no universal agreement in the Islamic 1093world about the calendar; Emacs uses a widely accepted version, but the 1094precise dates of Islamic holidays often depend on proclamation by 1095religious authorities, not on calculations. As a consequence, the 1096actual dates of occurrence can vary slightly from the dates computed by 1097Emacs. Islamic calendar dates begin and end at sunset. 1098 1099 The French Revolutionary calendar was created by the Jacobins after 1100the 1789 revolution, to represent a more secular and nature-based view 1101of the annual cycle, and to install a 10-day week in a rationalization 1102measure similar to the metric system. The French government officially 1103abandoned this calendar at the end of 1805. 1104 1105 The Maya of Central America used three separate, overlapping calendar 1106systems, the *long count*, the *tzolkin*, and the *haab*. Emacs knows 1107about all three of these calendars. Experts dispute the exact 1108correlation between the Mayan calendar and our calendar; Emacs uses the 1109Goodman-Martinez-Thompson correlation in its calculations. 1110 1111 1112File: emacs, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars 1113 1114Converting To Other Calendars 1115----------------------------- 1116 1117 The following commands describe the selected date (the date at point) 1118in various other calendar systems: 1119 1120`Mouse-2 Other calendars' 1121 Display the date that you click on, expressed in various other 1122 calendars. 1123 1124`p c' 1125 Display ISO commercial calendar equivalent for selected day 1126 (`calendar-print-iso-date'). 1127 1128`p j' 1129 Display Julian date for selected day 1130 (`calendar-print-julian-date'). 1131 1132`p a' 1133 Display astronomical (Julian) day number for selected day 1134 (`calendar-print-astro-day-number'). 1135 1136`p h' 1137 Display Hebrew date for selected day 1138 (`calendar-print-hebrew-date'). 1139 1140`p i' 1141 Display Islamic date for selected day 1142 (`calendar-print-islamic-date'). 1143 1144`p f' 1145 Display French Revolutionary date for selected day 1146 (`calendar-print-french-date'). 1147 1148`p m' 1149 Display Mayan date for selected day (`calendar-print-mayan-date'). 1150 1151 If you are using X windows, the easiest way to translate a date into 1152other calendars is to click on it with `Mouse-2', then choose `Other 1153calendars' from the menu that appears. This displays the equivalent 1154forms of the date in all the calendars Emacs understands, in the form 1155of a menu. (Choosing an alternative from this menu doesn't actually do 1156anything--the menu is used only for display.) 1157 1158 Put point on the desired date of the Gregorian calendar, then type 1159the appropriate keys. The `p' is a mnemonic for "print" since Emacs 1160"prints" the equivalent date in the echo area. 1161 1162 1163File: emacs, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars 1164 1165Converting From Other Calendars 1166------------------------------- 1167 1168 You can move to dates that you specify on the Commercial, Julian, 1169astronomical, Hebrew, Islamic, or French calendars: 1170 1171`g c' 1172 Move to a date specified in the ISO commercial calendar 1173 (`calendar-goto-iso-date'). 1174 1175`g j' 1176 Move to a date specified in the Julian calendar 1177 (`calendar-goto-julian-date'). 1178 1179`g a' 1180 Move to a date specified in astronomical (Julian) day number 1181 (`calendar-goto-astro-day-number'). 1182 1183`g h' 1184 Move to a date specified in the Hebrew calendar 1185 (`calendar-goto-hebrew-date'). 1186 1187`g i' 1188 Move to a date specified in the Islamic calendar 1189 (`calendar-goto-islamic-date'). 1190 1191`g f' 1192 Move to a date specified in the French Revolutionary calendar 1193 (`calendar-goto-french-date'). 1194 1195 These commands ask you for a date on the other calendar, move point 1196to the Gregorian calendar date equivalent to that date, and display the 1197other calendar's date in the echo area. Emacs uses strict completion 1198(*note Completion::.) whenever it asks you to type a month name, so you 1199don't have to worry about the spelling of Hebrew, Islamic, or French 1200names. 1201 1202 One common question concerning the Hebrew calendar is the computation 1203of the anniversary of a date of death, called a "yahrzeit." The Emacs 1204calendar includes a facility for such calculations. If you are in the 1205calendar, the command `M-x list-yahrzeit-dates' asks you for a range of 1206years and then displays a list of the yahrzeit dates for those years 1207for the date given by point. If you are not in the calendar, this 1208command first asks you for the date of death and the range of years, 1209and then displays the list of yahrzeit dates. 1210 1211 1212File: emacs, Node: Mayan Calendar, Prev: From Other Calendar, Up: Other Calendars 1213 1214Converting from the Mayan Calendar 1215---------------------------------- 1216 1217 Here are the commands to select dates based on the Mayan calendar: 1218 1219`g m l' 1220 Move to a date specified by the long count calendar 1221 (`calendar-goto-mayan-long-count-date'). 1222 1223`g m p t' 1224 Move to the previous occurrence of a place in the tzolkin calendar 1225 (`calendar-previous-tzolkin-date'). 1226 1227`g m n t' 1228 Move to the next occurrence of a place in the tzolkin calendar 1229 (`calendar-next-tzolkin-date'). 1230 1231`g m p h' 1232 Move to the previous occurrence of a place in the haab calendar 1233 (`calendar-previous-haab-date'). 1234 1235`g m n h' 1236 Move to the next occurrence of a place in the haab calendar 1237 (`calendar-next-haab-date'). 1238 1239`g m p c' 1240 Move to the previous occurrence of a place in the calendar round 1241 (`calendar-previous-calendar-round-date'). 1242 1243`g m n c' 1244 Move to the next occurrence of a place in the calendar round 1245 (`calendar-next-calendar-round-date'). 1246 1247 To understand these commands, you need to understand the Mayan 1248calendars. The "long count" is a counting of days with these units: 1249 1250 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal 1251 1 katun = 20 tun 1 baktun = 20 katun 1252 1253Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 1254tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long 1255count dates as early as 7.17.18.13.1, but no earlier. When you use the 1256`g m l' command, type the Mayan long count date with the baktun, katun, 1257tun, uinal, and kin separated by periods. 1258 1259 The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of 1260independent cycles of 13 and 20 days. Since this cycle repeats 1261endlessly, Emacs provides commands to move backward and forward to the 1262previous or next point in the cycle. Type `g m p t' to go to the 1263previous tzolkin date; Emacs asks you for a tzolkin date and moves point 1264to the previous occurrence of that date. Similarly, type `g m n t' to 1265go to the next occurrence of a tzolkin date. 1266 1267 The Mayan haab calendar is a cycle of 365 days arranged as 18 months 1268of 20 days each, followed a 5-day monthless period. Like the tzolkin 1269cycle, this cycle repeats endlessly, and there are commands to move 1270backward and forward to the previous or next point in the cycle. Type 1271`g m p h' to go to the previous haab date; Emacs asks you for a haab 1272date and moves point to the previous occurrence of that date. 1273Similarly, type `g m n h' to go to the next occurrence of a haab date. 1274 1275 The Maya also used the combination of the tzolkin date and the haab 1276date. This combination is a cycle of about 52 years called a *calendar 1277round*. If you type `g m p c', Emacs asks you for both a haab and a 1278tzolkin date and then moves point to the previous occurrence of that 1279combination. Use `g m p c' to move point to the next occurrence of a 1280combination. Emacs signals an error if the haab/tzolkin date you have 1281typed is impossible. 1282 1283 Emacs uses strict completion (*note Completion::.) whenever it asks 1284you to type a Mayan name, so you don't have to worry about spelling. 1285 1286