summaryrefslogtreecommitdiff
path: root/doc/misc/todo-mode.texi
blob: d68af9a23a0f0dbb75ad22b7e966c1aa09afe756 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
\input texinfo.tex   @c -*-texinfo-*-
@c %**start of header
@setfilename ../../info/todo-mode.info
@settitle Todo Mode User Manual
@include docstyle.texi
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@c %**end of header

@copying
Copyright @copyright{} 2013-2016 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs misc features
@direntry
* Todo Mode: (todo-mode).       Make and maintain todo lists.
@end direntry

@titlepage
@title Todo Mode User Manual
@subtitle Facilities for making and maintaining todo lists.

@author Stephen Berman
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex

@node Top
@top Todo Mode User Manual

This manual describes the version of Todo mode first appearing in
Emacs 24.4.

@insertcopying
@end ifnottex

@menu
* Overview::
* Todo Mode Entry Points::
* Key Binding Conventions::
* Navigation::                  Moving within and between categories.
* Editing::                     Adding, deleting and changing todo
                                  files, categories and items.
* Todo Archives::               Files of done todo items.
* Marked Items::                Acting on multiple items simultaneously.
* Todo Categories Mode::        Table of categories and item counts.
* Searching for Items::
* Todo Filtered Items Mode::    Making virtual categories of items from
                                  different categories and files.
* Todo Display Features::
* Printing Todo Buffers::
* Legacy Todo Mode Files::      Converting old-style todo files.

* GNU Free Documentation License::

@detailmenu
--- The Detailed Node Listing ---

Overview

* Levels of Organization::
* Todo Items as Diary Entries::

Editing

* File Editing::
* Category Editing::
* Item Editing::

Item Editing

* Inserting New Items::
* Editing Item Headers and Text::
* Relocating and Removing Items::

Relocating and Removing Items

* Reprioritizing Items::
* Moving and Deleting Items::
* Done Items::

Todo Archives

* Creating and Visiting Archives::
* Todo Archive Mode::

Todo Categories Mode

* Table of Item Counts::
* Reordering Categories::

Todo Filtered Items Mode

* Filtering Items::
* Todo Filtered Items Mode Commands::
* Files of Filtered Items::

Todo Display Features

* Faces::
* Item Prefix::
* Other Display Commands and Options::
@end detailmenu
@end menu

@node Overview, Todo Mode Entry Points, Top, Top
@chapter Overview

The Todo mode package provides facilities for making and maintaining
todo lists.  A todo list is a list of todo items---things to do (in the
widest sense)---arranged in order of priority, with the highest priority
item at the top of the list and the lowest priority item at the bottom.

This manual describes the Todo mode user interface.  Todo mode comprises
a large number of commands and user options for creating, displaying,
navigating and editing todo lists, distributed across five major modes.
The principle major mode is Todo mode; the other four (Todo Edit mode,
Todo Archive mode, Todo Categories mode, and Todo Filtered Items mode)
are subsidiary to and accessible from Todo mode.

This version of Todo mode greatly expands on, and in significant ways
differs from, the original version; for details and consequences of the
most important differences, @ref{Legacy Todo Mode Files}.

@menu
* Levels of Organization::
* Todo Items as Diary Entries::
@end menu

@node Levels of Organization, Todo Items as Diary Entries, , Overview
@section Levels of Organization

In Todo mode each todo list is identified with a named category, so you
can group together thematically related todo items.  Each category is
stored in a file, which thus provides a further level of organization.
You can create as many todo files, and in each as many categories, as
you want.

All todo files reside in a single directory, whose location is specified
by the user option @code{todo-directory}.  This directory may also
contain other types of Todo files, which are discussed later
(@pxref{Todo Archive Mode} and @ref{Todo Filtered Items Mode}).
@c Emacs recognizes Todo files by their extension, so when you visit
@c the files the buffer is in the appropriate mode and the current
@c category is correctly displayed.
When you use a Todo mode command to create a todo file, the extension
@samp{.todo} is automatically added to the base name you choose (as a
rule, this name is also used for the other types of Todo files, which
have their own extensions).  As a user, you only have to deal with the
base name of a Todo file.

When you create a new todo file, you must also add at least one category
to it, and each todo item belongs to a category.  It is not possible to
have an uncategorized todo list, but you can always make a catch-all
category with a generic name like ``Todo'', which is in fact the default
name assigned to the first category when you create a new todo file, if
you don't provide a different name; you can change the default by
customizing @code{todo-initial-category}.

The most basic level of organization is the todo item itself, since it
contains the information about what you want to do.  As detailed in
subsequent sections of this manual, most Todo mode commands and user
options concern ways of classifying and deploying this information by
associating various kinds of metadata with it, e.g., the category it
belongs to, its priority, whether it is to be included in the Emacs
diary, date and time stamps, whether it is done or still to do.

@node Todo Items as Diary Entries, , Levels of Organization, Overview
@section Todo Items as Diary Entries

You can have todo items show up in the Emacs Fancy Diary display by
including the todo file in your diary file (@pxref{Fancy Diary
Display,,, emacs}).  This effectively augments the Emacs diary with
categorized diary entries.  All items in an included todo file will
appear in the Fancy Diary display except for those that are marked
with @code{todo-nondiary-marker}.  You can add or omit this marking
upon creating a new todo item, or you can do so by editing an existing
item, see @ref{Inserting New Items} and @ref{Editing Item Headers and
Text} for details.

To ensure the proper display of todo items in the Fancy Diary display,
they must have the format of diary entries, i.e., they have to begin
with a date string recognized by the Emacs diary,@footnote{Two types of
dates recognized by the Emacs diary are not supported in the current
Todo mode implementation: sexp diary entries and date strings in which
the year is omitted (however, the latter type is equivalent to using
@samp{*} for an arbitrary year, which Todo mode does support).} and if
they are longer than one line, all lines but the first must begin with
white space.  Todo mode ensures that these requirements are satisfied
(@pxref{Other Display Commands and Options}).

The Fancy Diary display is also Todo mode aware: if it contains an item
from a Todo mode file, clicking or typing @key{RET} on this item will
switch to the buffer visiting that file and properly display the item's
category, with point on the item.

@node Todo Mode Entry Points, Key Binding Conventions, Overview, Top
@chapter Todo Mode Entry Points

To initialize your first todo file, invoke the command @code{todo-show}.
This prompts you for a file name (defaulting to the value of
@code{todo-initial-file}), prompts you for the name of the first
category (defaulting to the value of @code{todo-initial-category}),
creates and visits the file and displays the category in Todo mode, and
then prompts you to enter the first item.  If you choose not to enter an
item now, simply type @kbd{C-g}, which leaves the category empty but
otherwise well-formed.  If you prefer not to be prompted to enter an
item on adding a new category, disable the option
@code{todo-add-item-if-new-category}.

Once at least one todo file exists, invoking @code{todo-show} enters
Todo mode.  Invoked with a prefix argument, the command prompts for
which todo file to visit.  Otherwise, the first invocation of this
command after loading the Todo mode package visits the default todo file
(option @code{todo-default-todo-file}) and shows its first category.
(You can get a different display with the first invocation of
@code{todo-show} by customizing the option @code{todo-show-first};
@pxref{Todo Categories Mode} and @ref{Files of Filtered Items}.)

If you leave Todo mode and later invoke @code{todo-show} to re-enter it,
by default this returns you to the current (i.e., last displayed)
category of the current todo file, which is the one in the most recently
selected and still live buffer visiting a todo file.  If you disable the
option @code{todo-show-current-file}, then non-initial invocations of
@code{todo-show} always return to the first or current category of the
default todo file.

If you want to enter Todo mode and go directly to a specific category
instead the first or current category in the current or default todo
file, use the command @code{todo-jump-to-category}; @ref{Navigation},
for details.  You can also enter Todo mode by invoking the command
@code{todo-insert-item}; @ref{Inserting New Items}, for details.

The most convenient way to use these commands to enter Todo mode is to
define global key bindings for them in your init file.  Good choices
are @kbd{C-c t} for @code{todo-show}, @kbd{C-c j} for
@code{todo-jump-to-category} and @kbd{C-c i} for
@code{todo-insert-item}, since these commands are bound to @kbd{t},
@kbd{j} and @kbd{i}, respectively, in Todo mode.

@c You can also visit a Todo file via @code{find-file} or Dired, like any
@c other file, and since Emacs recognizes it, the buffer will automatically
@c be in the appropriate Todo mode.  Moreover, as long as the command you
@c use to visit the file is listed in the option
@c @code{todo-visit-files-commands} (which by default contains
@c @code{find-file} and @code{dired-find-file}), it will also correctly
@c display the file's first category on first visiting the file (otherwise
@c you have to use one of the commands for navigating between categories in
@c order to get a proper display).

