Source

XEmacs / man / xemacs / programs.texi

Full commit
   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
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063

@node Programs, Running, Text, Top
@chapter Editing Programs
@cindex Programming Languages
@cindex Lisp

  XEmacs provides specialized support for editing source files for many
different programming languages. For example it is possible to 

@itemize @bullet
@item
Follow the usual indentation conventions of the language
(@pxref{Grinding}).
@item
Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
@item
Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
functions, in C).
@item
Show how parentheses balance (@pxref{Matching}).
@item
Insert, kill, or align comments (@pxref{Comments}).
@item
Find functions and symbols in program by name (@pxref{Tags}).
@end itemize

  The commands available for words, sentences, and paragraphs are useful in
editing code even though their canonical application is for editing human
language text.  Most symbols contain words (@pxref{Words}); sentences can
be found in strings and comments (@pxref{Sentences}).  Paragraphs per se
are not present in code, but the paragraph commands are useful anyway,
because Lisp mode and C mode define paragraphs to begin and end at blank
lines (@pxref{Paragraphs}).  Judicious use of blank lines to make the
program clearer also provides interesting chunks of text for the
paragraph commands to work on.

  The selective display feature is useful for looking at the overall
structure of a function (@pxref{Selective Display}).  This feature causes
only the lines that are indented less than a specified amount to appear
on the screen.

@menu
* Program Modes::       Major modes for editing programs.
* Lists::               Expressions with balanced parentheses.
                         There are editing commands to operate on them.
* Defuns::              Each program is made up of separate functions.
                         There are editing commands to operate on them.
* Grinding::            Adjusting indentation to show the nesting.
* Matching::            Insertion of a close-delimiter flashes matching open.
* Comments::            Inserting, filling and aligning comments.
* Balanced Editing::    Inserting two matching parentheses at once, etc.
* Lisp Completion::     Completion on symbol names in Lisp code.
* Documentation::       Getting documentation of functions you plan to call.
* Change Log::          Maintaining a change history for your program.
* Tags::                Go direct to any function in your program in one
                         command.  Tags remembers which file it is in.
* CC Mode::             Modes for C, C++, Java and similar languages
* Fortran::		Fortran mode and its special features.
* Asm Mode::            Asm mode and its special features.
@end menu

@node Program Modes, Lists, Programs, Programs
@section Major Modes for Programming Languages

@cindex Lisp mode
  Emacs has several major modes (@pxref{Major Modes}) to support
programming languages. These major modes will typically understand
language syntax, provide automatic indentation features, syntax based
highlighting of text, and will often provide interfaces to the
programming environment to assist in compiling, executing and debugging
programs.

  A language mode exist when someone decides to take the trouble to
write it. At this time many widely used programming languages are
supported by XEmacs. Examples include Ada, Awk, C, C++, CORBA (IDL),
Fortran, Java, Lisp, Modula 2, Objective-C, Perl, Pike, Prolog, Python,
Ruby, Scheme, Simula, SQL, Tcl, Unix Shell scripts, and VHDL. Some of
these language have separate manuals, and some times more than one mode
may be available for a language.  For example, there are several
variants of Lisp mode, which differ in the way they interface to Lisp
execution.  @xref{Lisp Modes}. 

  Major modes for programming language support are distributed in
optional XEmacs packages (@pxref{Packages}) that must be installed
before use. A notable exception to this rule is that a Lisp Mode is
integral to XEmacs. The Programming Mode Package (@file{prog-modes})
contains many such modes. Some languages are supported by packages of
their own; prominent examples of such packages include @file{cc-mode}
for C, C++, Java, Objective C etc.@:, @file{python-modes} for Python,
and @file{scheme} for Scheme.

  For a language named @var{lang} the major mode for the language will
typically be named @code{@var{lang}-mode}.  For example, the mode for C
is called @code{c-mode}, that for Bourne shell scripts is called
@code{sh-mode} and so on.  These modes will invoke the functions listed
in the corresponding hook variables as a last step. @xref{Mode Hooks}.

  A mode can be invoked by typing @kbd{M-x @var{lang}-mode
@key{RET}}. However this step is not normally required. If the package
for a language mode is installed XEmacs usually knows when to
automatically invoke the mode. This is normally done based on examining
the file name to determine the language. @ref{Choosing Modes}.

  Each of the programming language modes defines the @key{TAB} key to
run an indentation function that knows the indentation conventions of
that language and updates the current line's indentation accordingly.
@key{LFD} is normally defined to do @key{RET} followed by @key{TAB};
thus it, too, indents in a mode-specific fashion.

@kindex DEL
@findex backward-delete-char-untabify
  In most programming languages, indentation is likely to vary from line to
line.  So the major modes for those languages rebind @key{DEL} to treat a
tab as if it were the equivalent number of spaces (using the command
@code{backward-delete-char-untabify}).  This makes it possible to rub out
indentation one column at a time without worrying whether it is made up of
spaces or tabs.  In these modes, use @kbd{C-b C-d} to delete a tab
character before point. 

  Programming language modes define paragraphs to be separated only by
blank lines, so that the paragraph commands remain useful.  Auto Fill mode,
if enabled in a programming language major mode, indents the new lines
which it creates.

@node Lists, Defuns, Program Modes, Programs
@section Lists and Sexps

@cindex Control-Meta
  By convention, Emacs keys for dealing with balanced expressions are
usually @kbd{Control-Meta-} characters.  They tend to be analogous in
function to their @kbd{Control-} and @kbd{Meta-} equivalents.  These commands
are usually thought of as pertaining to expressions in programming
languages, but can be useful with any language in which some sort of
parentheses exist (including English).

@cindex list
@cindex sexp
@cindex expression
  The commands fall into two classes.  Some commands deal only with
@dfn{lists} (parenthetical groupings).  They see nothing except
parentheses, brackets, braces (depending on what must balance in the
language you are working with), and escape characters that might be used
to quote those.

  The other commands deal with expressions or @dfn{sexps}.  The word `sexp'
is derived from @dfn{s-expression}, the term for a symbolic expression in
Lisp.  In Emacs, the notion of `sexp' is not limited to Lisp.  It
refers to an expression in the language  your program is written in.
Each programming language has its own major mode, which customizes the
syntax tables so that expressions in that language count as sexps.

  Sexps typically include symbols, numbers, and string constants, as well
as anything contained in parentheses, brackets, or braces.

  In languages that use prefix and infix operators, such as C, it is not
possible for all expressions to be sexps.  For example, C mode does not
recognize @samp{foo + bar} as an sexp, even though it @i{is} a C expression;
it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
@samp{+} as punctuation between them.  This is a fundamental ambiguity:
both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
move over if point is at the @samp{f}.  Note that @samp{(foo + bar)} is a
sexp in C mode.

  Some languages have obscure forms of syntax for expressions that nobody
has bothered to make Emacs understand properly.

@c doublewidecommands
@table @kbd
@item C-M-f
Move forward over an sexp (@code{forward-sexp}).
@item C-M-b
Move backward over an sexp (@code{backward-sexp}).
@item C-M-k
Kill sexp forward (@code{kill-sexp}).
@item C-M-u
Move up and backward in list structure (@code{backward-up-list}).
@item C-M-d
Move down and forward in list structure (@code{down-list}).
@item C-M-n
Move forward over a list (@code{forward-list}).
@item C-M-p
Move backward over a list (@code{backward-list}).
@item C-M-t
Transpose expressions (@code{transpose-sexps}).
@item C-M-@@
Put mark after following expression (@code{mark-sexp}).
@end table

@kindex C-M-f
@kindex C-M-b
@findex forward-sexp
@findex backward-sexp
  To move forward over an sexp, use @kbd{C-M-f} (@code{forward-sexp}).  If
