all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
blob 0fa37530ef62872fdac103b3b27fd1d823874f09 77213 bytes (raw)
name: doc/emacs/programs.texi 	 # note: path name is non-authoritative(*)

   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
 
@c -*- coding: utf-8 -*-
@c This is part of the Emacs manual.
@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2018 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Programs
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing
@cindex program editing

  This chapter describes Emacs features for facilitating editing
programs.  Some of the things these features can do are:

@itemize @bullet
@item
Find or move over top-level definitions (@pxref{Defuns}).
@item
Apply the usual indentation conventions of the language
(@pxref{Program Indent}).
@item
Balance parentheses (@pxref{Parentheses}).
@item
Insert, kill or align comments (@pxref{Comments}).
@item
Highlight program syntax (@pxref{Font Lock}).
@end itemize

@menu
* Program Modes::       Major modes for editing programs.
* Defuns::              Commands to operate on major top-level parts
                          of a program.
* Program Indent::      Adjusting indentation to show the nesting.
* Parentheses::         Commands that operate on parentheses.
* Comments::            Inserting, killing, and aligning comments.
* Documentation::       Getting documentation of functions you plan to call.
* Hideshow::            Displaying blocks selectively.
* Symbol Completion::   Completion on symbol names of your program or language.
* MixedCase Words::     Dealing with identifiersLikeThis.
* Semantic::            Suite of editing tools based on source code parsing.
* Misc for Programs::   Other Emacs features useful for editing programs.
* C Modes::             Special commands of C, C++, Objective-C, Java,
                          IDL, Pike and AWK modes.
* Asm Mode::            Asm mode and its special features.
@ifnottex
* Fortran::             Fortran mode and its special features.
@end ifnottex
@end menu

@node Program Modes
@section Major Modes for Programming Languages
@cindex modes for programming languages

  Emacs has specialized major modes (@pxref{Major Modes}) for many
programming languages.  A programming language mode typically
specifies the syntax of expressions, the customary rules for
indentation, how to do syntax highlighting for the language, and how
to find the beginning or end of a function definition.  It often has
features for compiling and debugging programs as well.  The major mode
for each language is named after the language; for instance, the major
mode for the C programming language is @code{c-mode}.