You can leave Todo mode by typing @kbd{q} (@code{todo-quit}), which
buries the current todo file buffer.  Doing this also saves any changes
you have made to the file, and leaves both the file and the category
that was displayed on quitting current for subsequent Todo mode commands
(unless the buffer made current by quitting is visiting another file and
category in Todo mode, in which case the latter become current for Todo
mode commands).

@node Key Binding Conventions, Navigation, Todo Mode Entry Points, Top
@chapter Key Binding Conventions

For Todo mode commands to function properly, it is essential to maintain
the correct format at all three levels of organization---item, category,
and file.  Todo mode tries to minimize the risk of format corruption by
hiding certain parts of the format from the user, making the buffer
read-only and suppressing the self-insertion keys.  Consequently, it is
normally impossible to make changes to your todo files without
explicitly invoking Todo mode commands.

A beneficial side effect of this restrictiveness is that you can invoke
almost all Todo commands by typing ordinary printing characters, either
singly or in specified sequences, without using modifier keys, except
for the shift key for capitalization and the raw prefix argument
@kbd{C-u}; numeric prefix arguments can be entered just by typing a
number key.

The predefined key bindings in Todo are more or less mnemonic.  As a
rule, key sequences beginning with @kbd{C} (capital @samp{C}, not the
control key) are bound to commands applying to categories, sequences
beginning with @kbd{F} apply to (non-archive) file-level commands, and
those beginning with @kbd{A} apply to archives (a special type of Todo
file; @ref{Todo Archive Mode}).  Todo commands applying to items,
which constitute the majority, are bound to lower case key sequences.

@node Navigation, Editing, Key Binding Conventions, Top
@chapter Navigation

The navigation commands are for making another todo file, category, or
item the current one by moving point to it.@footnote{Many editing
commands can also do this by side effect, but since that is not their
main function, they are not included in this section.} Since these
commands are likely to be used frequently and repetitively, it is
convenient for their key bindings to be single lower case keys, even for
navigation commands applying to categories and files.

Two of the navigation commands were already mentioned in @ref{Todo
Mode Entry Points}:

@table @kbd

@item t
Display another todo file in the selected window (@code{todo-show}).
When you invoke this command in Todo mode, it prompts for a file name,
which you can choose via minibuffer completion (like invoking
@code{todo-show} with a prefix argument outside of Todo mode).  If a
buffer is already visiting that file, it displays its current category;
if invoking @kbd{t} opens the file, it display its first category (by
default; see the option @code{todo-show-first} for other possibilities).

@item j
Display another todo category in the selected window
(@code{todo-jump-to-category}).  When you invoke this command, it
prompts for a category name, which you can choose via minibuffer
completion.  The candidates for completion include the categories in the
current todo file as well as those in the files listed in the option
@code{todo-category-completions-files}.  If you type @key{RET} without
choosing a category, the current category of the current todo file is
automatically selected (this can be a useful shortcut when you invoke
@code{todo-jump-to-category} outside of Todo mode).  If you type the
name of a non-existing category, you can add this to the file as a new
category and jump to it.  If you invoke this command with a prefix
argument, it first you prompts for which todo file to jump to (which you
can also choose with minibuffer completion) and then for which category
from that file; in this case, completion is only against the categories
in the selected file.
@end table

It is also convenient to navigate back and forth sequentially between
the categories of a single todo file.  The categories of a todo file are
numbered consecutively starting with @samp{1}.@footnote{A category's
number is automatically assigned when the category is created: the
category is appended to the end of the file, so its number is simply the
highest until another category is added.  There is no command in Todo
mode to reorder the numbering of the categories in a todo file, but this
is possible from the file's table of categories; @ref{Todo Categories
Mode}.}  The current category's number and name appear in the mode line.

@table @kbd

@item f
Move point to the first item of the category numerically directly
following the current category (@code{todo-forward-category}).

@item b
Move point to the first item of the category numerically directly
preceding the current category (@code{todo-backward-category}).
@end table

With @kbd{f} and @kbd{b} you can cycle through the categories, so for example,
if the last category is current and you type @kbd{f}, then the first
category becomes current.

You can also navigate between the items in the current category:

@table @kbd

@item n
Move point down to the next item below the current one (i.e., to the
item with the next lower priority) (@code{todo-next-item}).

@item p
Move point up to the item directly above the current one (i.e., to the
item with the next higher priority) (@code{todo-previous-item}).
@end table

These commands also accept a positive numeric prefix argument; e.g.,
typing @kbd{5 n} or @kbd{5 p} navigates in one step to the item five items lower
or higher than the current one.

Navigation to other types of Todo files is discussed in the relevant
sections below.

@node Editing, Todo Archives, Navigation, Top
@chapter Editing

Editing in Todo mode means making structural or textual changes at one
of the levels of organization (file, category, or item).  Structural
editing includes adding, relocating and removing units of information
at a level; textual editing includes renaming files or categories and
changing an item's content or date/time stamp, or adding certain kinds
of marks or tags to items.  Todo mode provides commands, detailed in
the following sections, which enable you to quickly and safely make
changes to your todo lists, without having to worry about preserving
the file format.

To save changes you make to the current todo file,
type @kbd{s} (@code{todo-save}).  Changes are also saved on quitting
Todo mode with @kbd{q}.

@menu
* File Editing::
* Category Editing::
* Item Editing::
@end menu

@node File Editing, Category Editing, , Editing
@section File Editing and Todo Edit Mode

There are four file-level editing commands:

@table @kbd

@item F a
Add a new todo file (@code{todo-add-file}).  This command prompts for
a name and creates the file in @code{todo-directory}, adding the
@samp{.todo} extension (so you should not include the extension in the
name you enter).  The command also prompts for the file's first
category and, if option @code{todo-add-item-if-new-category} is
enabled (the default), for that category's first item.

@item F r
Rename the current todo file (@code{todo-rename-file}).  If called with
a prefix argument, prompt for a todo file and rename it.  If the todo
file has an archive (@pxref{Todo Archive Mode}) or there are
corresponding filtered items files (@pxref{Todo Filtered Items Mode}),
this command renames these accordingly.  If there are live buffers
visiting any of these files, the command also renames them accordingly.

@item F k
Delete the current todo file (@code{todo-delete-file}).@footnote{The key
binding of this command is mnemonic for ``kill'' to parallel the binding
@kbd{k} for item deletion, since @kbd{d} is bound to another item
editing command (@pxref{Done Items}).}  If the todo file has an archive
(@pxref{Todo Archive Mode}), prompt for whether to delete that as well.
This command also kills the buffers visiting the deleted files.

@item F e
This command (@code{todo-edit-file}) changes the buffer's major mode to
Todo Edit mode.  In this mode the entire file is visible, the buffer is
writable and you can use the self-insertion keys and standard Emacs
editing commands to make changes.  To return to Todo mode, type @kbd{C-x
C-q} (@code{todo-edit-quit}).

The command @kbd{F e} is not intended for normal editing of items and
categories, as it circumvents the restrictions that Todo imposes to
protect against file format corruption (i.e., all categories, not just
the current one, and all internal formatting are exposed and editable).
It is provided primarily as a convenience for two types of use cases
that are likely to arise infrequently.  One is to be able to use
standard Emacs commands like @code{query-replace} to replace a piece of
text that occurs in different categories throughout the file.  The other
use case is to recover from a mistake, such as accidentally deleting an
item, since this cannot be undone in Todo mode.

Using @kbd{C-x C-q} to quit Todo Edit mode provides a measure of
safety, since it runs a file format check, signaling an error if the
format has become invalid.  However, this check cannot tell if the
number of items or categories changed, which could result in the file
containing inconsistent information (see the cautionary note in
@ref{Reordering Categories}, for more details).  Invoking @kbd{F e}
displays a warning to this effect.
@end table

@node Category Editing, Item Editing, File Editing, Editing
@section Category Editing

The following commands are available for editing specifically at the
category level (for two other category-editing commands, which are
extensions of item commands, @pxref{Editing Item Headers and Text}):

@table @kbd

@item C a
Add a new category to the current todo file and make that category
current (@code{todo-add-category}).  If called with a prefix argument,
prompt for a file name and add the new category to that file.  This
command is similar to using @kbd{j}, but it only accepts category names
that are not the name of an existing category in the file.

@item C r
Rename the current category (@code{todo-rename-category}).  If this
category's file has an archive (@pxref{Todo Archive Mode}) with a
corresponding category, rename the category there as well.

@item C m
Move the current category (with all its items) to another todo file
(@code{todo-move-category}).  If this category's file has an archive
(@pxref{Todo Archive Mode}) with a corresponding category, this command
also moves that category to the archive file corresponding to the moved
to todo file; if there is no such archive file, the command creates it
and adds the category.

