XEmacs / man / psgml.texi

   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
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ../info/psgml.info
@settitle psgml
@c @setchapternewpage odd
@syncodeindex fn cp
@syncodeindex vr cp
@synindex ky cp
@c %**end of header
@c $Id: psgml.texi,v 1.2 1997/04/10 05:56:17 steve Exp $

@ifinfo
@format
START-INFO-DIR-ENTRY
* PSGML: (psgml).          PSGML, a major mode for SGML documents.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
Documentation for PSGML, a major mode for SGML.

Copyright 1994, 1996 Lennart Staflin
     
Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, and provided that the entire
resulting derived work is distributed under the terms
of a permission notice identical to this one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

@end ifinfo

@titlepage

@title Editing SGML with Emacs and PSGML
@author Lennart Staflin
     
@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994, 1996 Lennart Staflin

@c Published by ...

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, and provided that the entire
resulting derived work is distributed under the terms
of a permission notice identical to this one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.
@end titlepage

@node  Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@ifinfo
@top PSGML

PSGML is a major mode for editing SGML documents.  This is the DRAFT
documentation for PSGML version 1.0.
@end ifinfo

@menu
* Introduction::                Introduction
* Install::                     How to install PSGML
* Invoke::                      How to invoke PSGML
* Entity manager::              The Entity Manager
* Validate::                    Running an external SGML parser
* SGML declaration::            Using an SGML declaration
* Managing the DTD::            Specifying what DTD to use
* Edit::                        Commands for editing
* Display::                     Appearance of text in the buffer
* Miscellaneous options::        
* Bugs::                        Reporting bugs
* Index::                       
@end menu


@c *** section about error recovery ??


@c ------------------------------------------------------------------

@node  Introduction, Install, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex CONCUR
@cindex DATATAG
@cindex LINK
@cindex RANK
@cindex SGML Declaration

PSGML is a major mode for editing SGML documents.  It works with GNU
Emacs 19.19 and later or with Lucid Emacs 19.9 and later.  PSGML
contains a simple SGML parser and can work with any DTD.  Functions
provided includes menus and commands for inserting tags with only the
contextually valid tags, identification of structural errors, editing of
attribute values in a separate window with information about types and
defaults, and structure based editing.

SGML, a language for encoding the structure of a document, is an ISO
standard: ISO 8879:1986 ``Information processing -- Text and office
systems -- Standard Generalized Markup Language (SGML)''.

A good introduction to SGML is @cite{A Gentle Introduction to SGML}
produced by Text Encoding Initiative (this is really chapter 2 of TEI
P3).  This can be found on

@display
@file{ftp://ftp.ifi.uio.no/pub/SGML/TEI/P3SG.DOC}.
@end display

A SGML document has three major parts, in order:

@enumerate
@item
SGML Declaration (@samp{<!SGML "ISO 8879:1986" @dots{} >})
@item
Document Type Declaration (@samp{<!DOCTYPE @var{name} @dots{} >})
@item
Document Element (@samp{<@var{name}> @dots{} </@var{name}>})
@end enumerate

The SGML declaration contains general information about character sets,
concrete syntax, and SGML features used.  PSGML does not use the SGML
Declaration, it can be left out, and if included is ignored.  Many SGML
systems allow the SGML declaration to be defaulted.  PSGML always use
the Concrete Reference Syntax but without limitations on
lengths.  Features used has to be indicated with variables (@pxref{SGML
declaration}).

The document type declaration specifies the valid elements and entities
and how they can be nested. A document type is usually needed, but can
reside in another file (@pxref{Managing the DTD}).

The system declaration for PSGML:
@example
SYSTEM "ISO 8879:1986"
   CHARSET
     BASESET  "ISO 646-1983//CHARSET
               International Reference Version (IRV)//ESC 2/5 4/0"
     DESCSET  0 128 0
     CAPACITY PUBLIC  "ISO 8879:1986//CAPACITY Reference//EN"
   FEATURES
     MINIMIZE DATATAG NO  OMITTAG  YES   RANK     NO  SHORTTAG YES
     LINK     SIMPLE  NO  IMPLICIT NO    EXPLICIT NO
     OTHER    CONCUR  NO  SUBDOC   YES 1 FORMAL   YES
     SCOPE    DOCUMENT
     SYNTAX   PUBLIC  "ISO 8879:1986//SYNTAX Reference//EN"
@c     SYNTAX   PUBLIC  "ISO 8879:1986//SYNTAX Core//EN"
     VALIDATE
              GENERAL NO  MODEL    NO   EXCLUDE  NO  CAPACITY NO
              NONSGML NO  SGML     NO   FORMAL   NO
     SDIF     PACK    NO  UNPACK   NO
@end example


@c -------------------------------------------------------------------------
@node Install, Invoke, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Installing PSGML

To install PSGML you first need to uncompress and unpack the source
archive.  This is done with the @code{gunzip} and @code{tar} commands.

@example
gunzip psgml-1.0.1.tar.gz; tar xf psgml-1.0.1.tar
@end example

This should create a subdirectory to the current directory with the
source code. This directory contains a @code{configure} command (see the
file INSTALL for more information about configure).  You can use the
@code{configure} command to configure the package or you can load the
file @file{psgml-maint} and execute the @code{psgml-compile-files}
command.

Place the @file{*.el} and the @file{*.elc} files in a directory where
Emacs can find it (i.e. one of the directories in the @code{load-path}
variable, you can add a directory to this variable in your
@file{.emacs}.)  

If you use the @code{configure} approach, compile psgml with @code{make}
and the you can run @code{make install} to install it in the system
library @file{site-lisp}.  The files are installed in a subdirectory
named @file{psgml}.  The location of @file{site-lisp} is figured out by
@code{configure}, but you can change it in the @file{Makefile}.  You
need to make sure that this subdirectory is in Emacs @code{load-path}.


Put the following line in your .emacs:

@lisp
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
@end lisp

You may also want to set up search paths for external entities,
@xref{Entity manager}.

The @file{psgml.info} is the documentation for PSGML in the info format.
You can read this with the Emacs command @kbd{C-u C-h i}.  You can also
install the file in your systems info directory and edit the
@file{dir} file to include @file{psgml.info} in the menu.

The info file @file{psgml.info} is created from the texinfo file
@file{psgml.texi}.  The texinfo file can also be used to create a hard
copy of the documentation.  To do this you need the @TeX{} program and a
copy of @file{texinfo.tex}.




@c --------------------------------------------------------------------------
@node  Invoke, Entity manager, Install, Top
@comment  node-name,  next,  previous,  up
@chapter How to invoke PSGML
@cindex invoke
@cindex start up
@cindex major mode

@findex sgml-mode
PSGML defines a major mode called @code{sgml-mode}.  Files with
extensions @file{.sgml}, @file{.sgm} or @file{.dtd} will
automatically be edited in SGML mode.  To edit some other file in
sgml mode, type @kbd{M-x sgml-mode @key{RET}} after finding the
file.

If you can modify the file you can add a @dfn{Local Variables} list
(@pxref{file variables, , Local Variables in Files, emacs, The Emacs
Editor}) to the end of the file.  This can make Emacs
automatically set sgml mode and user options when the file is loaded.
The simplest Local Variables list would look like:

@example
<!--
Local Variables:
mode: sgml
End:
-->
@end example

You can also put a line at the top of the file to tell emacs to use sgml
mode:

@example
<!-- -*- sgml -*- -->
@end example

But remember that you can't have a comment before the @emph{SGML
declaration}.