@cindex Perl mode
@cindex Icon mode
@cindex Makefile mode
@cindex Tcl mode
@cindex CPerl mode
@cindex DSSSL mode
@cindex Octave mode
@cindex Metafont mode
@cindex Modula2 mode
@cindex Prolog mode
@cindex Python mode
@cindex Ruby mode
@cindex Simula mode
@cindex VHDL mode
@cindex M4 mode
@cindex Shell-script mode
@cindex OPascal mode
@cindex PostScript mode
@cindex Conf mode
@cindex DNS mode
@cindex Javascript mode
  Emacs has programming language modes for Lisp, Scheme, the
Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont
(@TeX{}'s companion for font creation), Modula2, Object Pascal, Objective-C,
Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl,
and VHDL@.  An alternative mode for Perl is called CPerl mode.  Modes are
also available for the scripting languages of the common GNU and Unix
shells, and MS-DOS/MS-Windows @samp{BAT} files, and for makefiles,
DNS master files, and various sorts of configuration files.

  Ideally, Emacs should have a major mode for each programming
language that you might want to edit.  If it doesn't have a mode for
your favorite language, the mode might be implemented in a package not
distributed with Emacs (@pxref{Packages}); or you can contribute one.

@kindex DEL @r{(programming modes)}
@findex backward-delete-char-untabify
  In most programming languages, indentation should vary from line to
line to illustrate the structure of the program.  Therefore, in most
programming language modes, typing @key{TAB} updates the indentation
of the current line (@pxref{Program Indent}).  Furthermore, @key{DEL}
is usually bound to @code{backward-delete-char-untabify}, which
deletes backward treating each tab as if it were the equivalent number
of spaces, so that you can delete one column of indentation without
worrying whether the whitespace consists of spaces or tabs.

@cindex mode hook, and major modes
@vindex c-mode-hook
@vindex lisp-mode-hook
@vindex emacs-lisp-mode-hook
@vindex lisp-interaction-mode-hook
@vindex scheme-mode-hook
  Entering a programming language mode runs the custom Lisp functions
specified in the hook variable @code{prog-mode-hook}, followed by
those specified in the mode's own mode hook (@pxref{Major Modes}).
For instance, entering C mode runs the hooks @code{prog-mode-hook} and
@code{c-mode-hook}.  @xref{Hooks}, for information about hooks.

@ifnottex
  Separate manuals are available for the modes for Ada (@pxref{Top,,
Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE
(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
@end ifnottex
@iftex
  The Emacs distribution contains Info manuals for the major modes for
Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE@.  For
Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
@end iftex

@node Defuns
@section Top-Level Definitions, or Defuns

  In Emacs, a major definition at the top level in the buffer, such as
a function, is called a @dfn{defun}.  The name comes from Lisp, but in
Emacs we use it for all languages.

@menu
* Left Margin Paren::   An open-paren or similar opening delimiter
                          starts a defun if it is at the left margin.
* Moving by Defuns::    Commands to move over or mark a major definition.
* Imenu::               Making buffer indexes as menus.
* Which Function::      Which Function mode shows which function you are in.
@end menu

@node Left Margin Paren
@subsection Left Margin Convention

@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
  Many programming-language modes assume by default that any opening
delimiter found at the left margin is the start of a top-level
definition, or defun.  Therefore, in these modes, don't put an opening
delimiter at the left margin, except in a comment or string, unless it
should have that significance.  For instance, never put an
open-parenthesis at the left margin in a Lisp file unless it is the
start of a top-level list.

  In earlier versions of Emacs (through version 26.n), Emacs exploited
this convention to speed up many low-level operations, which would
otherwise have to scan back to the beginning of the buffer.
Unfortunately, this caused confusion when an opening delimiter
occurred at column zero inside a comment.  The resulting faulty
analysis often caused wrong indentation or fontification.  The
convention could be overridden by setting the user option
@code{open-paren-in-column-0-is-defun-start} to @code{nil}, but this
slowed Emacs down, particularaly when editing large buffers.

  To eliminate these problems, the low level functionality which used
to test for opening delimiters at column 0 no longer does so.  Open
delimiters may now be freely written at the left margin inside
comments and strings without triggering these problems.

@vindex open-paren-in-column-0-is-defun-start
  If you want to override the convention, which is still used by some
higher level commands, you can do so by setting the variable
@code{open-paren-in-column-0-is-defun-start} to @code{nil}.  If this
user option is set to @code{t} (the default), these commands will stop
at opening parentheses or braces at column zero when seeking the start
of defuns.  When it is @code{nil}, defuns are found by searching for
parens or braces at the outermost level.

@node Moving by Defuns
@subsection Moving by Defuns
@cindex defuns

  These commands move point or set up the region based on top-level
major definitions, also called @dfn{defuns}.

@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

@cindex move to beginning or end of function
@cindex function, move to beginning or end
@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}).  If you repeat one of these commands, or use a
positive numeric argument, each repetition moves to the next defun in
the direction of motion.

  @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
@var{n} times to the next beginning of a defun.  This is not exactly
the same place that @kbd{C-M-e} with argument @var{n} would move to;
the end of this defun is not usually exactly the same place as the
beginning of the following defun.  (Whitespace, comments, and perhaps
declarations can separate them.)  Likewise, @kbd{C-M-e} with a
negative argument moves back to an end of a defun, which is not quite
the same as @kbd{C-M-a} with a positive argument.

@kindex C-M-h @r{(C mode)}
@findex c-mark-function
  To operate on the current defun, use @kbd{C-M-h}
(@code{mark-defun}), which sets the mark at the end of the current
defun and puts point at its beginning.  @xref{Marking Objects}.  This
is the easiest way to get ready to kill the defun in order to move it
to a different place in the file.  If the defun is directly preceded
by comments (with no intervening blank lines), they are marked, too.
If you use the command while point is between defuns, it uses the
following defun.  If you use the command while the mark is already
active, it extends the end of the region to include one more defun.
With a prefix argument, it marks that many defuns or extends the
region by the appropriate number of defuns.  With negative prefix
argument it marks defuns in the opposite direction and also changes
the direction of selecting for subsequent uses of @code{mark-defun}.

  In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
which is almost the same as @code{mark-defun}; the difference is that
it backs up over the argument declarations, function name and returned
data type so that the entire C function is inside the region.  This is
an example of how major modes adjust the standard key bindings so that
they do their standard jobs in a way better fitting a particular
language.  Other major modes may replace any or all of these key
bindings for that purpose.

@node Imenu
@subsection Imenu
@cindex index of buffer definitions
@cindex buffer definitions index

  The Imenu facility offers a way to find the major definitions in
a file by name.  It is also useful in text formatter major modes,
where it treats each chapter, section, etc., as a definition.
(@xref{Xref}, for a more powerful feature that handles multiple files
together.)

@findex imenu
  If you type @kbd{M-x imenu}, it reads the name of a definition using
the minibuffer, then moves point to that definition.  You can use
completion to specify the name; the command always displays the whole
list of valid names.

@findex imenu-add-menubar-index
  Alternatively, you can bind the command @code{imenu} to a mouse
click.  Then it displays mouse menus for you to select a definition
name.  You can also add the buffer's index to the menu bar by calling
@code{imenu-add-menubar-index}.  If you want to have this menu bar
item available for all buffers in a certain major mode, you can do
this by adding @code{imenu-add-menubar-index} to its mode hook.  But
if you have done that, you will have to wait a little while each time
you visit a file in that mode, while Emacs finds all the definitions
in that buffer.

@vindex imenu-auto-rescan
  When you change the contents of a buffer, if you add or delete
definitions, you can update the buffer's index based on the
new contents by invoking the @samp{*Rescan*} item in the menu.
Rescanning happens automatically if you set @code{imenu-auto-rescan} to
a non-@code{nil} value.  There is no need to rescan because of small
changes in the text.

@vindex imenu-sort-function
  You can customize the way the menus are sorted by setting the
variable @code{imenu-sort-function}.  By default, names are ordered as
they occur in the buffer; if you want alphabetic sorting, use the
symbol @code{imenu--sort-by-name} as the value.  You can also
define your own comparison function by writing Lisp code.

  Imenu provides the information to guide Which Function mode
@ifnottex
(@pxref{Which Function}).
@end ifnottex
@iftex
(see below).
@end iftex
The Speedbar can also use it (@pxref{Speedbar}).

@node Which Function
@subsection Which Function Mode
@cindex current function name in mode line

  Which Function mode is a global minor mode (@pxref{Minor Modes})
which displays the current function name in the mode line, updating it
as you move around in a buffer.

@findex which-function-mode
@vindex which-func-modes
  To either enable or disable Which Function mode, use the command
@kbd{M-x which-function-mode}.  Which Function mode is a global minor
mode.  By default, it takes effect in all major modes that
know how to support it (i.e., all the major modes that support
Imenu).  You can restrict it to a specific list of major modes by
changing the value of the variable @code{which-func-modes} from
@code{t} (which means to support all available major modes) to a list
of major mode names.

@node Program Indent
@section Indentation for Programs
@cindex indentation for programs

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

  @xref{Indentation}, for general information about indentation.  This
section describes indentation features specific to programming
language modes.

@menu
* Basic Indent::        Indenting a single line.
* Multi-line Indent::   Commands to reindent many lines at once.
* Lisp Indent::         Specifying how each Lisp function should be indented.
* C Indent::            Extra features for indenting C and related modes.
* Custom C Indent::     Controlling indentation style for C and related modes.
@end menu

@cindex pretty-printer
  Emacs also provides a Lisp pretty-printer in the @code{pp} package,
which reformats Lisp objects with nice-looking indentation.

@node Basic Indent
@subsection Basic Program Indentation Commands

@table @kbd
@item @key{TAB}
Adjust indentation of current line (@code{indent-for-tab-command}).
@item @key{RET}
Insert a newline, then adjust indentation of following line
(@code{newline}).
@end table

@kindex TAB @r{(programming modes)}
@findex indent-line-function
  The basic indentation command is @key{TAB}
(@code{indent-for-tab-command}), which was documented in
@ref{Indentation}.  In programming language modes, @key{TAB} indents
the current line, based on the indentation and syntactic content of
the preceding lines; if the region is active, @key{TAB} indents each
line within the region, not just the current line.

  The command @key{RET} (@code{newline}), which was documented in
@ref{Inserting Text}, does the same as @kbd{C-j} followed by
@key{TAB}: it inserts a new line, then adjusts the line's indentation.

  When indenting a line that starts within a parenthetical grouping,
Emacs usually places the start of the line under the preceding line
within the group, or under the text after the parenthesis.  If you
manually give one of these lines a nonstandard indentation (e.g., for
aesthetic purposes), the lines below will follow it.

  The indentation commands for most programming language modes assume
that a open-parenthesis, open-brace or other opening delimiter at the
left margin is the start of a function.  If the code you are editing
violates this assumption---even if the delimiters occur in strings or
comments---you must set @code{open-paren-in-column-0-is-defun-start}
to @code{nil} for indentation to work properly.  @xref{Left Margin
Paren}.

@node Multi-line Indent
@subsection Indenting Several Lines

  Sometimes, you may want to reindent several lines of code at a time.
One way to do this is to use the mark; when the mark is active and the
region is non-empty, @key{TAB} indents every line in the region.
Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
every line in the region, whether or not the mark is active
(@pxref{Indentation Commands}).

  In addition, Emacs provides the following commands for indenting
large chunks of code:

@table @kbd
@item C-M-q
Reindent all the lines within one parenthetical grouping.
@item C-u @key{TAB}
Shift an entire parenthetical grouping rigidly sideways so that its
first line is properly indented.
@item M-x indent-code-rigidly
Shift all the lines in the region rigidly sideways, but do not alter
lines that start inside comments and strings.
@end table

@kindex C-M-q
@findex indent-pp-sexp
  To reindent the contents of a single parenthetical grouping,
position point before the beginning of the grouping and type
@kbd{C-M-q}.  This changes the relative indentation within the
grouping, without affecting its overall indentation (i.e., the
indentation of the line where the grouping starts).  The function that
@kbd{C-M-q} runs depends on the major mode; it is
@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
etc.  To correct the overall indentation as well, type @key{TAB}
first.

@kindex C-u TAB
  If you like the relative indentation within a grouping but not the
indentation of its first line, move point to that first line and type
@kbd{C-u @key{TAB}}.  In Lisp, C, and some other major modes,
@key{TAB} with a numeric argument reindents the current line as usual,
then reindents by the same amount all the lines in the parenthetical
grouping starting on the current line.  It is clever, though, and does
not alter lines that start inside strings.  Neither does it alter C
preprocessor lines when in C mode, but it does reindent any
continuation lines that may be attached to them.

@findex indent-code-rigidly
  The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
lines in the region sideways, like @code{indent-rigidly} does
(@pxref{Indentation Commands}).  It doesn't alter the indentation of
lines that start inside a string, unless the region also starts inside
that string.  The prefix arg specifies the number of columns to
indent.

@node Lisp Indent
@subsection Customizing Lisp Indentation
@cindex customizing Lisp indentation

  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-indent
  Certain functions override the standard pattern.  Functions whose
names start with @code{def} treat the second lines as the start of
a @dfn{body}, by indenting the second line @code{lisp-body-indent}
additional columns beyond the open-parenthesis that starts the
expression.

@cindex @code{lisp-indent-function} property
  You can override the standard pattern in various ways for individual
functions, according to the @code{lisp-indent-function} property of
the function name.  This is normally done for macro definitions, using
the @code{declare} construct.  @xref{Defining Macros,,, elisp, the
Emacs Lisp Reference Manual}.

@node C Indent
@subsection Commands for C Indentation

  Here are special features for indentation in C mode and related modes:

@table @code
@item C-c C-q
@kindex C-c C-q @r{(C mode)}
@findex c-indent-defun
Reindent the current top-level function definition or aggregate type
declaration (@code{c-indent-defun}).

@item C-M-q
@kindex C-M-q @r{(C mode)}
@findex c-indent-exp
Reindent each line in the balanced expression that follows point
(@code{c-indent-exp}).  A prefix argument inhibits warning messages
about invalid syntax.

@item @key{TAB}
@findex c-indent-command
Reindent the current line, and/or in some cases insert a tab character
(@code{c-indent-command}).

@vindex c-tab-always-indent
If @code{c-tab-always-indent} is @code{t}, this command always reindents
the current line and does nothing else.  This is the default.

If that variable is @code{nil}, this command reindents the current line
only if point is at the left margin or in the line's indentation;
otherwise, it inserts a tab (or the equivalent number of spaces,
if @code{indent-tabs-mode} is @code{nil}).

Any other value (not @code{nil} or @code{t}) means always reindent the
line, and also insert a tab if within a comment or a string.
@end table

  To reindent the whole current buffer, type @kbd{C-x h C-M-\}.  This
first selects the whole buffer as the region, then reindents that
region.

  To reindent the current block, use @kbd{C-M-u C-M-q}.  This moves
to the front of the block and then reindents it all.

@node Custom C Indent
@subsection Customizing C Indentation
@cindex style (for indentation)

  C mode and related modes use a flexible mechanism for customizing
indentation.  C mode indents a source line in two steps: first it
classifies the line syntactically according to its contents and
context; second, it determines the indentation offset associated by
your selected @dfn{style} with the syntactic construct and adds this
onto the indentation of the @dfn{anchor statement}.

@table @kbd
@item C-c . @var{style} @key{RET}
Select a predefined style @var{style} (@code{c-set-style}).
@end table

  A @dfn{style} is a named collection of customizations that can be
used in C mode and the related modes.  @ref{Styles,,, ccmode, The CC
Mode Manual}, for a complete description.  Emacs comes with several
predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
@code{stroustrup}, @code{linux}, @code{python}, @code{java},
@code{whitesmith}, @code{ellemtel}, and @code{awk}.  Some of these
styles are primarily intended for one language, but any of them can be
used with any of the languages supported by these modes.  To find out
what a style looks like, select it and reindent some code, e.g., by
typing @kbd{C-M-q} at the start of a function definition.

@kindex C-c . @r{(C mode)}
@findex c-set-style
  To choose a style for the current buffer, use the command @w{@kbd{C-c
.}}.  Specify a style name as an argument (case is not significant).
This command affects the current buffer only, and it affects only
future invocations of the indentation commands; it does not reindent
the code already in the buffer.  To reindent the whole buffer in the
new style, you can type @kbd{C-x h C-M-\}.

@vindex c-default-style
  You can also set the variable @code{c-default-style} to specify the
default style for various major modes.  Its value should be either the
style's name (a string) or an alist, in which each element specifies
one major mode and which indentation style to use for it.  For
example,

@example
(setq c-default-style
      '((java-mode . "java")
        (awk-mode . "awk")
        (other . "gnu")))
@end example

@noindent
specifies explicit choices for Java and AWK modes, and the default
@samp{gnu} style for the other C-like modes.  (These settings are
actually the defaults.)  This variable takes effect when you select
one of the C-like major modes; thus, if you specify a new default
style for Java mode, you can make it take effect in an existing Java
mode buffer by typing @kbd{M-x java-mode} there.

  The @code{gnu} style specifies the formatting recommended by the GNU
Project for C; it is the default, so as to encourage use of our
recommended style.

  @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
information on customizing indentation for C and related modes,
including how to override parts of an existing style and how to define
your own styles.

@findex c-guess
@findex c-guess-install
  As an alternative to specifying a style, you can tell Emacs to guess
a style by typing @kbd{M-x c-guess} in a sample code buffer.  You can
then apply the guessed style to other buffers with @kbd{M-x
c-guess-install}.  @xref{Guessing the Style,,, ccmode, the CC Mode
Manual}, for details.

@node Parentheses
@section Commands for Editing with Parentheses

@findex check-parens
@cindex unbalanced parentheses and quotes
  This section describes the commands and features that take advantage
of the parenthesis structure in a program, or help you keep it
balanced.

  When talking about these facilities, the term ``parenthesis'' also
includes braces, brackets, or whatever delimiters are defined to match
in pairs.  The major mode controls which delimiters are significant,
through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
The Emacs Lisp Reference Manual}).  In Lisp, only parentheses count;
in C, these commands apply to braces and brackets too.

  You can use @kbd{M-x check-parens} to find any unbalanced