the first significant character after point is an opening delimiter
(@samp{(} in Lisp; @samp{(}, @samp{[}, or @samp{@{} in C), @kbd{C-M-f}
moves past the matching closing delimiter.  If the character begins a
symbol, string, or number, @kbd{C-M-f} moves over that.  If the character
after point is a closing delimiter, @kbd{C-M-f} just moves past it.  (This
last is not really moving across an sexp; it is an exception which is
included in the definition of @kbd{C-M-f} because it is as useful a
behavior as anyone can think of for that situation.)@refill

  The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
sexp.  The detailed rules are like those above for @kbd{C-M-f}, but with
directions reversed.  If there are any prefix characters (single quote,
back quote, and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
over them as well.

  @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
specified number of times; with a negative argument, it moves in the
opposite direction.

@kindex C-M-k
@findex kill-sexp
  Killing an sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
@kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.

@kindex C-M-n
@kindex C-M-p
@findex forward-list
@findex backward-list
  The @dfn{list commands}, @kbd{C-M-n} (@code{forward-list}) and
@kbd{C-M-p} (@code{backward-list}), move over lists like the sexp
commands but skip over any number of other kinds of sexps (symbols,
strings, etc).  In some situations, these commands are useful because
they usually ignore comments, since the comments usually do not contain
any lists.@refill

@kindex C-M-u
@kindex C-M-d
@findex backward-up-list
@findex down-list
  @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
that is possible.  To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u}
(@code{backward-up-list}).
@kbd{C-M-u} moves backward up past one unmatched opening delimiter.  A
positive argument serves as a repeat count; a negative argument reverses
direction of motion and also requests repetition, so it moves forward and
up one or more levels.@refill

  To move @i{down} in list structure, use @kbd{C-M-d}
(@code{down-list}).  In Lisp mode, where @samp{(} is the only opening
delimiter, this is nearly the same as searching for a @samp{(}.  An
argument specifies the number of levels of parentheses to go down.

@cindex transposition
@kindex C-M-t
@findex transpose-sexps
@kbd{C-M-t} (@code{transpose-sexps}) drags the previous sexp across
the next one.  An argument serves as a repeat count, and a negative
argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with
a positive argument).  An argument of zero, rather than doing nothing,
transposes the sexps ending after point and the mark.

@kindex C-M-@@
@findex mark-sexp
  To make the region be the next sexp in the buffer, use @kbd{C-M-@@}
(@code{mark-sexp}) which sets the mark at the same place that
@kbd{C-M-f} would move to.  @kbd{C-M-@@} takes arguments like
@kbd{C-M-f}.  In particular, a negative argument is useful for putting
the mark at the beginning of the previous sexp.

  The list and sexp commands' understanding of syntax is completely
controlled by the syntax table.  Any character can, for example, be
declared to be an opening delimiter and act like an open parenthesis.
@xref{Syntax}.

@node Defuns, Grinding, Lists, Programs
@section Defuns
@cindex defuns

  In Emacs, a parenthetical grouping at the top level in the buffer is
called a @dfn{defun}.  The name derives from the fact that most
top-level lists in Lisp are instances of the special operator
@code{defun}, but Emacs calls any top-level parenthetical
grouping counts a defun regardless of its contents or
the programming language.  For example, in C, the body of a
function definition is a defun.

@c doublewidecommands
@table @kbd
@item C-M-a
Move to beginning of current or preceding defun
(@code{beginning-of-defun}).
@item C-M-e
Move to end of current or following defun (@code{end-of-defun}).
@item C-M-h
Put region around whole current or following defun (@code{mark-defun}).
@end table

@kindex C-M-a
@kindex C-M-e
@kindex C-M-h
@findex beginning-of-defun
@findex end-of-defun
@findex mark-defun
  The commands to move to the beginning and end of the current defun are
@kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).

  To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
which puts point at the beginning and the mark at the end of the current
or next defun.  This is the easiest way to prepare for moving the defun
to a different place.  In Lisp modes, a ``defun'' is merely any sexp
starting in column 1.  In other modes, a defun is a syntactic unit
defining an entity, and these modes often bind @kbd{C-M-h} to a
different function.  For example, in CC Mode's C mode, @kbd{C-M-h} runs
the function @code{c-mark-function}, which is almost the same as
@code{mark-defun}, but which backs up over the argument declarations,
function name, and returned data type so that the entire C function is
inside the region.  It also knows about struct definitions, macro
definitions, and many other constructs.

@findex compile-defun
To compile and evaluate the current defun, use @kbd{M-x compile-defun}. 
This function prints the results in the minibuffer. If you include an 
argument, it inserts the value in the current buffer after the defun.

  Emacs assumes that any open-parenthesis found in the leftmost column is
the start of a defun.  Therefore, @i{never put an open-parenthesis at the
left margin in a Lisp file unless it is the start of a top level list.
Never put an open-brace or other opening delimiter at the beginning of a
line of C code unless it starts the body of a function.}  The most likely
problem case is when you want an opening delimiter at the start of a line
inside a string.  To avoid trouble, put an escape character (@samp{\} in C
and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening
delimiter.  It will not affect the contents of the string.

  The original Emacs found defuns by moving upward a
level of parentheses until there were no more levels to go up.  This
required scanning back to the beginning of the buffer for every
function.  To speed this up, Emacs was changed to assume
that any @samp{(} (or other character assigned the syntactic class of
opening-delimiter) at the left margin is the start of a defun.  This
heuristic is nearly always right; however, it mandates the convention 
described above.

@node Grinding, Matching, Defuns, Programs
@section Indentation for Programs
@cindex indentation
@cindex grinding

  The best way to keep a program properly indented (``ground'') is to
use Emacs to re-indent it as you change the program.  Emacs has commands
to indent properly either a single line, a specified number of lines, or
all of the lines inside a single parenthetical grouping.

@menu
* Basic Indent::
* Multi-line Indent::   Commands to reindent many lines at once.
* Lisp Indent::		Specifying how each Lisp function should be indented.
@end menu

@node Basic Indent, Multi-line Indent, Grinding, Grinding
@subsection Basic Program Indentation Commands

@c WideCommands
@table @kbd
@item @key{TAB}
Adjust indentation of current line.
@item @key{LFD}
Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
@end table

@kindex TAB
@findex c-indent-line
@findex lisp-indent-line
  The basic indentation command is @key{TAB}, which gives the current
line the correct indentation as determined from the previous lines.  The
function that @key{TAB} runs depends on the major mode; it is
@code{lisp-indent-line} in Lisp mode, @code{c-indent-line} in C mode,
etc.  These functions understand different syntaxes for different
languages, but they all do about the same thing.  @key{TAB} in any
programming language major mode inserts or deletes whitespace at the
beginning of the current line, independent of where point is in the
line.  If point is inside the whitespace at the beginning of the line,
@key{TAB} leaves it at the end of that whitespace; otherwise, @key{TAB}
leaves point fixed with respect to the characters around it.

  Use @kbd{C-q @key{TAB}} to insert a tab at point.

@kindex LFD
@findex newline-and-indent
  When entering a large amount of new code, use @key{LFD}
(@code{newline-and-indent}), which is equivalent to a @key{RET} followed
by a @key{TAB}.  @key{LFD} creates a blank line, then gives it the
appropriate indentation.

  @key{TAB} indents the second and following lines of the body of a
parenthetical grouping each under the preceding one; therefore, if you
alter one line's indentation to be nonstandard, the lines below tend
to follow it.  This is the right behavior in cases where the standard
result of @key{TAB} does not look good.

  Remember that Emacs assumes that an open-parenthesis, open-brace, or
other opening delimiter at the left margin (including the indentation
routines) is the start of a function.  You should therefore never have
an opening delimiter in column zero that is not the beginning of a
function, not even inside a string.  This restriction is vital for
making the indentation commands fast. @xref{Defuns}, for more
information on this behavior.

@node Multi-line Indent, Lisp Indent, Basic Indent, Grinding
@subsection Indenting Several Lines

  Several commands are available to re-indent several lines of code
which have been altered or moved to a different level in a list
structure.


@table @kbd
@item C-M-q
Re-indent all the lines within one list (@code{indent-sexp}).
@item C-u @key{TAB}
Shift an entire list rigidly sideways so that its first line
is properly indented.
@item C-M-\
Re-indent all lines in the region (@code{indent-region}).
@end table

@kindex C-M-q
@findex indent-sexp
@findex indent-c-exp
 To re-indent the contents of a single list, position point before the
beginning of it and type @kbd{C-M-q}. This key is bound to
@code{indent-sexp} in Lisp mode, @code{indent-c-exp} in C mode, and
bound to other suitable functions in other modes.  The indentation of
the line the sexp starts on is not changed; therefore, only the relative
indentation within the list, and not its position, is changed.  To
correct the position as well, type a @key{TAB} before @kbd{C-M-q}.

@kindex C-u TAB
  If the relative indentation within a list is correct but the
indentation of its beginning is not, go to the line on which the list
begins and type @kbd{C-u @key{TAB}}.  When you give @key{TAB} a numeric
argument, it moves all the lines in the group, starting on the current
line, sideways the same amount that the current line moves.  The command
does not move lines that start inside strings, or C
preprocessor lines when in C mode.

@kindex C-M-\
@findex indent-region
  Another way to specify a range to be re-indented is with point and
mark.  The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB}
to every line whose first character is between point and mark.

@node Lisp Indent,  , Multi-line Indent, Grinding
@subsection Customizing Lisp Indentation
@cindex customization

  The indentation pattern for a Lisp expression can depend on the function
called by the expression.  For each Lisp function, you can choose among
several predefined patterns of indentation, or define an arbitrary one with
a Lisp program.

  The standard pattern of indentation is as follows: the second line of the
expression is indented under the first argument, if that is on the same
line as the beginning of the expression; otherwise, the second line is
indented underneath the function name.  Each following line is indented
under the previous line whose nesting depth is the same.

@vindex lisp-indent-offset
  If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
the usual indentation pattern for the second line of an expression, so that
such lines are always indented @code{lisp-indent-offset} more columns than
the containing list.

@vindex lisp-body-indention
  Certain functions override the standard pattern.  Functions
whose names start with @code{def} always indent the second line by
@code{lisp-body-indention} extra columns beyond the open-parenthesis
starting the expression.

  Individual functions can override the standard pattern in various
ways, according to the @code{lisp-indent-function} property of the
function name.  (Note: @code{lisp-indent-function} was formerly called
@code{lisp-indent-hook}).  There are four possibilities for this
property:

@table @asis
@item @code{nil}
This is the same as no property; the standard indentation pattern is used.
@item @code{defun}
The pattern used for function names that start with @code{def} is used for
this function also.
@item a number, @var{number}
The first @var{number} arguments of the function are
@dfn{distinguished} arguments; the rest are considered the @dfn{body}
of the expression.  A line in the expression is indented according to
whether the first argument on it is distinguished or not.  If the
argument is part of the body, the line is indented @code{lisp-body-indent}
more columns than the open-parenthesis starting the containing
expression.  If the argument is distinguished and is either the first
or second argument, it is indented @i{twice} that many extra columns.
If the argument is distinguished and not the first or second argument,
the standard pattern is followed for that line.
@item a symbol, @var{symbol}
@var{symbol} should be a function name; that function is called to
calculate the indentation of a line within this expression.  The
function receives two arguments:
@table @asis
@item @var{state}
The value returned by @code{parse-partial-sexp} (a Lisp primitive for
indentation and nesting computation) when it parses up to the
beginning of this line.
@item @var{pos}
The position at which the line being indented begins.
@end table
@noindent
It should return either a number, which is the number of columns of
indentation for that line, or a list whose first element is such a
number.  The difference between returning a number and returning a list
is that a number says that all following lines at the same nesting level
should be indented just like this one; a list says that following lines
might call for different indentations.  This makes a difference when the
indentation is computed by @kbd{C-M-q}; if the value is a number,
@kbd{C-M-q} need not recalculate indentation for the following lines
until the end of the list.
@end table


@node Matching, Comments, Grinding, Programs
@section Automatic Display of Matching Parentheses
@cindex matching parentheses
@cindex parentheses

  The Emacs parenthesis-matching feature shows you automatically how
parentheses match in the text.  Whenever a self-inserting character that
is a closing delimiter is typed, the cursor moves momentarily to the
location of the matching opening delimiter, provided that is visible on
the screen.  If it is not on the screen, some text starting with that
opening delimiter is displayed in the echo area.  Either way, you see
the grouping you are closing off. 

  In Lisp, automatic matching applies only to parentheses.  In C, it
also applies to braces and brackets.  Emacs knows which characters to regard
as matching delimiters based on the syntax table set by the major
mode.  @xref{Syntax}.

  If the opening delimiter and closing delimiter are mismatched---as
in @samp{[x)}---the echo area displays a warning message.  The
correct matches are specified in the syntax table.

@vindex blink-matching-paren
@vindex blink-matching-paren-distance
  Two variables control parenthesis matching displays.
@code{blink-matching-paren} turns the feature on or off. The default is 
@code{t} (match display is on); @code{nil} turns it off.
@code{blink-matching-paren-distance} specifies how many characters back
Emacs searches to find a matching opening delimiter.  If the match is
not found in the specified region, scanning stops, and nothing is
displayed.  This prevents wasting lots of time scanning when there is no
match.  The default is 4000.

@node Comments, Balanced Editing, Matching, Programs
@section Manipulating Comments
@cindex comments
@kindex M-;
@cindex indentation
@findex indent-for-comment

  The comment commands insert, kill and align comments.

@c WideCommands
@table @kbd
@item M-;
Insert or align comment (@code{indent-for-comment}).
@item C-x ;
Set comment column (@code{set-comment-column}).
@item C-u - C-x ;
Kill comment on current line (@code{kill-comment}).
@item M-@key{LFD}
Like @key{RET} followed by inserting and aligning a comment
(@code{indent-new-comment-line}).
@end table

  The command that creates a comment is @kbd{Meta-;}
(@code{indent-for-comment}).  If there is no comment already on the
line, a new comment is created and aligned at a specific column called
the @dfn{comment column}.  Emacs creates the comment by inserting the
string at the value of @code{comment-start}; see below.  Point is left
after that string.  If the text of the line extends past the comment
column, indentation is done to a suitable boundary (usually, at least
one space is inserted).  If the major mode has specified a string to
terminate comments, that string is inserted after point, to keep the
syntax valid.

  You can also use @kbd{Meta-;} to align an existing comment.  If a line
already contains the string that starts comments, @kbd{M-;} just moves
point after it and re-indents it to the conventional place.  Exception:
comments starting in column 0 are not moved.

  Some major modes have special rules for indenting certain kinds of
comments in certain contexts.  For example, in Lisp code, comments which
start with two semicolons are indented as if they were lines of code,
instead of at the comment column.  Comments which start with three
semicolons are supposed to start at the left margin.  Emacs understands
these conventions by indenting a double-semicolon comment using @key{TAB}
and by not changing the indentation of a triple-semicolon comment at all.

@example
;; This function is just an example.
;;; Here either two or three semicolons are appropriate.
(defun foo (x)
;;; And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.
@end example

  In C code, a comment preceded on its line by nothing but whitespace
is indented like a line of code.

  Even when an existing comment is properly aligned, @kbd{M-;} is still
useful for moving directly to the start of the comment.

@kindex C-u - C-x ;
@findex kill-comment
  @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the
current line, if there is one.  The indentation before the start of the
comment is killed as well.  If there does not appear to be a comment in
the line, nothing happens.  To reinsert the comment on another line,
move to the end of that line, type first @kbd{C-y}, and then @kbd{M-;}
to realign the comment.  Note that @kbd{C-u - C-x ;} is not a distinct
key; it is @kbd{C-x ;} (@code{set-comment-column}) with a negative
argument.  That command is programmed to call @code{kill-comment} when
called with a negative argument.  However, @code{kill-comment} is a
valid command which you could bind directly to a key if you wanted to.

@subsection Multiple Lines of Comments

@kindex M-LFD
@cindex blank lines
@cindex Auto Fill mode
@findex indent-new-comment-line
  If you are typing a comment and want to continue it on another line,
use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}),
which terminates the comment you are typing, creates a new blank line
afterward, and begins a new comment indented under the old one.  If
Auto Fill mode is on and you go past the fill column while typing, the 
comment is continued in just this fashion.  If point is
not at the end of the line when you type @kbd{M-@key{LFD}}, the text on
the rest of the line becomes part of the new comment line.

@subsection Options Controlling Comments

@vindex comment-column
@kindex C-x ;
@findex set-comment-column
  The comment column is stored in the variable @code{comment-column}.  You
can explicitly set it to a number.  Alternatively, the command @kbd{C-x ;}
(@code{set-comment-column}) sets the comment column to the column point is
at.  @kbd{C-u C-x ;} sets the comment column to match the last comment
before point in the buffer, and then calls @kbd{Meta-;} to align the
current line's comment under the previous one.  Note that @kbd{C-u - C-x ;}
runs the function @code{kill-comment} as described above.

  @code{comment-column} is a per-buffer variable; altering the variable
affects only the current buffer.  You can also change the default value.
@xref{Locals}.  Many major modes initialize this variable
for the current buffer.

@vindex comment-start-skip
  The comment commands recognize comments based on the regular expression
that is the value of the variable @code{comment-start-skip}.  This regexp
should not match the null string.  It may match more than the comment
starting delimiter in the strictest sense of the word; for example, in C
mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra
stars and spaces after the @samp{/*} itself.  (Note that @samp{\\} is
needed in Lisp syntax to include a @samp{\} in the string, which is needed
to deny the first star its special meaning in regexp syntax.  @xref{Regexps}.)

@vindex comment-start
@vindex comment-end
  When a comment command makes a new comment, it inserts the value of
@code{comment-start} to begin it.  The value of @code{comment-end} is
inserted after point and will follow the text you will insert
into the comment.  In C mode, @code{comment-start} has the value
@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.

@vindex comment-multi-line
  @code{comment-multi-line} controls how @kbd{M-@key{LFD}}
(@code{indent-new-comment-line}) behaves when used inside a comment.  If
@code{comment-multi-line} is @code{nil}, as it normally is, then
@kbd{M-@key{LFD}} terminates the comment on the starting line and starts
a new comment on the new following line.  If @code{comment-multi-line}
is not @code{nil}, then @kbd{M-@key{LFD}} sets up the new following line
as part of the same comment that was found on the starting line.  This
is done by not inserting a terminator on the old line and not inserting
a starter on the new line.  In languages where multi-line comments are legal,
the value you choose for this variable is a matter of taste.

@vindex comment-indent-hook
  The variable @code{comment-indent-hook} should contain a function that
is called to compute the indentation for a newly inserted comment or for
aligning an existing comment.  Major modes set this variable differently.
The function is called with no arguments, but with point at the
beginning of the comment, or at the end of a line if a new comment is to
be inserted.  The function should return the column in which the comment
ought to start.  For example, in Lisp mode, the indent hook function
bases its decision on the number of semicolons that begin an existing
comment and on the code in the preceding lines.

@node Balanced Editing, Lisp Completion, Comments, Programs
@section Editing Without Unbalanced Parentheses

@table @kbd
@item M-(
Put parentheses around next sexp(s) (@code{insert-parentheses}).
@item M-)
Move past next close parenthesis and re-indent
(@code{move-over-close-and-reindent}).
@end table

@kindex M-(
@kindex M-)
@findex insert-parentheses
@findex move-over-close-and-reindent
  The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
(@code{move-over-close-and-reindent}) are designed to facilitate a style of
editing which keeps parentheses balanced at all times.  @kbd{M-(} inserts a
pair of parentheses, either together as in @samp{()}, or, if given an
argument, around the next several sexps, and leaves point after the open
parenthesis.  Instead of typing @kbd{( F O O )}, you can type @kbd{M-( F O
O}, which has the same effect except for leaving the cursor before the
close parenthesis.  You can then type @kbd{M-)}, which moves past the
close parenthesis, deletes any indentation preceding it (in this example
there is none), and indents with @key{LFD} after it.

@node Lisp Completion, Documentation, Balanced Editing, Programs
@section Completion for Lisp Symbols
@cindex completion (symbol names)

   Completion usually happens in the minibuffer.  An exception is
completion for Lisp symbol names, which is available in all buffers.

@kindex M-TAB
@findex lisp-complete-symbol
  The command @kbd{M-@key{TAB}} (@code{lisp-complete-symbol}) takes the
partial Lisp symbol before point to be an abbreviation, and compares it
against all non-trivial Lisp symbols currently known to Emacs.  Any
additional characters that they all have in common are inserted at point.
Non-trivial symbols are those that have function definitions, values, or
properties.

  If there is an open-parenthesis immediately before the beginning of
the partial symbol, only symbols with function definitions are considered
as completions.

  If the partial name in the buffer has more than one possible completion
and they have no additional characters in common, a list of all possible
completions is displayed in another window.

@node Documentation, Change Log, Lisp Completion, Programs
@section Documentation Commands

@kindex C-h f
@findex describe-function
@kindex C-h v
@findex describe-variable
  As you edit Lisp code to be run in Emacs, you can use the commands
@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
(@code{describe-variable}) to print documentation of functions and
variables you want to call.  These commands use the minibuffer to
read the name of a function or variable to document, and display the
documentation in a window.

  For extra convenience, these commands provide default arguments based on
the code in the neighborhood of point.  @kbd{C-h f} sets the default to the
function called in the innermost list containing point.  @kbd{C-h v} uses
the symbol name around or adjacent to point as its default.

@findex manual-entry
  The @kbd{M-x manual-entry} command gives you access to documentation
on Unix commands, system calls, and libraries.  The command reads a
topic as an argument, and displays the Unix manual page for that topic. 
@code{manual-entry} always searches all 8 sections of the
manual and concatenates all the entries it finds.  For example,
the topic @samp{termcap} finds the description of the termcap library
from section 3, followed by the description of the termcap data base
from section 5.

@node Change Log, Tags, Documentation, Programs
@section Change Logs

@cindex change log
@findex add-change-log-entry
  The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record
of when and why you have changed a program.  It assumes that you have a
file in which you write a chronological sequence of entries describing
individual changes.  The default is to store the change entries in a file
called @file{ChangeLog} in the same directory as the file you are editing.
The same @file{ChangeLog} file therefore records changes for all the files
in a directory.

  A change log entry starts with a header line that contains your name
and the current date.  Except for these header lines, every line in the
change log starts with a tab.  One entry can describe several changes;
each change starts with a line starting with a tab and a star.  @kbd{M-x
add-change-log-entry} visits the change log file and creates a new entry
unless the most recent entry is for today's date and your name.  In
either case, it adds a new line to start the description of another
change just after the header line of the entry.  When @kbd{M-x
add-change-log-entry} is finished, all is prepared for you to edit in
the description of what you changed and how.  You must then save the
change log file yourself.

  The change log file is always visited in Indented Text mode, which means
that @key{LFD} and auto-filling indent each new line like the previous
line.  This is convenient for entering the contents of an entry, which must
be indented.  @xref{Text Mode}.

  Here is an example of the formatting conventions used in the change log
for Emacs:

@smallexample
Wed Jun 26 19:29:32 1985  Richard M. Stallman  (rms at mit-prep)

        * xdisp.c (try_window_id):
        If C-k is done at end of next-to-last line,
        this fn updates window_end_vpos and cannot leave
        window_end_pos nonnegative (it is zero, in fact).
        If display is preempted before lines are output,
        this is inconsistent.  Fix by setting
        blank_end_of_window to nonzero.

Tue Jun 25 05:25:33 1985  Richard M. Stallman  (rms at mit-prep)

        * cmds.c (Fnewline):
        Call the auto fill hook if appropriate.

        * xdisp.c (try_window_id):
        If point is found by compute_motion after xp, record that
        permanently.  If display_text_line sets point position wrong
        (case where line is killed, point is at eob and that line is
        not displayed), set it again in final compute_motion.
@end smallexample

@node Tags, CC Mode, Change Log, Programs
@section Tags Tables
@cindex tags table

  A @dfn{tags table} is a description of how a multi-file program is
broken up into files.  It lists the names of the component files and the
names and positions of the functions (or other named subunits) in each
file.  Grouping the related files makes it possible to search or replace
through all the files with one command.  Recording the function names
and positions makes possible the @kbd{M-.} command which finds the
definition of a function by looking up which of the files it is in.

  Tags tables are stored in files called @dfn{tags table files}.  The
conventional name for a tags table file is @file{TAGS}.

  Each entry in the tags table records the name of one tag, the name of the
file that the tag is defined in (implicitly), and the position in that file
of the tag's definition.

  Just what names from the described files are recorded in the tags table
depends on the programming language of the described file.  They
normally include all functions and subroutines, and may also include
global variables, data types, and anything else convenient.  Each name
recorded is called a @dfn{tag}.

@cindex C++ class browser, tags
@cindex tags, C++
@cindex class browser, C++
@cindex Ebrowse
The Ebrowse is a separate facility tailored for C++, with tags and a
class browser.  @xref{Ebrowse,,, ebrowse, Ebrowse User's Manual}.

@menu
* Tag Syntax::		Tag syntax for various types of code and text files.
* Create Tags Table::	Creating a tags table with @code{etags}.
* Etags Regexps::       Create arbitrary tags using regular expressions.
* Select Tags Table::	How to visit a tags table.
* Find Tag::		Commands to find the definition of a specific tag.
* Tags Search::		Using a tags table for searching and replacing.
* List Tags::		Listing and finding tags defined in a file.
@end menu

@node Tag Syntax
@subsection Source File Tag Syntax

  Here is how tag syntax is defined for the most popular languages:

@itemize @bullet
@item
In C code, any C function or typedef is a tag, and so are definitions of
@code{struct}, @code{union} and @code{enum}.  You can tag function
declarations and external variables in addition to function definitions
by giving the @samp{--declarations} option to @code{etags}.
@code{#define} macro definitions and @code{enum} constants are also
tags, unless you specify @samp{--no-defines} when making the tags table.
Similarly, global variables are tags, unless you specify
@samp{--no-globals}.  Use of @samp{--no-globals} and @samp{--no-defines}
can make the tags table file much smaller.

@item
In C++ code, in addition to all the tag constructs of C code, member
functions are also recognized, and optionally member variables if you
use the @samp{--members} option.  Tags for variables and functions in
classes are named @samp{@var{class}::@var{variable}} and
@samp{@var{class}::@var{function}}.  @code{operator} functions tags are
named, for example @samp{operator+}.

@item
In Java code, tags include all the constructs recognized in C++, plus
the @code{interface}, @code{extends} and @code{implements} constructs.
Tags for variables and functions in classes are named
@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.

@item
In La@TeX{} text, the argument of any of the commands @code{\chapter},
@code{\section}, @code{\subsection}, @code{\subsubsection},
@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
tag.@refill

Other commands can make tags as well, if you specify them in the
environment variable @code{TEXTAGS} before invoking @code{etags}.  The
value of this environment variable should be a colon-separated list of
command names.  For example,

@example
TEXTAGS="def:newcommand:newenvironment"
export TEXTAGS
@end example

@noindent
specifies (using Bourne shell syntax) that the commands @samp{\def},
@samp{\newcommand} and @samp{\newenvironment} also define tags.

@item
In Lisp code, any function defined with @code{defun}, any variable
defined with @code{defvar} or @code{defconst}, and in general the first
argument of any expression that starts with @samp{(def} in column zero, is
a tag.

@item
In Scheme code, tags include anything defined with @code{def} or with a
construct whose name starts with @samp{def}.  They also include variables
set with @code{set!} at top level in the file.
@end itemize

  Several other languages are also supported:

@itemize @bullet

@item
In Ada code, functions, procedures, packages, tasks, and types are
tags.  Use the @samp{--packages-only} option to create tags for
packages only.

With Ada, it is possible to have the same name used for different
entity kinds (e.g.@: the same name for a procedure and a function).  Also,
for things like packages, procedures and functions, there is the spec
(i.e.@: the interface) and the body (i.e.@: the implementation).  To
facilitate the choice to the user, a tag value is appended with a
qualifier:

@table @asis
@item function
 @kbd{/f}
@item procedure
 @kbd{/p}
@item package spec
 @kbd{/s}
@item package body
 @kbd{/b}
@item type
 @kbd{/t}
@item task
 @kbd{/k}
@end table

So, as an example, @kbd{M-x find-tag bidule/b} will go directly to the
body of the package @var{bidule} while @kbd{M-x find-tag bidule} will
just search for any tag @var{bidule}.

@item
In assembler code, labels appearing at the beginning of a line,
followed by a colon, are tags.

@item
In Bison or Yacc input files, each rule defines as a tag the nonterminal
it constructs.  The portions of the file that contain C code are parsed
as C code.

@item
In Cobol code, tags are paragraph names; that is, any word starting in
column 8 and followed by a period.

@item
In Erlang code, the tags are the functions, records, and macros defined
in the file.

@item
In Fortran code, functions, subroutines and blockdata are tags.

@item
In makefiles, targets are tags.

@item
In Objective C code, tags include Objective C definitions for classes,
class categories, methods, and protocols.

@item
In Pascal code, the tags are the functions and procedures defined in
the file.

@item
In Perl code, the tags are the procedures defined by the @code{sub},
@code{my} and @code{local} keywords.  Use @samp{--globals} if you want
to tag global variables.

@item
In PHP code, tags are functions, classes and defines.  When using the
@samp{--members} option, vars are tags too.

@item
In PostScript code, the tags are the functions.

@item
In Prolog code, tags are predicates and rules at the beginning of
line.

@item
In Python code, @code{def} or @code{class} at the beginning of a line
generate a tag.
@end itemize

  You can also generate tags based on regexp matching (@pxref{Etags
Regexps}) to handle other formats and languages.

@node Create Tags Table
@subsection Creating Tags Tables
@cindex @code{etags} program

  The @code{etags} program is used to create a tags table file.  It knows
the syntax of several languages, as described in
@iftex
the previous section.
@end iftex
@ifinfo
@ref{Tag Syntax}.
@end ifinfo
Here is how to run @code{etags}:

@example
etags @var{inputfiles}@dots{}
@end example

@noindent
The @code{etags} program reads the specified files, and writes a tags
table named @file{TAGS} in the current working directory.  You can
intermix compressed and plain text source file names.  @code{etags}
knows about the most common compression formats, and does the right
thing.  So you can compress all your source files and have @code{etags}
look for compressed versions of its file name arguments, if it does not
find uncompressed versions.  Under MS-DOS, @code{etags} also looks for
file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
command line and @samp{mycode.c} does not exist.

  @code{etags} recognizes the language used in an input file based on
its file name and contents.  You can specify the language with the
@samp{--language=@var{name}} option, described below.

  If the tags table data become outdated due to changes in the files
described in the table, the way to update the tags table is the same way it
was made in the first place.  It is not necessary to do this often.

  If the tags table fails to record a tag, or records it for the wrong
file, then Emacs cannot possibly find its definition.  However, if the
position recorded in the tags table becomes a little bit wrong (due to
some editing in the file that the tag definition is in), the only
consequence is a slight delay in finding the tag.  Even if the stored
position is very wrong, Emacs will still find the tag, but it must
search the entire file for it.

  So you should update a tags table when you define new tags that you want
to have listed, or when you move tag definitions from one file to another,
or when changes become substantial.  Normally there is no need to update
the tags table after each edit, or even every day.

  One tags table can effectively include another.  Specify the included
tags file name with the @samp{--include=@var{file}} option when creating
the file that is to include it.  The latter file then acts as if it
contained all the files specified in the included file, as well as the
files it directly contains.

  If you specify the source files with relative file names when you run
@code{etags}, the tags file will contain file names relative to the
directory where the tags file was initially written.  This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source
files.

  If you specify absolute file names as arguments to @code{etags}, then
the tags file will contain absolute file names.  This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place.  Absolute file names start with
@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.

  When you want to make a tags table from a great number of files, you
may have problems listing them on the command line, because some systems
have a limit on its length.  The simplest way to circumvent this limit
is to tell @code{etags} to read the file names from its standard input,
by typing a dash in place of the file names, like this:

@smallexample
find . -name "*.[chCH]" -print | etags -
@end smallexample

  Use the option @samp{--language=@var{name}} to specify the language
explicitly.  You can intermix these options with file names; each one
applies to the file names that follow it.  Specify
@samp{--language=auto} to tell @code{etags} to resume guessing the
language from the file names and file contents.  Specify
@samp{--language=none} to turn off language-specific processing
entirely; then @code{etags} recognizes tags by regexp matching alone
(@pxref{Etags Regexps}).

  @samp{etags --help} prints the list of the languages @code{etags}
knows, and the file name rules for guessing the language. It also prints
a list of all the available @code{etags} options, together with a short
explanation.

@node Etags Regexps
@subsection Etags Regexps

  The @samp{--regex} option provides a general way of recognizing tags
based on regexp matching.  You can freely intermix it with file names.
Each @samp{--regex} option adds to the preceding ones, and applies only
to the following files.  The syntax is:

@smallexample
--regex=/@var{tagregexp}[/@var{nameregexp}]/
@end smallexample

@noindent
where @var{tagregexp} is used to match the lines to tag.  It is always
anchored, that is, it behaves as if preceded by @samp{^}.  If you want
to account for indentation, just match any initial number of blanks by
beginning your regular expression with @samp{[ \t]*}.  In the regular
expressions, @samp{\} quotes the next character, and @samp{\t} stands
for the tab character.  Note that @code{etags} does not handle the other
C escape sequences for special characters.

@cindex interval operator (in regexps)
  The syntax of regular expressions in @code{etags} is the same as in
Emacs, augmented with the @dfn{interval operator}, which works as in
@code{grep} and @code{ed}.  The syntax of an interval operator is
@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
expression at least @var{m} times and up to @var{n} times.

  You should not match more characters with @var{tagregexp} than that
needed to recognize what you want to tag.  If the match is such that
more characters than needed are unavoidably matched by @var{tagregexp}
(as will usually be the case), you should add a @var{nameregexp}, to
pick out just the tag.  This will enable Emacs to find tags more
accurately and to do completion on tag names more reliably.  You can
find some examples below.

  The option @samp{--ignore-case-regex} (or @samp{-c}) is like
@samp{--regex}, except that the regular expression provided will be
matched without regard to case, which is appropriate for various
programming languages.

  The @samp{-R} option deletes all the regexps defined with
@samp{--regex} options.  It applies to the file names following it, as
you can see from the following example:

@smallexample
etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
    bar.ber -R --lang=lisp los.er
@end smallexample

@noindent
Here @code{etags} chooses the parsing language for @file{voo.doo} and
@file{bar.ber} according to their contents.  @code{etags} also uses
@var{reg1} to recognize additional tags in @file{voo.doo}, and both
@var{reg1} and @var{reg2} to recognize additional tags in
@file{bar.ber}.  @code{etags} uses the Lisp tags rules, and no regexp
matching, to recognize tags in @file{los.er}.

  A regular expression can be bound to a given language, by prepending
it with @samp{@{lang@}}.  When you do this, @code{etags} will use the
regular expression only for files of that language.  @samp{etags --help}
prints the list of languages recognised by @code{etags}.  The following
example tags the @code{DEFVAR} macros in the Emacs source files.
@code{etags} applies this regular expression to C files only:

@smallexample
--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
@end smallexample

@noindent
This feature is particularly useful when storing a list of regular
expressions in a file.  The following option syntax instructs
@code{etags} to read two files of regular expressions.  The regular
expressions contained in the second file are matched without regard to
case.

@smallexample
--regex=@@first-file --ignore-case-regex=@@second-file
@end smallexample

@noindent
A regex file contains one regular expressions per line.  Empty lines,
and lines beginning with space or tab are ignored.  When the first
character in a line is @samp{@@}, @code{etags} assumes that the rest of
the line is the name of a file of regular expressions.  This means that
such files can be nested.  All the other lines are taken to be regular
expressions.  For example, one can create a file called
@samp{emacs.tags} with the following contents (the first line in the
file is a comment):

@smallexample
        -- This is for GNU Emacs source files
@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
@end smallexample

@noindent
and then use it like this:

@smallexample
etags --regex=@@emacs.tags *.[ch] */*.[ch]
@end smallexample

  Here are some more examples.  The regexps are quoted to protect them
from shell interpretation.

@itemize @bullet

@item
Tag Octave files:

@smallexample
etags --language=none \
      --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
      --regex='/###key \(.*\)/\1/' \
      --regex='/[ \t]*global[ \t].*/' \
      *.m
@end smallexample

@noindent
Note that tags are not generated for scripts so that you have to add a
line by yourself of the form `###key <script-name>' if you want to jump
to it.

@item
Tag Tcl files:

@smallexample
etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
@end smallexample

@item
Tag VHDL files:

@smallexample
--language=none \
--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
@end smallexample
@end itemize

@node Select Tags Table, Find Tag, Etags Regexps, Tags
@subsection Selecting a Tags Table

@vindex tag-table-alist
   At any time Emacs has one @dfn{selected} tags table, and all the commands
for working with tags tables use the selected one.  To select a tags table,
use the variable @code{tag-table-alist}.

The value of @code{tag-table-alist} is a list that determines which
@code{TAGS} files should be active for a given buffer.  This is not
really an association list, in that all elements are checked.  The car
of each element of this list is a pattern against which the buffers file
name is compared; if it matches, then the cdr of the list should be the
name of the tags table to use.  If more than one element of this list
matches the buffers file name, all of the associated tags tables are
used.  Earlier ones are searched first.

If the car of elements of this list are strings, they are treated
as regular-expressions against which the file is compared (like the
@code{auto-mode-alist}).  If they are not strings, they are evaluated.
If they evaluate to non-@code{nil}, the current buffer is considered to
match.

If the cdr of the elements of this list are strings, they are
assumed to name a tags file.  If they name a directory, the string
@file{tags} is appended to them to get the file name.  If they are not 
strings, they are evaluated and must return an appropriate string.

For example:

@example
  (setq tag-table-alist
        '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
          ("\\.el$" . "/usr/local/emacs/src/")
          ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
          ("" . "/usr/local/emacs/src/")
          ))
@end example

The example defines the tags table alist in the following way:
 
@itemize @bullet
@item
Anything in the directory @file{/usr/src/public/perl/} 
should use the @file{TAGS} file @file{/usr/src/public/perl/perl-3.0/TAGS}. 
@item
Files ending in @file{.el} should use the @file{TAGS} file
@file{/usr/local/emacs/src/TAGS}. 
@item
Anything in or below the directory @file{/jbw/gnu/} should use the 
@file{TAGS} file @file{/usr15/degree/stud/jbw/gnu/TAGS}.  
@end itemize

If you had a file called @file{/usr/jbw/foo.el}, it would use both
@file{TAGS} files, @* @file{/usr/local/emacs/src/TAGS} and
@file{/usr15/degree/stud/jbw/gnu/TAGS} (in that order), because it
matches both patterns.

If the buffer-local variable @code{buffer-tag-table} is set, it names a
tags table that is searched before all others when @code{find-tag} is
executed from this buffer.

If there is a file called @file{TAGS} in the same directory as the file
in question, then that tags file will always be used as well (after the
@code{buffer-tag-table} but before the tables specified by this list).

If the variable @code{tags-file-name} is set, the @file{TAGS} file it names
will apply to all buffers (for backwards compatibility.)  It is searched
first.

@vindex tags-always-build-completion-table
If the value of the variable @code{tags-always-build-completion-table}
is @code{t}, the tags file will always be added to the completion table
without asking first, regardless of the size of the tags file.

@vindex tags-file-name
@findex visit-tags-table
The function @kbd{M-x visit-tags-table}, is largely made obsolete by
the variable @code{tag-table-alist}, tells tags commands to use the tags
table file @var{file} first.  The @var{file} should be the name of a
file created with the @code{etags} program.  A directory name is also
acceptable; it means the file @file{TAGS} in that directory.  The
function only stores the file name you provide in the variable
@code{tags-file-name}.  Emacs does not actually read in the tags table
contents until you try to use them.  You can set the variable explicitly
instead of using @code{visit-tags-table}.  The value of the variable
@code{tags-file-name} is the name of the tags table used by all buffers.
This is for backward compatibility, and is largely supplanted by the
variable @code{tag-table-alist}.
 
@node Find Tag, Tags Search, Select Tags Table, Tags
@subsection Finding a Tag

  The most important thing that a tags table enables you to do is to find
the definition of a specific tag.

@table @kbd
@item M-.@: @var{tag &optional other-window}
Find first definition of @var{tag} (@code{find-tag}).
@item C-u M-.
Find next alternate definition of last tag specified.
@item C-x 4 . @var{tag}
Find first definition of @var{tag}, but display it in another window
(@code{find-tag-other-window}).
@end table

@kindex M-.
@findex find-tag
  @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
a specified tag.  It searches through the tags table for that tag, as a
string, then uses the tags table information to determine the file in
which the definition is used and the approximate character position of
the definition in the file.  Then @code{find-tag} visits the file,
moves point to the approximate character position, and starts searching
ever-increasing distances away for the text that should appear at
the beginning of the definition.

  If an empty argument is given (by typing @key{RET}), the sexp in the
buffer before or around point is used as the name of the tag to find.
@xref{Lists}, for information on sexps.

  The argument to @code{find-tag} need not be the whole tag name; it can
be a substring of a tag name.  However, there can be many tag names
containing the substring you specify.  Since @code{find-tag} works by
searching the text of the tags table, it finds the first tag in the table
that the specified substring appears in.  To find other tags that match
the substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
M-.}.  This does not read a tag name, but continues searching the tag
table's text for another tag containing the same substring last used.
If your keyboard has a real @key{META} key, @kbd{M-0 M-.}@: is an easier
alternative to @kbd{C-u M-.}.

If the optional second argument @var{other-window} is non-@code{nil}, it uses
another window to display the tag.
Multiple active tags tables and completion are supported.

Variables of note include the following:

@vindex tag-table-alist
@vindex tags-file-name
@vindex tags-build-completion-table
@vindex buffer-tag-table
@vindex make-tags-files-invisible
@vindex tag-mark-stack-max

@table @kbd
@item tag-table-alist
Controls which tables apply to which buffers.
@item tags-file-name
Stores a default tags table.
@item tags-build-completion-table
Controls completion behavior.
@item buffer-tag-table
Specifies a buffer-local table.
@item make-tags-files-invisible
Sets whether tags tables should be very hidden.
@item tag-mark-stack-max
Specifies how many tags-based hops to remember.
@end table

@kindex C-x 4 .
@findex find-tag-other-window
  Like most commands that can switch buffers, @code{find-tag} has another
similar command that displays the new buffer in another window.  @kbd{C-x 4
.}@: invokes the function @code{find-tag-other-window}.  (This key sequence
ends with a period.)

  Emacs comes with a tags table file @file{TAGS} (in the directory
containing Lisp libraries) that includes all the Lisp libraries and all
the C sources of Emacs.  By specifying this file with @code{visit-tags-table}
and then using @kbd{M-.}@: you can quickly look at the source of any Emacs
function.

@node Tags Search, List Tags, Find Tag, Tags
@subsection Searching and Replacing with Tags Tables

  The commands in this section visit and search all the files listed in the
selected tags table, one by one.  For these commands, the tags table serves
only to specify a sequence of files to search.  A related command is
@kbd{M-x grep} (@pxref{Compilation}).

@table @kbd
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
Search for @var{regexp} through the files in the selected tags
table.
@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
Perform a @code{query-replace-regexp} on each file in the selected tags table.
@item M-,
Restart one of the commands above, from the current location of point
(@code{tags-loop-continue}).
@end table

@findex tags-search
  @kbd{M-x tags-search} reads a regexp using the minibuffer, then
searches for matches in all the files in the selected tags table, one
file at a time.  It displays the name of the file being searched so you
can follow its progress.  As soon as it finds an occurrence,
@code{tags-search} returns.

@kindex M-,
@findex tags-loop-continue
  Having found one match, you probably want to find all the rest.  To find
one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
@code{tags-search}.  This searches the rest of the current buffer, followed
by the remaining files of the tags table.@refill

@findex tags-query-replace
  @kbd{M-x tags-query-replace} performs a single
@code{query-replace-regexp} through all the files in the tags table.  It
reads a regexp to search for and a string to replace with, just like
ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
tags-search}, but repeatedly, processing matches according to your
input.  @xref{Replace}, for more information on query replace.

  It is possible to get through all the files in the tags table with a
single invocation of @kbd{M-x tags-query-replace}.  But often it is
useful to exit temporarily, which you can do with any input event that
has no special query replace meaning.  You can resume the query replace
subsequently by typing @kbd{M-,}; this command resumes the last tags
search or replace command that you did.

  The commands in this section carry out much broader searches than the
@code{find-tag} family.  The @code{find-tag} commands search only for
definitions of tags that match your substring or regexp.  The commands
@code{tags-search} and @code{tags-query-replace} find every occurrence
of the regexp, as ordinary search commands and replace commands do in
the current buffer.

  These commands create buffers only temporarily for the files that they
have to search (those which are not already visited in Emacs buffers).
Buffers in which no match is found are quickly killed; the others
continue to exist.

  It may have struck you that @code{tags-search} is a lot like
@code{grep}.  You can also run @code{grep} itself as an inferior of
Emacs and have Emacs show you the matching lines one by one.  This works
much like running a compilation; finding the source locations of the
@code{grep} matches works like finding the compilation errors.
@xref{Compilation}.

  If you wish to process all the files in a selected tags table, but
@kbd{M-x tags-search} and @kbd{M-x tags-query-replace} are not giving
you the desired result, you can use @kbd{M-x next-file}.

@table @kbd
@item C-u M-x next-file
With a numeric argument, regardless of its value, visit the first
file in the tags table and prepare to advance sequentially by files.
@item M-x next-file
Visit the next file in the selected tags table.
@end table

@node List Tags,  , Tags Search, Tags
@subsection Tags Table Inquiries

@table @kbd
@item M-x list-tags
Display a list of the tags defined in a specific program file.
@item M-x tags-apropos
Display a list of all tags matching a specified regexp.
@end table

@findex list-tags
  @kbd{M-x list-tags} reads the name of one of the files described by the
selected tags table, and displays a list of all the tags defined in that
file.  The ``file name'' argument is really just a string to compare
against the names recorded in the tags table; it is read as a string rather
than a file name.  Therefore, completion and defaulting are not
available, and you must enter the string the same way it appears in the tag
table.  Do not include a directory as part of the file name unless the file
name recorded in the tags table contains that directory.

@findex tags-apropos
  @kbd{M-x tags-apropos} is like @code{apropos} for tags.  It reads a regexp,
then finds all the tags in the selected tags table whose entries match that
regexp, and displays the tag names found.

@node CC Mode, Fortran, Tags, Programs
@section Modes for C, C++, Java and similar languages
@cindex C Mode
@cindex C++ Mode
@cindex Java Mode
@cindex AWK Mode
@cindex Objective C Mode
@cindex CORBA IDL Mode
@findex c-mode
@findex c++-mode
@findex java-mode
@findex idl-mode
@findex awk-mode
@findex pike-mode
@findex objc-mode
@vindex c-mode-hook
@vindex c++-mode-hook
@vindex java-mode-hook
@vindex idl-mode-hook
@vindex awk-mode-hook
@vindex pike-mode-hook
@vindex objc-mode-hook
@vindex c-mode-common-hook
@vindex c-initialization-hook

  The recommended means for supporting the ``C--like'' programming
languages in XEmacs is the @file{cc-mode} package.  CC Mode is not
included in the basic XEmacs distribution but is available as an
optional package. If loading a file whose names ends in the @file{.cc}
extension does not automatically invoke a C++ Mode then the
@file{cc-mode} package is probably not yet installed. @xref{Packages}.

  CC Mode provides modes for editing source files in Awk
(@code{awk-mode}), C (@code{c-mode}), C++ (@code{c++-mode}), CORBA IDL
(@code{idl-mode}), Java (@code{java-mode}), Objective C
(@code{objc-mode}), and Pike (@code{pike-mode}). All these languages are
supported with an sophisticated ``indentation engine'' that is feature
rich, customizable and quite efficient.

  Each language major mode runs hooks in the conventionally named hook
variables (@pxref{Mode Hooks}). In addition to this conventional
behavior all the CC Mode major modes will also run hooks in
@code{c-mode-common-hook} @emph{before} invoking the major mode specific
hook. 

  CC Mode runs any hooks in @code{c-initialization-hook} exactly once
when it is first loaded.
  
  CC Mode is a very comprehensive and flexible system and full
description of its capabilities is beyond the scope of this manual.  It
is strongly recommended that the reader consult the CC Mode
documentation for details once the package has been
installed. @xref{Top,CC Mode,,cc-mode, The CC Mode Manual}.

@menu
* Older Modes::             Older Modes for C and AWK
* Customizing CC Mode::     An Introduction to Customizing CC Mode.
@end menu


@node Older Modes, Customizing CC Mode, CC Mode, CC Mode
@subsection Older Modes for C and AWK
@cindex Old C Mode
@cindex Old AWK Mode
@cindex C Mode without CC Mode
@cindex AWK Mode without CC Mode
@cindex old-c-mode

  XEmacs provides older versions of a C Mode and an AWK Mode in the
@file{prog-modes} package. These older modes do not share the
indentation engine in CC Mode have have their own specific means of
customizing indentation. To use these modes the @file{prog-modes}
package must be installed.

  This older C mode is known simply as the ``Old C Mode''. It supports
only the C language and it lacks many of the features of CC Mode.
However the old C mode offers modest space requirements and very fast
operation.  Old C Mode might be useful in space constrained
environments, on slow machines, or for editing very large files. This
old C mode is available in the @file{old-c-mode}
library. @xref{old-c-mode,Old C Mode,old-c-mode,prog-modes,The
Programming Modes Package Manual}.

  The old AWK mode exists for similar reasons. It is available in the
@file{awk-mode} library.  @xref{awk-mode,Old AWK
Mode,awk-mode,prog-modes,The Programming Modes Package Manual}.

  Note that the prog-modes package will never automatically invoke these
older modes for a user. However installing the @file{cc-mode} package
@emph{will} make CC Mode's versions available automatically.  As a
result a user who wants to use these older modes must explicitly load
the old libraries to use them.

@node Customizing CC Mode,  , Older Modes, CC Mode
@subsection Customizing Indentation in CC Mode

  A very brief introduction is included here on customizing CC Mode. CC
Mode has many features, including useful minor modes, that are
completely documented in its own manual.

  CC Mode implements several different ``styles'' for C code (and the
other languages supported by CC Mode). If you need to change the
indentation style for CC Mode it is recommended that you first see if an
existing style meets your requirements. The style chosen will affect the
placement of language elements like braces, function declarations and
comments. You can choose a style interactively by typing @kbd{C-c .} and
pressing the space bar at the prompt to get a list of supported
styles. @kbd{C-c .} runs the function @code{c-set-style} which applies
to all CC Mode language modes though its name might suggest otherwise. A
few of the the supported styles are listed below.

@itemize @bullet
@item
``gnu'' --- The recommended style from the Free Software Foundation for
GNU software. 
@item
``k&r'' --- The classic style from Kernighan and Ritchie.
@item
``linux'' --- The style recommended for code in the Linux kernel.
@item
``bsd'' --- The style recommended for software developed in BSD.
@item
``java --- The ``traditional'' Java style.
@end itemize

  The default style in XEmacs is ``gnu'' except for Java mode where it
is the ``java'' style (this is governed by the variable
@code{c-default-style}).

  The styles included in CC Mode all use a buffer local variable called
@code{c-basic-offset} as the basic indentation level (this buffer local
variable is used in all CC Mode language modes though its name might
suggest otherwise). All indentation is, by default, expressed in
multiples of @code{c-basic-offset}. 

  Each style defines a default value for @code{c-basic-offset}, for the
``gnu'' style sets it to 2. A very common customization scenario is
where a user wants to use an existing style but with a different basic
offset value. An easy way to do this is to set @code{c-basic-offset} in
the language mode hook after selecting the chosen style.

  For example, a user might want to follow a local coding convention of
using the ``k&r'' style for C code with indentation in two columns
multiples (instead of the five column default provided by the CC Mode
``k&r'' style). This can be achieved with the following code in the
initialization file (@pxref{Init File})

@example
(defun my-c-mode-hook ()
  (c-set-style "k&r")
  (setq c-basic-offset 2))
(add-hook 'c-mode-hook 'my-c-mode-hook)
@end example

  Most customizations for indentation in various CC modes can be
accomplished by choosing a style and then choosing value for
@code{c-basic-offset} that meets the local coding convention. CC Mode
has a very customizable indentation engine and a further discussion is
really beyond the scope of this manual. @xref{Indentation
Engine,,,cc-mode,The CC Mode Manual}.


@node Fortran, Asm Mode, CC Mode, Programs
@section Fortran Mode
@cindex Fortran mode

  Fortran mode provides special motion commands for Fortran statements and
subprograms, and indentation commands that understand Fortran conventions
of nesting, line numbers, and continuation statements.

  Special commands for comments are provided because Fortran comments are
unlike those of other languages.

  Built-in abbrevs optionally save typing when you insert Fortran keywords.

@findex fortran-mode
  Use @kbd{M-x fortran-mode} to switch to this major mode.  Doing so calls
the value of @code{fortran-mode-hook} as a function of no arguments if
that variable has a non-@code{nil} value.

@menu
* Motion: Fortran Motion.     Moving point by statements or subprograms.
* Indent: Fortran Indent.     Indentation commands for Fortran.
* Comments: Fortran Comments. Inserting and aligning comments.
* Columns: Fortran Columns.   Measuring columns for valid Fortran.
* Abbrev: Fortran Abbrev.     Built-in abbrevs for Fortran keywords.
@end menu

  Fortran mode was contributed by Michael Prange.

@node Fortran Motion, Fortran Indent, Fortran, Fortran
@subsection Motion Commands

  Fortran mode provides special commands to move by subprograms (functions
and subroutines) and by statements.  There is also a command to put the
region around one subprogram, which is convenient for killing it or moving it.

@kindex C-M-a (Fortran mode)
@kindex C-M-e (Fortran mode)
@kindex C-M-h (Fortran mode)
@kindex C-c C-p (Fortran mode)
@kindex C-c C-n (Fortran mode)
@findex beginning-of-fortran-subprogram
@findex end-of-fortran-subprogram
@findex mark-fortran-subprogram
@findex fortran-previous-statement
@findex fortran-next-statement

@table @kbd
@item C-M-a
Move to beginning of subprogram@*
(@code{beginning-of-fortran-subprogram}).
@item C-M-e
Move to end of subprogram (@code{end-of-fortran-subprogram}).
@item C-M-h
Put point at beginning of subprogram and mark at end
(@code{mark-fortran-subprogram}).
@item C-c C-n
Move to beginning of current or next statement
(@code{fortran-next-@*statement}).
@item C-c C-p
Move to beginning of current or previous statement
(@code{fortran-@*previous-statement}).
@end table

@node Fortran Indent, Fortran Comments, Fortran Motion, Fortran
@subsection Fortran Indentation

  Special commands and features are available for indenting Fortran
code.  They make sure various syntactic entities (line numbers, comment line
indicators, and continuation line flags) appear in the columns that are
required for standard Fortran.

@menu
* Commands: ForIndent Commands. Commands for indenting Fortran.
* Numbers:  ForIndent Num.      How line numbers auto-indent.
* Conv:     ForIndent Conv.     Conventions you must obey to avoid trouble.
* Vars:     ForIndent Vars.     Variables controlling Fortran indent style.
@end menu

@node ForIndent Commands, ForIndent Num, Fortran Indent, Fortran Indent
@subsubsection Fortran Indentation Commands

@table @kbd
@item @key{TAB}
Indent the current line (@code{fortran-indent-line}).
@item M-@key{LFD}
Break the current line and set up a continuation line.
@item C-M-q
Indent all the lines of the subprogram point is in
(@code{fortran-indent-subprogram}).
@end table

@findex fortran-indent-line
  @key{TAB} is redefined by Fortran mode to reindent the current line for
Fortran (@code{fortran-indent-line}).  Line numbers and continuation
markers are indented to their required columns, and the body of the
statement is independently indented, based on its nesting in the program.

@kindex C-M-q (Fortran mode)
@findex fortran-indent-subprogram
  The key @kbd{C-M-q} is redefined as @code{fortran-indent-subprogram}, a
command that reindents all the lines of the Fortran subprogram (function or
subroutine) containing point.

@kindex M-LFD (Fortran mode)
@findex fortran-split-line
  The key @kbd{M-@key{LFD}} is redefined as @code{fortran-split-line}, a
command to split a line in the appropriate fashion for Fortran.  In a
non-comment line, the second half becomes a continuation line and is
indented accordingly.  In a comment line, both halves become separate
comment lines.

@node ForIndent Num, ForIndent Conv, ForIndent Commands, Fortran Indent
@subsubsection Line Numbers and Continuation

  If a number is the first non-whitespace in the line, it is assumed to be
a line number and is moved to columns 0 through 4.  (Columns are always
counted from 0 in XEmacs.)  If the text on the line starts with the
conventional Fortran continuation marker @samp{$}, it is moved to column 5.
If the text begins with any non whitespace character in column 5, it is
assumed to be an unconventional continuation marker and remains in column
5.

@vindex fortran-line-number-indent
  Line numbers of four digits or less are normally indented one space.
This amount is controlled by the variable @code{fortran-line-number-indent},
which is the maximum indentation a line number can have.  Line numbers
are indented to right-justify them to end in column 4 unless that would
require more than the maximum indentation.  The default value of the
variable is 1.

@vindex fortran-electric-line-number
  Simply inserting a line number is enough to indent it according to these
rules.  As each digit is inserted, the indentation is recomputed.  To turn
off this feature, set the variable @code{fortran-electric-line-number} to
@code{nil}.  Then inserting line numbers is like inserting anything else.

@node ForIndent Conv, ForIndent Vars, ForIndent Num, Fortran Indent
@subsubsection Syntactic Conventions

  Fortran mode assumes that you follow certain conventions that simplify
the task of understanding a Fortran program well enough to indent it
properly:

@vindex fortran-continuation-char
@itemize @bullet
@item
Two nested @samp{do} loops never share a @samp{continue} statement.

@item
The same character appears in column 5 of all continuation lines.  It
is the value of the variable @code{fortran-continuation-char}.
By default, this character is @samp{$}.
@end itemize

@noindent
If you fail to follow these conventions, the indentation commands may
indent some lines unaesthetically.  However, a correct Fortran program will
retain its meaning when reindented even if the conventions are not
followed.

@node ForIndent Vars,  , ForIndent Conv, Fortran Indent
@subsubsection Variables for Fortran Indentation

@vindex fortran-do-indent
@vindex fortran-if-indent
@vindex fortran-continuation-indent
@vindex fortran-check-all-num-for-matching-do
@vindex fortran-minimum-statement-indent
  Several additional variables control how Fortran indentation works.

@table @code
@item fortran-do-indent
Extra indentation within each level of @samp{do} statement (the default is 3).

@item fortran-if-indent
Extra indentation within each level of @samp{if} statement (the default is 3).

@item fortran-continuation-indent
Extra indentation for bodies of continuation lines (the default is 5).

@item fortran-check-all-num-for-matching-do
If this is @code{nil}, indentation assumes that each @samp{do}
statement ends on a @samp{continue} statement.  Therefore, when
computing indentation for a statement other than @samp{continue}, it
can save time by not checking for a @samp{do} statement ending there.
If this is non-@code{nil}, indenting any numbered statement must check
for a @samp{do} that ends there.  The default is @code{nil}.

@item fortran-minimum-statement-indent
Minimum indentation for Fortran statements.  For standard Fortran,
this is 6.  Statement bodies are always indented at least this much.
@end table

@node Fortran Comments, Fortran Columns, Fortran Indent, Fortran
@subsection Comments

  The usual Emacs comment commands assume that a comment can follow a line
of code.  In Fortran, the standard comment syntax requires an entire line
to be just a comment.  Therefore, Fortran mode replaces the standard Emacs
comment commands and defines some new variables.

  Fortran mode can also handle a non-standard comment syntax where comments
start with @samp{!} and can follow other text.  Because only some Fortran
compilers accept this syntax, Fortran mode will not insert such comments
unless you have specified to do so in advance by setting the variable
@code{comment-start} to @samp{"!"} (@pxref{Variables}).

@table @kbd
@item M-;
Align comment or insert new comment (@code{fortran-comment-indent}).

@item C-x ;
Applies to nonstandard @samp{!} comments only.

@item C-c ;
Turn all lines of the region into comments, or (with arg)
turn them back into real code (@code{fortran-comment-region}).
@end table

  @kbd{M-;} in Fortran mode is redefined as the command
@code{fortran-comment-indent}.  Like the usual @kbd{M-;} command,
it recognizes an existing comment and aligns its text appropriately.
If there is no existing comment, a comment is inserted and aligned.

Inserting and aligning comments is not the same in Fortran mode as in
other modes.  When a new comment must be inserted, a full-line comment is
inserted if the current line is blank.  On a non-blank line, a
non-standard @samp{!} comment is inserted if you previously specified
you wanted to use them.  Otherwise a full-line comment is inserted on a
new line before the current line.

  Non-standard @samp{!} comments are aligned like comments in other
languages, but full-line comments are aligned differently.  In a
standard full-line comment, the comment delimiter itself must always
appear in column zero.  What can be aligned is the text within the
comment.  You can choose from three styles of alignment by setting the
variable @code{fortran-comment-indent-style} to one of these values:

@vindex fortran-comment-indent-style
@vindex fortran-comment-line-column
@table @code
@item fixed
The text is aligned at a fixed column, which is the value of
@code{fortran-comment-line-column}.  This is the default.
@item relative
The text is aligned as if it were a line of code, but with an
additional @code{fortran-comment-line-column} columns of indentation.
@item nil
Text in full-line columns is not moved automatically.
@end table

@vindex fortran-comment-indent-char
  You can also specify the character to be used to indent within
full-line comments by setting the variable @code{fortran-comment-indent-char}
to the character you want to use.

@vindex comment-line-start
@vindex comment-line-start-skip
  Fortran mode introduces two variables @code{comment-line-start} and
@code{comment-line-start-skip}, which do for full-line comments what
@code{comment-start} and @code{comment-start-skip} do for
ordinary text-following comments.  Normally these are set properly by
Fortran mode, so you do not need to change them.

  The normal Emacs comment command @kbd{C-x ;} has not been redefined.
It can therefore be used if you use @samp{!} comments, but is useless in
Fortran mode otherwise. 

@kindex C-c ; (Fortran mode)
@findex fortran-comment-region
@vindex fortran-comment-region
  The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
lines of the region into comments by inserting the string @samp{C$$$} at
the front of each one.  With a numeric arg, the region is turned back into
live code by deleting @samp{C$$$} from the front of each line.  You can
control the string used for the comments by setting the variable
@code{fortran-comment-region}.  Note that here we have an example of a
command and a variable with the same name; the two uses of the name never
conflict because in Lisp and in Emacs it is always clear from the context
which one is referred to.

@node Fortran Columns, Fortran Abbrev, Fortran Comments, Fortran
@subsection Columns

@table @kbd
@item C-c C-r
Displays a ``column ruler'' momentarily above the current line
(@code{fortran-column-ruler}).
@item C-c C-w
Splits the current window horizontally so that it is 72 columns wide.
This may help you avoid going over that limit (@code{fortran-window-create}).
@end table

@kindex C-c C-r (Fortran mode)
@findex fortran-column-ruler
  The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
ruler above the current line.  The comment ruler consists of two lines
of text that show you the locations of columns with special significance
in Fortran programs.  Square brackets show the limits of the columns for
line numbers, and curly brackets show the limits of the columns for the
statement body.  Column numbers appear above them.

  Note that the column numbers count from zero, as always in XEmacs.  As
a result, the numbers may not be those you are familiar with; but the
actual positions in the line are standard Fortran.

  The text used to display the column ruler is the value of the variable
@code{fortran-comment-ruler}.  By changing this variable, you can change
the display.

@kindex C-c C-w (Fortran mode)
@findex fortran-window-create
  For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a
command which splits the current window horizontally, resulting in a window 72
columns wide.  When you edit in this window, you can immediately see
when a line gets too wide to be correct Fortran.

@node Fortran Abbrev,  , Fortran Columns, Fortran
@subsection Fortran Keyword Abbrevs

  Fortran mode provides many built-in abbrevs for common keywords and
declarations.  These are the same sort of abbrevs that you can define
yourself.  To use them, you must turn on Abbrev mode.  @pxref{Abbrevs}.

  The built-in abbrevs are unusual in one way: they all start with a
semicolon.  You cannot normally use semicolon in an abbrev, but Fortran
mode makes this possible by changing the syntax of semicolon to ``word
constituent''.

  For example, one built-in Fortran abbrev is @samp{;c} for
@samp{continue}.  If you insert @samp{;c} and then insert a punctuation
character such as a space or a newline, the @samp{;c} changes
automatically to @samp{continue}, provided Abbrev mode is enabled.@refill

  Type @samp{;?} or @samp{;C-h} to display a list of all built-in
Fortran abbrevs and what they stand for.

@node Asm Mode,  , Fortran, Programs
@section Asm Mode

@cindex Asm mode
Asm mode is a major mode for editing files of assembler code.  It
defines these commands:

@table @kbd
@item @key{TAB}
@code{tab-to-tab-stop}.
@item @key{LFD}
Insert a newline and then indent using @code{tab-to-tab-stop}.
@item :
Insert a colon and then remove the indentation from before the label
preceding colon.  Then do @code{tab-to-tab-stop}.
@item ;
Insert or align a comment.
@end table

  The variable @code{asm-comment-char} specifies which character
starts comments in assembler syntax.