@c -------------------------------------------------------------------------
@node  Entity manager, Validate, Invoke, Top
@comment node-name,  next,  previous,  up
@chapter The Entity Manager
@cindex public identifier
@cindex system identifier
@cindex external identifier
@cindex entity catalog

@c *** sgml-sysid-resolve-functions

SGML can refer to an external file (really entity) with an
@emph{external identifier}, this is a @emph{public identifier} or a
@emph{system identifier}, or both.

A typical public identifier looks like

@example
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
@end example

@noindent
where ``ISO 8879:1986'' is the owner, ``ENTITIES'' is the text class and
``Added Latin 1'' is the text description (and ``EN'' is language).

A system identifier looks like

@example
SYSTEM "htmlplus.dtd"
@end example

@noindent where ``htmlplus.dtd'' is a system-specific identifier. 

To map external identifiers to file names, PSGML first searches entity
catalog files and then search the list of file name templates in the
variable @code{sgml-public-map}.

The catalog format is according to SGML/Opens resolution on entity
management.  The catalog consists of a series of entries and comments.  A
comment is delimited by @samp{--} like in a markup declaration.
The entry types recognized are described in the following table.

@table @samp

@item public @var{pubid} @var{file}
The @var{file} will be used for the entity text of an entity
with the public identifier @var{pubid}.

@item entity @var{name} @var{file}
The @var{file} will be used for the entity text of an entity
with the name @var{name}.  If the @var{name} starts with a @samp{%} the
rest of the name will be matched against parameter entities.

@item doctype @var{name} @var{file}
The @var{file} will be used for the entity text of an entity
used as external subset of a document declaration with @var{name} as
document type name.

@item sgmldecl @var{file}
Used to specify a default SGML declaration.  Recognized but not used by
PSGML other than to pass to an external validation command
(@code{sgml-validate-command}).

@end table

When PSGML is looking for the file containing an external entity, the
following things will be tried in order:

@enumerate

@vindex sgml-system-identifiers-are-preferred
@item
Try the system identifier, as a file name, if there is a system
identifier and the variable @code{sgml-system-identifiers-are-preferred}
is non-@code{nil} and there is no elements containing @samp{%s} in
@code{sgml-public-map}.  If the system identifier is a relative file name
it will be relative to the directory containing the defining entity.

@item
Look thru each catalog in @code{sgml-local-catalogs} and
@code{sgml-catalog-files} in order.  For each catalog look first for
entries matching the public identifier, if any.  Then look for other
matching entries in the order they appear in the catalog.

Currently an entry will be ignored if it is matching but its file is
non-existent or unreadable.  (This is under reconsideration, perhaps it
should signal error instead).

@item
Try the system identifier, if any, as a file name.
If @code{sgml-system-identifiers-are-preferred} is @code{nil}
and there is no elements containing @samp{%s} in @code{sgml-public-map}.

@item
Try the entries in @code{sgml-public-map}.  Using the catalogs are
preferred.  The @code{sgml-public-map} may disappear in a future version
of PSGML (not soon though).

@end enumerate

The @code{sgml-public-map} variable can contain a list of file name
templates where @samp{%P} will be substituted with the whole public
identifier, owner is substituted for @samp{%O}, public text class for
@samp{%C}, and public text description for @samp{%D}.  The text class
will be converted to lower case and the owner and description will be
transliterated according to the variable
@code{sgml-public-transliterations}.  The templates in the list is tried
in order until an existing file is found.  The @code{sgml-public-map} is
modeled after @file{sgmls} environment variable @code{SGML_PATH} and
psgml understand the following substitution characters: %%, %N, %P, %S,
%Y, %C, %L, %O, %T, and %V.  The the default value of
@code{sgml-public-map} is taken from the environment variable
@code{SGML_PATH}.

Given the public identifier above and the file name template 
@samp{/usr/local/lib/sgml/%o/%c/%d}, the resulting file name is

@example
/usr/local/lib/sgml/ISO_8879:1986/entities/Added_Latin_1
@end example

Note: blanks are transliterated to @samp{_} (and also @samp{/} to
@samp{%}) and the text class is down cased.



@defopt sgml-catalog-files
This is a list of catalog entry files.
The files are in the format defined in the SGML Open Draft Technical
Resolution on Entity Management.  The Emacs variable is initialized from
the environment variable @code{SGML_CATALOG_FILES} or if this variable
is undefined the default is

@lisp
("CATALOG" "/usr/local/lib/sgml/CATALOG")
@end lisp
@end defopt

@defopt sgml-local-catalogs
A list of SGML entity catalogs to be searched first when parsing the
buffer.  This is used in addition to @code{sgml-catalog-files}, and
@code{sgml-public-map}.  This variable is automatically local to the
buffer.
@end defopt

@defopt sgml-system-identifiers-are-preferred
If @code{nil}, PSGML will look up external entities by searching the
catalogs in @code{sgml-local-catalogs} and @code{sgml-catalog-files} and
only if the entity is not found in the catalogs will a given system
identifier be used.  If the variable is non-nil and a system identifier is
given, the system identifier will be used for the entity.  If no system
identifier is given the catalogs will searched.
@end defopt