parentheses and unbalanced string quotes in the buffer.

@menu
* Expressions::         Expressions with balanced parentheses.
* Moving by Parens::    Commands for moving up, down and across
                          in the structure of parentheses.
* Matching::            Insertion of a close-delimiter flashes matching open.
@end menu

@node Expressions
@subsection Expressions with Balanced Parentheses

@cindex sexp
@cindex expression
@cindex balanced expression
  Each programming language mode has its own definition of a
@dfn{balanced expression}.  Balanced expressions typically include
individual symbols, numbers, and string constants, as well as pieces
of code enclosed in a matching pair of delimiters.  The following
commands deal with balanced expressions (in Emacs, such expressions
are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
is used to refer to an expression in Lisp.}).

@table @kbd
@item C-M-f
Move forward over a balanced expression (@code{forward-sexp}).
@item C-M-b
Move backward over a balanced expression (@code{backward-sexp}).
@item C-M-k
Kill balanced expression forward (@code{kill-sexp}).
@item C-M-t
Transpose expressions (@code{transpose-sexps}).
@item C-M-@@
@itemx C-M-@key{SPC}
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 a balanced expression, use @kbd{C-M-f}
(@code{forward-sexp}).  If the first significant character after point
is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
this command moves past the matching closing delimiter.  If the
character begins a symbol, string, or number, the command moves over
that.

  The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
balanced expression---like @kbd{C-M-f}, but in the reverse direction.
If the expression is preceded by any prefix characters (single-quote,
backquote and comma, in Lisp), the command 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 means to move
in the opposite direction.  In most modes, these two commands move
across comments as if they were whitespace.  Note that their keys,
@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
@kbd{M-b}, which move by words (@pxref{Words}).

@cindex killing expressions
@kindex C-M-k
@findex kill-sexp
  To kill a whole balanced expression, type @kbd{C-M-k}
(@code{kill-sexp}).  This kills the text that @kbd{C-M-f} would move
over.

@cindex transposition of expressions
@kindex C-M-t
@findex transpose-sexps
  @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
previous balanced expression and the next one.  It is analogous to the
@kbd{C-t} command, which transposes characters (@pxref{Transpose}).
An argument to @kbd{C-M-t} serves as a repeat count, moving the
previous expression over that many following ones.  A negative
argument moves the previous balanced expression backwards across those
before it.  An argument of zero, rather than doing nothing, transposes
the balanced expressions ending at or after point and the mark.

@kindex C-M-SPC
  To operate on balanced expressions with a command which acts on the
region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}).  This sets the
mark where @kbd{C-M-f} would move to.  While the mark is active, each
successive call to this command extends the region by shifting the
mark by one expression.  Positive or negative numeric arguments move
the mark forward or backward by the specified number of expressions.
The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
@xref{Marking Objects}, for more information about this and related
commands.

  In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions because there can be multiple
possibilities at a given position.  For example, C mode does not treat
@samp{foo + bar} as a single expression, even though it @emph{is} one
C expression; instead, it recognizes @samp{foo} as one expression and
@samp{bar} as another, with the @samp{+} as punctuation between them.
However, C mode recognizes @samp{(foo + bar)} as a single expression,
because of the parentheses.

@node Moving by Parens
@subsection Moving in the Parenthesis Structure

@cindex parenthetical groupings
@cindex parentheses, moving across
@cindex matching parenthesis and braces, moving to
@cindex braces, moving across
@cindex list commands

  The following commands move over groupings delimited by parentheses