@item C k
Delete the current category (@code{todo-delete-category}).@footnote{This
binding is mnemonic for ``kill'' to parallel the binding @kbd{k} for
item deletion, since @kbd{d} is bound to another item editing command
(@pxref{Done Items}).}  To delete a category that contains items, you
have to confirm your intent; if the category is empty, deletion is
immediate.

@item C g
Merge the items of one category into another category, delete the first
category and make the second category current
(@code{todo-merge-category}).  If both the first and second categories
also have archived items (@pxref{Todo Archive Mode}), merge the former
to the latter.  If only the first category has archived items, rename
the archive category to the merged to category.  Minibuffer completion
of the name of the category merged to works as with the navigation
command @kbd{j}, and as with that command, passing a prefix argument,
i.e., typing @kbd{C-u C g}, prompts for a file and confines merging to a
category in that file.
@end table

@node Item Editing, , Category Editing, Editing
@section Item Editing

Todo mode provides commands for adding new items as well as textually
changing, deleting and relocating existing items.  The commands and
associated options for adding and editing items, in particular, offer
you a lot of flexibility to fine-tune these operations to your needs.

@menu
* Inserting New Items::
* Editing Item Headers and Text::
* Relocating and Removing Items::
@end menu

@node  Inserting New Items, Editing Item Headers and Text, , Item Editing
@subsection Inserting New Items

To add a new todo item to a category, type @kbd{i}, which is bound to
the command @code{todo-insert-item}.

@table @kbd

@item i
This command is the entry point for inserting new items into a
category (@code{todo-insert-item}).  It prompts for additional keys
until reaching a complete key sequence, which specifies the insertion
parameters you wish to apply (see below).  It then prompts for the
text of the item, which you enter in the minibuffer.@footnote{There
are two insertion parameters that override prompting for and manually
entering the new item's text, see below.}  Called with one prefix
argument, it also prompts for a category, and called with two prefix
arguments, it prompts for both a file and a category from that file,
and inserts the item accordingly; category name completion works as
with the navigation command @kbd{j}.  Finally, it inserts the item
into the current or selected category of the current or selected todo
file at the position in the list corresponding to the priority you
choose, which also depends on the insertion parameters.
@end table

@noindent
The name of this command reflects the fact that you can insert a new
item into the category at any position, giving each new item any
priority in the list, whereas speaking of adding an item to a category
suggests appending it to the top or bottom.

In addition to its file and category, each newly inserted todo item
has a priority in the category and begins with a header string, which
includes at least the current date in the same format used by
@code{diary-insert-entry} (@pxref{Date Formats,,, emacs}).  You can
specify the priority and the content of the header string in two ways.
First, you can set the following item insertion options, which apply
on every invocation of @code{todo-insert-item}.

@itemize @bullet

@item
@code{todo-default-priority} is for automatically assigning a new item
the highest or lowest priority in the category, if you do not
explicitly assign it a priority on invoking @code{todo-insert-item}.
By default, such new items are given highest priority, i.e., inserted
at the top of the list.

@item
@code{todo-always-add-time-string} is for including or omitting the
current time in the new item's header.  By default, this time string
is omitted.

@item
@code{todo-include-in-diary} is for specifying whether the item
appears in the Fancy Diary display (when the todo file is included in
the Emacs diary file) by adding or omitting
@code{todo-nondiary-marker}.  By default, new todo items are so
marked, thus excluded from the diary.

@item
@code{todo-diary-nonmarking} is for adding or omitting
@code{diary-nonmarking-symbol} to items displayed in the diary, to
control whether they are marked in the calendar (@pxref{Format of
Diary File,,, emacs}).  By default, todo items that are diary entries
lack this symbol, thus are marked in the calendar.
@end itemize

Beside setting these options, for more flexibility you can also pass
certain parameters on each invocation of @code{todo-insert-item}.
These parameters concern not only the new item's priority and header,
but also its textual content.  You pass these parameters by typing a
sequence of one or more keys after the initial @kbd{i}.

Here is a list of the item insertion parameters together with their
mnemonically associated keys@footnote{The non-mnemonic choice of
@kbd{i} for the parameter @samp{default} is motivated by the
convenience of repeating the @kbd{i} used to invoke
@code{todo-insert-item}.} and descriptions of their effect in
@code{todo-insert-item}:

@enumerate

@item
@samp{default} (@kbd{i}): Prompt for the new item's priority
(a number between 1 and one more than the number of items already in
the category) and add a header string conforming to the values of the
above options.

@samp{copy} (@kbd{p}): Make an exact copy of the item at point,
including its header string, and prompt for its priority.  (This is
useful for quickly making a new todo item whose text or header you
want to differ only partly from that of an existing item: after
inserting the copy, you can quickly edit it as needed by using
operations described in the next section.)

@item
@samp{diary} (@kbd{y}): Override the option
@code{todo-include-in-diary}; that is, add @code{todo-nondiary-marker}
if the option is non-@code{nil}, omit this marker if the option is @code{nil}.

@samp{nonmarking} (@kbd{k}): Override the option
@code{todo-diary-nonmarking}; that is, add
@code{diary-nonmarking-symbol} if the option is non-@code{nil}, omit this
symbol if the option is @code{nil}.  Since this symbol only applies to diary
items, the new item is automatically marked as such, i.e., lacks
@code{todo-nondiary-marker}.

@item
@samp{calendar} (@kbd{c}): Pop up the Emacs calendar and click a date
in it to use that date in the new todo item's header.

@samp{date} (@kbd{d}): Prompt for entering in the minibuffer
the year, month (with completion) and day number components of the
header.

@samp{dayname} (@kbd{n}): Prompt for entering in the minibuffer
a weekday name as the date header instead of a year-month-day string.

@item
@samp{time} (@kbd{t}): Prompt for entering a time string in
the minibuffer instead of automatically inserting the current time;
however, typing @key{RET} at the prompt enters the current time if
@code{todo-always-add-time-string} is non-@code{nil}, otherwise it enters the
empty string (i.e., no time string).

@item
@samp{here} (@kbd{h}): Insert the new item in the position of
the item at point, pushing that and all lower items in the category
down, i.e., lowering their priority, by one.

@samp{region} (@kbd{r}): Use the text of the selected region as the
text of the new item, and insert this in accordance with the item
insertion options and other parameters passed.  If the option
@code{todo-use-only-highlighted-region} is non-@code{nil}, then use the
region only when it is highlighted; otherwise, use the region
regardless of highlighting.
@end enumerate

Note that the parameters are divided into five numbered groups; within
a group, the parameters are mutually exclusive.  Hence, to build a
complete insertion operation, you select at most one parameter from at
least one of these groups, by typing the corresponding key.  If you
want to apply more than one parameter, you must type the corresponding
keys in the order of the numbered groups, subject to the following
constraints.

The keys of groups 2-4 are continuation keys, that is, each can be
followed by a key from a following group.  If you want to finish the
sequence with a continuation key, you must double the final key.  For
example, @kbd{i y} is not a complete key sequence; rather, you must
type @kbd{i y y}.

By contrast, the keys of groups 1 and 5 are final keys; for example,
@kbd{i i} and @kbd{i h} are complete sequences.  The reason for making
two separate groups of the final keys is that the parameters
@samp{default} and @samp{copy} cannot be combined with any other
parameters, while @samp{here} and @samp{region} can be combined with
any of the parameters from groups 2-4.

To aid you in building item insertion key sequences, when you type an
insertion key, this displays a prompt in the echo area showing pairs
of the remaining possible keys and their associated parameters,
grouped and ordered in accordance with the above list.  The initial
prompt, after typing @kbd{i} to invoke @code{todo-insert-item}, looks
like this:

@example
Press a key (so far @kbd{i}):  @{ i=>default p=>copy @} @{ y=>diary k=>nonmarking @} @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @}
@end example

@noindent If you now type @kbd{y}, the prompt changes to this:

@example
Press a key (so far @kbd{i y}):  y=>diary:GO! @{ c=>calendar d=>date n=>dayname @} t=>time @{ h=>here r=>region @}
@end example

@noindent Notice that the pair @samp{k=>nonmarking} is now absent, since it
belongs to the same group as the selected pair @samp{y=>diary}, hence
is no longer available for this sequence.  Since @kbd{y} is a
continuation key, it is still available, but now the string
@samp{:GO!} is appended to the pair to remind you that pressing this
key again will complete the sequence.



@c Here are some examples of item insertion command key sequences:

@c @itemize @bullet

