mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-29 11:02:01 +00:00
866 lines
31 KiB
Plaintext
866 lines
31 KiB
Plaintext
\input texinfo @c -*- texinfo -*-
|
|
@c %**start of header
|
|
@setfilename ../../info/nxml-mode
|
|
@settitle nXML Mode
|
|
@c %**end of header
|
|
|
|
@copying
|
|
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.
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 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.
|
|
|
|
(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.''
|
|
|
|
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
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* nXML Mode: (nxml-mode). XML editing mode with RELAX NG support.
|
|
@end direntry
|
|
|
|
@node Top
|
|
@top nXML Mode
|
|
|
|
@insertcopying
|
|
|
|
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
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<h@point{}
|
|
@end example
|
|
|
|
@noindent
|
|
and the schema is XHTML. In this context, the symbol to be completed
|
|
is @samp{h}. The possible completions consist of just
|
|
@samp{head}. Another example, is
|
|
|
|
@example
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<@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
|
|
<html xmlns="@point{}
|
|
@end example
|
|
|
|
@noindent
|
|
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
|
|
on what the set of possible completions are.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If the set of completions is empty, nothing
|
|
happens.
|
|
@item
|
|
If there is one possible completion, then that completion is
|
|
inserted, together with any following characters that are
|
|
required. For example, in this case:
|
|
|
|
@example
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<@point{}
|
|
@end example
|
|
|
|
@noindent
|
|
@kbd{C-@key{RET}} will yield
|
|
|
|
@example
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head@point{}
|
|
@end example
|
|
@item
|
|
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:
|
|
|
|
@example
|
|
<html x@point{}
|
|
@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:
|
|
|
|
@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.
|
|
@item
|
|
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 it contains:
|
|
|
|
@example
|
|
<html xml@point{}
|
|
@end example
|
|
|
|
@noindent
|
|
Emacs will prompt you in the minibuffer with
|
|
|
|
@example
|
|
Attribute: xml@point{}
|
|
@end example
|
|
|
|
@noindent
|
|
and the buffer showing possible completions will contain
|
|
|
|
@example
|
|
Possible completions are:
|
|
xml:lang xmlns
|
|
@end example
|
|
|
|
@noindent
|
|
If you input @kbd{xmlns}, the result will be:
|
|
|
|
@example
|
|
<html xmlns="@point{}
|
|
@end example
|
|
|
|
@noindent
|
|
(If you do @kbd{C-@key{RET}} 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
|
|
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.
|
|
|
|
@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,
|
|
then input the content and finally input the end-tag. The @samp{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 @kbd{C-c C-i}. This inserts a @samp{>}, then inserts
|
|
the end-tag and leaves point before the end-tag. @kbd{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 @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
|
|
|
|
@display
|
|
@kbd{M-x customize-variable @key{RET} nxml-slash-auto-complete-flag @key{RET}}
|
|
@end display
|
|
|
|
@noindent
|
|
and then following the instructions in the displayed buffer.
|
|
|
|
@node Paragraphs
|
|
@chapter Paragraphs
|
|
|
|
Emacs has several commands that operate on paragraphs, most
|
|
notably @kbd{M-q}. nXML mode redefines these to work in a way
|
|
that is useful for XML. The exact rules that are used to find the
|
|
beginning and end of a paragraph are complicated; they are designed
|
|
mainly to ensure that @kbd{M-q} does the right thing.
|
|
|
|
A paragraph consists of one or more complete, consecutive lines.
|
|
A group of lines is not considered a paragraph unless it contains some
|
|
non-whitespace characters between tags or inside comments. A blank
|
|
line separates paragraphs. A single tag on a line by itself also
|
|
separates paragraphs. More precisely, if one tag together with any
|
|
leading and trailing whitespace completely occupy one or more lines,
|
|
then those lines will not be included in any paragraph.
|
|
|
|
A start-tag at the beginning of the line (possibly indented) may
|
|
be treated as starting a paragraph. Similarly, an end-tag at the end
|
|
of the line may be treated as ending a paragraph. The following rules
|
|
are used to determine whether such a tag is in fact treated as a
|
|
paragraph boundary:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If the schema does not allow text at that point, then it
|
|
is a paragraph boundary.
|
|
@item
|
|
If the end-tag corresponding to the start-tag is not at
|
|
the end of its line, or the start-tag corresponding to the end-tag is
|
|
not at the beginning of its line, then it is not a paragraph
|
|
boundary. For example, in
|
|
|
|
@example
|
|
<p>This is a paragraph with an
|
|
<emph>emphasized</emph> phrase.
|
|
@end example
|
|
|
|
@noindent
|
|
the @samp{<emph>} start-tag would not be considered as
|
|
starting a paragraph, because its corresponding end-tag is not at the
|
|
end of the line.
|
|
@item
|
|
If there is text that is a sibling in element tree, then
|
|
it is not a paragraph boundary. For example, in
|
|
|
|
@example
|
|
<p>This is a paragraph with an
|
|
<emph>emphasized phrase that takes one source line</emph>
|
|
@end example
|
|
|
|
@noindent
|
|
the @samp{<emph>} start-tag would not be considered as
|
|
starting a paragraph, even though its end-tag is at the end of its
|
|
line, because there the text @samp{This is a paragraph with an}
|
|
is a sibling of the @samp{emph} element.
|
|
@item
|
|
Otherwise, it is a paragraph boundary.
|
|
@end itemize
|
|
|
|
@node Outlining
|
|
@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
|
|
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
|
|
child element. A section also contains its subordinate sections (its
|
|
subsections). The text content of a section consists of anything in a
|
|
section that is neither a subsection nor a heading.
|
|
|
|
Note that this is a different model from that used by XHTML.
|
|
nXML mode's outline support will not be useful for XHTML unless you
|
|
adopt a convention of adding a @code{div} to enclose each
|
|
section, rather than having sections implicitly delimited by different
|
|
@code{h@var{n}} elements. This limitation may be removed
|
|
in a future version.
|
|
|
|
The variable @code{nxml-section-element-name-regexp} gives
|
|
a regexp for the local names (i.e. the part of the name following any
|
|
prefix) of section elements. The variable
|
|
@code{nxml-heading-element-name-regexp} gives a regexp for the
|
|
local names of heading elements. For an element to be recognized
|
|
as a section
|
|
|
|
@itemize @bullet
|
|
@item
|
|
its start-tag must occur at the beginning of a line
|
|
(possibly indented);
|
|
@item
|
|
its local name must match
|
|
@code{nxml-section-element-name-regexp};
|
|
@item
|
|
either its first child element or a descendant of that
|
|
first child element must have a local name that matches
|
|
@code{nxml-heading-element-name-regexp}; the first such element
|
|
is treated as the section's heading.
|
|
@end itemize
|
|
|
|
@noindent
|
|
You can customize these variables using @kbd{M-x
|
|
customize-variable}.
|
|
|
|
There are three possible outline states for a section:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
normal, showing everything, including its heading, text
|
|
content and subsections; each subsection is displayed according to the
|
|
state of that subsection;
|
|
@item
|
|
showing just its heading, with both its text content and
|
|
its subsections hidden; all subsections are hidden regardless of their
|
|
state;
|
|
@item
|
|
showing its heading and its subsections, with its text
|
|
content hidden; each subsection is displayed according to the state of
|
|
that subsection.
|
|
@end itemize
|
|
|
|
In the last two states, where the text content is hidden, the
|
|
heading is displayed specially, in an abbreviated form. An element
|
|
like this:
|
|
|
|
@example
|
|
<section>
|
|
<title>Food</title>
|
|
<para>There are many kinds of food.</para>
|
|
</section>
|
|
@end example
|
|
|
|
@noindent
|
|
would be displayed on a single line like this:
|
|
|
|
@example
|
|
<-section>Food...</>
|
|
@end example
|
|
|
|
@noindent
|
|
If there are hidden subsections, then a @code{+} will be used
|
|
instead of a @code{-} like this:
|
|
|
|
@example
|
|
<+section>Food...</>
|
|
@end example
|
|
|
|
@noindent
|
|
If there are non-hidden subsections, then the section will instead be
|
|
displayed like this:
|
|
|
|
@example
|
|
<-section>Food...
|
|
<-section>Delicious Food...</>
|
|
<-section>Distasteful Food...</>
|
|
</-section>
|
|
@end example
|
|
|
|
@noindent
|
|
The heading is always displayed with an indent that corresponds to its
|
|
depth in the outline, even it is not actually indented in the buffer.
|
|
The variable @code{nxml-outline-child-indent} controls how much
|
|
a subheading is indented with respect to its parent heading when the
|
|
heading is being displayed specially.
|
|
|
|
Commands to change the outline state of sections are bound to
|
|
key sequences that start with @kbd{C-c C-o} (@kbd{o} is
|
|
mnemonic for outline). The third and final key has been chosen to be
|
|
consistent with outline mode. In the following descriptions
|
|
current section means the section containing point, or, more precisely,
|
|
the innermost section containing the character immediately following
|
|
point.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@kbd{C-c C-o C-a} shows all sections in the buffer
|
|
normally.
|
|
@item
|
|
@kbd{C-c C-o C-t} hides the text content
|
|
of all sections in the buffer.
|
|
@item
|
|
@kbd{C-c C-o C-c} hides the text content
|
|
of the current section.
|
|
@item
|
|
@kbd{C-c C-o C-e} shows the text content
|
|
of the current section.
|
|
@item
|
|
@kbd{C-c C-o C-d} hides the text content
|
|
and subsections of the current section.
|
|
@item
|
|
@kbd{C-c C-o C-s} shows the current section
|
|
and all its direct and indirect subsections normally.
|
|
@item
|
|
@kbd{C-c C-o C-k} shows the headings of the
|
|
direct and indirect subsections of the current section.
|
|
@item
|
|
@kbd{C-c C-o C-l} hides the text content of the
|
|
current section and of its direct and indirect
|
|
subsections.
|
|
@item
|
|
@kbd{C-c C-o C-i} shows the headings of the
|
|
direct subsections of the current section.
|
|
@item
|
|
@kbd{C-c C-o C-o} hides as much as possible without
|
|
hiding the current section's text content; the headings of ancestor
|
|
sections of the current section and their child section sections will
|
|
not be hidden.
|
|
@end itemize
|
|
|
|
When a heading is displayed specially, you can use
|
|
@key{RET} in that heading to show the text content of the section
|
|
in the same way as @kbd{C-c C-o C-e}.
|
|
|
|
You can also use the mouse to change the outline state:
|
|
@kbd{S-mouse-2} hides the text content of a section in the same
|
|
way as@kbd{C-c C-o C-c}; @kbd{mouse-2} on a specially
|
|
displayed heading shows the text content of the section in the same
|
|
way as @kbd{C-c C-o C-e}; @kbd{mouse-1} on a specially
|
|
displayed start-tag toggles the display of subheadings on and
|
|
off.
|
|
|
|
The outline state for each section is stored with the first
|
|
character of the section (as a text property). Every command that
|
|
changes the outline state of any section updates the display of the
|
|
buffer so that each section is displayed correctly according to its
|
|
outline state. If the section structure is subsequently changed, then
|
|
it is possible for the display to no longer correctly reflect the
|
|
stored outline state. @kbd{C-c C-o C-r} can be used to refresh
|
|
the display so it is correct again.
|
|
|
|
@node Locating a schema
|
|
@chapter Locating a schema
|
|
|
|
nXML mode has a configurable set of rules to locate a schema for
|
|
the file being edited. The rules are contained in one or more schema
|
|
locating files, which are XML documents.
|
|
|
|
The variable @samp{rng-schema-locating-files} specifies
|
|
the list of the file-names of schema locating files that nXML mode
|
|
should use. The order of the list is significant: when file
|
|
@var{x} occurs in the list before file @var{y} then rules
|
|
from file @var{x} have precedence over rules from file
|
|
@var{y}. A filename specified in
|
|
@samp{rng-schema-locating-files} may be relative. If so, it will
|
|
be resolved relative to the document for which a schema is being
|
|
located. It is not an error if relative file-names in
|
|
@samp{rng-schema-locating-files} do not exist. You can use
|
|
@kbd{M-x customize-variable @key{RET} rng-schema-locating-files
|
|
@key{RET}} to customize the list of schema locating
|
|
files.
|
|
|
|
By default, @samp{rng-schema-locating-files} list has two
|
|
members: @samp{schemas.xml}, and
|
|
@samp{@var{dist-dir}/schema/schemas.xml} where
|
|
@samp{@var{dist-dir}} is the directory containing the nXML
|
|
distribution. The first member will cause nXML mode to use a file
|
|
@samp{schemas.xml} in the same directory as the document being
|
|
edited if such a file exist. The second member contains rules for the
|
|
schemas that are included with the nXML distribution.
|
|
|
|
@menu
|
|
* Commands for locating a schema::
|
|
* Schema locating files::
|
|
@end menu
|
|
|
|
@node Commands for locating a schema
|
|
@section Commands for locating a schema
|
|
|
|
The command @kbd{C-c C-s C-w} will tell you what schema
|
|
is currently being used.
|
|
|
|
The rules for locating a schema are applied automatically when
|
|
you visit a file in nXML mode. However, if you have just created a new
|
|
file and the schema cannot be inferred from the file-name, then this
|
|
will not locate the right schema. In this case, you should insert the
|
|
start-tag of the root element and then use the command @kbd{C-c C-s
|
|
C-a}, which reapplies the rules based on the current content of
|
|
the document. It is usually not necessary to insert the complete
|
|
start-tag; often just @samp{<@var{name}} is
|
|
enough.
|
|
|
|
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
|
|
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
|
|
associates the document with the selected schema. The rule will be
|
|
added to the first file in the list specified
|
|
@samp{rng-schema-locating-files}; it will create the file if
|
|
necessary, but will not create a directory. If the variable
|
|
@samp{rng-schema-locating-files} has not been customized, this
|
|
means that the rule will be added to the file @samp{schemas.xml}
|
|
in the same directory as the document being edited.
|
|
|
|
The command @kbd{C-c C-s C-t} allows you to select a schema by
|
|
specifying an identifier for the type of the document. The schema
|
|
locating files determine the available type identifiers and what
|
|
schema is used for each type identifier. This is useful when it is
|
|
impossible to infer the right schema from either the file-name or the
|
|
content of the document, even though the schema is already in the
|
|
schema locating file. A situation in which this can occur is when
|
|
there are multiple variants of a schema where all valid documents have
|
|
the same document element. For example, XHTML has Strict and
|
|
Transitional variants. In a situation like this, a schema locating file
|
|
can define a type identifier for each variant. As with @kbd{C-c
|
|
C-s C-f}, Emacs will ask whether you wish to add a rule to a schema
|
|
locating file that persistently associates the document with the
|
|
specified type identifier.
|
|
|
|
The command @kbd{C-c C-s C-l} adds a rule to a schema
|
|
locating file that persistently associates the document with
|
|
the schema that is currently being used.
|
|
|
|
@node Schema locating files
|
|
@section Schema locating files
|
|
|
|
Each schema locating file specifies a list of rules. The rules
|
|
from each file are appended in order. To locate a schema each rule is
|
|
applied in turn until a rule matches. The first matching rule is then
|
|
used to determine the schema.
|
|
|
|
Schema locating files are designed to be useful for other
|
|
applications that need to locate a schema for a document. In fact,
|
|
there is nothing specific to locating schemas in the design; it could
|
|
equally well be used for locating a stylesheet.
|
|
|
|
@menu
|
|
* Schema locating file syntax basics::
|
|
* Using the document's URI to locate a schema::
|
|
* Using the document element to locate a schema::
|
|
* Using type identifiers in schema locating files::
|
|
* Using multiple schema locating files::
|
|
@end menu
|
|
|
|
@node Schema locating file syntax basics
|
|
@subsection Schema locating file syntax basics
|
|
|
|
There is a schema for schema locating files in the file
|
|
@samp{locate.rnc} in the schema directory. Schema locating
|
|
files must be valid with respect to this schema.
|
|
|
|
The document element of a schema locating file must be
|
|
@samp{locatingRules} and the namespace URI must be
|
|
@samp{http://thaiopensource.com/ns/locating-rules/1.0}. The
|
|
children of the document element specify rules. The order of the
|
|
children is the same as the order of the rules. Here's a complete
|
|
example of a schema locating file:
|
|
|
|
@example
|
|
<?xml version="1.0"?>
|
|
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
|
|
<namespace ns="http://www.w3.org/1999/xhtml" uri="xhtml.rnc"/>
|
|
<documentElement localName="book" uri="docbook.rnc"/>
|
|
</locatingRules>
|
|
@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
|
|
<uri resource="spec.xml" uri="docbook.rnc"/>
|
|
@end example
|
|
|
|
@noindent
|
|
specifies 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
|
|
<uri pattern="*.xsl" uri="xslt.rnc"/>
|
|
@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
|
|
<transformURI fromPattern="*.xml" toPattern="*.rnc"/>
|
|
@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
|
|
<documentElement prefix="xsl" localName="stylesheet" uri="xslt.rnc"/>
|
|
@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
|
|
<namespace ns="http://www.w3.org/1999/XSL/Transform" uri="xslt.rnc"/>
|
|
@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
|
|
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
|
|
<namespace ns="http://www.w3.org/1999/xhtml" typeId="XHTML"/>
|
|
<typeId id="XHTML" typeId="XHTML Strict"/>
|
|
<typeId id="XHTML Strict" uri="xhtml-strict.rnc"/>
|
|
<typeId id="XHTML Transitional" uri="xhtml-transitional.rnc"/>
|
|
</locatingRules>
|
|
@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
|
|
<namespace ns="http://www.w3.org/1999/xhtml" uri="xhtml-strict.rnc"/>
|
|
@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
|
|
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
|
|
<typeId id="XHTML" typeId="XHTML Transitional"/>
|
|
</locatingRules>
|
|
@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
|
|
<include rules="../rules.xml"/>
|
|
@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
|
|
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
|
|
<namespace ns="http://www.w3.org/1999/xhtml" uri="xhtml.rnc"/>
|
|
</locatingRules>
|
|
@end example
|
|
|
|
@noindent
|
|
followed by a public file
|
|
|
|
@example
|
|
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
|
|
<transformURI pathSuffix=".xml" replacePathSuffix=".rnc"/>
|
|
<namespace ns="http://www.w3.org/1999/XSL/Transform" typeId="XSLT"/>
|
|
</locatingRules>
|
|
@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
|
|
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
|
|
<applyFollowingRules ruleType="transformURI"/>
|
|
<namespace ns="http://www.w3.org/1999/xhtml" uri="xhtml.rnc"/>
|
|
</locatingRules>
|
|
@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
|
|
|
|
@ignore
|
|
arch-tag: 3b6e8ac2-ae8d-4f38-bd43-ce9f80be04d6
|
|
@end ignore
|