(or whatever else serves as delimiters in the language you are working
with).  They ignore strings and comments, including any parentheses
within them, and also ignore parentheses that are quoted with an
escape character.  These commands are mainly intended for editing
programs, but can be useful for editing any text containing
parentheses.  They are referred to internally as ``list commands''
because in Lisp these groupings are lists.

  These commands assume that the starting point is not inside a string
or a comment.  If you invoke them from inside a string or comment, the
results are unreliable.

@table @kbd
@item C-M-n
Move forward over a parenthetical group (@code{forward-list}).
@item C-M-p
Move backward over a parenthetical group (@code{backward-list}).
@item C-M-u
Move up in parenthesis structure (@code{backward-up-list}).
@item C-M-d
Move down in parenthesis structure (@code{down-list}).
@end table

@kindex C-M-n
@kindex C-M-p
@findex forward-list
@findex backward-list
  The list commands @kbd{C-M-n} (@code{forward-list}) and
@kbd{C-M-p} (@code{backward-list}) move forward or backward over one
(or @var{n}) parenthetical groupings.

@kindex C-M-u
@findex backward-up-list
  @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
parenthesis structure.  To move @emph{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 the direction of motion, so
that the command moves forward and up one or more levels.

@kindex C-M-d
@findex down-list
  To move @emph{down} in the parenthesis 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 to go down.

@node Matching
@subsection Matching Parentheses
@cindex matching parentheses
@cindex parentheses, displaying matches

  Emacs has a number of @dfn{parenthesis matching} features, which
make it easy to see how and whether parentheses (or other delimiters)
match up.

  Whenever you type a self-inserting character that is a closing
delimiter, Emacs briefly indicates the location of the matching
opening delimiter, provided that is on the screen.  If it is not on
the screen, Emacs displays some of the text near it in the echo area.
Either way, you can tell which grouping you are closing off.  If the
opening delimiter and closing delimiter are mismatched---such as in
@samp{[x)}---a warning message is displayed in the echo area.

@vindex blink-matching-paren
@vindex blink-matching-paren-distance
@vindex blink-matching-delay
  Three variables control the display of matching parentheses:

@itemize @bullet
@item
@code{blink-matching-paren} turns the feature on or off: @code{nil}
disables it, but the default is @code{t} to enable it.  Set it to
@code{jump} to make indication work by momentarily moving the cursor
to the matching opening delimiter.  Set it to @code{jump-offscreen} to
make the cursor jump, even if the opening delimiter is off screen.

@item
@code{blink-matching-delay} says how many seconds to keep indicating
the matching opening delimiter.  This may be an integer or
floating-point number; the default is 1.

@item
@code{blink-matching-paren-distance} specifies how many characters
back to search to find the matching opening delimiter.  If the match
is not found in that distance, Emacs stops scanning and nothing is
displayed.  The default is 102400.
@end itemize

@cindex Show Paren mode
@cindex highlighting matching parentheses
@findex show-paren-mode
  Show Paren mode, a global minor mode, provides a more powerful kind
of automatic matching.  Whenever point is before an opening delimiter
or after a closing delimiter, the delimiter, its matching delimiter,
and optionally the text between them are highlighted.  To toggle Show
Paren mode, type @kbd{M-x show-paren-mode}.  To customize it, type
@kbd{M-x customize-group @key{RET} paren-showing}.  The customizable
options which control the operation of this mode include:

@itemize @bullet
@item
@code{show-paren-highlight-open-paren} controls whether to highlight
an open paren when point stands just before it, and hence its position
is marked by the cursor anyway.  The default is non-@code{nil} (yes).

@item
@code{show-paren-style} controls whether just the two parens, or also
the space between them get highlighted.  The valid options here are
@code{parenthesis} (show the matching paren), @code{expression}
(highlight the entire expression enclosed by the parens), and
@code{mixed} (highlight the matching paren if it is visible, the
expression otherwise).

@item
@code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes
highlighting also when point is on the inside of a parenthesis.

@item
@code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes
highlighting also when point is in whitespace at the beginning or end
of a line, and there is a paren at, respectively, the first or last,
or the last, non-whitespace position on the line.
@end itemize

@cindex Electric Pair mode
@cindex inserting matching parentheses
@findex electric-pair-mode
  Electric Pair mode, a global minor mode, provides a way to easily
insert matching delimiters.  Whenever you insert an opening delimiter,
the matching closing delimiter is automatically inserted as well,
leaving point between the two.  Conversely, when you insert a closing
delimiter over an existing one, no inserting takes places and that
position is simply skipped over.  These variables control additional
features of Electric Pair mode:

@itemize @bullet
@item
@vindex electric-pair-preserve-balance
@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
default pairing logic balance out the number of opening and closing
delimiters.

@item
@vindex electric-pair-delete-adjacent-pairs
@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
backspacing between two adjacent delimiters also automatically delete
the closing delimiter.

@item
@vindex electric-pair-open-newline-between-pairs
@code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
makes inserting a newline between two adjacent pairs also
automatically open an extra newline after point.

@item
@vindex electric-pair-skip-whitespace
@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
mode to skip whitespace forward before deciding whether to skip over
the closing delimiter.
@end itemize

To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.  To
toggle the mode in a single buffer, use @kbd{M-x
electric-pair-local-mode}.

@node Comments
@section Manipulating Comments
@cindex comments

  Because comments are such an important part of programming, Emacs
provides special commands for editing and inserting comments.  It can
also do spell checking on comments with Flyspell Prog mode
(@pxref{Spelling}).

  Some major modes have special rules for indenting different kinds of
comments.  For example, in Lisp code, comments starting with two
semicolons are indented as if they were lines of code, while those
starting with three semicolons are supposed to be aligned to the left
margin and are often used for sectioning purposes.  Emacs understand
these conventions; for instance, typing @key{TAB} on a comment line
will indent the comment to the appropriate position.

@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

@menu
* Comment Commands::    Inserting, killing, and aligning comments.
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
* Options for Comments::Customizing the comment features.
@end menu

@node Comment Commands
@subsection Comment Commands
@cindex indentation for comments
@cindex alignment for comments

  The following commands operate on comments:

@table @asis
@item @kbd{M-;}
Insert or realign comment on current line; if the region is active,
comment or uncomment the region instead (@code{comment-dwim}).
@item @kbd{C-x C-;}
Comment or uncomment the current line (@code{comment-line}).
@item @kbd{C-u M-;}
Kill comment on current line (@code{comment-kill}).
@item @kbd{C-x ;}
Set comment column (@code{comment-set-column}).
@item @kbd{C-M-j}
@itemx @kbd{M-j}
Like @key{RET} followed by inserting and aligning a comment
(@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
Add comment delimiters to all the lines in the region.
@end table

@kindex M-;
@findex comment-dwim
  The command to create or align a comment is @kbd{M-;}
(@code{comment-dwim}).  The word ``dwim'' is an acronym for ``Do What
I Mean''; it indicates that this command can be used for many
different jobs relating to comments, depending on the situation where
you use it.

  When a region is active (@pxref{Mark}), @kbd{M-;} either adds
comment delimiters to the region, or removes them.  If every line in
the region is already a comment, it uncomments each of those lines
by removing their comment delimiters.  Otherwise, it adds comment
delimiters to enclose the text in the region.

  If you supply a prefix argument to @kbd{M-;} when a region is
active, that specifies the number of comment delimiters to add or
delete.  A positive argument @var{n} adds @var{n} delimiters, while a
negative argument @var{-n} removes @var{n} delimiters.

  If the region is not active, and there is no existing comment on the
current line, @kbd{M-;} adds a new comment to the current line.  If
the line is blank (i.e., empty or containing only whitespace
characters), the comment is indented to the same position where
@key{TAB} would indent to (@pxref{Basic Indent}).  If the line is
non-blank, the comment is placed after the last non-whitespace
character on the line; normally, Emacs tries putting it at the column
specified by the variable @code{comment-column} (@pxref{Options for
Comments}), but if the line already extends past that column, it puts
the comment at some suitable position, usually separated from the
non-comment text by at least one space.  In each case, Emacs places
point after the comment's starting delimiter, so that you can start
typing the comment text right away.

  You can also use @kbd{M-;} to align an existing comment.  If a line
already contains the comment-start string, @kbd{M-;} realigns it to
the conventional alignment and moves point after the comment's
starting delimiter.  As an exception, comments starting in column 0
are not moved.  Even when an existing comment is properly aligned,
@kbd{M-;} is still useful for moving directly to the start of the
comment text.

@findex comment-line
@kindex C-x C-;
  @kbd{C-x C-;} (@code{comment-line}) comments or uncomments complete
lines.  When a region is active (@pxref{Mark}), @kbd{C-x C-;} either
comments or uncomments the lines in the region.  If the region is not
active, this command comments or uncomments the line point is on.
With a positive prefix argument @var{n}, it operates on @var{n} lines
starting with the current one; with a negative @var{n}, it affects
@var{n} preceding lines.  After invoking this command with a negative
argument, successive invocations with a positive argument will operate
on preceding lines as if the argument were negated.

@findex comment-kill
@kindex C-u M-;
  @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
comment on the current line, along with the whitespace before it.
Since the comment is saved to the kill ring, you can reinsert it on
another line by moving to the end of that line, doing @kbd{C-y}, and
then @kbd{M-;} to realign the comment.  You can achieve the same
effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
(@code{comment-dwim} actually calls @code{comment-kill} as a
subroutine when it is given a prefix argument).

@kindex C-c C-c (C mode)
@findex comment-region
@findex uncomment-region
  The command @kbd{M-x comment-region} is equivalent to calling
@kbd{M-;} on an active region, except that it always acts on the
region, even if the mark is inactive.  In C mode and related modes,
this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
uncomment-region} uncomments each line in the region; a numeric prefix
argument specifies the number of comment delimiters to remove
(negative arguments specify the number of comment to delimiters to
add).

  For C-like modes, you can configure the exact effect of @kbd{M-;} by
setting the variables @code{c-indent-comment-alist} and
@code{c-indent-comments-syntactically-p}.  For example, on a line
ending in a closing brace, @kbd{M-;} puts the comment one space after
the brace rather than at @code{comment-column}.  For full details see
@ref{Comment Commands,,, ccmode, The CC Mode Manual}.

@node Multi-Line Comments
@subsection Multiple Lines of Comments

@kindex C-M-j
@kindex M-j
@cindex blank lines in programs
@findex comment-indent-new-line
@vindex comment-multi-line
  If you are typing a comment and wish to continue it to another line,
type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}).  This
breaks the current line, and inserts the necessary comment delimiters
and indentation to continue the comment.

  For languages with closing comment delimiters (e.g., @samp{*/} in
C), the exact behavior of @kbd{M-j} depends on the value of the
variable @code{comment-multi-line}.  If the value is @code{nil}, the
command closes the comment on the old line and starts a new comment on
the new line.  Otherwise, it opens a new line within the current
comment delimiters.

  When Auto Fill mode is on, going past the fill column while typing a