@c @item
@c @kbd{i h} inserts a new item at the position of the item at point (pushing
@c the latter down) with a header containing the current date and,
@c depending on the values of the mentioned options, possibly the current
@c time and diary-related markings.
@c @item
@c @kbd{i y h} does the same as the preceding command, except that
@c @code{todo-nondiary-marker} is added if @code{todo-include-in-diary} is
@c non-@code{nil} and omitted if that option is @code{nil}; that is,
@c the diary key @kbd{y} @c overrides the setting of this option.
@c @item
@c @kbd{i y t h} does the same as the preceding command, except that it
@c prompts for a time string instead of automatically inserting the
@c current time; however, typing @key{RET} at the prompt returns the
@c current time if @code{todo-always-add-time-string} is non-@code{nil},
@c otherwise the empty string (i.e., no time string).
@c @item
@c @kbd{i y t t} does the same as the preceding command, except that it
@c prompts for the item's priority and inserts it accordingly.
@c @end itemize


An alternative to the key sequence @kbd{i c c} for choosing the item's
date from the calendar is also available: when point is already on a
date in the calendar, typing @kbd{i t}
(@code{todo-insert-item-from-calendar}) prompts for a new item and its
priority and inserts it in the current category.  This command, like
@code{todo-insert-item}, also accepts one or two prefix arguments for
choosing the category via minibuffer completion.  Note, however, that
the key sequence @kbd{i t} is not defined in Todo mode but in the
Calendar mode keymap.  It is a convenient shortcut if you happen to be
using the calendar when you decide to make a new todo item.  (Contrast
this with passing the @samp{calendar} parameter, which pops open the
calendar after you have entered the item's text, and then you can
choose a date from the calendar.)


@node  Editing Item Headers and Text, Relocating and Removing Items, Inserting New Items, Item Editing
@subsection Editing Item Headers and Text

To make changes to an existing item's content or header, type @kbd{e},
which is bound to the command @code{todo-edit-item}.

@table @kbd

@item e
This command is the entry point for textually editing existing items
in a category (@code{todo-edit-item}).  It prompts for additional keys
until reaching a complete key sequence, which specifies the editing
parameters you wish to apply (see below), and then executes the
editing operation accordingly.
@end table

Here is a list of the item editing parameters together with their
mnemonically associated keys and descriptions of their effect in
@code{todo-edit-item}.  The list is divided into three groups, for
reasons explained below.

@enumerate 1

@item
@samp{edit} (@kbd{e}): Edit the text of the current item in the
minibuffer; the item's header is omitted.

@samp{header} (@kbd{h}): Edit the text and header of the current item
in the minibuffer.

@samp{multiline} (@kbd{m}): Edit the text of the current item in a
special buffer in Todo Edit mode.  After editing, type @kbd{C-x C-q}
to return to Todo mode.@footnote{This runs a format check to ensure
the item is well-formed.  However, unlike the command @kbd{F e}
(@pxref{File Editing}), @kbd{e m} does not expose you to the risk of
putting the file in an inconsistent state, since it puts only the
current item in Todo Edit mode.}

@samp{diary} (@kbd{y}): Change the current item's diary inclusion
status by adding @code{todo-nondiary-marker} if the item lacks this,
or by removing it if present.

@samp{nonmarking} (@kbd{k}): Change the current item's calendar
marking status by adding @code{diary-nonmarking-symbol} if the item
lacks this, or by removing it if present. Since this symbol only
applies to diary items, the item is automatically marked as such,
i.e., if @code{todo-nondiary-marker} is present, it is removed.

@samp{date} (@kbd{d}): Prompt for a final key from the second group
of item editing parameters to edit the current item's date string.

@samp{time} (@kbd{t}): Edit the current item's time string, if
present; otherwise, add one.  Typing @key{RET} at the prompt enters
the current time if @code{todo-always-add-time-string} is non-@code{nil},
otherwise it enters the empty string (i.e., no time string).
@end enumerate

@noindent
Editing the text of a lengthy item in the minibuffer can be
inconvenient; therefore, if you type @kbd{e e} or @kbd{e h} on an item
whose text contains more than one logical line, the effect is the same
as if you had typed @kbd{e m}, that is, you switch a special buffer in
Todo Edit mode.

When you pass any of the parameters of the preceding group, except for
the @samp{date} parameter, this completes the item editing invocation
begun by typing @kbd{e}.  Pressing @kbd{d} to pass the @samp{date}
parameter, however, prompts you with the following parameters and
their associated keys, and pressing any of these completes the
invocation.

@enumerate 2

@item
@samp{full} (@kbd{f}): Successively prompt for editing the year, month
(with completion) and day number parts of the current item's date
string, and, if the option @code{todo-always-add-time-string} is
non-@code{nil}, also for editing its time string.

@samp{calendar} (@kbd{c}): This pops up the Emacs calendar, and after
you type @key{RET} on a date in the calendar makes that date the
item's date.

@samp{today} (@kbd{a}): Make the item's date today's date.

@samp{dayname} (@kbd{n}): Prompt for a weekday name (with completion)
and make it the item's date header.  Note that this replaces an
existing date string, it does not add the day name to the date string.

@samp{year} (@kbd{y}): Edit just the year component of the current
item's date string.

@samp{month} (@kbd{m}): Edit just the month component of the current
item's date string (with completion).

@samp{daynum} (@kbd{d}): Edit just the day number component of the
current item's date string.
@end enumerate

@noindent
With the latter three parameters you can add a positive or negative
numeric prefix argument to the invocation: this increments or
decrements the selected date component by the given number and
automatically adjusts the other date components if necessary.  For
example, if the item's date string is ``January 1, 2013'', then typing
@kbd{- 3 e d d} results in ``December 29, 2012''.

The first two groups of parameters apply only to todo items that are
not marked as done (@pxref{Done Items}); the two parameters of the
third group, in contrast, apply only to done todo items.  You cannot
edit the text of such items, but you can edit or delete the comment
you may have added on marking the item as done (@pxref{Done Items,
@code{todo-item-done}},), or retroactively add a comment, by passing
either of these parameters.

@enumerate 3

@item
@samp{add/edit comment} (@kbd{c}): Edit the current done item's
comment, if it has one; otherwise, prompt for and add a comment.

@samp{delete comment} (@kbd{d}): Delete the current done item's
comment, if it has one.
@end enumerate

The command @code{todo-edit-item} is sensitive to the distinction
between not done and done todo items.  If you type @kbd{e} when point
is on a done item, this displays the following prompt in the echo
area:

@example
Press a key (so far @kbd{e}): c=>add/edit comment d=>delete comment
@end example

@noindent
Only by typing @kbd{c} or @kbd{d} in response to this prompt can you
complete the invocation.  In contrast, if you type @kbd{e} when point
is on a non-done todo item, this displays the following prompt in the
echo area, and you can continue or complete the invocation only by
typing one of the listed keys:

@example
Press a key (so far @kbd{e}): e=>edit h=>header m=>multiline y=>diary k=>nonmarking d=>date t=>time
@end example

As noted above, passing the @samp{date} parameter does not complete
the invocation of @code{todo-edit-item}; rather, it displays the
following prompt, and typing any of these keys does complete the
invocation:

@example
Press a key (so far @kbd{e d}): f=>full c=>calendar a=>today n=>dayname y=>year m=>month d=>daynum
@end example

In addition to the item-level invocations @kbd{e y}, to change the
current item's diary inclusion status, and @kbd{e k}, to change the
current item's calendar marking status, Todo mode also has two related
category-level commands:

@table @kbd

@item C e y
@itemx C e k
Add @code{todo-nondiary-marker} and @code{diary-nonmarking-symbol},
respectively, to all todo items in the current category; if invoked with
a prefix argument, these markings are removed from all items in the
category.
@end table

@noindent
Like @kbd{e k}, @kbd{C e k} automatically removes @code{todo-nondiary-marker}
from all items it is present on, since only diary items can bear
@code{diary-nonmarking-symbol}.

Since categories often contain a mix of items marked for diary
inclusion and exclusion, and of the former, a mix of those to be
marked and those not to be marked in the calendar, it is more useful
for these category-level commands, unlike the item-level commands, not
to be toggles, but to have the same effect on all items in the
category, and take a prefix argument to reverse the effect.  (If you
really want to toggle the diary-inclusion and calendar-marking status
of all items in the category, you can do this by marking all the items
and then invoking @kbd{e y} or @kbd{e k}, @pxref{Marked Items}).

@node  Relocating and Removing Items,  , Editing Item Headers and Text, Item Editing
@subsection Relocating and Removing Items

In addition to inserting a new todo item and changing the text or header
of an existing item, you can also move an item to another category
(i.e., recategorize it), change its priority within its category, delete
it from the category and file, or mark it as a ``done'' item, which
removes it from the todo list but does not delete it.