@defopt sgml-public-map
This should be a list of file name templates.  This variable is
initialized from the environment variable @code{SGML_PATH}.  This is
the same environment variable that @file{sgmls} uses.  If the
environment variable is undefined the default is

@lisp
("%S" "/usr/local/lib/sgml/%o/%c/%d")
@end lisp
@c Mapping from public identifiers to file names.
@end defopt

@c the colon separated list in @code{SGML_PATH} is converted to a lisp list

@c -------------------------------------------------------------------------
@node  Validate, SGML declaration, Entity manager, Top
@comment node-name,  next,  previous,  up
@chapter Running an external SGML parser

@kindex C-c C-v
@findex sgml-validate
PSGML can not validate an SGML document (see below what it can
and can't do).  If you have a validating SGML parser, like
@file{sgmls}, you can run the parser on your file with the
command @kbd{C-c C-v} (@code{sgml-validate}).

Some variables control this function:

@defopt sgml-validate-command
The shell command to validate an SGML document.

This is a @code{format} control string that by default should contain two
@code{%s} conversion specifications: the first will be replaced by the
value of @code{sgml-declaration} (or the empty string, if nil); the
second will be replaced by the current buffer's file name (or the
empty string, if nil).

If @code{sgml-validate-files} is non-nil, the format string should contain
one @code{%s} conversion specification for each element of its result.

If sgml-validate-command is a list, then every element should be a
string.  The strings will be tried in order and @samp{%}-sequences in the
string will be replaced according to the list below, if the string contains
@samp{%}-sequences with no replacement value the next string will be tried.

@table @code
@item %b
means the visited file of the current buffer

@item %s
means the SGML declaration specified in the sgml-declaration variable

@item %d
means the file containing the DOCTYPE declaration, if not in the buffer 
@end table

The default value is @code{nsgmls -s %s %s}.
@end defopt

@defopt sgml-validate-files
If non-nil, a function of no arguments that returns a list of
file names.  These file names will serve as the arguments to the
@code{sgml-validate-command} format control string instead of
the defaults.
@end defopt

@defopt sgml-declaration
The name of the SGML declaration file.
@end defopt

@defopt sgml-offer-save
If non-nil, @kbd{C-c C-v} (@code{sgml-validate}) will ask about
saving modified buffers before running the validate command.
The default value is @code{t}.
@end defopt


@kindex C-c C-o
@findex sgml-next-trouble-spot
The built-in parser can find some markup errors.  The command @kbd{C-c
C-o} (@code{sgml-next-trouble-spot}) is the best way to use the built-in
parser for this.  To check the whole file go to the beginning of the
buffer and use @kbd{C-c C-o}.

Some of the markup errors not found are:

@itemize @bullet
@item
Errors in the SGML declaration.
@item
Errors in attribute specifications.
@item
Omitted start-tags for empty elements.
@end itemize


@c --------------------------------------------------------------------------
@node SGML declaration, Managing the DTD, Validate, Top
@comment  node-name,  next,  previous,  up
@chapter SGML Declaration
@cindex SHORTTAG
@cindex OMITTAG

PSGML does not understand the SGML declaration, it accepts one in the
file but it is ignored.  If you have the SGML declaration in another
file you can make @file{sgmls} use it when you use the @kbd{C-c C-v}
(@code{sgml-validate}) command (@pxref{Validate}).

PSGML has some options in what features it uses and what markup it
creates.  You have to set these options to make PSGML's behavior
consistent with your SGML declaration and personal preferences.

@defopt sgml-omittag
Set this to @code{t} if the SGML declaration has @samp{OMITTAG YES} and
to @code{nil} otherwise.
@end defopt

@defopt sgml-shorttag
Set this to @code{t} if the SGML declaration has @samp{SHORTTAG YES} and
to @code{nil} otherwise.
@end defopt

@defopt sgml-always-quote-attributes
If non-nil, quote all attribute values inserted after finishing edit
attributes.  If this variable is @code{nil} and @code{sgml-shorttag} is
non-@code{nil}, attribute values that consists of only name characters
will not be quoted.
@end defopt

@defopt sgml-minimize-attributes
Determines minimization of attributes inserted by edit-attributes.  If
non-nil, omit attribute name if the attribute value is from a token
group.  If @code{max}, omit attributes with default value.  Minimization
will only be done if they produce legal SGML (assuming
@code{sgml-omittag} and @code{sgml-shorttag} are set correctly).
@end defopt


@c --------------------------------------------------------------------------
@node Managing the DTD, Edit, SGML declaration, Top
@comment  node-name,  next,  previous,  up
@chapter Document Type Declaration
@cindex DOCTYPE
@cindex DTD

@vindex sgml-default-doctype-name
PSGML needs to know about the DTD you are using for many of its commands.
If you do not have a @samp{DOCTYPE} declaration in your file, 
PSGML will try assume that there is one of the form

@example
<!DOCTYPE @var{name} SYSTEM>
@end example

where @var{name} is the value of @code{sgml-default-doctype-name}, if
the value is non-@code{nil}, else the GI of the first tag will be used.

@findex sgml-parse-prolog
@vindex sgml-auto-activate-dtd
PSGML will try to parse the document type declaration the first time
you do something that needs to parse the document or immediately if the
variable @code{sgml-auto-activate-dtd} is @code{t}.  You can also
initiate the parsing of the document type declaration with the command
@code{sgml-parse-prolog}.  Big DTDs take some time to parse.

When the DTD has been parsed or loaded the name of the document element
will be displayed in the mode line inside brackets.  If there was an
error parsing the DTD or there is no DTD, the mode line will display
@samp{[ANY]} (*** this is not really correct! a DTD will be established
even if there are missing entities, it may even be empty).

@menu
* Precompiled DTD Subsets::     
* Using a Split Document::      
* Inserting a DOCTYPE::         
* Information from the DTD::    
@end menu


@c ------------------------------------------------------------
@node  Precompiled DTD Subsets, Using a Split Document, Managing the DTD, Managing the DTD
@comment  node-name,  next,  previous,  up
@section Precompiled DTD Subsets