comment also continues the comment, in the same way as an explicit
invocation of @kbd{M-j}.

  To turn existing lines into comment lines, use @kbd{M-;} with the
region active, or use @kbd{M-x comment-region}
@ifinfo
(@pxref{Comment Commands}).
@end ifinfo
@ifnotinfo
as described in the preceding section.
@end ifnotinfo

  You can configure C Mode such that when you type a @samp{/} at the
start of a line in a multi-line block comment, this closes the
comment.  Enable the @code{comment-close-slash} clean-up for this.
@xref{Clean-ups,,, ccmode, The CC Mode Manual}.

@node Options for Comments
@subsection Options Controlling Comments

@vindex comment-column
@kindex C-x ;
@findex comment-set-column
  As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
adds a comment to a line, it tries to place the comment at the column
specified by the buffer-local variable @code{comment-column}.  You can
set either the local value or the default value of this buffer-local
variable in the usual way (@pxref{Locals}).  Alternatively, you can
type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
@code{comment-column} in the current buffer to the column where point
is currently located.  @kbd{C-u C-x ;} sets the comment column to
match the last comment before point in the buffer, and then does a
@kbd{M-;} to align the current line's comment under the previous one.

@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}.
Make sure this regexp does 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
@c This stops M-q from breaking the line inside that @code.
@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
spaces after the @samp{/*} itself, and accepts C++ style comments
also.  (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{Regexp Backslash}.)

@vindex comment-start
@vindex comment-end
  When a comment command makes a new comment, it inserts the value of
@code{comment-start} as an opening comment delimiter.  It also inserts
the value of @code{comment-end} after point, as a closing comment
delimiter.  For example, in Lisp mode, @code{comment-start} is
@samp{";"} and @code{comment-end} is @code{""} (the empty string).  In
C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
@code{" */"}.

@vindex comment-padding
  The variable @code{comment-padding} specifies a string that the
commenting commands should insert between the comment delimiter(s) and
the comment text.  The default, @samp{" "}, specifies a single space.
Alternatively, the value can be a number, which specifies that number
of spaces, or @code{nil}, which means no spaces at all.

  The variable @code{comment-multi-line} controls how @kbd{M-j} and
Auto Fill mode continue comments over multiple lines.
@xref{Multi-Line Comments}.

@vindex comment-indent-function
  The variable @code{comment-indent-function} should contain a function
that will be called to compute the alignment for a newly inserted
comment or for aligning an existing comment.  It is set differently by
various major modes.  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.  It should return the column in which the
comment ought to start.  For example, the default hook function bases
its decision on how many comment characters begin an existing comment.

Emacs also tries to align comments on adjacent lines.  To override
this, the function may return a cons of two (possibly equal) integers
to indicate an acceptable range of indentation.

@node Documentation
@section Documentation Lookup

  Emacs provides several features you can use to look up the
documentation of functions, variables and commands that you plan to
use in your program.

@menu
* Info Lookup::         Looking up library functions and commands in Info files.
* Man Page::            Looking up man pages of library functions and commands.
* Lisp Doc::            Looking up Emacs Lisp functions, etc.
@end menu

@node Info Lookup
@subsection Info Documentation Lookup

@findex info-lookup-file
  For major modes that apply to languages which have documentation in
Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
Info documentation for a symbol used in the program.  You specify the
symbol with the minibuffer; the default is the symbol appearing in the
buffer at point.  For example, in C mode this looks for the symbol in
the C Library Manual.  The command only works if the appropriate
manual's Info files are installed.

  The major mode determines where to look for documentation for the
symbol---which Info files to look in, and which indices to search.
You can also use @kbd{M-x info-lookup-file} to look for documentation
for a file name.

  If you use @kbd{C-h S} in a major mode that does not support it,
it asks you to specify the symbol help mode.  You should enter
a command such as @code{c-mode} that would select a major
mode which @kbd{C-h S} does support.

@node Man Page
@subsection Man Page Lookup

@cindex man page
  On Unix, the main form of on-line documentation was the @dfn{manual
page} or @dfn{man page}.  In the GNU operating system, we aim to
replace man pages with better-organized manuals that you can browse
with Info (@pxref{Misc Help}).  This process is not finished, so it is
still useful to read manual pages.

@findex man
  You can read the man page for an operating system command, library
function, or system call, with the @kbd{M-x man} command.  This
prompts for a topic, with completion (@pxref{Completion}), and runs
the @command{man} program to format the corresponding man page.  If
the system permits, it runs @command{man} asynchronously, so that you
can keep on editing while the page is being formatted.  The result
goes in a buffer named @file{*Man @var{topic}*}.  These buffers use a
special major mode, Man mode, that facilitates scrolling and jumping
to other manual pages.  For details, type @kbd{C-h m} while in a Man
mode buffer.

@cindex sections of manual pages
  Each man page belongs to one of ten or more @dfn{sections}, each
named by a digit or by a digit and a letter.  Sometimes there are man
pages with the same name in different sections.  To read a man page
from a specific section, type @samp{@var{topic}(@var{section})} or
@samp{@var{section} @var{topic}} when @kbd{M-x man} prompts for the
topic.  For example, the man page for the C library function
@code{chmod} is in section 2, but there is a shell command of the same
name, whose man page is in section 1; to view the former, type
@w{@kbd{M-x man @key{RET} chmod(2) @key{RET}}}.

@vindex Man-switches
@kindex M-n @r{(Man mode)}
@kindex M-p @r{(Man mode)}
  If you do not specify a section, @kbd{M-x man} normally displays
only the first man page found.  On some systems, the @code{man}
program accepts a @samp{-a} command-line option, which tells it to
display all the man pages for the specified topic.  To make use of
this, change the value of the variable @code{Man-switches} to
@samp{"-a"}.  Then, in the Man mode buffer, you can type @kbd{M-n} and
@kbd{M-p} to switch between man pages in different sections.  The mode
line shows how many manual pages are available.

@findex woman
@cindex manual pages, on MS-DOS/MS-Windows
  An alternative way of reading manual pages is the @kbd{M-x woman}
command.  Unlike @kbd{M-x man}, it does not run any external programs
to format and display the man pages; the formatting is done by Emacs,
so it works on systems such as MS-Windows where the @command{man}
program may be unavailable.  It prompts for a man page, and displays
it in a buffer named @file{*WoMan @var{section} @var{topic}}.

  @kbd{M-x woman} computes the completion list for manpages the first
time you invoke the command.  With a numeric argument, it recomputes
this list; this is useful if you add or delete manual pages.

  If you type a name of a manual page and @kbd{M-x woman} finds that
several manual pages by the same name exist in different sections, it
pops up a window with possible candidates asking you to choose one of
them.

  For more information about setting up and using @kbd{M-x woman}, see
@ifinfo
@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
WoMan Manual}.
@end ifinfo
@ifnotinfo
the WoMan Info manual, which is distributed with Emacs.
@end ifnotinfo

