nxml-mode.texi 31.1 KB
 Mark A. Hershberger committed Nov 23, 2007 1 2 ``````\input texinfo @c -*- texinfo -*- @c %**start of header `````` Mark A. Hershberger committed Nov 23, 2007 3 ``````@setfilename ../../info/nxml-mode `````` Mark A. Hershberger committed Nov 23, 2007 4 5 6 ``````@settitle nXML Mode @c %**end of header `````` Glenn Morris committed Jan 09, 2008 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 ``````@copying This manual documents nxml-mode, an Emacs major mode for editing XML with RELAX NG support. Copyright @copyright{} 2007, 2008 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual. `````` Glenn Morris committed Jun 13, 2008 23 24 25 ``````(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.'' `````` Glenn Morris committed Jan 09, 2008 26 27 28 29 30 31 32 33 `````` This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license. @end quotation @end copying `````` Mark A. Hershberger committed Nov 23, 2007 34 35 ``````@dircategory Emacs @direntry `````` Romain Francoise committed Nov 24, 2007 36 ``````* nXML Mode: (nxml-mode). XML editing mode with RELAX NG support. `````` Mark A. Hershberger committed Nov 23, 2007 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 ``````@end direntry @node Top @top nXML Mode This manual documents nxml-mode, an Emacs major mode for editing XML with RELAX NG support. This manual is not yet complete. @menu * Completion:: * Inserting end-tags:: * Paragraphs:: * Outlining:: * Locating a schema:: * DTDs:: * Limitations:: @end menu @node Completion @chapter Completion Apart from real-time validation, the most important feature that nxml-mode provides for assisting in document creation is "completion". Completion assists the user in inserting characters at point, based on knowledge of the schema and on the contents of the buffer before point. The traditional GNU Emacs key combination for completion in a buffer is @kbd{M-@key{TAB}}. However, many window systems and window managers use this key combination themselves (typically for switching between windows) and do not pass it to applications. It's hard to find key combinations in GNU Emacs that are both easy to type and not taken by something else. @kbd{C-@key{RET}} (i.e. pressing the Enter or Return key, while the Ctrl key is held down) is available. It won't be available on a traditional terminal (because it is indistinguishable from Return), but it will work with a window system. Therefore we adopt the following solution by default: use @kbd{C-@key{RET}} when there's a window system and @kbd{M-@key{TAB}} when there's not. In the following, I will assume that a window system is being used and will therefore refer to @kbd{C-@key{RET}}. Completion works by examining the symbol preceding point. This is the symbol to be completed. The symbol to be completed may be the empty. Completion considers what symbols starting with the symbol to be completed would be valid replacements for the symbol to be completed, given the schema and the contents of the buffer before point. These symbols are the possible completions. An example may make this clearer. Suppose the buffer looks like this (where @point{} indicates point): @example <@point{} @end example @noindent In this case, the symbol to be completed is empty, and the possible completions are @samp{base}, @samp{isindex}, @samp{link}, @samp{meta}, @samp{script}, @samp{style}, @samp{title}. Another example is: @example <@point{} @end example @noindent @kbd{C-@key{RET}} will yield @example @end example @noindent This says to use the schema @samp{xhtml.rnc} for a document with namespace @samp{http://www.w3.org/1999/xhtml}, and to use the schema @samp{docbook.rnc} for a document whose local name is @samp{book}. If the document element had both a namespace URI of @samp{http://www.w3.org/1999/xhtml} and a local name of @samp{book}, then the matching rule that comes first will be used and so the schema @samp{xhtml.rnc} would be used. There is no precedence between different types of rule; the first matching rule of any type is used. As usual with XML-related technologies, resources are identified by URIs. The @samp{uri} attribute identifies the schema by specifying the URI. The URI may be relative. If so, it is resolved relative to the URI of the schema locating file that contains attribute. This means that if the value of @samp{uri} attribute does not contain a @samp{/}, then it will refer to a filename in the same directory as the schema locating file. @node Using the document's URI to locate a schema @subsection Using the document's URI to locate a schema A @samp{uri} rule locates a schema based on the URI of the document. The @samp{uri} attribute specifies the URI of the schema. The @samp{resource} attribute can be used to specify the schema for a particular document. For example, @example @end example @noindent specifies that that the schema for @samp{spec.xml} is @samp{docbook.rnc}. The @samp{pattern} attribute can be used instead of the @samp{resource} attribute to specify the schema for any document whose URI matches a pattern. The pattern has the same syntax as an absolute or relative URI except that the path component of the URI can use a @samp{*} character to stand for zero or more characters within a path segment (i.e. any character other @samp{/}). Typically, the URI pattern looks like a relative URI, but, whereas a relative URI in the @samp{resource} attribute is resolved into a particular absolute URI using the base URI of the schema locating file, a relative URI pattern matches if it matches some number of complete path segments of the document's URI ending with the last path segment of the document's URI. For example, @example @end example @noindent specifies that the schema for documents with a URI whose path ends with @samp{.xsl} is @samp{xslt.rnc}. A @samp{transformURI} rule locates a schema by transforming the URI of the document. The @samp{fromPattern} attribute specifies a URI pattern with the same meaning as the @samp{pattern} attribute of the @samp{uri} element. The @samp{toPattern} attribute is a URI pattern that is used to generate the URI of the schema. Each @samp{*} in the @samp{toPattern} is replaced by the string that matched the corresponding @samp{*} in the @samp{fromPattern}. The resulting string is appended to the initial part of the document's URI that was not explicitly matched by the @samp{fromPattern}. The rule matches only if the transformed URI identifies an existing resource. For example, the rule @example @end example @noindent would transform the URI @samp{file:///home/jjc/docs/spec.xml} into the URI @samp{file:///home/jjc/docs/spec.rnc}. Thus, this rule specifies that to locate a schema for a document @samp{@var{foo}.xml}, Emacs should test whether a file @samp{@var{foo}.rnc} exists in the same directory as @samp{@var{foo}.xml}, and, if so, should use it as the schema. @node Using the document element to locate a schema @subsection Using the document element to locate a schema A @samp{documentElement} rule locates a schema based on the local name and prefix of the document element. For example, a rule @example @end example @noindent specifies that when the name of the document element is @samp{xsl:stylesheet}, then @samp{xslt.rnc} should be used as the schema. Either the @samp{prefix} or @samp{localName} attribute may be omitted to allow any prefix or local name. A @samp{namespace} rule locates a schema based on the namespace URI of the document element. For example, a rule @example @end example @noindent specifies that when the namespace URI of the document is @samp{http://www.w3.org/1999/XSL/Transform}, then @samp{xslt.rnc} should be used as the schema. @node Using type identifiers in schema locating files @subsection Using type identifiers in schema locating files Type identifiers allow a level of indirection in locating the schema for a document. Instead of associating the document directly with a schema URI, the document is associated with a type identifier, which is in turn associated with a schema URI. nXML mode does not constrain the format of type identifiers. They can be simply strings without any formal structure or they can be public identifiers or URIs. Note that these type identifiers have nothing to do with the DOCTYPE declaration. When comparing type identifiers, whitespace is normalized in the same way as with the @samp{xsd:token} datatype: leading and trailing whitespace is stripped; other sequences of whitespace are normalized to a single space character. Each of the rules described in previous sections that uses a @samp{uri} attribute to specify a schema, can instead use a @samp{typeId} attribute to specify a type identifier. The type identifier can be associated with a URI using a @samp{typeId} element. For example, @example @end example @noindent declares three type identifiers @samp{XHTML} (representing the default variant of XHTML to be used), @samp{XHTML Strict} and @samp{XHTML Transitional}. Such a schema locating file would use @samp{xhtml-strict.rnc} for a document whose namespace is @samp{http://www.w3.org/1999/xhtml}. But it is considerably more flexible than a schema locating file that simply specified @example @end example @noindent A user can easily use @kbd{C-c C-s C-t} to select between XHTML Strict and XHTML Transitional. Also, a user can easily add a catalog @example @end example @noindent that makes the default variant of XHTML be XHTML Transitional. @node Using multiple schema locating files @subsection Using multiple schema locating files The @samp{include} element includes rules from another schema locating file. The behavior is exactly as if the rules from that file were included in place of the @samp{include} element. Relative URIs are resolved into absolute URIs before the inclusion is performed. For example, @example @end example @noindent includes the rules from @samp{rules.xml}. The process of locating a schema takes as input a list of schema locating files. The rules in all these files and in the files they include are resolved into a single list of rules, which are applied strictly in order. Sometimes this order is not what is needed. For example, suppose you have two schema locating files, a private file @example @end example @noindent followed by a public file @example @end example @noindent The effect of these two files is that the XHTML @samp{namespace} rule takes precedence over the @samp{transformURI} rule, which is almost certainly not what is needed. This can be solved by adding an @samp{applyFollowingRules} to the private file. @example @end example @node DTDs @chapter DTDs nxml-mode is designed to support the creation of standalone XML documents that do not depend on a DTD. Although it is common practice to insert a DOCTYPE declaration referencing an external DTD, this has undesirable side-effects. It means that the document is no longer self-contained. It also means that different XML parsers may interpret the document in different ways, since the XML Recommendation does not require XML parsers to read the DTD. With DTDs, it was impractical to get validation without using an external DTD or reference to an parameter entity. With RELAX NG and other schema languages, you can simulataneously get the benefits of validation and standalone XML documents. Therefore, I recommend that you do not reference an external DOCTYPE in your XML documents. One problem is entities for characters. Typically, as well as providing validation, DTDs also provide a set of character entities for documents to use. Schemas cannot provide this functionality, because schema validation happens after XML parsing. The recommended solution is to either use the Unicode characters directly, or, if this is impractical, use character references. nXML mode supports this by providing commands for entering characters and character references using the Unicode names, and can display the glyph corresponding to a character reference. @node Limitations @chapter Limitations nXML mode has some limitations: @itemize @bullet @item DTD support is limited. Internal parsed general entities declared in the internal subset are supported provided they do not contain elements. Other usage of DTDs is ignored. @item The restrictions on RELAX NG schemas in section 7 of the RELAX NG specification are not enforced. @item Unicode support has problems. This stems mostly from the fact that the XML (and RELAX NG) character model is based squarely on Unicode, whereas the Emacs character model is not. Emacs 22 is slated to have full Unicode support, which should improve the situation here. @end itemize @bye `````` Miles Bader committed Nov 23, 2007 862 863 864 865 `````` @ignore arch-tag: 3b6e8ac2-ae8d-4f38-bd43-ce9f80be04d6 @end ignore``````