X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/e957f9ae90f3cab1584c06877cbff075d52a6a9a..4a970ff58d74df85f4c20b48c36edb5f58683cfe:/doc/misc/nxml-mode.texi

diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi
index d076f0dd82..b8b69da443 100644
--- a/doc/misc/nxml-mode.texi
+++ b/doc/misc/nxml-mode.texi
@@ -5,37 +5,40 @@
 @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--2014 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.
+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''.
 
 (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.
+modify this GNU manual.''
 @end quotation
 @end copying
 
-@dircategory Emacs
+@dircategory Emacs editing modes
 @direntry
 * nXML Mode: (nxml-mode).       XML editing mode with RELAX NG support.
 @end direntry
 
+
+@titlepage
+@title nXML mode
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+
 @node Top
 @top nXML Mode
 
@@ -52,6 +55,7 @@ This manual is not yet complete.
 * Locating a schema::
 * DTDs::
 * Limitations::
+* GNU Free Documentation License::  The license for this documentation.
 @end menu
 
 @node Introduction
@@ -70,14 +74,14 @@ 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
+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.
+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:
@@ -93,7 +97,11 @@ convert a RELAX NG XML syntax schema to an RNC schema.
 
 @noindent To convert a RELAX NG XML syntax (@samp{.rng}) schema to a RNC
 one, you can also use the XSLT stylesheet from
+@url{https://github.com/oleg-pavliv/emacs/tree/master/xsl}.
+@ignore
+@c Original location, now defunct.
 @url{http://www.pantor.com/download.html}.
+@end ignore
 
 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}
@@ -109,31 +117,25 @@ 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{}
@@ -145,7 +147,7 @@ indicates point):
 @end example
 
 @noindent
-and the schema is XHTML.  In this context, the symbol to be completed
+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
 
@@ -169,7 +171,7 @@ completions are @samp{base}, @samp{isindex},
 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
@@ -187,7 +189,7 @@ required. For example, in this case:
 @end example
 
 @noindent
-@kbd{C-@key{RET}} will yield
+@kbd{C-M-i} will yield
 
 @example
 <html xmlns="http://www.w3.org/1999/xhtml">
@@ -203,18 +205,17 @@ is inserted. For example, suppose the buffer is:
 @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
@@ -252,19 +253,19 @@ If you input @kbd{xmlns}, the result will be:
 @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,
@@ -280,9 +281,9 @@ 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
+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}}
@@ -296,7 +297,7 @@ and then following the instructions in the displayed buffer.
 
 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
+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.
 
@@ -355,7 +356,7 @@ Otherwise, it is a paragraph boundary.
 @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
@@ -363,7 +364,7 @@ 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.
+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
@@ -371,7 +372,7 @@ section, rather than having sections implicitly delimited by different
 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
+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
@@ -661,7 +662,7 @@ 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
+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
@@ -688,13 +689,13 @@ The @samp{pattern} attribute can be used instead of the
 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{/}).
+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,
+segment of the document's URI@. For example,
 
 @example
 <uri pattern="*.xsl" uri="xslt.rnc"/>
@@ -765,7 +766,7 @@ specifies that when the namespace URI of the document is
 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
+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
@@ -869,16 +870,16 @@ an @samp{applyFollowingRules} to the private file.
 @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
+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
+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.
 
@@ -907,5 +908,8 @@ The restrictions on RELAX NG schemas in section 7 of the RELAX NG
 specification are not enforced.
 @end itemize
 
-@bye
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
 
+@bye