@menu
* Reprioritizing Items::
* Moving and Deleting Items::
* Done Items::
@end menu

@node Reprioritizing Items, Moving and Deleting Items, , Relocating and Removing Items
@subsubsection Reprioritizing Items

There are three ways to change a todo item's priority:

@table @kbd

@item r
Raise the current item's priority by one, exchanging its position in the list
with that of the item directly above it (@code{todo-raise-item-priority}).

@item l
Lower the current item's priority by one, exchanging its position in the list
with that of the item directly below it (@code{todo-lower-item-priority}).

@item #
Prompt for a number and relocate the item to the corresponding
position in the list (@code{todo-set-item-priority}).  For example,
entering @kbd{3} at the prompt makes the item the third in the
category, i.e., gives it third highest priority; all lower priority
items are pushed down by one.  You can also pass the desired priority
as a numeric prefix argument, e.g., @kbd{3 #} gives the item third
highest priority without prompting.  (Prefix arguments have no effect
with @kbd{r} or @kbd{l}.)
@end table

@node Moving and Deleting Items, Done Items, Reprioritizing Items, Relocating and Removing Items
@subsubsection Moving and Deleting Items

You can move an item to another category, thereby recategorizing it:

@table @kbd

@item m
Move the item at point to another category (@code{todo-move-item}).
This prompts for a category to move the item to, displays that category,
prompts for the priority of the moved item in the category moved to and
inserts the item accordingly.  Minibuffer completion of the name of the
category moved to works as with the navigation command @kbd{j}, and as
with that command, passing a prefix argument prompts for a file and
moves the item to a category in that file; and if the category name you
enter is new, then you are asked whether to add the category to the
file, and if you affirm, the item is moved to the new category.
@end table

You can delete an item, thereby permanently (and, as far as Todo mode
is concerned, irrevocably) removing it from the todo file:

@table @kbd

@item k
Delete the todo item at point (@code{todo-delete-item}; the binding is
mnemonic for ``kill'', since @kbd{d} is used for marking items as done
(@pxref{Done Items}); but note that @kbd{k} does not put the item into
the kill ring).  This command requires confirmation that you want to
delete the item, since you cannot undo the deletion in Todo mode.  (You
could use @kbd{F e} to recover the item, but be aware that this would
put the file in an inconsistent state, which you can recover from, but
not without a risk; cf.@: the cautionary note in @ref{Reordering
Categories}.)
@end table

@quotation Note
Todo commands that require user confirmation, such as @kbd{k}, use a
modified form of @code{y-or-n-p}, which by default only accepts @kbd{y}
or @kbd{Y}, but not @key{SPC}, as an affirmative answer.  This is to
diminish the risk of unintentionally executing the command, which is
especially important with commands that do deletion, since there is no
Todo command to undo a deletion.  If you want to be able to use @key{SPC} for
confirmation, enable the option @code{todo-y-with-space}.
@end quotation

@node Done Items, , Moving and Deleting Items, Relocating and Removing Items
@subsubsection Done Items

When the activity or thing that a todo item is about has been done, it
is natural to eliminate the item from the todo list.  But instead of
deleting it permanently, you may prefer to keep a record of your
accomplishments by marking the item as done.  In Todo mode, this removes
the done item from the todo list, so as not to clutter it up, and stores
it elsewhere.  Such stored items form a record or diary of things done.
The Todo package provides two such stores: the ``done items'' section of
a Todo category, described here, and done item archives (@pxref{Todo
Archive Mode}).

@table @kbd

@anchor{todo-item-done}
@item d
This command (@code{todo-item-done}) removes the todo item at point
from the todo list, appends to the original header a header consisting
of @code{todo-done-string} (by default @samp{DONE }) and the current
date, and if @code{todo-always-add-time-string} is enabled, also the
current time, and adds the resulting done item to the top of the done
items section of the category.  Invoked with a prefix argument, it
also prompts you to enter a comment, which is appended to the end of
the done item, prefixed with @code{todo-comment-string} (by default
@samp{COMMENT: }).
@end table

A category's done items section is located below the last todo (i.e.,
not done) item in the category.  By default this section is hidden from
view.  There are two commands for viewing and hiding done items; since
these are toggle commands, for convenience they also have a single key
binding:

@table @kbd

@item C v
@itemx v
Make the done items section of the current category visible if it is
hidden, or hide it if it is visible
(@code{todo-toggle-view-done-items}).  If you always want to see the
done items section on entering a category, enable the option
@code{todo-show-with-done}; you can still use @kbd{C v} or @kbd{v} to
hide (and unhide) it.

@item F V
@itemx V
Toggle the standard category display in the current todo file, i.e.,
display only the done items section of each category in the file, or if
this is visible, hide it again and display only the todo items section
(@code{todo-toggle-view-done-only}).
@end table

Since done items are meant to be a record of your finished todo items,
you cannot apply to them the same kinds of editing operations
available to unfinished todo items.  However, as explained in
@ref{Editing Item Headers and Text} and repeated below for
convenience, you can edit or delete a done item's comment, or
retroactively add a comment.  You can also relocate a done item, and
you can revert its done status, making it an unfinished item again.

@table @kbd

@item e c
Edit the current done item's comment, if it has one; otherwise, prompt
for and add a comment.

@item e d
Delete the current done item's comment, if it has one.

@item m
Move the done item at point to the top of the done items section of
another category (@code{todo-move-item}).  This is useful in case,
after having finished a todo item and relocated it to its category's
done items section, you create a category that is better suited to the
content of the done item than its current category; in other words,
you can retroactively recategorize the done item.

@item u
If you decide the done item at point is not done after all, this command
``undoes'' it, i.e., restores it to the todo list of its category, with
the priority you choose for it (@code{todo-item-undone}).  If the done
item has a comment, you are asked whether to delete it from the restored
item.
@end table

@node Todo Archives, Marked Items, Editing, Top
@chapter Todo Archives

When the done items section of a category itself starts to become
cluttered, or if you just want to store some accomplished todo items in
a separate file, you can move them to a Todo archive.  This is a file
with exactly the same structure as a todo file, i.e., divided into
categories, but differs in that the categories contain only done items.
Todo archives reside, like todo files, in @code{todo-directory} but have
the extension @samp{.toda} instead of @samp{.todo}.

@menu
* Creating and Visiting Archives::
* Todo Archive Mode::
@end menu

@node Creating and Visiting Archives, Todo Archive Mode, , Todo Archives
@section Creating and Visiting Archives

Todo mode provides the following command for archiving items:

@table @kbd

@item A d
This command (@code{todo-archive-done-item}) archives the done item at point.
Invoked with a prefix argument, it archives all done items in the
current todo category.  If an archive for the current todo file
already exists and contains a category with the same name as the
current todo category, then this command moves the done item to the
top of the corresponding archive category.  If the archive exists but
it does not have a corresponding category, this command creates the
category in the archive and moves the done item to it.  If no archive
for the todo file exists, the command creates both the archive file,
using the same base name as that of the todo file, as well as the
category, and moves the done item to it.
@end table

Typing @kbd{A d} is also the only way within the Todo mode package to
create an archive file and its categories.  Consequently, as a rule each
archive file corresponds to exactly one todo file and has the same base
name as this file, and each category in an archive file corresponds to
and has the same name as a category in the corresponding todo file.
Exceptions can only arise if you delete a todo file but not the
corresponding archive, or if you delete a category in a todo file that
has a corresponding category in an archive.

You might be inclined to do the latter if you have archived all the
items from a given todo category and you don't plan to add new items to
it.  In particular, if you have numerous such empty categories in a todo
file, this can make sequential navigation in the file annoying.  You can
avoid this annoyance by deleting these categories, but only at the cost
of putting the todo file out of synch with the archive file.

You may find it preferable not to delete empty todo categories but to
enable the option @code{todo-skip-archived-categories}.  When this is
non-@code{nil}, such empty todo categories are skipped over by the sequential
category navigation commands @kbd{f} and @kbd{b}, so they don't distract you
while navigating and you maintain the structural correspondence between
todo and archive files (you can also still jump to empty todo categories
with @kbd{j}).

If you rename a todo category that has a corresponding category in an
archive, the archive category is also automatically identically renamed.
Likewise, if you move such a todo category to another file; in this
case, if there is no archive file corresponding to the todo file the
category is moved to, then the archive is automatically created and the
archived category is moved to it.

There are two commands in Todo mode for visiting archive files:

@table @kbd

@item A f
Switch to a buffer displaying the archived category corresponding to the
current todo category (@code{todo-find-archive}).  If the todo category
has no archived items, the command asks if you want to visit the archive
anyway.  If there is no archive for this todo file, it asks if you want
to visit another archive, which you can select via minibuffer
completion.

