This contains some notes on using nxml-mode.  Eventually, this will
turn into a proper manual.

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 M-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.  C-return (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 C-return when there's a window
system and M-TAB when there's not.  In the following, I will assume
that a window system is being used and will therefore refer to
C-return.

Completion works 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 -!-
indicates point):

<html xmlns="http://www.w3.org/1999/xhtml">
<h-!-

and the schema is XHTML.  In this context, the symbol to be completed
is "h".  The possible completions consist of just "head".  Another
example, is

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<-!-

In this case, the symbol to be completed is "", and the possible
completions are "base", "isindex", "link", "meta", "script", "style",
"title".  Another example is:

<html xmlns="-!-

In this case, the symbol to be completed is "", and the possible
completions are just "http://www.w3.org/1999/xhtml".

When you type C-return, what happens depends on what the set of
possible completions are.

(a) If it is empty, nothing happens.

(b) If there is one possible completion, then that completion is
inserted, together with any following characters that are
required. For example, in this case:

<html xmlns="http://www.w3.org/1999/xhtml">
<-!-

C-return will yield

<html xmlns="http://www.w3.org/1999/xhtml">
<head-!-

(c) If there is more than one possible completion, but all possible
completions share a common non-empty prefix, then that prefix is
inserted. For example, suppose the buffer is:

<html x-!-

The symbol to be completed is x. The possible completions
are "xmlns" and "xml:lang".  These share a common prefix of
"xml".  Thus, C-return will yield:

<html xml-!-

Typically, you would do C-return again, which would have the result
described in case (d).

(d) If there is more than one possible completion, but the possible
completions do not share a non-empty prefix, then Emacs will prompt
you to input the symbol in the minibuffer, initializing the minibuffer
with the symbol to be completed, and popping up a buffer showing the
possible completions.  You can now input the symbol to be inserted.
The symbol you input will be inserted in the buffer instead of the
symbol to be completed.  Emacs will then insert any required
characters after the symbol.  For example, if contains:

<html xml-!-

Emacs will prompt you in the minibuffer with

Attribute: xml-!-

and the buffer showing possible completions will contain

Possible completions are:
xml:lang			   xmlns

If you input "xmlns", the result will be:

<html xmlns="-!-

(If you do C-return again, the namespace URI will be inserted. Should
that happen automatically?)

Inserting end-tags
------------------

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 C-return after </ to complete the rest of the end-tag.

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, then input the
content and finally input the end-tag. The `f' is mnemonic for finish.

If you want to keep tags balanced and input the end-tag at the same
time as the start-tag, before inputting the content, then you can use
C-c C-i. This inserts a >, then inserts the end-tag and leaves point
before the end-tag.  C-c C-b is similar but more convenient for
block-level elements: it puts the start-tag, point and the end-tag on
successive lines, appropriately indented. The `i' is mnemonic for
inline and the `b' is mnemonic for block.

Finally, you can customize nxml-mode so that `/' automatically inserts
the rest of the end-tag when it occurs after `<', by doing

  M-x customize-variable RET nxml-slash-auto-complete-flag RET

and then following the instructions in the displayed buffer.

Finding a schema
----------------

Unlike DTDs, RELAX NG does not specify a way to find the schema for a
document.  With rng-validate-mode, the easiest way is to specify the
schema explicitly using

  C-c C-s SCHEMA.rnc RET

However, this is effective only for the current buffer and the current
session.

You can also specify rules to automatically find the schema.  There
are two lists of rules, one based on the file name of the buffer you
are editing and one based on the root element (more properly called
the document element) of the contents of the buffer. The rules in each
list are applied in order. The file-name-based rules are applied
first.  If they are not enough to find a schema, then the
root-element-based rules are used.  If they are still not enough, then
a built-in vacuous schema is used, which allows any well-formed XML
document.  Both of these lists of rules can be customized using Emacs'
customization facility. These customizations can be set for future
sessions as well as the current session.

To customize the file-name-based rules do:

  M-x customize-variable RET rng-auto-file-name-alist RET

and follow the instructions in the displayed buffer.

The file-name-based rules work by specifying a regular expression for
the buffer file name and a replacement to use for the part of the
buffer file name matched by the regular expression.  For example, a
rule might say, when the buffer file name matches:

  \`.*\.xsl\'

use a replacement of:

  /usr/local/share/schema/xslt.rnc

The buffer file name is searched for an occurrence of the regexp
without anchoring: \` means to match the beginning of the file name
and \' means to match the end of the file name. So this rule says to
use the schema /usr/local/share/schema/xslt.rnc for files with an
extension of ".xsl".

As with the Emacs query-replace-regexp command the "\" character has a
special meaning in the replacement: "\&" stands for the complete file
name matched by the regexp; \N where N is a digit matches what matched
the N-th subexpression (i.e. N-th "\(...\)") in the regexp.  So, for
example, a rule could specify that when the file name matches

  \`\(.*\).xml\'

a schema of

  \1.rnc

would be used.

There's an additional frill.  Instead of the replacement replacing the
everything matched by the regexp, you can specify that the replacement
should replace only the part matched by the Nth subexpression.  Thus
an alternative way of specifying this rule is to specify that when the
file name matches

  \.\(xml\)\'

the 1st subexpression should be replaced by

  rnc

After the schema file name has been determined, Emacs checks whether
this file exists and is readable.  The rule will only be used if it
is.  Thus this rule allows you to specify a schema for a particular
.xml document just by creating a schema in the same directory and with
the same basename as the .xml document , but with an extension of
.rnc.  This rule is included by default.

This is particularly convenient in conjunction with the "external"
feature of RELAX NG.  Suppose for example, you have a directory
containing files chapter1.xml, chapter2.xml, chapter.rnc, and you want
to use the chapter.rnc file to validate the chapter1.xml and
chapter2.xml files.  You would create two additional files
chapter1.rnc and chapter2.rnc in the same directory (for a total of
five files). Both chapter1.rnc and chapter2.rnc would contain just the
line:

external "chapter.rnc"

If you have an OS that supports symbolic links, you could instead
simply make chapter1.rnc and chapter2.rnc be symbolic links pointing
to chapter.rnc.

To customize the root-element-based rules do:

  M-x customize-variable RET rng-auto-element-alist RET

and follow the instructions in the displayed buffer.

With the root-element-based rules, you can specify requirements for
the namespace URI, the local name and the prefix.  The local name is
the part of the element name after the colon or the entire element
name if it does not habe a colon.  The requirement can either require
a specific string or allow anything. Note that the specific strings
are not treated as a regular expression, and that "\" is not special
in the schema file name, and that the schema file name must exist.

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 declare the character entities in the internal DTD
subset of the document, for example:

<!DOCTYPE doc [
<!ENTITY mdash	"&#x2014;">
<!ENTITY hellip	"&#x2026;">
]>

It is rather tedious and error-prone to have to manually create these
entity declarations.  In a future version of nxml-mode, I plan to add
support for maintaining entity declarations in the internal DTD
subset, using a configurable list of entity sets (files containing
entity declarations).