If parsing the DTD takes too long time you can arrange to have PSGML
cache an internal complied version of the DTD.  Caching can be done of
DTD fragments in favourable situations.  It is possible to have an
external DTD subset cached but still have an internal DTD subset as long
as the internal subset does not define parameter entities that affect
the parsing of the external subset (*** what is the exact conditions?,
probably you can't use the cached external subset if the internal subset
defines parameter entities that are also defined in the external subset
with another value).

@vindex sgml-ecat-files
@vindex sgml-local-ecat-files
To enable caching you have to create special catalog files, hear after
called ECAT files due to (temporary) lack of imagination.  These catalogs
have similar syntax to the entity catalogs and there are two variables
containing lists of catalogs to search: @code{sgml-ecat-files} and
@code{sgml-local-ecat-files}.  The ECAT files can contain the following
types of entries:

@table @samp
@item file @var{dtdfile} @var{entitydef} @var{cfile}
The @var{dtdfile} is the name of a file containing a DTD subset that
should be cached in @var{cfile}.  The @var{entitydef} is optional and if
given have the following syntax:
@example
[ @var{name1} @var{literal1} @var{name2} @var{literal2} @dots{} ]
@end example
Using @var{entitydef} will modify the DTD subset by defining the
parameter entity with name @var{name1} to be @var{literal1}, @dots{}.  The
cached version of the subset will be created with those entity
definitions, and when PSGML search for a matching cached subset will check
that the parameter entities in @var{entitydef} has been defined with
those values before trying to use @file{cfile}. 

@item public @var{pubid} @var{entitydef} @var{cfile}
Cache the DTD subset with public identifier @var{pubid} in file
@var{cfile}. 
@end table


@defopt sgml-recompile-out-of-date-cdtd
If non-@code{nil}, out of date compiled DTDs will be automatically
recompiled.  If the value is @code{ask}, PSGML will ask before
recompiling.  A @code{nil} value will cause PSGML to silently load an out
of date compiled DTD.  A DTD that refers to undefined external entities
is always out of date, thus in such case it can be useful to set this
variable to @code{nil}.
@end defopt


Previous versions of PSGML have had another way of speeding up DTD
parsing.  This code remains in this version of PSGML, but is not actively
maintained and may disappear in the future.

@findex sgml-save-dtd
@findex sgml-load-dtd
@vindex sgml-default-dtd-file
You can save the parsed DTD in a file using the command @kbd{M-x
sgml-save-dtd}.  Next time PSGML can load that file instead of parsing
the DTD.  For PSGML to find the saved DTD you must either save the DTD
using the default name or do a @kbd{M-x sgml-save-options} after saving
the DTD.  To directly use an already parsed and saved DTD, load the file
containing the saved DTD with the command @kbd{M-x sgml-load-dtd}.

@defopt sgml-default-dtd-file
This is the default file name for saved DTD.  This is set by
@code{sgml-mode} to the buffer file name less extension plus the
extension @code{.ced}, if that file exists.  Can be changed in the Local
variables section of the file.
@end defopt

@c true with system-path
@c either or by creating a saved DTD and setting
@c @code{sgml-default-dtd-file} to that file.  If
@c @code{sgml-default-dtd-file} contains a relative file name, the
@c directories in @code{sgml-system-path} will be searched for the file.


@c ------------------------------------------------------------
@node  Using a Split Document, Inserting a DOCTYPE, Precompiled DTD Subsets, Managing the DTD
@comment  node-name,  next,  previous,  up
@section Using a Split Document

@c *** why not defopt??
@vindex sgml-doctype
You can have the @samp{DOCTYPE} declaration in another file by setting
@code{sgml-doctype} to the other file.

@defopt sgml-parent-document
Used when the current file is part of a bigger document.

The variable describes how the current file's content fit into the element
hierarchy.  The variable should have the form

@lisp
(@var{parent-file} @var{context-element}* @var{top-element} (@var{has-seen-element}*)?)
@end lisp

@table @var
@item parent-file
is a string, the name of the file containing the
document entity.

@item context-element
is a string, that is the name of an element type.
It can occur 0 or more times and is used to set up
exceptions and short reference map.  Good candidates
for these elements are the elements open when the
entity pointing to the current file is used. 

@item top-element
is a string that is the name of the element type
of the top level element in the current file.  The file
should contain one instance of this element, unless
the last (lisp) element of sgml-parent-document is a
list.  If it is a list, the top level of the file
should follow the content model of top-element. 

@item has-seen-element
is a string that is the name of an element type.  This
element is satisfied in the content model of top-element.
@end table
@end defopt


@c ------------------------------------------------------------
@node  Inserting a DOCTYPE, Information from the DTD, Using a Split Document, Managing the DTD
@comment  node-name,  next,  previous,  up
@section Inserting a DOCTYPE

@kindex C-c C-u C-d
@findex sgml-custom-dtd
*** Describe the DTD menu in general.  Describe customized entries for
special DTDs.  Mention @kbd{C-c C-u C-d} for inserting a DOCTYPE from
keyboard.

If you change the doctype you must execute @code{sgml-parse-prolog},
changes in the doctype are not automatically recognized.

@defopt sgml-custom-dtd
Menu entries to be added to the DTD menu.  The value should be a list of
entries to be added to the DTD menu.

Every entry should be a list.  The first element of the entry is a string
used as the menu entry.  The second element is a string containing a
doctype declaration (this can be nil if no doctype).  The rest of the
list should be a list of variables and values.  For backward
compatibility a single string instead of a variable is assigned to
@code{sgml-default-dtd-file}.  All variables are made buffer local and
are also added to the buffers local variables list.

When an entry is selected from the DTD menu, the doctype declaration will
be inserted, the variables will be set to the values in the entry and a
local variables list will be created in the buffer.

Example:

@example
   (("HTML" nil
     sgml-default-dtd-file "~/sgml/html.ced"
     sgml-omittag nil sgml-shorttag nil)
    ("HTML+" "<!doctype htmlplus system 'htmlplus.dtd'>"
     "~/sgml/htmlplus.ced"
     sgml-omittag t sgml-shorttag nil)
    ("DOCBOOK" "<!doctype docbook system 'docbook.dtd'>"
     "~/sgml/docbook.ced"
     sgml-omittag nil sgml-shorttag t)))
@end example
@end defopt


@c ------------------------------------------------------------
@node  Information from the DTD,  , Inserting a DOCTYPE, Managing the DTD
@comment  node-name,  next,  previous,  up
@section Information from the DTD
@cindex DTD
@cindex Element

PSGML can list various information about the current DTD.  
The following commands can be used via @kbd{M-x} and 
can also be found in the DTD menu.

@table @code
@findex sgml-general-dtd-info
@item sgml-general-dtd-info
Display information about the current DTD.

@findex sgml-describe-element-type
@item sgml-describe-element-type
Describe the properties of an element type as declared in the current DTD.

@cindex entity
@findex sgml-describe-entity
@item sgml-describe-entity
Describe the properties of an entity as declared in the current DTD.

@findex sgml-list-elements
@item sgml-list-elements
Will list all elements and the attributes declared for the element.

@findex sgml-list-attributes
@item sgml-list-attributes
  Will list all attributes declared and the elements that use them.

@findex sgml-list-terminals
@item sgml-list-terminals
Will list all elements that can contain data.

@findex sgml-list-occur-in-elements
@item sgml-list-occur-in-elements
Will list all element types and where it can occur.

@findex sgml-list-content-elements
@item sgml-list-content-elements
Will list all element types and the element types that can occur
in its content.
@end table


@c ---------------------------------------------------------------------------
@node  Edit, Display, Managing the DTD, Top
@comment  node-name,  next,  previous,  up
@chapter Commands for editing

@menu
* Insert::                      Inserting Markup
* Complete::                    Markup completion
* Information::                 Showing information
* Indent::                      Indentation according to structure
* Move::                        Move in the element structure
* Attributes::                  Editing attributes
* Change and delete::           Changing and deleting markup
* Translating characters and entities::  
@end menu

@c ------------------------------------------------------------------
@node Insert, Complete, Edit, Edit
@comment  node-name,  next,  previous,  up
@section Inserting Markup

@c erik says "inserts" ??
The commands that insert start-tags works only if the document has an
associated DTD.

Keyboard commands for inserting:

@table @kbd
@kindex C-c <
@findex sgml-insert-tag
@item C-c <
Will ask, for the tag to insert, in the mini-buffer with completion on the 
tags that are valid at point (@code{sgml-insert-tag}).

If the option @code{sgml-balanced-tag-edit} is non-nil, inserting a
start-tag will also insert the corresponding end-tag.  If, in addition,
@code{sgml-auto-insert-required-elements} is non-nil, tags for elements
required between the inserted tags will also be inserted.

The list of valid tags, computed for a position in the buffer, will
contain:

@enumerate
@item
The end-tag for the current element, if it can be ended at the position
and @code{sgml-balanced-tag-edit} is nil.  Furthermore it will contain
end-tags for enclosing elements if the necessary omissible end-tag
declarations have been made in the DTD.

@item
The start-tags of all elements that could occur after point.  If
@code{sgml-omittag-transparent} is nil, the above will be limited to the
elements that can occur within the current element.
@end enumerate


@kindex C-c C-e
@findex sgml-insert-element
@vindex sgml-insert-end-tag-on-new-line
@item C-c C-e
Insert start and end-tags for an element
(@code{sgml-insert-element}).  The name of the element is read
from the mini-buffer with completion on valid elements.  If
@code{sgml-insert-end-tag-on-new-line} is non-nil or the
element has element content, the end-tag will be inserted on a
new line after the start-tag.

@vindex sgml-omittag-transparent
If @code{sgml-omittag-transparent} is nil, the list of valid elements
will only contain the elements that can be in the content of the current
element.

@vindex sgml-auto-insert-required-elements
@vindex sgml-insert-missing-element-comment
Required elements in the content will be automatically inserted if the
option @code{sgml-auto-insert-required-elements} is non-nil. 
When the content model demands an element but there is more
than one to choose from, a comment can be inserted with the
available choices if the option
@code{sgml-insert-missing-element-comment} is non-nil.

@kindex C-c C-r
@findex sgml-tag-region
@item C-c C-r
Makes the region into a new element (@code{sgml-tag-region}).  Reads
element name from mini-buffer with completion as for @kbd{C-c C-e}.

@kindex C-c /
@findex sgml-insert-end-tag
@item C-c /
Inserts an end-tag for the current element (@code{sgml-insert-end-tag}).

@kindex C-c RET
@findex sgml-split-element
@item C-c RET
Split the current element at point.  If repeated, the containing element
will be split before the beginning of then current element.

Typical use is to start a new paragraph element when inside a paragraph.

@kindex C-c +
@findex sgml-insert-attribute
@item C-c +
Read attribute name and value from mini-buffer and insert attribute
specification (@code{sgml-insert-attribute}).  If point is immediately
after a start-tag, this command operates on that start-tag.  Otherwise
the command will operate on the element after point.

The attribute name will be read with completion.  If the attribute has a
token list as declared value the attribute value will also be read with
completion.  The prompt for attribute value will typically look like:

@example
Value for @var{attribute} (@var{type} Default: @var{current value}):
@end example

@kindex C-c C-u C-m
@findex sgml-custom-markup
@item C-c C-u C-m
Give keyboard access to the customized part of the Markup menu.
Emacs will prompt for the markup to insert using the menu line as
selector. (See @var{sgml-custom-markup} below.)

@end table

Menu bar:

@table @samp
@item Markup
Selecting from this menu will insert markup.  The menu contains
sub menus with tags and with entities, some other markup and a user
defined section.

Sub menus:

@item Insert element
Pops up a menu of valid elements and insert start and end-tags for
the selected element.  Selections from the menu works like the @kbd{C-c
C-e} command.

@item Insert start-tag
Pops up a menu of valid start-tags and insert the selected tag.  The
menu has the same start-tags as the completion list for @kbd{C-c <}.

@item Insert end-tag
Pops up a menu of valid end-tags and insert the selected tag. 

@item Tag region
Pops up a menu of valid elements and tag the region with the
selection.  Selections from the menu works like the @kbd{C-c C-r}
command.

@item Insert entity
Menu of all general entities defined in the DTD.

@item Insert attribute
Pops up a menu with all the attributes of an element.  The element is
either the one which start-tag is immediately before point or the
element after point.  Selecting from this menu edits the attribute
specification list for the element.

The menu has a sub menu for every attribute which declared value is a
token list.  The rest of the attributes are collected in one sub menu.
For the token list attributes, selecting a value will insert that
attribute-value pair.  Selecting some other attribute reads the
attribute-value from the mini-buffer and inserts the attribute value
pair.
@end table

@kindex S-@key{mouse-1}
A menu is also available directly with a mouse button click in the
buffer.  In GNU Emacs it is the first mouse button combined with shift
(@kbd{S-@key{mouse-1}}).  In XEmacs it is bound to the third mouse
button.  The mouse button click will pop-up a menu of valid tags or a
menu of attributes if the point is in a start-tag.  The attributes menu
works as the ``Insert attribute'' menu from the menu-bar.  The tags list
is the list of valid tags described above for command @kbd{C-c <}.
Selection from the tags menu works like the @kbd{C-c <} command, with
the following exception:

You can tag a region, with start and end-tag.  There are two ways to
indicate the region to mark:

@enumerate
@item
Use the normal mouse commands to mark region.  

For this to work you must either use @dfn{transient mark mode}
(@pxref{Transient Mark, , Transient Mark Mode, emacs, The Emacs
Editor}) or set the option @code{sgml-tag-region-if-active} to non-nil
(don't set this unless you are sure that you want it).

@item
Alternatively make a secondary selection, this is done by holding down
the meta key and using the mouse buttons.  
@xref{Secondary selection, , , emacs, The Emacs Editor}.
Some window managers intercept these events, which makes it hard use the
secondary selection in Emacs.
@end enumerate

@defopt sgml-balanced-tag-edit
If non-nil, inserting a start-tag will also insert the corresponding
end-tag.
@end defopt

@defopt sgml-auto-insert-required-elements
If non-nil, automatically inserts required elements in the content
of an inserted element.
@end defopt

@defopt sgml-omittag-transparent
If non-nil, will show legal tags inside elements with omissible start-tags
and legal tags beyond omissible end-tags.
@end defopt

@defopt sgml-tag-region-if-active
If non-nil, the @samp{Insert tags} menu will tag a region if the region
is considered active by emacs.  If nil, region must be active and
@code{transient-mark-mode} must be on for the region to be tagged.
@end defopt

@defopt sgml-custom-markup
Menu entries to be added to the Markup menu.  The value should be a list
of lists of two strings.  The first string is the menu line and the
second string is the text inserted when the menu item is selected.  The
second string can contain a @samp{\r} where the cursor should be left.
Also, if a selection is made according to the same rules as for the
@kbd{S-mouse-1} menu, the selection is replaced with the second string
and @samp{\r} is replaced with the selection.

Example:

@example
  (("Version1" "<![%Version1[\r]]>")
   ("New page"  "<?NewPage>"))
@end example
@end defopt


@defopt sgml-insert-missing-element-comment
If non-nil, and sgml-auto-insert-required-elements also true,
@code{sgml-insert-element} will insert a comment if there is an
element required but there is more than one to choose from.
@end defopt

@defopt sgml-insert-end-tag-on-new-line
If non-nil, @code{sgml-insert-element} will put the end-tag on
a new line after the start-tag.  Useful on slow terminals if you
find the end-tag after the cursor irritating.
@end defopt


@c -------------------------------------------------------------------------
@node Complete, Information, Insert, Edit
@comment  node-name,  next,  previous,  up
@section Markup completion

@kindex M-TAB
@findex sgml-complete
If you are typing in markup directly, @kbd{M-TAB} will help you by
completing a tag name, an entity name or a markup declaration name.  If
you type @kbd{M-TAB} after a plain word, @code{ispell-complete-word}
will be invoked instead.

If you have typed (@point{} marks the position of point)

@example
&At@point{}
@end example

@noindent and type @kbd{M-TAB} (assuming you use the @file{ISOLat1}
entity set) you get:

@example
&Atilde@point{}
@end example


@c ---------------------------------------------------------------------------
@node Information, Indent, Complete, Edit
@comment  node-name,  next,  previous,  up
@section Showing information

Commands for showing information obtained by parsing the buffer.

@table @kbd
@kindex C-c C-c
@findex sgml-show-context
@item C-c C-c
Shows in the message area: context at point, if in a tag or in mixed
content and the open elements (@code{sgml-show-context}).

@kindex C-c C-w
@findex sgml-what-element
@item C-c C-w
Shows what element the character after point (under the cursor) belongs
to; also shows context of element (@code{sgml-what-element}).

@kindex C-c C-t
@findex sgml-list-valid-tags
@item C-c C-t
List contextually valid tags (@code{sgml-list-valid-tags}).  Displays
information about current element, all valid end-tags, valid start-tags
in current element, and start-tags valid at this point but in other
elements together with the tags omitted.
@end table

You can make the mode-line display the name of the current open element
by setting the @code{sgml-live-element-indicator} variable.  Setting
this will make all commands slower due to the work needed to keep the
mode-line up to date.

@defopt sgml-live-element-indicator
If non-nil, indicate current element in mode line.

NOTE: Setting this implies that every command can cause a parse.  
@end defopt



@c --------------------------------------------------------------------------
@node  Indent, Move, Information, Edit
@comment  node-name,  next,  previous,  up
@section Indentation according to structure

@kindex @key{TAB}
@kindex @key{LFD}
@findex sgml-indent-or-tab
@findex newline-and-indent
You can indent a line according to the depth of element nesting at the
beginning of the line.  To indent the current line use @kbd{@key{TAB}}.
You can also use @kbd{@key{LFD}} (@code{newline-and-indent}) to start a
new line with correct indentation.

@defopt sgml-indent-step
How much to increment indent for every element level.  If nil, no
indentation.

If this is nil, @kbd{@key{TAB}} will insert a tab instead of indenting.
@end defopt

@defopt sgml-indent-data
If non-nil, indent in data/mixed context also.
@end defopt



@c ---------------------------------------------------------------------------
@node  Move, Attributes, Indent, Edit
@comment  node-name,  next,  previous,  up
@section Move in the element structure

These commands move in the element structure.  The commands uses
knowledge of SGML syntax, and if available the specific DTD.

@table @kbd
@kindex C-M-a
@findex sgml-beginning-of-element
@item C-M-a
Move to the (content) beginning of the current element
(@code{sgml-beginning-of-element}).

@kindex C-M-e
@findex sgml-end-of-element
@item C-M-e
Move to the (content) end of the current element (@code{sgml-end-of-element}).

@kindex C-M-f
@findex sgml-forward-element
@item C-M-f
Move forward by element (@code{sgml-forward-element}).

@kindex C-M-b
@findex sgml-backward-element
@item C-M-b
Move backward by element (@code{sgml-backward-element}).

@kindex C-M-u
@findex sgml-backward-up-element
@item C-M-u
Move up to before current element (@code{sgml-backward-up-element}).

@kindex C-c C-n
@findex sgml-up-element
@item C-c C-n
Move up to after current element (@code{sgml-up-element}).

@kindex C-M-d
@findex sgml-down-element
@item C-M-d
Move down to the (content) beginning of the next element
(@code{sgml-down-element}).

@kindex C-c C-d
@findex sgml-next-data-field
@item C-c C-d
Move to the next place where data is allowed (@code{sgml-next-data-field}).
@end table

You can also move to the next place where there is some structural error
with @kbd{C-c C-o} (@pxref{Validate}).


@c ---------------------------------------------------------------------------
@node Attributes, Change and delete, Move, Edit
@comment  node-name,  next,  previous,  up
@section Editing attributes

@findex sgml-edit-attributes
@kindex C-c C-a
If you want to change the attributes of a start-tag you can simply edit
them directly in the buffer.  Or you can place the cursor at or after
the start-tag and use the @code{sgml-edit-attributes} command, available
from the @samp{SGML}-menu or on @kbd{C-c C-a}.  This will create a new
Emacs window with all possible attributes listed in the form

@example
@var{attribute name} = @var{current value}.
@end example

The @var{current value} may be shown as @samp{#DEFAULT} if the attribute
has not been given a value in the start-tag.  The list also contains the
attributes declaration as a comment.  Note also that the @var{current
value} is show without eventual quotes.

@kindex C-c C-d
@kindex @key{TAB}
It is now possible to edit the attribute values.  You can move to the
next attribute with @kbd{@key{TAB}}.  If you want to let an attribute
have its default value use @kbd{C-c C-d}, this will insert a
@samp{#DEFAULT} in the value field.

If Emacs is running in an X window, the @samp{#DEFAULT} will be
underlined to distinguish it from normal values.

@kindex C-c C-c
Finish the editing with @kbd{C-c C-c}; this will replace the attribute
values in the main buffer with those edited.  Note that values will be
quoted as needed.

If you want to abort the editing, you can remove the window with
@kbd{C-x 0} or if you want it neat, kill the buffer and remove the
window.

Some other keys are:
@table @kbd
@kindex C-a
@findex sgml-edit-attrib-field-start
@item C-a
Go to the beginning of the value field
(@code{sgml-edit-attrib-field-start}).

@kindex C-e
@findex sgml-edit-attrib-field-end
@item C-e
Go to the end of the value field
(@code{sgml-edit-attrib-field-end}).

@kindex C-c C-k
@findex sgml-edit-attrib-clear
@item C-c C-k
Clear the value field
(@code{sgml-edit-attrib-clear}).

@kindex C-c C-d
@findex sgml-edit-attrib-default
@item C-c C-d
Set the value field to @samp{#DEFAULT}
(@code{sgml-edit-attrib-default}).  This is a special value that will
make the attribute be implied.
@end table


@c --------------------------------------------------------------------------
@node Change and delete, Translating characters and entities, Attributes, Edit
@comment  node-name,  next,  previous,  up
@section Changing and deleting markup

@table @kbd
@kindex C-c =
@findex sgml-change-element-name
@item C-c =
Change the name of the current element (@code{sgml-change-element-name}).
Tries to translate attribute specifications.  An attribute will be
translated to an attribute with the same name.  If the new element has
no attribute with the same name, the attribute will be ignored.  If
there is an attribute with the same name but different declared content,
a warning is given.

ID attributes are handled specially, an attribute with declared value ID
will always be translated to the attribute with declared value ID.

@kindex C-c C-k
@findex sgml-kill-markup
@item C-c C-k
Kill next tag, markup declaration or process instruction
(@code{sgml-kill-markup}).

@kindex C-M-k
@findex sgml-kill-element
@item C-M-k
Kill the element following the cursor (@code{sgml-kill-element}).

@kindex C-c -
@findex sgml-untag-element
@item C-c -
Remove tags from current element (@code{sgml-untag-element}).

@kindex C-c #
@findex sgml-make-character-reference
@item C-c #
Convert character after point to a character reference
(@code{sgml-make-character-reference}).  If called with a numeric
argument, convert a character reference back to a normal character.

@kindex C-c C-q
@findex sgml-fill-element
@item C-c C-q
Fills an element as a paragraph (@code{sgml-fill-element}).  This is a
substitute for the normal @code{fill-paragraph}.  The command uses
heuristics to decide what should be a paragraph.

@enumerate
@item
If point is in an element content, recursively fill the sub-elements.
@item
Find the biggest element with mixed content containing point.
@item
If the above element is mixed but contains elements with pure element
content then fill what is between the pure elements as paragraphs and
fill the pure elements recursively.
@end enumerate

@findex sgml-expand-all-shortrefs
@item M-x sgml-expand-all-shortrefs
Short references to text entities are expanded to the replacement text
of the entity other short references are expanded into general entity
references.  If argument, @var{to-entity}, is non-@code{nil}, or if
called interactive with numeric prefix argument, all short references
are replaced by generally entity references.

@findex sgml-normalize
@item M-x sgml-normalize
Normalize the document in the buffer.  This will

@enumerate
@item
expand short references,
@item
insert missing tags,
@item
replace minimized tags with full tags,
@item
fix attribute specification lists according to options set.
@end enumerate

There is one argument, @var{to-entity}, with the same meaning as for
@code{sgml-expand-all-shortrefs}.

There is one option for the normalize command.  With its default value,
normalize may actually change the data content of some elements.  But
only by removing some white-space from the end of elements with omitted
end-tags.
@end table

@defopt sgml-normalize-trims
If non-nil, @code{sgml-normalize} will trim off white space from end of
element when adding end-tag.

Default: @code{t}.
@end defopt


@c --------------------------------------------------------------------------
@node Translating characters and entities,  , Change and delete, Edit
@comment  node-name,  next,  previous,  up
@section Translating between characters and entity references

@c *** Need work..

Set the variable @code{sgml-display-char-list-filename} to a file file that
contains mappings between all characters present in the presentation
character set, and their "standard replacement text" names, e.g. "�"
-> "[aring ]", e.t.c.

The default value for this variable is `iso88591.map'. 

The use the functions (also in the Modify menu)

@table @code
@findex sgml-charent-to-display-char
@item sgml-charent-to-display-char
@findex sgml-display-char-to-charent
@item sgml-display-char-to-charent
@end table

to translate between entities and characters.

@c ---------------------------------------------------------------------------
@node Display, Miscellaneous options, Edit, Top
@comment  node-name,  next,  previous,  up
@chapter Appearance of text in the buffer

@menu
* Fold::                        Folding editing
* Hiding markup::               
* Highlight::                   Highlighting markup
@end menu

@c ---------------------------------------------------------------------------
@node  Fold, Hiding markup, Display, Display
@comment  node-name,  next,  previous,  up
@section Folding editing

With these commands you can make parts of the text temporarily invisible
to make it easier to see the overall structure of your text.  

When folding a region all the lines but the first will be invisible.
The first line of the region will still be visible with an ellipsis at
the end.

@xref{Outline Mode, , , emacs, The Emacs Editor}.

@table @kbd
@kindex C-c C-f C-r
@findex sgml-fold-region
@item C-c C-f C-r
The region between point and mark will be folded (@code{sgml-fold-region}).

@kindex C-c C-f C-e
@findex sgml-fold-element
@item C-c C-f C-e
The region between the start and end of the current element will be
folded (@code{sgml-fold-element}).

This command can also fold the SGML declaration or the DOCTYPE
declaration.

@kindex C-c C-f C-s
@findex sgml-fold-subelement
@item C-c C-f C-s
Fold all the sub elements of the current element
(@code{sgml-fold-subelement}).

@kindex C-c C-s
@kindex C-c C-u C-l
@findex sgml-unfold-line
@item C-c C-s
@itemx C-c C-u C-l
Unfold the current line, assuming it is the first line of a folded
region (@code{sgml-unfold-line}).

@kindex C-c C-u C-e
@findex sgml-unfold-element
@item C-c C-u C-e
Make all lines in current element visible (@code{sgml-unfold-element}).

@kindex C-c C-u C-a
@findex sgml-unfold-all
@item C-c C-u C-a
Make all lines in current buffer visible (@code{sgml-unfold-all}).

@kindex C-c C-f C-x
@findex sgml-expand-element
@item C-c C-f C-x
Unfold current element and then fold the subelements
(@code{sgml-expand-element}).  If the current element is folded this
expands what is visible.
@end table


@c ---------------------------------------------------------------------------
@node  Hiding markup, Highlight, Fold, Display
@comment  node-name,  next,  previous,  up
@section Hiding markup

*** Describe hide-tags


@c ---------------------------------------------------------------------------
@node  Highlight,  , Hiding markup, Display
@comment  node-name,  next,  previous,  up
@section Highlighting markup


PSGML can highlight the markup giving the markup a different @dfn{face}
(@pxref{Faces, , Using Multiple Typefaces, emacs, The Emacs Editor}).
The highlighting will only be done if the variable @code{sgml-set-face}
is non-@code{nil}.  The default settings make tags bold and comments
italic, but this can be modified with the variable
@code{sgml-markup-faces}.  When highlighting is on PSGML will parse after
every command until the whole buffer has been parsed or user event
occurs. 

@findex sgml-clear-faces
To remove the highlighting type @kbd{M-x sgml-clear-faces}.

@defopt sgml-set-face
If non-nil, psgml will set the face of parsed markup.
@end defopt

@defopt sgml-markup-faces
A list of markup to face mappings.
Each element looks like @code{(@var{markup-type} . @var{face})}.
Possible values for @var{markup-type} is:

@table @code
@item comment
comment declaration
@item doctype
doctype declaration
@item end-tag
end-tag 
@item ignored
ignored marked section
@item ms-start
marked section end, if not ignored
@item ms-end
marked section start, if not ignored 
@item pi
processing instruction
@item sgml
SGML declaration
@item start-tag
start-tag
@item entity
entity reference
@item shortref
short reference
@end table
@end defopt



@c ------------------------------------------------------------------
@node  Miscellaneous options, Bugs, Display, Top
@comment  node-name,  next,  previous,  up
@chapter Miscellaneous options

*** describe sgml-save-options

@defopt sgml-ignore-undefined-elements
Start-tags for undefined elements will either be ignored, if
@code{sgml-ignore-undefined-elements} is @code{t}, or assumed to be
acceptable in the current element and defined with @code{O O ANY}
@end defopt

@defopt sgml-range-indicator-max-length
Maximum number of characters used from the first and last entry
of a sub-menu to indicate the range of that menu.

@vindex sgml-max-menu-size
This is used for long menus of elements, tags or entities that are split
into @code{sgml-max-menu-size} big sub-menus.
@end defopt




@c ------------------------------------------------------------------
@node Bugs, Index, Miscellaneous options, Top
@comment  node-name,  next,  previous,  up
@chapter Bugs


If you encounter something that you think is a bug, please report
it.  Try to include a clear description of the undesired behaviour.
A test case that exhibits the bug, would also be useful.

You can report a bug with the command @kbd{M-x sgml-submit-bug-report}.

When PSGML needs contextual information it parses the document up to
the point.  During the parsing, it builds a parse tree.  The parse
tree is used to initialize the next parse, to avoid having to parse
things already parsed.  Changes to the buffer is supposed to prune
the tree of all outdated information.  But if you get strange
complaints from the parser, try and back up a bit and use @kbd{C-c
C-o} (@code{sgml-next-trouble-spot}).



@c ------------------------------------------------------------------
@node Index,  , Bugs, Top
@comment    node-name,         next,       previous, up
@chapter Index
     
@printindex cp

@contents
@bye
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.