@item A c
Choose an archive to visit, whether or not the current todo file has an
archive (@code{todo-choose-archive}).
@end table

As with todo files, you can also visit a Todo archive by invoking a
standard Emacs file-visiting command; this displays the first (on the
initial invocation) or current category of the archive.

@node Todo Archive Mode, , Creating and Visiting Archives, Todo Archives
@section Todo Archive Mode

When you visit a Todo archive, the buffer is in Todo Archive mode.  It
displays categories just as in Todo mode, except that they only contain
done items.  It provides the same sequential navigation commands as
Todo mode: @kbd{f} and @kbd{b} navigate between the categories of the current
archive, and @kbd{n} and @kbd{p} navigate between the done items of the current
archive category.

The commands @kbd{t} and @kbd{j} are also available in Todo Archive
mode, and they work the same as in Todo mode, which means they can only
be used to return to Todo mode: @kbd{t} prompt for and switch to a todo
file, and with @kbd{j} you can only jump to a todo category.  These
commands exclude archives because an archive file has the same base name
as the corresponding todo file, and category name completion uses only
the base names, so the commands cannot know which type of file you want
to visit.  For this reason, there is a special command in Todo Archive
mode for jumping to another archive category or visiting another archive
file:

@table @kbd

@item a
This command (@code{todo-jump-to-archive-category}) prompts for a category in the
current archive and jumps to it.  Called with a prefix argument, it
prompts for another archive, then for a category in it and jumps to
that category.
@end table

None of the Todo mode editing commands are available in Todo Archive
mode, since archives are meant to be static records of accomplished todo
items.  Should you, however, archive an item by mistake or simply change
your mind about the archival status of an item, you can ``unarchive'' it:

@table @kbd

@item u
Restore the done item at point to the top of the done items section of
the corresponding category in the corresponding todo file, i.e., an
unarchived item remains a done item (@code{todo-unarchive-items}).  When
the last item in an archive category has been unarchived, the category
is automatically deleted from the archive.  If this was the only
category in the archive, the archive file is also automatically deleted.
@end table

Since it is natural to visit an archive from the corresponding todo
file, it would be convenient to easily return to the todo file when you
have finished browsing the archive.  If you type @kbd{q} to quit Todo
Archive mode, this switches to the corresponding todo file and shows the
todo category corresponding to the archive category you were just
visiting.

The command @kbd{F k} (@pxref{File Editing}) is also available in Todo
Archive mode.  It deletes the current archive file and prompts you
whether to delete the corresponding todo file.

@node Marked Items, Todo Categories Mode, Todo Archives, Top
@chapter Marked Items

For many item editing commands it can make sense and be convenient to
apply them simultaneously to more than one item in the current category.
Todo facilitates this by means of marked items.

@table @kbd

@item *
Mark the item at point if it is unmarked, and remove the mark it is
already marked (@code{todo-toggle-mark-item}).  The mark is a string
specified by the option @code{todo-item-mark} (by default @samp{*})
appended in front of the item header (more precisely, in front of the
item's priority number or prefix; see @ref{Todo Display Features}, for
details of the latter).  After marking the current item, the command
advances point to the next item.  It also accepts a numeric prefix
argument, which allows toggling the mark of multiple consecutive items.

@item C *
Mark all todo items in the current category.

@item C u
Unmark all todo item in the current category.
@end table

You can also use the last two commands to mark or unmark all done items in
the category, but only when only the done items section is being
displayed, i.e., after invoking @kbd{C V} or @kbd{V}.

The following commands operate on marked items:

@itemize @bullet

@item
@kbd{k} (deleting)
@item
@kbd{m} (moving to another category)
@item
@kbd{d} (moving to the done items section; note that @kbd{C-u d} adds
the same comment to all marked items)
@item
@kbd{A d} (archiving)
@item
@kbd{u} (both in Todo mode for undoing a done item and in Todo Archive
mode for unarchiving an item)
@item
the commands for editing the item header (those beginning with the
prefix @kbd{e d} as well as @kbd{e t}, @kbd{e y} and @kbd{e k})
@end itemize

@noindent
The item insertion, textual editing and priority changing commands do
not operate on marked items.

If you use @kbd{m}, @kbd{d}, @kbd{A d} or @kbd{u} on multiple
noncontiguous marked items, the relocated items retain their relative
order but are now listed consecutively en bloc.

You can mark both todo and done items, but note that only @kbd{m} and
@kbd{k} can apply to both; other commands only affect either marked
todo or marked done items, so if both types of items are marked,
invoking these commands has no effect and informs you of your
erroneous attempt.

@node Todo Categories Mode, Searching for Items, Marked Items, Top
@chapter Todo Categories Mode

It can be helpful to have a compact overview of the categories in a
todo file and the types of items it contains; the Todo package
provides a tabular view of this information.

@table @kbd

@item F c
Typing this command (@code{todo-show-categories-table}) in Todo mode or Todo
Archive mode switches to a buffer displaying a table that gives an
overview of the categories in the current todo or archive file.  This
buffer is in Todo Categories mode.
@end table

The table consists of a column containing the names of the categories in
the file, followed by columns containing counts of certain types of
items in each category.  With todo files there are four count types: all
todo (i.e., not done) items, diary items (i.e., those todo items lacking
the @code{todo-nondiary-marker}, which hence can appear in the Fancy Diary
display), done (but not archived) items, and archived items.  With
archive files all items are done, so the table only has a column for
this count.  The final row of the table gives total item counts across
all categories in the file.

Aside from explicitly invoking @kbd{F c} to display the table of
categories, you can also arrange to have it displayed on the first
invocation of @code{todo-show} for a given file (i.e., either using
@code{todo-show} to initiate a Todo session, or calling it in Todo mode
to visit another todo file).  To do this customize the option
@code{todo-show-first}.

@menu
* Table of Item Counts::
* Reordering Categories::
@end menu

@node Table of Item Counts, Reordering Categories, , Todo Categories Mode
@section Table of Item Counts

Above each column of the table is a labeled button you can press by
clicking with the mouse or by typing @key{RET} on it.  Pressing an item
count button sorts the table alternately in ascending or descending
order according to the type of count.  Pressing the category button
alternates between the initial numerical order of the categories and
alphabetical order.  In numerical order the column of category names is
preceded by a column containing the corresponding category numbers; this
column is not displayed in the alphabetical listing.  Instead of
pressing the buttons, you can also sort the table by typing the
following keys:

@itemize

@item @kbd{c}
to sort by category numerically or alphabetically;
@item @kbd{t}
to sort by todo item counts;
@item @kbd{y}
to sort by diary item counts;
@item @kbd{d}
to sort by done item counts;
@item @kbd{a}
to sort by archived item counts.
@end itemize

Each row of the table is also buttonized; pressing one of these exits
the buffer (killing it), returns to the buffer of the file from which
you had invoked @kbd{F c}, and displays the category that was named in
the row button you pressed (i.e., pressing this button jumps to that
category).  However, if the category named in the row is in a todo
file and all of its items have been archived, and you have enabled the
option @code{todo-skip-archived-categories}, then pressing the button
jumps to the archive category instead of the empty todo category.  You
can recognize such categories by their items counts in the table---all
columns but the archived one have counts of zero---and in addition,
their lines in the table are also distinguished from the others by a
different face (@pxref{Faces}).

You can navigate around the table:

@table @kbd

@item n
@itemx @key{TAB}
Advance point to the next button.

@item p
@itemx S-@key{TAB}
Put point on the previous button.
@end table

These commands are cyclic, e.g., when point is on the last button,
pressing @kbd{n} moves it to the first button.

Typing @kbd{q} exits Todo Categories mode, killing the buffer and returning
to the current category in the Todo mode or Todo Archive mode buffer
from which you had invoked @kbd{F c}.

@node Reordering Categories, , Table of Item Counts, Todo Categories Mode
@section Reordering Categories

Todo Categories mode provide commands with which you can change the
numbering of the categories in the current file.  This renumbering has
the effect of reordering the categories for sequential navigation by
@kbd{f} and @kbd{b} in Todo mode and Todo Archive mode.  These commands
are only operative when the table displays the categories in their
numerical order.  They work just like reprioritizing items in Todo mode,
hence have the same key bindings:

@table @kbd

@item r
Raise the current line of the table (the one the cursor is on),
decreasing the category's number by one (@code{todo-raise-category}).
This command exchanges lines, and hence the numbers, of the category at
point and the one above it before invoking the command.

@item l
Lower the current line of the table, increasing the category's number by
one (@code{todo-lower-category}).  This command exchanges lines, and
hence the numbers, of the category at point and the one below it before
invoking the command.

@item #
Prompt for a number between 1 and the number of categories in the file
and reorder the table accordingly (@code{todo-set-category-number}).  If
called with a numeric prefix argument within the allowed range, reorder
the table without prompting.
@end table