@node Lisp Doc
@subsection Emacs Lisp Documentation Lookup

  When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
to view the built-in documentation for the Lisp functions and
variables that you want to use.  @xref{Name Help}.

@cindex Eldoc mode
@findex eldoc-mode
@findex global-eldoc-mode
  Eldoc is a buffer-local minor mode that helps with looking up Lisp
documentation.  When it is enabled, the echo area displays some useful
information whenever there is a Lisp function or variable at point;
for a function, it shows the argument list, and for a variable it
shows the first line of the variable's documentation string.  To
toggle Eldoc mode, type @kbd{M-x eldoc-mode}.  There's also a Global
Eldoc mode, which is turned on by default, and affects buffers, such
as @samp{*scratch*}, whose major mode is Emacs Lisp or Lisp
Interaction (@w{@kbd{M-x global-eldoc-mode}} to turn it off globally).

@node Hideshow
@section Hideshow minor mode
@cindex Hideshow mode
@cindex mode, Hideshow

@findex hs-minor-mode
  Hideshow mode is a buffer-local minor mode that allows you to
selectively display portions of a program, which are referred to as
@dfn{blocks}.  Type @kbd{M-x hs-minor-mode} to toggle this minor mode
(@pxref{Minor Modes}).

  When you use Hideshow mode to hide a block, the block disappears
from the screen, to be replaced by an ellipsis (three periods in a
row).  Just what constitutes a block depends on the major mode.  In C
mode and related modes, blocks are delimited by braces, while in Lisp
mode they are delimited by parentheses.  Multi-line comments also
count as blocks.

  Hideshow mode provides the following commands:

@findex hs-hide-all
@findex hs-hide-block
@findex hs-show-all
@findex hs-show-block
@findex hs-show-region
@findex hs-hide-level
@kindex C-c @@ C-h
@kindex C-c @@ C-s
@kindex C-c @@ C-M-h
@kindex C-c @@ C-M-s
@kindex C-c @@ C-r
@kindex C-c @@ C-l
@kindex S-mouse-2
@table @kbd
@item C-c @@ C-h
@itemx C-c @@ C-d
Hide the current block (@code{hs-hide-block}).
@item C-c @@ C-s
Show the current block (@code{hs-show-block}).
@item C-c @@ C-c
@itemx C-x @@ C-e
Either hide or show the current block (@code{hs-toggle-hiding}).
@item S-mouse-2
Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}).
@item C-c @@ C-M-h
@itemx C-c @@ C-t
Hide all top-level blocks (@code{hs-hide-all}).
@item C-c @@ C-M-s
@itemx C-c @@ C-a
Show all blocks in the buffer (@code{hs-show-all}).
@item C-c @@ C-l
Hide all blocks @var{n} levels below this block
(@code{hs-hide-level}).
@end table

@vindex hs-hide-comments-when-hiding-all
@vindex hs-isearch-open
@vindex hs-special-modes-alist
  These variables can be used to customize Hideshow mode:

@table @code
@item hs-hide-comments-when-hiding-all
If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
comments too.

@item hs-isearch-open
This variable specifies the conditions under which incremental search
should unhide a hidden block when matching text occurs within the
block.  Its value should be either @code{code} (unhide only code
blocks), @code{comment} (unhide only comments), @code{t} (unhide both
code blocks and comments), or @code{nil} (unhide neither code blocks
nor comments).  The default value is @code{code}.
@end table

@node Symbol Completion
@section Completion for Symbol Names
@cindex completion (symbol names)

  Completion is normally done in the minibuffer (@pxref{Completion}),
but you can also complete symbol names in ordinary Emacs buffers.

@kindex M-TAB
@kindex C-M-i
  In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
to complete the partial symbol before point.  On graphical displays,
the @kbd{M-@key{TAB}} key is usually reserved by the window manager
for switching graphical windows, so you should type @kbd{C-M-i} or
@kbd{@key{ESC} @key{TAB}} instead.

@cindex tags-based completion
@findex completion-at-point@r{, in programming language modes}
@cindex Lisp symbol completion
@cindex completion (Lisp symbols)
  In most programming language modes, @kbd{C-M-i} (or
@kbd{M-@key{TAB}}) invokes the command @code{completion-at-point},
which generates its completion list in a flexible way.  If Semantic
mode is enabled, it tries to use the Semantic parser data for
completion (@pxref{Semantic}).  If Semantic mode is not enabled or
fails at performing completion, it tries to complete using the
selected tags table (@pxref{Tags Tables}).  If in Emacs Lisp mode, it
performs completion using the function, variable, or property names
defined in the current Emacs session.

  In all other respects, in-buffer symbol completion behaves like
minibuffer completion.  For instance, if Emacs cannot complete to a
unique symbol, it displays a list of completion alternatives in
another window.  @xref{Completion}.

  In Text mode and related modes, @kbd{M-@key{TAB}} completes words
based on the spell-checker's dictionary.  @xref{Spelling}.

@node MixedCase Words
@section MixedCase Words
@cindex camel case

  Some programming styles make use of mixed-case (or ``CamelCase'')
symbols like @samp{unReadableSymbol}.  (In the GNU project, we recommend
using underscores to separate words within an identifier, rather than
using case distinctions.)  Emacs has various features to make it easier
to deal with such symbols.

@cindex Glasses mode
@cindex mode, Glasses
  Glasses mode is a buffer-local minor mode that makes it easier to read
such symbols, by altering how they are displayed.  By default, it
displays extra underscores between each lower-case letter and the
following capital letter.  This does not alter the buffer text, only how
it is displayed.

  To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
Modes}).  When Glasses mode is enabled, the minor mode indicator
@samp{o^o} appears in the mode line.  For more information about
Glasses mode, type @kbd{C-h P glasses @key{RET}}.

@cindex Subword mode
@findex subword-mode
  Subword mode is another buffer-local minor mode.  In subword mode,
Emacs's word commands recognize upper case letters in
@samp{StudlyCapsIdentifiers} as word boundaries.  When Subword mode is
enabled, the minor mode indicator @samp{,} appears in the mode line.
See also the similar @code{superword-mode} (@pxref{Misc for Programs}).

@node Semantic
@section Semantic
@cindex Semantic package

Semantic is a package that provides language-aware editing commands
based on @code{source code parsers}.  This section provides a brief
description of Semantic; for full details,
@ifnottex
see @ref{Top, Semantic,, semantic, Semantic}.
@end ifnottex
@iftex
see the Semantic Info manual, which is distributed with Emacs.
@end iftex

  Most of the language-aware features in Emacs, such as Font Lock
mode (@pxref{Font Lock}), rely on rules of thumb@footnote{Regular
expressions and syntax tables.} that usually give good results but are
never completely exact.  In contrast, the parsers used by Semantic
have an exact understanding of programming language syntax.  This
allows Semantic to provide search, navigation, and completion commands
that are powerful and precise.

@cindex Semantic mode
@cindex mode, Semantic
  To begin using Semantic, type @kbd{M-x semantic-mode} or click on
the menu item named @samp{Source Code Parsers (Semantic)} in the
@samp{Tools} menu.  This enables Semantic mode, a global minor mode.

   When Semantic mode is enabled, Emacs automatically attempts to
parse each file you visit.  Currently, Semantic understands C, C++,
Scheme, Javascript, Java, HTML, and Make.  Within each parsed buffer,
the following commands are available:

@table @kbd
@item C-c , j
@kindex C-c , j
Prompt for the name of a function defined in the current file, and
move point there (@code{semantic-complete-jump-local}).

@item C-c , J
@kindex C-c , J
Prompt for the name of a function defined in any file Emacs has
parsed, and move point there (@code{semantic-complete-jump}).

@item C-c , @key{SPC}
@kindex C-c , SPC
Display a list of possible completions for the symbol at point
(@code{semantic-complete-analyze-inline}).  This also activates a set
of special key bindings for choosing a completion: @key{RET} accepts
the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible
completions, @key{TAB} completes as far as possible and then cycles,
and @kbd{C-g} or any other key aborts completion.

@item C-c , l
@kindex C-c , l
Display a list of the possible completions of the symbol at point, in
another window (@code{semantic-analyze-possible-completions}).
@end table

@noindent
In addition to the above commands, the Semantic package provides a
variety of other ways to make use of parser information.  For
instance, you can use it to display a list of completions when Emacs
is idle.
@ifnottex
@xref{Top, Semantic,, semantic, Semantic}, for details.
@end ifnottex

@node Misc for Programs
@section Other Features Useful for Editing Programs

  Some Emacs commands that aren't designed specifically for editing
programs are useful for that nonetheless.

  The Emacs commands that operate on words, sentences and paragraphs
are useful for editing code.  Most symbols names contain words
(@pxref{Words}), while sentences can be found in strings and comments
(@pxref{Sentences}).  As for paragraphs, they are defined in most
programming language modes to begin and end at blank lines
(@pxref{Paragraphs}).  Therefore, judicious use of blank lines to make
the program clearer will also provide useful chunks of text for the
paragraph commands to work on.  Auto Fill mode, if enabled in a
programming language major mode, indents the new lines which it
creates.

@findex superword-mode
 Superword mode is a buffer-local minor mode that causes editing and
motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
When Superword mode is enabled, the minor mode indicator
@iftex
@samp{@math{^2}}
@end iftex
@ifnottex
@samp{²}
@end ifnottex
appears in the mode line.  See also the similar @code{subword-mode}
(@pxref{MixedCase Words}).

@findex electric-layout-mode
  Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
minor mode that automatically inserts newlines when you type certain
characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript
mode.

  Apart from Hideshow mode (@pxref{Hideshow}), another way to
selectively display parts of a program is to use the selective display
feature (@pxref{Selective Display}).  Programming modes often also
support Outline minor mode (@pxref{Outline Mode}), which can be used
with the Foldout package (@pxref{Foldout}).

@ifinfo
  The automatic typing features may be useful for writing programs.
@xref{Top,,Autotyping, autotype, Autotyping}.
@end ifinfo

@findex prettify-symbols-mode
  Prettify Symbols mode is a buffer-local minor mode that replaces
certain strings with more attractive versions for display purposes.
For example, in Emacs Lisp mode, it replaces the string @samp{lambda}
with the Greek lambda character @samp{λ}.  In a @TeX{} buffer, it will
replace @samp{\alpha} @dots{} @samp{\omega} and other math macros with
their Unicode characters.  You may wish to use this in non-programming
modes as well.  You can customize the mode by adding more entries to
@code{prettify-symbols-alist}.  More elaborate customization is
available via customizing @code{prettify-symbols-compose-predicate} if
its default value @code{prettify-symbols-default-compose-p} is not
appropriate.  There is also a global version,
@code{global-prettify-symbols-mode}, which enables the mode in all
buffers that support it.

  The symbol at point can be shown in its original form.  This is
controlled by the variable @code{prettify-symbols-unprettify-at-point}:
if non-@code{nil}, the original form of symbol at point will be
restored for as long as point is at it.


@node C Modes
@section C and Related Modes
@cindex C mode
@cindex Java mode
@cindex Pike mode
@cindex IDL mode
@cindex CORBA IDL mode
@cindex Objective C mode
@cindex C++ mode
@cindex AWK mode
@cindex mode, Java
@cindex mode, C
@cindex mode, C++
@cindex mode, Objective C
@cindex mode, CORBA IDL
@cindex mode, Pike
@cindex mode, AWK

  This section gives a brief description of the special features
available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
(These are called ``C mode and related modes''.)
@ifinfo
@xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
@end ifinfo
@ifnotinfo
For more details, see the CC mode Info manual, which is distributed
with Emacs.
@end ifnotinfo

@menu
* Motion in C::                 Commands to move by C statements, etc.
* Electric C::                  Colon and other chars can automatically reindent.
* Hungry Delete::               A more powerful DEL command.
* Other C Commands::            Filling comments, viewing expansion of macros,
                                and other neat features.
@end menu

@node Motion in C
@subsection C Mode Motion Commands

  This section describes commands for moving point, in C mode and
related modes.

@table @code
@item C-M-a
@itemx C-M-e
@findex c-beginning-of-defun
@findex c-end-of-defun
Move point to the beginning or end of the current function or
top-level definition.  In languages with enclosing scopes (such as
C++'s classes) the @dfn{current function} is the immediate one,
possibly inside a scope.  Otherwise it is the one defined by the least
enclosing braces.  (By contrast, @code{beginning-of-defun} and
@code{end-of-defun} search for braces in column zero.)  @xref{Moving
by Defuns}.

@item C-c C-u
@kindex C-c C-u @r{(C mode)}
@findex c-up-conditional
Move point back to the containing preprocessor conditional, leaving the
mark behind.  A prefix argument acts as a repeat count.  With a negative
argument, move point forward to the end of the containing
preprocessor conditional.

@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
the function will stop at a @samp{#elif} when going backward, but not
when going forward.

@item C-c C-p
@kindex C-c C-p @r{(C mode)}
@findex c-backward-conditional
Move point back over a preprocessor conditional, leaving the mark
behind.  A prefix argument acts as a repeat count.  With a negative
argument, move forward.

@item C-c C-n
@kindex C-c C-n @r{(C mode)}
@findex c-forward-conditional
Move point forward across a preprocessor conditional, leaving the mark
behind.  A prefix argument acts as a repeat count.  With a negative
argument, move backward.

@item M-a
@kindex M-a (C mode)
@findex c-beginning-of-statement
Move point to the beginning of the innermost C statement
(@code{c-beginning-of-statement}).  If point is already at the beginning
of a statement, move to the beginning of the preceding statement.  With
prefix argument @var{n}, move back @var{n} @minus{} 1 statements.

In comments or in strings which span more than one line, this command
moves by sentences instead of statements.

@item M-e
@kindex M-e (C mode)
@findex c-end-of-statement
Move point to the end of the innermost C statement or sentence; like
@kbd{M-a} except that it moves in the other direction
(@code{c-end-of-statement}).
@end table

@node Electric C
@subsection Electric C Characters

  In C mode and related modes, certain printing characters are
@dfn{electric}---in addition to inserting themselves, they also
reindent the current line, and optionally also insert newlines.  The
electric characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
@kbd{)}.

  You might find electric indentation inconvenient if you are editing
chaotically indented code.  If you are new to CC Mode, you might find
it disconcerting.  You can toggle electric action with the command
@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
after the mode name:

@table @kbd
@item C-c C-l
@kindex C-c C-l @r{(C mode)}
@findex c-toggle-electric-state
Toggle electric action (@code{c-toggle-electric-state}).  With a
positive prefix argument, this command enables electric action, with a
negative one it disables it.
@end table

  Electric characters insert newlines only when, in addition to the
electric state, the @dfn{auto-newline} feature is enabled (indicated
by @samp{/la} in the mode line after the mode name).  You can turn
this feature on or off with the command @kbd{C-c C-a}:

@table @kbd
@item C-c C-a
@kindex C-c C-a @r{(C mode)}
@findex c-toggle-auto-newline
Toggle the auto-newline feature (@code{c-toggle-auto-newline}).  With a
prefix argument, this command turns the auto-newline feature on if the
argument is positive, and off if it is negative.
@end table

  Usually the CC Mode style configures the exact circumstances in
which Emacs inserts auto-newlines.  You can also configure this
directly.  @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.

@node Hungry Delete
@subsection Hungry Delete Feature in C
@cindex hungry deletion (C Mode)

  If you want to delete an entire block of whitespace at point, you
can use @dfn{hungry deletion}.  This deletes all the contiguous
whitespace either before point or after point in a single operation.
@dfn{Whitespace} here includes tabs and newlines, but not comments or
preprocessor commands.

@table @kbd
@item C-c C-@key{DEL}
@itemx C-c @key{DEL}
@findex c-hungry-delete-backwards
@kindex C-c C-DEL (C Mode)
@kindex C-c DEL (C Mode)
Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}).

