| XML plugin user's guide | Version 2.8.5 (May 31 2013) |
Legal Notice
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
"Invariant Sections", "Front-Cover Texts" or
"Back-Cover Texts", each as defined in the license. A copy of
the license can be found in the file COPYING.DOC.txt
included with jEdit.
The XML plugin itself is released under the GNU General Public License. A copy of the GPL can be found in the jEdit online help.
This version of the XML plugin for jEdit combines the HtmlSideKick plugin and EcmaScript parser by Dale Anson, the JavaScriptSideKick by Martin Raspe, the CSS SideKick by Jakub Roztocil, and the XmlIndenter plugin by Robert McKinnon, providing five distinct Sidekick parsers and four different completion services, as well as an indenting service for the Beauty plugin, ISO-RELAX and jing-trang, for validation and translation of documents that use Relax-NG schemas.
Table of Contents
This documentation assumes at least basic knowlege of HTML and XML.
The XML plugin makes jEdit one of the most advanced free Website editing tools available. It combines parsers for XML, HTML, JSP, Sidekick, and CSS files. Here are its features:
On-the-fly validation of XML files with DTD, XSD, or RNG schemas.
Tag, attribute, and entity completion popups for XML, HTML and CSS
Display of the element tree in a dockable window, for XML, HTML, JavaScript, JSP, and CSS
Matching tag highlighting
One click insertion of tags and entities
Graphical form to edit tags and attributes
With a keystroke, jump to matching tag or bracket
And more.
To provide most of its functionality, the XML plugin relies on the SideKick plugin. What this means is that Sidekick must be enabled, and docked (preferably to your right or left) and parsing your current buffer in order for certain operations to succeed. Select Plugins - SideKick - SideKick, and click on the little arrow, which is the docking menu in the upper left corner, to set its docked position.
Note: Since the XML plugin provides a separate Sidekick parser for HTML versus XML, and it may be possible to parse some documents with both, you may get different results depending on how 'strict' the HTML/XML syntax is used in the document.
The XML plugin can take advantage of other plugins, in addition to the required ones like Sidekick.
If you want to follow hyperlinks in HTML or XML, you'll have to install the Hyperlinks plugin.
The XML plugin comes with templates for a few common HTML and XML document types (e.g. HTML 4.01 strict, XSD, and XSL. To use them, install the Templates plugin and restart jEdit.
>> displays the XML insert window. This window is floating by default, but it can be docked into the view from the dock menu (a little arrow in the upper right corner), or from the pane of the dialog box.
This window lists elements that may be inserted at the caret position, all declared entities, and all IDs (element attributes with a value type of ID).
Clicking an element in the list with the left mouse button will insert it into the buffer and show the dialog box for specifying attributes. See the section called “The edit tag dialog box” for information about the dialog box. Clicking an element with the right mouse button will insert it in the text area, but the dialog box will not be shown.
Clicking an entity will insert it into the buffer.
Clicking an ID with the left mouse button will insert it into the buffer; clicking with the right mouse button will move the caret to the element that declares it.
If text is selected, each selection is wrapped in a pair of opening and closing tags. This is a very powerful feature; you can select any number of text chunks, and surround them with tags, all sharing a common set of attributes.
The dialog box can be opened in any of these ways:
Invoking >>.
Double-clicking a tag in the text area while holding down Control.
Hitting return in the completion dialog, if the option is set from the XML Options.
Clicking on an element from the XML Insert dockable.
The dialog box lists all declared attributes for the current tag in a table. The columns of the table are as follows:
Set. A check box that controls if the attribute is specified or not. Required attributes are always specified.
Name. The name of the attribute.
Type. This will either be "text" or "choice". If the attribute is required, "required" will be appended.
Value. For "text" attributes, this is a text field. For "choice" attributes, this is a combo box. Depending on the schema, some attributes might define a default value.
Note that special characters entered in the text field are automatically converted to entities if necessary.
The Preview text field shows what the tag will look like with all currently-specified attributes. Clicking will insert the tag into the buffer.
If the caret is positioned on a tag, the corresponding opening or closing tag will be highlighted in the text area. You can disable this feature, or change the tag highlight color in the > pane of the > dialog box.
>> moves the caret to the corresponding opening or closing tag.
>> inserts a closing tag for the last opened tag.
>> removes all tags from the current buffer, leaving only text.
>> splits the current tag at the cursor, and creates a new tag at the same
level. This is useful when editing HTML, DocBook or similar documents, for inserting
many <p> or <para> tags.
This command tries
to match the current indenting style.
>> converts special characters to entities in the current selection.
>> converts entities to characters in the current selection.
>> generates a DTD from the XML instance document in the current buffer. Generation of XSD and RelaxNG schemata is planned for the future.
>> inserts in the clipboard an XPath to current element. For instance,
if the caret is inside the style element of an HTML page,
will copy /html/head[1]/style[1] in the clipboard. This might be useful
when writing an XSL template over a complex document.
should handle namespaces and prefixes gracefully :
namespaces and local-names are used for comparison - not prefixes, though prefixes found in the document are retained;
only the first of 2 prefixes bound to the same namespace in the source document will be used in the XPath;
if the same prefix is bound to different namespaces, the second instance of the prefix will get a numbered suffix to distinguish it in the XPath.
DTDs or Document Type Definitions, are a common way to specify schemas. While an older standard, are still widely used. Buffers which have an associated DTD are validated for errors, and completion popups are shown for elements, attributes, and entities. DTDs are specified by including markup like the following near the start of an XML file:
<?xml version="1.0"?> <!DOCTYPE PUBLIC "public ID" "system ID">
Or alternatively:
<?xml version="1.0"?>
<!DOCTYPE SYSTEM "system ID">
XSDs, or XML schemas, perform a similar function to DTDs, however they are a newer standard and support some features that DTDs do not, like namespaces. Buffers which have an associated schema are validated for errors, and completion popups are shown for elements and entities.
Schemas are specified with a http://www.w3.org/2001/XMLSchema-instance namespace in the document's root element:
<personnel
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation='personal.xsd'>Or if the target schema has an associated namespace:
<dictionary xmlns="http://www.xml-cml.org/schema/stmml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.xml-cml.org/schema/stmml ../schema/stmml.xsd
http://www.xml-cml.org/schema/cml2/core ../schema/cmlCore.xsd">In all cases, the XML parser will first look for the specified system or public ID in the plugin's built-in catalog, along with any catalog files specified in the > pane of the > dialog box.
Catalog files must either be in OASIS OPEN or XML catalog format. These two formats are documented below.
If the DTD or XSD cannot be located in the catalogs, the plugin will ask if it should be downloaded and cached for future use in the dtds
subdirectory of the jEdit settings directory.
The download cache can be cleared using the >> command.
The XML plugin catalogs the following DTDs which are included with jEdit itself, or the XML plugin.
DTDs declared by jEdit: actions.dtd,
catalog.dtd,
dockables.dtd,
perspective.dtd,
plugins.dtd,
recent.dtd,
registers.dtd,
services.dt,
xmode.dtd.
A few plugin DTDs: commando.dtd (Console
plugin), sqlServerType.dtd (SQL plugin).
XHTML 1.0 and XHTML 1.1 DTDs, referenced using one of the following public IDs:
-//W3C//DTD XHTML 1.0 Frameset//EN
-//W3C//DTD XHTML 1.0 Strict//EN
-//W3C//DTD XHTML 1.0 Transitional//EN
-//W3C//DTD XHTML 1.1//EN
DocBook 4.4 DTDs, referenced with the
-//OASIS//DTD DocBook XML V4.4//EN public ID.
For example, these doctypes are recognized by the XML plugin, and when they are used, tell the XML plugin to load a built-in DTD, and provide you with completion popups for elements and attributes.
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd"> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "xhtml11-flat.dtd">
If the less-than symbol ("<") is typed and no other key is pressed within a specified delay (half a second by default), a tag list popup will be shown. Note that only tags which the parent element is allowed to contain are listed. The arrow keys can be used to select a tag; if you start typing a tag name, only tags whose names begin with the already-entered text will be shown.
Pressing Space or > will insert the currently selected tag into the buffer. Pressing Enter will insert the tag and show the dialog box; see the section called “The edit tag dialog box”.
Attribute Completion works in a similar manner - when the XML plugin detects that you are inside a tag and about to enter an attribute name, it will provide you with a list of possible attributes or completions of attributes if it can obtain this information from the schema.
Entity completion works in a similar manner; typing & will show an entity list popup. Pressing Space, Enter or ; will insert the currently selected entity into the buffer.
Typing "</" will automatically close the last open tag.
Another convenient feature inserts a closing tag when you finish typing an opening tag. It is disabled by default, but can be activated from the plugin options.
These features can be enabled, disabled and configured in the and > pane of the > dialog box.
XML files are validated against their DTD, XSD or RNG schema. If no schema can be loaded, only minimal error checking will be performed. No validation of any kind is performed for HTML files, but XHTML files can be validated using their regular schema.
Any errors found while parsing XML are handled by the ErrorList plugin; in other words, they are highlighted in the text area, and shown in the >> window. See the documentation for the ErrorList plugin for details.
DTDs (document type definitions), XSDs (w3c XML Schemas), and Relax-NGs are three different standards for defining XML Schemas, to describe which elements and entities are allowed within a specific context. In order to implement completion or validation, the XML plugin needs to be able to load a schema. A few file types for which no schema is available are supported using built-in completion information included with the plugin.
Validation can be disabled on a global basis in the > pane of the > dialog box. It can also be disabled on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:
:xml.validate=false:
Namespaces processing can be disabled on a per-buffer basis by inserting the following in the first or last 10 lines of the buffer:
:xml.namespaces.disable=true:
Why would you do that ? If you use the XHTML plus Math 1.1 DTD, you will
get an error because the DTD uses a prefixed name IS10744:arch
somewhere, which is incompatible with namespaces. The typical error message is :
A colon is not allowed in the name XXX when namespaces are enabled.
DTD Validation can be disabled on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:
:xml.validate.ignore-dtd=true:
This way, one can use DTDs for entities and a schema for validation. Here is a sample of what you'd do :
<!-- :xml.validate.ignore-dtd=true: -->
<!DOCTYPE article [
<!ENTITY % isolat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
"http://www.oasis-open.org/docbook/xmlcharent/0.3/iso-lat1.ent" >
<!ENTITY % isogrk1 PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN//XML"
"http://www.oasis-open.org/docbook/xmlcharent/0.3/iso-grk1.ent" >
%isolat1;
%isogrk1;
]>
<article
xmlns:xi="http://www.w3.org/2001/XInclude"
xsi:noNamespaceSchemaLocation="http://www.docbook.org/xsd/4.4/docbook.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
id="root-article">
<title>Using entities like &ecute; </title>
Validation will be performed if it is enabled (see the section called “Customizing validation”) and if a schema or a DTD can be found.
While DTDs and XSD schemas are declared in the document (see the section called “Schemas”), Relax NG schemas are not declared in the document. Therefore, there must be an external mean of specifying the RNG schema.
You can do this:
on a per-buffer basis by inserting the following in the first or last 10 lines of the buffer:
:xml.validation.schema=URI to the schema:You can use an absolute or relative URI or even an URI that will be resolved as
a system Id by some catalog (e.g. locate.rng).
on a per directory and/or global basis, by using schema mapping rules
(the so called schemas.xml). This is consistent with
the nXML mode for
Emacs (it's even 100% compatible !). These powerful mapping rules
work on filenames, paths, root element, namespace, etc.
When the XML plugin parses an XML buffer, it will look for a file named
schemas.xml in the same directory. Or, if it doesn't exist,
for a global
file in the settings directory (under JEDIT_SETTINGS/plugins/xml.XmlPlugin/schemas.xmlXML.jar!/xml/dtds/schemas.xml).
The rules contained in this file are given the public Id, system Id, doctype,
prefix, local name, namespace of the parsed document. The first rule to match
returns the schema that will be used for validation.
You can edit manually these schemas.xml files.
There is a built-in rule to find their schema, so XML completion and
validation should work. The schema is under xml/dtds/locate.rng
in the XML.jar archive (simply open your mapping document and use
>>
).
There are also three actions associated with schema mapping :
You can set the type of current buffer to a known type via >> . You will be prompted for a type, like :
for Relax NG Schemas
for schemas.xml
for any well formed XML
You can also directly point to an XSD or RNG schema via >> . You will be able to choose a schema file from the VFS browser.
It does not work from a remote filesystem yet !
Both of these actions will create a schemas.xml file
alongside the current buffer. If such a file exists already, it is updated.
The current implementation will retain any existing rule, but will erase any comment and any formatting in the document, so beware that all commented-out section of the schema-mapping will disappear next time you use .
If, for some reason, you want to disable this schema-mapping mechanism, you can do it on a global basis by unchecking the checkbox, in the > pane of the >.
You can also disable schema-mapping on a per-buffer basis (let's say on a file in a read-only directory), by inserting the following in the first or last 10 lines of the buffer:
:xml.enable-schema-mapping=false:
The XML parser will no more try to find a schema using schemas.xml.
However, it will still pick a schema defined via a buffer-local property in a buffer,
or if you set a schema via or .
What will happen if you use
and schema-mapping is disabled is that
the chosen schema won't be saved and any existing schemas.xml
in the same directory won't be updated. You will have to select the schema
again next time you edit the buffer.
Conversely, will still work.
It will even propose you schema types defined in a schemas.xml
in the same directory as the buffer. However, the schema-type won't be saved
and the schemas.xml won't be updated.
Also, if you update the definition of the typeId (ie. you change its target to another
schema), the schema defined for the buffer won't be updated and you'll have to do
again.
Thanks to Trang's schema translation capabilities, you will be able to translate from any of DTD, RNG, RNC, XML instances to DTD, RNG, RNC, XSD.
Trang (http://www.thaiopensource.com/relaxng/trang.html, James Clark and others)
is Copyright © 2002, 2003, 2008 Thai Open Source Software Center Ltd.
A copy of its user-guide is included here.
You may do a basic conversion of current buffer using the
xml-translate-to-dtd, xml-translate-to-rnc, xml-translate-to-rng,
xml-translate-to-xsd actions.
You may specify advanced options using >> . The meaning of each parameter is described in Trang's user manual (docs/trang-manual.html).
The output of Trang is converted to jEdit buffers, so that you may review them before saving. Any existing file will be overwritten but you'll get its contents back, using .
It is sometimes necessary to split a long XML document into smaller parts, or to assemble parts in different ways. This can be achieved via external entities (a DTD feature) or via XInclude.
When editing an XML file which is included from another file, it can be desirable for validation to always start at the root file, rather than the one that is currently being edited. For example, you might be writing a user manual using DocBook, with each chapter split into its own XML file. This can be achieved by inserting the following in the first or last 10 lines of each child file:
:xml.root=relative or absolute path of root documentNote that even if this property is specified, the window only shows elements defined in the current buffer. However, when validating an included file, validation errors will be reported for all files included from the root file.
External entities were used in the user guide for jEdit 4.4 and earlier (see excerpt of users-guide.xml).
The DOCTYPE declaration lists some entities,
which are referenced via &your_entity;.
This is similar to #include directives in C or C++.
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ <!ENTITY conventions SYSTEM "conventions.xml"> ]> <book> <title>your title</title> &conventions; </book>
The inclusion is performed before DTD validation which allows the ID/IDREF
validation to succeed : ie. a section declared with id="ID1" in one
file can be referenced from another included file via <xref linkend="ID1"/>.
For validation in jEdit, you will also need the section called “ Child Documents ”.
XInclude defines a namespace associated with the URI
| ||
| --XML Inclusions (XInclude) Version 1.0 (Second Edition) W3C Recommendation 15 November 2006 | ||
The jEdit 4.5 FAQ and users guide both use XIncludes to join together child documents into a whole.
The following example shows an inclusion similar to excerpt of users-guide.xml.
<book>
<title>your title</title>
<xi:include href="conventions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
XInclude can be activated on a global basis in the > pane of the > dialog box. It can also be activated on a per-buffer basis by inserting the following in the first of last 10 lines of the buffer:
:xml.xinclude=true:
You can fine-tune the way relative URIs will be interpreted in the included fragment :
either resolve the URIs based on the URI of the fragment, or based on the URI of the parent
(see http://www.w3.org/TR/xinclude/#base). This is controlled globally
in the option pane or via the property xml.xinclude.fixup-base-uris on a per-buffer
basis.
See the following example:
:xml.xinclude=true:xml.xinclude.fixup-base-uris=true:
Note that DTD validation would fail on ID/IDREF attributes (ids
and linkends). This is because the document seen by the DTD validator
is prior to XInclude resolution. You are then forced to use either XML Schemas or
RelaxNG validation.
For validation in jEdit, you will also need the section called “ Child Documents ”.
For more informations regarding XInclude and docbook, you should reed
Chapter 22 of DocBook XSL: The Complete Guide by Bob Stayton :
http://docs.huihoo.com/docbook/docbook-xsl-complete-guide-3rd/ModularDoc.html
Xinclude is activated in xsltproc via the --xinclude command-line switch.
Each line in an OASIS OPEN catalog file must look like one of the following:
--
- comments are ignored.comment
SYSTEM " - maps the first system ID
to the second.system ID"
"new system ID"
PUBLIC " - maps the public ID
to the system ID.public ID"
"new system ID"
Catalog files in the OASIS XML catalog format are themselves XML files, and must have the following DOCTYPE declaration:
<![CDATA[<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "oasis-catalog.dtd">]]>
The XML plugin bundles the above DTD so you can use the completion features to construct an OASIS XML catalog.
If the Hyperlinks plugin is installed and active, some attributes will be available for navigation. To show them, simply hold the Ctrl key and hover over them with the mouse. A solid blue underline will appear under attribute values recognised as hyperlinks. Then, clicking on the link will open the referenced document in a buffer and in some cases move to the referenced element.
Hereafter is the list of supported hyperlinks in the XML mode.
xml:base attributes are used to resolve relative hyperlinks.
href attributes in XInclude (<xi:include href="..."/>). Fragments are not supported: the buffer is opened and that's all.
simple XLinks (<myelt xlink:href="..."/>). Only simple links are supported and the fragment identifier is ignored: the buffer is opened and that's all.
IDREF attributes, when the buffer has been parsed and the attribute has the IDREF datatype. This includes DocBook 4.x links (<xref linkend="id"/>). IDREFS attributes are also supported. Each idref is highlighted on its own. Datatype is derived from the RNG, XSD, or DTD grammar used for the document.
XML Schema (XSD) schema location (<myelt xsi:schemaLocation="ns1 url1...">) and no-namespace schema location (<myelt xsi:noNamespaceSchemaLocation="url">). Multiple namespace-url couples are supported.
attributes with datatype anyURI, e.g. XSD include and import (<xs:include schemaLocation="url"/>). Datatype is derived from the RNG, XSD, or DTD grammar used for the document.
DocBook ulink (<ulink url="...">). This is really the url attribute of an ulink element in no namespace.
Hereafter is the list of supported hyperlinks in the HTML mode.
Supported hyperlinks are all attributes with type URI in the HTML 4.01 spec.
Links to other documents and anchors inside document are supported,
but fragment identifiers in other documents are not.
The HTML/HEAD/BASE element is used to resolve URIs, if present.
href attributes in a, area, link
elements.
longdesc, usemap attributes of img element.
cite attribute of q, blockquote,
ins and del elements.
usemap attribute of input and object elements.
src attribute of script element.
Attributes with type anyURI
are recognised as hyperlinks.
Attributes with type IDREF and IDREFS work
as hyperlinks to the referenced element.
The Xml Indenter plugin allows you to indent the XML contents of the current open buffer. You can invoke the "Indent XML" action via a keyboard shortcut or toolbar icon; this can be configured from "Utilities->Global Options->jEdit->Shortcuts" or "Utilities->Global Options->jEdit->Tool Bar" respectively.
The indent width amount and whether to use soft (emulated with spaces) tabs can be configured in the buffer options: "Utilities->Buffer Options".
The following improvements should eventually be made to the Indent XML feature:
Correctly support different line separator encodings.
You can configure elements whose enclosing text nodes should have whitespace preserved by going to: "Plugins->Plugin Options->XML Indenter".
On the options pane click the add button and in the dialog enter the qualified name of an element whose whitespace should be preserved.
A qualified name consists of the element name plus any namespace prefix if there is one. For example the XML Indenter comes preconfigured with whitespace preservation for elements named xsl:text, text and tspan.
You can remove elements from the list by selecting them and clicking the remove button.
Click here to see the detailed changelog of the XML plugin. There are also separate changelogs for XmlIndenter and JavaScript SideKick, two plugins that were merged into the XML plugin.
All jEdit users are encouraged to join the <jedit-users@lists.sourceforge.net> mailing list to give feedback or ask questions of other users and developers.
The preferred way to send bug reports against the XML plugin is to use the jEdit Plugin Bugs Tracker.
Feature requests can be found on the jEdit Plugin feature requests tracker.
Development questions should be posted to the jEdit development
mailing-list <jedit-devel@lists.sourceforge.net>.