The reordering done by these commands remains in effect when you return
to Todo mode or Todo Archive mode and, as long as you save the todo
or archive file after reordering, in subsequent sessions as well.

@quotation @strong{Caution}
It is important to be aware that renumbering the categories does not
change the textual order of the categories in the file.  This is
significant if you should invoke @kbd{F e} to edit the entire file
manually and in so doing alter the number of categories or the number
of items in a category: this will make the information shown in the
table of categories of this file inconsistent with its actual state.
You can repair this inconsistency by invoking the command
@code{todo-repair-categories-sexp} (which lacks a key binding, since
it is meant to be a rarely needed rescue operation).  But this will
revert any renumbering of the categories you have made, so you will
have to renumber them again.  This is one reason why you should
exercise caution when using @kbd{F e}.
@end quotation

@node Searching for Items, Todo Filtered Items Mode, Todo Categories Mode, Top
@chapter Searching for Items

It can be useful to be able to locate and examine all todo items that
fit certain criteria, regardless of which category they belong to.  One
way to do this in Todo mode is by sequentially searching in the file:

@table @kbd

@item S
This command (@code{todo-search}; the key is capital @kbd{S}) prompts for a
regular expression, searches from the beginning of the current todo file
and displays the category containing the first match it finds, with the
match highlighted.  If there are further matches, a message saying how
many are left is displayed and you are asked if you want to go to the
next match.  When you reach the last match, or if you decide not to go
to further matches, you are asked whether the match highlighting should
be removed.

@item X
This command (@code{todo-clear-matches}) removes any highlighting added by @kbd{S}.
This is so you can leave the matches highlighted at the end of the
search and remove the highlighting later.
@end table

These commands are also available in Todo Archive mode.

@node Todo Filtered Items Mode, Todo Display Features, Searching for Items, Top
@chapter Todo Filtered Items Mode

A more powerful alternative to sequential searching is item filtering,
by which items from different categories that match specified criteria
are gathered and displayed in a new buffer as a kind of virtual
category in a distinct mode, Todo Filtered Items mode.

@menu
* Filtering Items::
* Todo Filtered Items Mode Commands::
* Files of Filtered Items::
@end menu

@node Filtering Items, Todo Filtered Items Mode Commands, , Todo Filtered Items Mode
@section Filtering Items

Todo mode provides three ways to filter items: a general filter for
items matching a user-entered regular expression, as with the search
command; and two specific filters, one for diary-displayable items
(i.e., those lacking @code{todo-nondiary-marker}) and one for top
priority items (more on the latter below).  The commands for each
filter come in pairs, one for filtering just the current todo file and
one for filtering a user-specified list of todo files.  Thus, there
are six item filtering commands:@footnote{The use of @kbd{F} in the key
sequences of these commands naturally recalls ``filter'', but is also
consistent with the Todo mode mnemonic key binding convention, since the
commands involve one or more whole files.}

@itemize @bullet

@item
@kbd{F x x} (@code{todo-filter-regexp-items})
@item
@kbd{F x m} (@code{todo-filter-regexp-items-multifile})
@item
@kbd{F y y} (@code{todo-filter-diary-items})
@item
@kbd{F y m} (@code{todo-filter-diary-items-multifile})
@item
@kbd{F t t} (@code{todo-filter-top-priorities})
@item
@kbd{F t m} (@code{todo-filter-top-priorities-multifile})
@end itemize

There are two ways to specify which files the multifile filtering
commands apply to.  If there are files you want to filter every time you
use these commands, customize the option @code{todo-filter-files}.  If you
leave this option empty (the default), invoking a multifile filtering
command pops up a buffer similar to the Customization buffer for
@code{todo-filter-files}, in which you can select files to filter just for
this invocation.

Diary and top priority items are by definition non-done todo items, but
when filtering by regular expression, you can extend the scope of the
command to done items by enabling the option @code{todo-filter-done-items}.
Then @kbd{F x x} and @kbd{F x m} will gather both matching todo and matching
done items (including done items from any archive files corresponding to
the selected todo files) into the virtual category of filtered items.

There are several ways to specify how many items in each category count
as top priorities and hence get filtered by @kbd{F t t} and @kbd{F t m}:

@itemize @bullet

@item
The option @code{todo-top-priorities} specifies a single default number
for all categories and all todo files; its default value is 1, which
means just the highest priority item in every category is filtered,
unless otherwise specified.
@item
The option @code{todo-top-priorities-overrides} lists file-wide overrides
of @code{todo-top-priorities} as well as category-specific overrides.  It
is empty by default.  However, using the Custom facility to set this
option would be tedious and error-prone, so instead you should use the
commands @kbd{F t s} and @kbd{C t s}.  The former sets (i.e., overrides) the
default number of top priorities for all categories in the current
todo file, and the latter sets the number of top priorities for the
current category.  To exclude a category or file from filtering by @kbd{F t t}
and @kbd{F t m}, set the number to @samp{0}.
@item
You can invoke @kbd{F t t} and @kbd{F t m} with a numeric prefix argument,
which specifies the number of top priorities in each category just for
this invocation, overriding both @code{todo-top-priorities-overrides} and
@code{todo-top-priorities}.
@end itemize

@node Todo Filtered Items Mode Commands, Files of Filtered Items, Filtering Items, Todo Filtered Items Mode
@section Todo Filtered Items Mode Commands

The output of the item filtering commands looks similar to a regular
Todo category, but it is not contained in any todo file and does not
have a name on being created, so it is not a ``real'' category but a
``virtual'' category.  Another difference is the lack of a done items
section; either there are no done items in the list (when the filtered
items are diary or top priority items), or these are displayed in the
same list as todo items (if you filtered by regular expression and
allowed done items).  A further difference is that the items have an
additional header, between the item's date/time header and its text,
specifying which category (and if you invoked a multifile command, also
which file) the item comes from, and if you filtered by regular
expression, also whether the item comes from a Todo archive.

The sequential item navigation commands @kbd{n} and @kbd{p} work the same in
Todo Filtered Items mode as in Todo mode, as do the file and category
jumping commands @kbd{t} and @kbd{j}; however, the sequential category
navigation commands are unavailable, since virtual categories of
filtered items are not ordered with respect to ``real'' categories.  In
addition, Todo Filtered Items mode provides a special navigation
command:

@table @kbd

@item g
@itemx @key{RET}
If you type this command (@code{todo-go-to-source-item}) with point on a
filtered item, the buffer switches to the item's source file (in Todo
mode or Todo Archive mode, as the case may be) and displays its
category, with point on the item.
@end table

Filtered items cannot be textually edited, moved to another category,
marked done or archived like items in a real todo category, since these
would then be out of synch with each other.  But there is one type of
editing command that does work in Todo Filtered Items mode: changing an
item's priority:

@table @kbd

@item r
@itemx l
@itemx #
These commands raise, lower, or set, respectively, the current item's
priority in the virtual category.
@end table

@noindent
Using these commands, you can create a cross-category (and even
cross-file) prioritized list of filtered items.  However, there is a
restriction on these commands in Todo Filtered Items mode: you cannot
change the relative priorities of items from the same real category,
since that would make the filtered list inconsistent with the source
todo list.

@node Files of Filtered Items, , Todo Filtered Items Mode Commands, Todo Filtered Items Mode
@section Files of Filtered Items

Typing @kbd{s} in Todo Filtered Items mode saves the buffer of filtered
items to a file in @code{todo-directory}.  Files of items filtered by
regular expression have the extension @samp{.todr}, those with filtered
diary items have the extension @samp{.tody} and those with filtered top
priorities have the extension @samp{.todt}.  The extensions are added
automatically the first time you save the buffer to a file.

With filtered top priority or diary items, the file is automatically
named on first saving it, using as the base name either the same base
name as the single todo file it was generated from, or combining the
base names of the todo files used in multifile filtering commands.
With items filtered by regular expression, it can be useful to save
separate lists generated from the same file(s) using different regular
expressions, so when saving such a list, you are prompted for a short
identifying string to add to the file name.

When you invoke one of the item filtering commands without a prefix
argument and a corresponding file already exists, the command visits
this file (if, for the current file or chosen files, there are multiple
files of items filtered by regular expression, you are prompted to
choose one).  To force generation of a new filtered list, invoke the
command with a prefix argument (in the case of top priority items,
either numeric as described above, or the raw prefix argument @kbd{C-u} to
use the values of @code{todo-top-priorities-overrides} or
@code{todo-top-priorities}).

Aside from explicitly invoking an item filtering command to display a
saved list of items filtered by a given method from given todo files,
there are two other ways to visit a saved file of filtered items.  You
can invoke a command similar to @code{find-file}:

@table @kbd
@item F f
Visit a saved file of filtered items, which you choose via minibuffer
completion (@code{todo-find-filtered-items-file}).
@end table

@noindent
Alternatively, as with tables of categories, by customizing
@code{todo-show-first} you can have the first invocation of
@code{todo-show} for a given todo file display the corresponding saved
file of filtered items.  If there is no saved filtered items list for
the file, @code{todo-show} simply defaults to visiting the file and
displaying its first category, as usual.

The command @kbd{F k} (@pxref{File Editing}) is also available in Todo
Filtered Items mode.  It deletes the current filtered items file.

@node Todo Display Features, Printing Todo Buffers, Todo Filtered Items Mode, Top
@chapter Todo Display Features

You can change the appearance of Todo mode buffers in a variety of ways.

@menu
* Faces::
* Item Prefix::
* Other Display Commands and Options::
@end menu

@node Faces, Item Prefix, , Todo Display Features
@section Faces

Each of the Todo modes uses faces to distinguish various aspects of
the display, both structural and informational.  For example, the
faces for the date and time strings of todo item headers
(@code{todo-date} and @code{todo-time}, respectively) by default
inherit the attributes of the corresponding faces used by the Emacs
diary; but when the date and time of a Todo diary item (i.e., an item
lacking @code{todo-nondiary-marker}) is earlier than the current date
and time, they are displayed in a different face
(@code{todo-diary-expired}).  In this way, you can readily recognize
diary items that have ``expired'' and act accordingly (e.g., by
tagging them as done or by updating the deadlines).

Another example of an informational face is the face used to
distinguish top priority items (@code{todo-top-priority}).  A third
case is the face used in Todo Categories mode to mark rows of the
table containing categories with only archived items
(@code{todo-archived-only}).

The @code{todo-faces} customization group contains a complete list of
Todo mode faces and brief descriptions of their use.


@node Item Prefix, Other Display Commands and Options, Faces, Todo Display Features
@section Item Prefix

In the default display of (real or virtual) categories in Todo mode,
Todo Archive mode and Todo Filtered Item mode the items are visually
numbered in ascending order, starting with @samp{1} on the top item,
displayed to the left of its header (date/time string).  With todo items
the numbers indicate each item's priority in the list, so when you
reprioritize an item with @kbd{#} or move it with @kbd{m}, these numbers make
it easier to choose the item's new priority.  The numbering also lets
you to see at a glance how many items there are in the list.  When an
item is inserted, deleted, or moved, the numbering is automatically
updated.  In Todo mode, the todo and done items sections in each
category are separately numbered.

If you prefer not to have item numbering displayed, disable the option
@code{todo-number-prefix}; then the display of each item starts by default
simply with its header.  But you can also replace the numbering with a
visually distinctive string of your choice by customizing the option
@code{todo-prefix} (the empty string by default).  Another alternative is to
temporarily hide the item numbering:

@table @kbd

@item F N
@itemx N
Toggle between displaying item numbering and displaying the
@code{todo-prefix} string in the current Todo file (todo, archive, or
saved virtual category of filtered items).  (This command also works in
buffers of filtered items that have not yet been written to a file.)
@end table

In the todo items section of each Todo mode category, the item prefix
(whether a priority number or a fixed string) of the top priority
items (determined as specified in @pxref{Filtering Items}) is
displayed in a face (@code{todo-top-priority}) different from the face
of the prefix of non-top-priority items, so you see at a glance how
many items in the category are top priorities.

@node Other Display Commands and Options, , Item Prefix, Todo Display Features
@section Other Display Commands and Options

There are two additional toggle commands that affect display in the
current file:

@table @kbd

@item F h
@itemx h
Hide the item headers if visible, or show them if they are hidden.
With done items, only the done header (i.e., the done tag and date-time
string inserted when the item was marked done) is hidden, the original
date-time string is not. With filtered items, the category (or
category-file) tag is not hidden.

@item F H
@itemx H
Highlight the current item (with the face @code{hl-line}) if
unhighlighted, or remove its highlighting.  When item highlighting is
enabled, it follows navigation by @kbd{n} or @kbd{p}.  If you want to
have current item highlighting by default, enable the option
@code{todo-highlight-item}.  @kbd{F H} or @kbd{H} will still toggle
it.
@end table

There are two options which affect the display of items whose content is
longer than one screen line:

@itemize @bullet{}

@item
@code{todo-indent-to-here} sets the amount of indentation for all lines
after the first in multiline todo items, which is necessary in order
for todo diary items to be fully visible in the Fancy Diary display.
The default indentation is 3 spaces.  For a uniform appearance this
option applies to all items, i.e., diary and nondiary todo items and
also done items.

@item
@code{todo-wrap-lines} allows you to choose, for the purposes of
insertion and editing, between treating multiline todo items as
containing multiple logical lines with hard line breaks or as multiple
visual lines using Visual Line mode; the latter is the default.  Since
multiparagraph items also contain hard line breaks in Visual Line mode,
for a uniform appearance this display shows indentation on wrapped lines
by using a wrap-prefix of @code{todo-indent-to-here} spaces.
@end itemize

The indentation inserted after a hard newline is actually a tab
character, and the Todo modes that display items bind @code{tab-width} to
@code{todo-indent-to-here}, so if you change the default value of the
latter, the next time you visit a Todo file, the indentation will
reflect your change.

By default, the todo and done items sections of a todo category are
visually separated by a line as wide as the window the buffer is
displayed in.  You can change the appearance and width of the separator
by customizing @code{todo-done-separator-string}; you can also change the
face of the separator string (@code{todo-done-sep}).

There are also several options for changing the appearance in Todo
Categories mode and Todo Filtered Items mode, beyond those mentioned
above in the sections on these modes; see the customization groups
@code{todo-categories} and @code{todo-filtered} for details.

@node Printing Todo Buffers, Legacy Todo Mode Files, Todo Display Features, Top
@chapter Printing Todo Buffers

If you print a Todo buffer using one of the standard Emacs printing
commands, it does not look exactly like what you see in the buffer.
This is because some of the display features are non-printable
(specifically, those using overlays, word-wrap and wrap-prefix).  Todo
mode provides two print commands that produce output which includes
printable counterparts of such display features:

@table @kbd

@item P B
Send the printable buffer output directly to your printer.

@item P F
Prompt for a file name and write the printable output to that file.
@end table

By default, Todo uses @code{ps-print-buffer-with-faces} to make the
printable version; you can change this by setting the option
@code{todo-print-function}.

@node Legacy Todo Mode Files, GNU Free Documentation License, Printing Todo Buffers, Top
@chapter Legacy Todo Mode Files

Users of the original version of Todo mode will recognize from the
description in this user manual that, although the new version shares
with the original version the same basic user interface and handling of
todo items, there are some incompatible differences between them, such
as the done items sections (there are also other file format
incompatibilities behind the scenes that are normally not visible to
users).

The most significant incompatibility concerns the item prefix.  In the
earlier version of Todo mode the prefix was the initial part of the item
string itself, so in order for the item to be displayable in the Emacs
diary, the prefix had to be a date/time pattern recognizable by the
diary (although the todo item also has its own date/time header).
Moreover, since all items had the same prefix string in the original
version, this means that either only all or no items could appear in the
Fancy Diary display on any given date.  This considerably restricts the
practicality of including todo items in the diary.  In contrast, the
current version of Todo mode uses overlays for item priority numbering
or prefixes, and item-specific diary-compatible date/time headers and
special marks for todo items to be excluded from the diary, so you can
determine for each item whether and when it appears in the Fancy Diary
display.

Due to these incompatibilities, files created with the original version
of Todo mode cannot be displayed or edited with the current version.
However, this version provides a function that converts the two main
types of files used by the original version into new-style valid todo
and archive files, respectively, and saves them in
@code{todo-directory}.@footnote{The original version of Todo mode also
allowed saving a file of top priority items, but since you can readily
create such a file with the new version, which is also more flexible,
no conversion is provided for this file.}

This conversion function is automatically called the first time you
invoke @code{todo-show} (i.e., before you have created a todo file with
the new version), and if it finds the old-style files, it offers to
convert them, making them the first new-style todo and archive files.
If you choose not to convert the old-style files at this time, you can
do so later by invoking the command @code{todo-convert-legacy-files}
(there is no key binding for it, since it shouldn't be necessary to use
it often).  (A delicate part of the conversion concerns the customizable
format of item date/time headers in the old-style; see the documentation
string of @code{todo-legacy-date-time-regexp} for details.)

@node GNU Free Documentation License, , Legacy Todo Mode Files, Top
@appendix GNU Free Documentation License
@include doclicense.texi

@bye

@c End: