From: Mark A. Hershberger Date: Fri, 23 Nov 2007 19:38:49 +0000 (+0000) Subject: Fixups for nxml per Romain Francoise email. X-Git-Tag: emacs-pretest-23.0.90~9515 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=ac97a16bd1a96fd728c3830c2680ba3b223ad278;p=emacs.git Fixups for nxml per Romain Francoise email. --- diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 18e4686c431..bcf97b80baf 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,7 @@ +2007-11-23 Mark A. Hershberger + + * nxml-mode.texi: Move to ../misc. + 2007-11-23 Thien-Thi Nguyen * files.texi (Why Version Control?): Fix typo. diff --git a/doc/emacs/nxml-mode.texi b/doc/emacs/nxml-mode.texi deleted file mode 100644 index e2ab3fdbd58..00000000000 --- a/doc/emacs/nxml-mode.texi +++ /dev/null @@ -1,834 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename nxml-mode.info -@settitle nXML Mode -@c %**end of header - -@dircategory Emacs -@direntry -* nXML Mode: (nxml-mode.info). -@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 diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index d1f74ca756c..24dbe68d4ed 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,14 @@ +2007-11-23 Mark A. Hershberger + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add nxml-mode. + ($(infodir)/nxml-mode): New rule. + + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Add nxml-mode. + ($(infodir)/nxml-mode): New rule. + (clean): Add nxml-mode*. + + * nxml-mode.texi: New file with nxml manual. + 2007-11-18 Michael Albinus * tramp.texi (Filename completion): Simplify explanation of diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 93982f419dc..2e3bfad0823 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -60,6 +60,7 @@ INFO_TARGETS = \ $(infodir)/message \ $(infodir)/mh-e \ $(infodir)/newsticker \ + $(infodir)/nxml-mode \ $(infodir)/org \ $(infodir)/pcl-cvs \ $(infodir)/pgg \ @@ -100,6 +101,7 @@ DVI_TARGETS = \ message.dvi \ mh-e.dvi \ newsticker.dvi \ + nxml-mode.dvi \ org.dvi \ pcl-cvs.dvi \ pgg.dvi \ @@ -278,6 +280,12 @@ $(infodir)/newsticker: newsticker.texi newsticker.dvi: newsticker.texi $(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi +nxml-mode : $(infodir)/nxml-mode +$(infodir)/nxml-mode: nxml-mode.texi + cd $(srcdir); $(MAKEINFO) nxml-mode.texi +nxml-mode.dvi: nxml-mode.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/nxml-mode.texi + org : $(infodir)/org $(infodir)/org: org.texi cd $(srcdir); $(MAKEINFO) org.texi diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in index 4d8d44765d4..d626ef2fe99 100644 --- a/doc/misc/makefile.w32-in +++ b/doc/misc/makefile.w32-in @@ -43,7 +43,7 @@ INFO_TARGETS = $(infodir)/ccmode \ $(infodir)/url $(infodir)/speedbar $(infodir)/tramp \ $(infodir)/ses $(infodir)/smtpmail $(infodir)/flymake \ $(infodir)/newsticker $(infodir)/rcirc $(infodir)/erc \ - $(infodir)/remember + $(infodir)/remember $(infodir)/nxml-mode DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \ ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ gnus.dvi message.dvi sieve.dvi pgg.dvi mh-e.dvi \ @@ -51,7 +51,7 @@ DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \ ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \ pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \ speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \ - newsticker.dvi rcirc.dvi erc.dvi remember.dvi + newsticker.dvi rcirc.dvi erc.dvi remember.dvi nxml-mode.dvi INFOSOURCES = info.texi # The following rule does not work with all versions of `make'. @@ -271,6 +271,11 @@ $(infodir)/newsticker: newsticker.texi newsticker.dvi: newsticker.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi +$(infodir)/nxml-mode: nxml-mode.texi + $(MAKEINFO) nxml-mode.texi +nxml-mod.dvi: nxml-mode.texi + $(ENVADD) $(TEXI2DVI) $(srcdir)/nxml-mode.texi + $(infodir)/rcirc: rcirc.texi $(MAKEINFO) rcirc.texi rcirc.dvi: rcirc.texi @@ -304,7 +309,7 @@ clean: mostlyclean $(infodir)/flymake* $(infodir)/newsticker* \ $(infodir)/sieve* $(infodir)/pgg* \ $(infodir)/erc* $(infodir)/rcirc* \ - $(infodir)/remember* + $(infodir)/remember* $(infodir)/nxml-mode* distclean: clean diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi new file mode 100644 index 00000000000..fec3350312c --- /dev/null +++ b/doc/misc/nxml-mode.texi @@ -0,0 +1,834 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename ../../info/nxml-mode +@settitle nXML Mode +@c %**end of header + +@dircategory Emacs +@direntry +* nXML Mode: (nxml-mode.info). +@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 diff --git a/etc/ChangeLog b/etc/ChangeLog index 419522c810a..45dce8b9c0a 100644 --- a/etc/ChangeLog +++ b/etc/ChangeLog @@ -1,5 +1,7 @@ 2007-11-23 Mark A. Hershberger + * NXML-NEWS: New File. + * schema: Initial merge of nxml. 2007-11-22 Francesco Potort,Al(B diff --git a/etc/NXML-NEWS b/etc/NXML-NEWS new file mode 100644 index 00000000000..cebbab82fda --- /dev/null +++ b/etc/NXML-NEWS @@ -0,0 +1,199 @@ +20041004 +-------- + +Support for outlining has been added. See the manual for more details. + +C-u C-c C-n goes to the first error. + +20040910 +-------- + +C-c RET splits the current element as in PSGML. + +20040908 +-------- + +Indentation has been rewritten. Indentation of attribute names and +values should work better. The default value of +`nxml-attribute-indent' has been changed to 4. + +Syntax highlighting with a dark background should now work. + +20040726 +-------- + +The attribute pathSuffix on the uri element in schema locating files +has been replaced by a more general pattern attribute. The +transformURI element now has required fromPattern and toPattern +attributes. + +The schema related bindings have been changed to use C-c C-s as a prefix +as follows: + + C-c C-s => C-c C-s C-f (f for file) + C-c C-a => C-c C-s C-a + C-c C-t => C-c C-s C-t + C-c C-l => C-c C-s C-l + C-c C-w => C-c C-s C-w + +There's now an XML menu on the menu-bar. + +20031031 +-------- + +C-c C-d "dynamically" chooses a tag to put around the word before +point, rather like M-/. + +The mechanism for locating the schema has changed completely. The new +mechanism is described in the manual. Any existing customizations of +`rng-auto-element-alist' or `rng-auto-file-name-alist' will no longer +be effective. + +C-c C-a is now bound to rng-auto-set-schema. + +20031018 +-------- + +Unicode names can be used to insert characters with the new command +C-c C-u. Normally, this inserts a character reference. With a prefix +arg (i.e. C-u C-c C-u), it inserts the character directly. You can +customize `nxml-enabled-unicode-blocks' to control what Unicode blocks +are used for completing names. + +Extra information is displayed for character references. The Unicode +name is displayed in a tooltip. A glyph for the referenced character +is displayed in a distinguished face following the character +reference; this can be disabled by customizing +`nxml-char-ref-display-glyph-flag'. The command +`nxml-toggle-char-ref-extra-display' dynamically toggles the display +of extra information for character references for a particular buffer. +This can be used if the display of extra information is causing +performance problems. nXML mode tries to figure out which glyphs can +be displayed. Unfortunately Emacs doesn't provide the primitives +necessary to do this properly, so nXML mode has to guess and will +sometimes guess wrong. The hook `nxml-glyph-set-hook' can be used to +change nXML mode's guess. + +New command C-c C-w says what schema is being used. + +C-c C-s now turns on validation if it is not already on. + +20030928 +-------- + +M-q has been implemented so that it works reasonably with XML. Other +paragraph-related commands (M-{, M-}, M-h) have also been implemented. + +New command M-x rng-auto-set-schema to set the schema based on the +buffer's current contents and file-name. This is called automatically +when rng-validate-mode is first enabled. + +There's now a C-M-d to go with C-M-u. C-M-d moves forward down into +the content of an element. C-M-n and C-M-p move to the next or +previous element. + +By default, the sexp commands (C-M-f, C-M-b, C-M-k, C-M-SPC) operate +on tags rather than elements. To restore the old behaviour, +customize nxml-sexp-element-flag. + +The file TUTORIAL has been replaced by nxml-mode.info; this is in info +format and can be read using Emacs. The source is maintained in a +simple, ad-hoc XML format. + +20030915 +-------- + +XML encodings should now work properly. When saving a buffer, +nxml-mode arranges to use the encoding declared in the XML +declaration. If there is no encoding declared, then nxml-mode will +use utf-8 or utf-16 according to the user options +`nxml-prefer-utf-16-to-utf-8-flag' and +`nxml-prefer-utf-16-little-to-big-endian-flag'. If the chosen encoding +cannot encode all the characters in the buffer, nxml-mode will +complain and give the user an opportunity to use an encoding that can. + +A new command C-c C-x inserts an XML declaration. + +The option `nxml-auto-insert-xml-declaration-flag' automatically +inserts an XML declaration in new files. + +The `nxml-default-buffer-file-coding-system' option allows a different +default buffer-file-coding-system for nXML mode buffers. This affects +what XML declaration is inserted. + +Encoding names in XML declarations are now validated by +rng-validate-mode. + +RDF/XML schema was updated to version in 05 September 2003 WD. + +20030912 +-------- + +The tutorial has a new section on inserting end-tags. + +By default to close the start-tag of an +inline-level element. After inserting the >, it will insert the +end-tag and leave point before the end-tag. The `i' is supposed to be +mnemonic for `inline'. C-c C-b is similar, but for block elements: the +start-tag, point and the end-tag will all be on separate lines. + +The binding for inserting an end-tag has changed from C-c / to C-c C-f +to comply with Emacs guidelines about what keys major modes should +bind. The `f' is supposed to be mnemonic for `finish'. + +Completion always puts point after all the characters it inserts. It +doesn't insert a `>' after completing a start-tag name. + +Completion no longer completes CDATA section and comment delimiters. + +The nxml-start-auto-coding command enables auto-detection of a file's +encoding as specified in the XML Recommendation for files that use +nxml-mode; rng-auto.el calls this. + +20030906 +-------- + +Validation messages applicable to point are displayed automatically. + +Completion can deal with prefixes that haven't yet been declared. + +rng-preferred-prefix-alist variable added. + +Namespace URIs can be completed. + +xmlns and xmlns:* attributes can be completed. + +CDATA section and comment delimiters can be completed. + +Each kind of completion has its own history. + +Completion function moved to nxml-mode; uses a hook to allow +schema-sensitive completion. Completion function bound to C-return. +Also bound to M-TAB as before, unless +nxml-bind-meta-tab-to-complete-flag is nil. When there is a window +system, nxml-bind-meta-tab-to-complete-flag is nil by default, This +avoid problems with M-TAB, which is not passed through by several +window systems/managers. + +TUTORIAL file added. + +NEWS file added. + +Bug fixes. + +20030901 +-------- + +Initial release. diff --git a/lisp/nxml/Makefile b/lisp/nxml/Makefile deleted file mode 100644 index 13eee93a0e8..00000000000 --- a/lisp/nxml/Makefile +++ /dev/null @@ -1,80 +0,0 @@ -EXTRA=README NEWS VERSION TODO COPYING Makefile rng-auto.el \ - nxml-mode.xml nxml-mode.rnc nxml-mode.texi nxml-mode.info dir \ - test.valid.xml test.invalid.xml - -SRC=nxml-rap.el nxml-outln.el nxml-mode.el nxml-parse.el nxml-enc.el \ - nxml-uchnm.el nxml-glyph.el nxml-maint.el nxml-util.el nxml-ns.el \ - rng-dt.el rng-valid.el rng-pttrn.el rng-xsd.el rng-cmpct.el \ - rng-match.el rng-nxml.el rng-util.el rng-loc.el rng-uri.el \ - rng-parse.el rng-maint.el xsd-regexp.el xmltok.el - -ELC=nxml-rap.elc nxml-outln.elc nxml-mode.elc nxml-parse.elc nxml-enc.elc \ - nxml-uchnm.elc nxml-glyph.elc nxml-maint.elc nxml-util.elc nxml-ns.elc \ - rng-dt.elc rng-valid.elc rng-pttrn.elc rng-xsd.elc rng-cmpct.elc \ - rng-match.elc rng-nxml.elc rng-util.elc rng-loc.elc rng-uri.elc \ - rng-parse.elc rng-maint.elc xsd-regexp.elc xmltok.elc - -FILESTOCLEAN=stamp-byte-compile $(ELC) VERSION TAGS \ - nxml-mode.texi nxml-mode.info dir - -EMACS=emacs -ETAGS=etags -MAKEINFO=makeinfo -INSTALL-INFO=install-info -PACKAGE=nxml-mode - -stamp-byte-compile: $(SRC) - -rm -f $(ELC) - $(EMACS) -batch -l rng-auto.el -f rng-byte-compile-load - touch $(@) - -all: stamp-byte-compile nxml-mode.info - -dir: nxml-mode.info - rm -f $@ - $(INSTALL-INFO) $< $@ - -info: nxml-mode.info - -nxml-mode.info: nxml-mode.texi - $(MAKEINFO) $< - -nxml-mode.texi: nxml-mode.xml - $(EMACS) -batch -l rng-auto.el -f rng-format-manual - -VERSION: stamp-byte-compile rng-auto.el - $(EMACS) -batch -l rng-auto.el -f rng-write-version - -TAGS: $(SRC) - $(ETAGS) $(SRC) - -dist: stamp-byte-compile $(EXTRA) - @version=`cat VERSION`; \ - set -e; \ - echo Making $(PACKAGE)-$$version.tar.gz; \ - rm -fr $(PACKAGE)-$$version; \ - mkdir $(PACKAGE)-$$version; \ - cd $(PACKAGE)-$$version; \ - for f in $(EXTRA) $(SRC) $(ELC); do \ - ln -s ../$$f .; \ - done; \ - mkdir schema; \ - cd schema; \ - for f in ../../schema/*.rnc ../../schema/*.xml; do \ - ln -s $$f .; \ - done; \ - cd ..; \ - mkdir char-name; \ - mkdir char-name/unicode; \ - cd char-name/unicode; \ - for f in ../../../char-name/unicode/*-*.el; do \ - ln -s $$f .; \ - done; \ - cd ../../..; \ - tar cfhz $(PACKAGE)-$$version.tar.gz $(PACKAGE)-$$version; \ - rm -fr $(PACKAGE)-$$version - -clean: - -rm -f $(FILESTOCLEAN) - -.PHONY: all clean info diff --git a/lisp/nxml/NEWS b/lisp/nxml/NEWS deleted file mode 100644 index cebbab82fda..00000000000 --- a/lisp/nxml/NEWS +++ /dev/null @@ -1,199 +0,0 @@ -20041004 --------- - -Support for outlining has been added. See the manual for more details. - -C-u C-c C-n goes to the first error. - -20040910 --------- - -C-c RET splits the current element as in PSGML. - -20040908 --------- - -Indentation has been rewritten. Indentation of attribute names and -values should work better. The default value of -`nxml-attribute-indent' has been changed to 4. - -Syntax highlighting with a dark background should now work. - -20040726 --------- - -The attribute pathSuffix on the uri element in schema locating files -has been replaced by a more general pattern attribute. The -transformURI element now has required fromPattern and toPattern -attributes. - -The schema related bindings have been changed to use C-c C-s as a prefix -as follows: - - C-c C-s => C-c C-s C-f (f for file) - C-c C-a => C-c C-s C-a - C-c C-t => C-c C-s C-t - C-c C-l => C-c C-s C-l - C-c C-w => C-c C-s C-w - -There's now an XML menu on the menu-bar. - -20031031 --------- - -C-c C-d "dynamically" chooses a tag to put around the word before -point, rather like M-/. - -The mechanism for locating the schema has changed completely. The new -mechanism is described in the manual. Any existing customizations of -`rng-auto-element-alist' or `rng-auto-file-name-alist' will no longer -be effective. - -C-c C-a is now bound to rng-auto-set-schema. - -20031018 --------- - -Unicode names can be used to insert characters with the new command -C-c C-u. Normally, this inserts a character reference. With a prefix -arg (i.e. C-u C-c C-u), it inserts the character directly. You can -customize `nxml-enabled-unicode-blocks' to control what Unicode blocks -are used for completing names. - -Extra information is displayed for character references. The Unicode -name is displayed in a tooltip. A glyph for the referenced character -is displayed in a distinguished face following the character -reference; this can be disabled by customizing -`nxml-char-ref-display-glyph-flag'. The command -`nxml-toggle-char-ref-extra-display' dynamically toggles the display -of extra information for character references for a particular buffer. -This can be used if the display of extra information is causing -performance problems. nXML mode tries to figure out which glyphs can -be displayed. Unfortunately Emacs doesn't provide the primitives -necessary to do this properly, so nXML mode has to guess and will -sometimes guess wrong. The hook `nxml-glyph-set-hook' can be used to -change nXML mode's guess. - -New command C-c C-w says what schema is being used. - -C-c C-s now turns on validation if it is not already on. - -20030928 --------- - -M-q has been implemented so that it works reasonably with XML. Other -paragraph-related commands (M-{, M-}, M-h) have also been implemented. - -New command M-x rng-auto-set-schema to set the schema based on the -buffer's current contents and file-name. This is called automatically -when rng-validate-mode is first enabled. - -There's now a C-M-d to go with C-M-u. C-M-d moves forward down into -the content of an element. C-M-n and C-M-p move to the next or -previous element. - -By default, the sexp commands (C-M-f, C-M-b, C-M-k, C-M-SPC) operate -on tags rather than elements. To restore the old behaviour, -customize nxml-sexp-element-flag. - -The file TUTORIAL has been replaced by nxml-mode.info; this is in info -format and can be read using Emacs. The source is maintained in a -simple, ad-hoc XML format. - -20030915 --------- - -XML encodings should now work properly. When saving a buffer, -nxml-mode arranges to use the encoding declared in the XML -declaration. If there is no encoding declared, then nxml-mode will -use utf-8 or utf-16 according to the user options -`nxml-prefer-utf-16-to-utf-8-flag' and -`nxml-prefer-utf-16-little-to-big-endian-flag'. If the chosen encoding -cannot encode all the characters in the buffer, nxml-mode will -complain and give the user an opportunity to use an encoding that can. - -A new command C-c C-x inserts an XML declaration. - -The option `nxml-auto-insert-xml-declaration-flag' automatically -inserts an XML declaration in new files. - -The `nxml-default-buffer-file-coding-system' option allows a different -default buffer-file-coding-system for nXML mode buffers. This affects -what XML declaration is inserted. - -Encoding names in XML declarations are now validated by -rng-validate-mode. - -RDF/XML schema was updated to version in 05 September 2003 WD. - -20030912 --------- - -The tutorial has a new section on inserting end-tags. - -By default to close the start-tag of an -inline-level element. After inserting the >, it will insert the -end-tag and leave point before the end-tag. The `i' is supposed to be -mnemonic for `inline'. C-c C-b is similar, but for block elements: the -start-tag, point and the end-tag will all be on separate lines. - -The binding for inserting an end-tag has changed from C-c / to C-c C-f -to comply with Emacs guidelines about what keys major modes should -bind. The `f' is supposed to be mnemonic for `finish'. - -Completion always puts point after all the characters it inserts. It -doesn't insert a `>' after completing a start-tag name. - -Completion no longer completes CDATA section and comment delimiters. - -The nxml-start-auto-coding command enables auto-detection of a file's -encoding as specified in the XML Recommendation for files that use -nxml-mode; rng-auto.el calls this. - -20030906 --------- - -Validation messages applicable to point are displayed automatically. - -Completion can deal with prefixes that haven't yet been declared. - -rng-preferred-prefix-alist variable added. - -Namespace URIs can be completed. - -xmlns and xmlns:* attributes can be completed. - -CDATA section and comment delimiters can be completed. - -Each kind of completion has its own history. - -Completion function moved to nxml-mode; uses a hook to allow -schema-sensitive completion. Completion function bound to C-return. -Also bound to M-TAB as before, unless -nxml-bind-meta-tab-to-complete-flag is nil. When there is a window -system, nxml-bind-meta-tab-to-complete-flag is nil by default, This -avoid problems with M-TAB, which is not passed through by several -window systems/managers. - -TUTORIAL file added. - -NEWS file added. - -Bug fixes. - -20030901 --------- - -Initial release. diff --git a/lisp/nxml/README b/lisp/nxml/README deleted file mode 100644 index 4f3fc96c0f4..00000000000 --- a/lisp/nxml/README +++ /dev/null @@ -1,106 +0,0 @@ -This is a new major mode for GNU Emacs for editing XML documents. It -supports editing well-formed XML documents and also provides -schema-sensitive editing of XML documents using RELAX NG Compact -Syntax. - -To use this, you need GNU Emacs version 21.x, preferably 21.3. GNU -Emacs version 20 will not work properly, nor will XEmacs. - -To get started, do - - M-x load-file rng-auto.el - -This defines the necessary autoloads. Now, visit a file containing -an XML document, and do - - M-x nxml-mode - -Now do - - C-h m - -for information on how to use nxml-mode. - -The beginnings of a manual are in nxml-mode.info. You can read this -using - - C-u M-x info RET nxml-mode.info RET - -It's also installed as an entry at the end of the top-level info -directory. So you can read it with C-h i as usual. - -You can use test.valid.xml and test.invalid.xml as examples of valid -and invalid XML documents. - -To get things automatically loaded each time you start Emacs, add - - (load "~/nxml-mode-200YMMDD/rng-auto.el") - -to your .emacs, where ~/nxml-mode-200YMMDD is the directory containing -the .elc files. Note that rng-auto.el does not load all of the -nxml-mode code; it merely sets things up so that all the features of -nxml-mode will be autoloaded properly. You should not try to autoload -rng-auto.el itself. - -To use nxml-mode automatically for files with an extension of xml, -xsl, rng or xhtml, add - - (setq auto-mode-alist - (cons '("\\.\\(xml\\|xsl\\|rng\\|xhtml\\)\\'" . nxml-mode) - auto-mode-alist)) - -to your .emacs. - -If you edit XML using iso-8859-N encodings other than iso-8859-1 and -you are running Emacs 21.3 or later, then I recommend enabling -unify-8859-on-decoding-mode, by adding - - (unify-8859-on-decoding-mode) - -to you .emacs. - -To get validation and schema-sensitive editing, you need a RELAX NG -Compact Syntax (RNC) schema for you document. The schema directory -includes some schemas for popular document types. - -For more on RELAX NG, see - - http://relaxng.org - -For a tutorial on RELAX NG Compact Syntax, see - - http://relaxng.org/compact-tutorial.html - -For automatically creating RNC schemas, I recommend my Trang program: - - http://www.thaiopensource.com/relaxng/trang.html - -You can use this to - -- infer an RNC schema from an instance document; - -- convert a DTD to an RNC schema; - -- convert a RELAX NG XML syntax schema to an RNC schema. - -To convert a RELAX NG XML syntax (.rng) schema to a RNC schema, you -can also use the XSLT stylesheet from - - http://www.pantor.com/download.html - -To convert a W3C XML Schema to an RNC schema, you need first to -convert it to RELAX NG XML syntax using Sun's RELAX NG converter tool -rngconv (built on top of MSV). See - - https://msv.dev.java.net/ - -The file NEWS describes recent changes. - -Please use the list - - http://groups.yahoo.com/group/emacs-nxml-mode/ - -for bug reports, discussion. I will announce all new versions there. - -James Clark -http://www.jclark.com/contact.html