@c %**end of header
@copying
-This manual documents nxml-mode, an Emacs major mode for editing
+This manual documents nXML mode, an Emacs major mode for editing
XML with RELAX NG support.
-Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+Copyright @copyright{} 2007-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs editing modes
@direntry
* nXML Mode: (nxml-mode). XML editing mode with RELAX NG support.
@end direntry
This manual is not yet complete.
@menu
+* Introduction::
* Completion::
* Inserting end-tags::
* Paragraphs::
* Limitations::
@end menu
+@node Introduction
+@chapter Introduction
+
+nXML mode is an Emacs major-mode for editing XML documents. It supports
+editing well-formed XML documents, and provides schema-sensitive editing
+using RELAX NG Compact Syntax. To get started, visit a file containing an
+XML document, and, if necessary, use @kbd{M-x nxml-mode} to switch to nXML
+mode. By default, @code{auto-mode-alist} and @code{magic-fallback-alist}
+put buffers in nXML mode if they have recognizable XML content or file
+extensions. You may wish to customize the settings, for example to
+recognize different file extensions.
+
+Once in nXML mode, you can type @kbd{C-h m} for basic information on the
+mode.
+
+The @file{etc/nxml} directory in the Emacs distribution contains some data
+files used by nXML mode, and includes two files (@file{test-valid.xml} and
+@file{test-invalid.xml}) that provide examples of valid and invalid XML
+documents.
+
+To get validation and schema-sensitive editing, you need a RELAX NG Compact
+Syntax (RNC) schema for your document (@pxref{Locating a schema}). The
+@file{etc/schema} directory includes some schemas for popular document
+types. See @url{http://relaxng.org/} for more information on RELAX NG.
+You can use the @samp{Trang} program from
+@url{http://www.thaiopensource.com/relaxng/trang.html} to
+automatically create RNC schemas. This program can:
+
+@itemize @bullet
+@item
+infer an RNC schema from an instance document;
+@item
+convert a DTD to an RNC schema;
+@item
+convert a RELAX NG XML syntax schema to an RNC schema.
+@end itemize
+
+@noindent To convert a RELAX NG XML syntax (@samp{.rng}) schema to a RNC
+one, you can also use the XSLT stylesheet from
+@url{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 the RELAX NG converter tool @code{rngconv}
+(built on top of MSV). See @url{https://github.com/kohsuke/msv}
+and @url{https://msv.dev.java.net/}.
+
+For historical discussions only, see the mailing list archives at
+@url{http://groups.yahoo.com/group/emacs-nxml-mode/}. Please make all new
+discussions on the @samp{help-gnu-emacs} and @samp{emacs-devel} mailing
+lists. Report any bugs with @kbd{M-x report-emacs-bug}.
+
+
@node Completion
@chapter Completion
-Apart from real-time validation, the most important feature that
-nxml-mode provides for assisting in document creation is "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
+nXML mode adapts the standard GNU Emacs command for completion in a
+buffer: @code{completion-at-point}, which is bound to @kbd{C-M-i} and
+@kbd{M-@key{TAB}}. Note that many window systems and window managers
+use @kbd{M-@key{TAB}} themselves (typically for switching between
+windows) and do not pass it to applications. In that case, you should
+type @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} for completion, or bind
+@code{completion-at-point} to a key that is convenient for you. In
+the following, I will assume that you type @kbd{C-M-i}.
+
+nXML mode 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{}
In this case, the symbol to be completed is empty, and the possible
completions are just @samp{http://www.w3.org/1999/xhtml}.
-When you type @kbd{C-@key{RET}}, what happens depends
+When you type @kbd{C-M-i}, what happens depends
on what the set of possible completions are.
@itemize @bullet
@end example
@noindent
-@kbd{C-@key{RET}} will yield
+@kbd{C-M-i} will yield
@example
<html xmlns="http://www.w3.org/1999/xhtml">
@end example
@noindent
-The symbol to be completed is @samp{x}. The possible completions
-are @samp{xmlns} and @samp{xml:lang}. These share a
-common prefix of @samp{xml}. Thus, @kbd{C-@key{RET}}
-will yield:
+The symbol to be completed is @samp{x}. The possible completions are
+@samp{xmlns} and @samp{xml:lang}. These share a common prefix of
+@samp{xml}. Thus, @kbd{C-M-i} will yield:
@example
<html xml@point{}
@end example
@noindent
-Typically, you would do @kbd{C-@key{RET}} again, which would
-have the result described in the next item.
+Typically, you would do @kbd{C-M-i} again, which would have the result
+described in the next item.
@item
If there is more than one possible completion, but the
possible completions do not share a non-empty prefix, then Emacs will
@example
Possible completions are:
-xml:lang xmlns
+xml:lang xmlns
@end example
@noindent
@end example
@noindent
-(If you do @kbd{C-@key{RET}} again, the namespace URI will
-be inserted. Should that happen automatically?)
+(If you do @kbd{C-M-i} again, the namespace URI will be
+inserted. Should that happen automatically?)
@end itemize
@node Inserting end-tags
@chapter Inserting end-tags
-The main redundancy in XML syntax is end-tags. nxml-mode provides
+The main redundancy in XML syntax is end-tags. nXML mode provides
several ways to make it easier to enter end-tags. You can use all of
these without a schema.
-You can use @kbd{C-@key{RET}} after @samp{</}
-to complete the rest of the end-tag.
+You can use @kbd{C-M-i} after @samp{</} to complete the rest of the
+end-tag.
@kbd{C-c C-f} inserts an end-tag for the element containing
point. This command is useful when you want to input the start-tag,
indented. The @samp{i} is mnemonic for inline and the
@samp{b} is mnemonic for block.
-Finally, you can customize nxml-mode so that @kbd{/}
-automatically inserts the rest of the end-tag when it occurs after
-@samp{<}, by doing
+Finally, you can customize nXML mode so that @kbd{/} automatically
+inserts the rest of the end-tag when it occurs after @samp{<}, by
+doing
@display
@kbd{M-x customize-variable @key{RET} nxml-slash-auto-complete-flag @key{RET}}
@chapter Outlining
nXML mode allows you to display all or part of a buffer as an
-outline, in a similar way to Emacs' outline mode. An outline in nXML
+outline, in a similar way to Emacs's outline mode. An outline in nXML
mode is based on recognizing two kinds of element: sections and
headings. There is one heading for every section and one section for
every heading. A section contains its heading as or within its first
If you want to use a schema that has not yet been added to the
schema locating files, you can use the command @kbd{C-c C-s C-f}
-to manually select the file contaiing the schema for the document in
+to manually select the file containing the schema for the document in
current buffer. Emacs will read the file-name of the schema from the
minibuffer. After reading the file-name, Emacs will ask whether you
wish to add a rule to a schema locating file that persistently
@node DTDs
@chapter DTDs
-nxml-mode is designed to support the creation of standalone XML
+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
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
+simultaneously get the benefits of validation and standalone XML
documents. Therefore, I recommend that you do not reference an
external DOCTYPE in your XML documents.
@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
-
-@ignore
- arch-tag: 3b6e8ac2-ae8d-4f38-bd43-ce9f80be04d6
-@end ignore
HCoop / bpt / emacs.git / blobdiff