@item C-c C-d
@itemx C-c C-@key{Delete}
@itemx C-c @key{Delete}
@findex c-hungry-delete-forward
@kindex C-c C-d (C Mode)
@kindex C-c C-Delete (C Mode)
@kindex C-c Delete (C Mode)
Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}).
@end table

  As an alternative to the above commands, you can enable @dfn{hungry
delete mode}.  When this feature is enabled (indicated by @samp{/h} in
the mode line after the mode name), a single @key{DEL} deletes all
preceding whitespace, not just one space, and a single @kbd{C-d}
(but @emph{not} plain @key{Delete}) deletes all following whitespace.

@table @kbd
@item M-x c-toggle-hungry-state
@findex c-toggle-hungry-state
Toggle the hungry-delete feature
(@code{c-toggle-hungry-state}).  With a prefix argument,
this command turns the hungry-delete feature on if the argument is
positive, and off if it is negative.
@end table

@vindex c-hungry-delete-key
   The variable @code{c-hungry-delete-key} controls whether the
hungry-delete feature is enabled.

@node Other C Commands
@subsection Other Commands for C Mode

@table @kbd
@item M-x c-context-line-break
@findex c-context-line-break
This command inserts a line break and indents the new line in a manner
appropriate to the context.  In normal code, it does the work of
@key{RET} (@code{newline}), in a C preprocessor line it additionally
inserts a @samp{\} at the line break, and within comments it's like
@kbd{M-j} (@code{c-indent-new-comment-line}).

@code{c-context-line-break} isn't bound to a key by default, but it
needs a binding to be useful.  The following code will bind it to
@key{RET}.  We use @code{c-initialization-hook} here to make sure
the keymap is loaded before we try to change it.

@example
(defun my-bind-clb ()
  (define-key c-mode-base-map "\C-m"
              'c-context-line-break))
(add-hook 'c-initialization-hook 'my-bind-clb)
@end example

@item C-M-h
Put mark at the end of a function definition, and put point at the
beginning (@code{c-mark-function}).

@item M-q
@kindex M-q @r{(C mode)}
@findex c-fill-paragraph
Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
If any part of the current line is a comment or within a comment, this
command fills the comment or the paragraph of it that point is in,
preserving the comment indentation and comment delimiters.

@item C-c C-e
@cindex macro expansion in C
@cindex expansion of C macros
@findex c-macro-expand
@kindex C-c C-e @r{(C mode)}
Run the C preprocessor on the text in the region, and show the result,
which includes the expansion of all the macro calls
(@code{c-macro-expand}).  The buffer text before the region is also
included in preprocessing, for the sake of macros defined there, but the
output from this part isn't shown.

When you are debugging C code that uses macros, sometimes it is hard to
figure out precisely how the macros expand.  With this command, you
don't have to figure it out; you can see the expansions.

@item C-c C-\
@findex c-backslash-region
@kindex C-c C-\ @r{(C mode)}
Insert or align @samp{\} characters at the ends of the lines of the
region (@code{c-backslash-region}).  This is useful after writing or
editing a C macro definition.

If a line already ends in @samp{\}, this command adjusts the amount of
whitespace before it.  Otherwise, it inserts a new @samp{\}.  However,
the last line in the region is treated specially; no @samp{\} is
inserted on that line, and any @samp{\} there is deleted.

@item M-x cpp-highlight-buffer
@cindex preprocessor highlighting
@findex cpp-highlight-buffer
Highlight parts of the text according to its preprocessor conditionals.
This command displays another buffer named @file{*CPP Edit*}, which
serves as a graphic menu for selecting how to display particular kinds
of conditionals and their contents.  After changing various settings,
click on @samp{[A]pply these settings} (or go to that buffer and type
@kbd{a}) to rehighlight the C mode buffer accordingly.

@item C-c C-s
@findex c-show-syntactic-information
@kindex C-c C-s @r{(C mode)}
Display the syntactic information about the current source line
(@code{c-show-syntactic-information}).  This information directs how
the line is indented.

@item M-x cwarn-mode
@itemx M-x global-cwarn-mode
@findex cwarn-mode
@findex global-cwarn-mode
@vindex global-cwarn-mode
@cindex CWarn mode
@cindex suspicious constructions in C, C++
CWarn minor mode highlights certain suspicious C and C++ constructions:

@itemize @bullet{}
@item
Assignments inside expressions.
@item
Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
(except after a @samp{do @dots{} while} statement);
@item
C++ functions with reference parameters.
@end itemize

@noindent
You can enable the mode for one buffer with the command @kbd{M-x
cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
global-cwarn-mode} or by customizing the variable
@code{global-cwarn-mode}.  You must also enable Font Lock mode to make
it work.

@item M-x hide-ifdef-mode
@findex hide-ifdef-mode
@cindex Hide-ifdef mode
@vindex hide-ifdef-shadow
Hide-ifdef minor mode hides selected code within @samp{#if} and
@samp{#ifdef} preprocessor blocks.  If you change the variable
@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
shadows preprocessor blocks by displaying them with a less
prominent face, instead of hiding them entirely.  See the
documentation string of @code{hide-ifdef-mode} for more information.

@item M-x ff-find-related-file
@cindex related files
@findex ff-find-related-file
@vindex ff-related-file-alist
Find a file related in a special way to the file visited by the
current buffer.  Typically this will be the header file corresponding
to a C/C++ source file, or vice versa.  The variable
@code{ff-related-file-alist} specifies how to compute related file
names.
@end table

@node Asm Mode
@section Asm Mode

@cindex Asm mode
@cindex assembler 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}.
@c FIXME: Maybe this should be consistent with other programming modes.
@item C-j
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.

@ifnottex
@include fortran-xtra.texi
@end ifnottex

debug log:

solving 0fa37530ef ...
found 0fa37530ef in https://yhetil.org/emacs/20180210112654.GA4537@ACM/
found 4289124545 in https://git.savannah.gnu.org/cgit/emacs.git
preparing index
index prepared:
100644 42891245451d3de3fd43e2b3012a2256e50db3df	doc/emacs/programs.texi

applying [1/1] https://yhetil.org/emacs/20180210112654.GA4537@ACM/
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 4289124545..0fa37530ef 100644

Checking patch doc/emacs/programs.texi...
Applied patch doc/emacs/programs.texi cleanly.

index at:
100644 0fa37530ef62872fdac103b3b27fd1d823874f09	doc/emacs/programs.texi

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.