In case you are editing document fragments, for instance the chapters from a book each one in a separate file, you can activate the Content Completion for these fragments in two ways:
The table available at -> -> Content Completion/Default contains a set of rules for associating a schema with the current document when no schema is specified within the document. The schema is one of the types: XML Schema, XML Schema with embedded Schematron rules, Relax NG, Relax NG with embedded Schematron rules, Schematron, DTD, NRL.
The rules are applied in the order they appear in the table and take into account the local name of the root element, the default namespace and the file name of the document.
The same effect is obtained by configuring a processing instruction that specifies the schema to be used. The advantage of this method is that you can configure the Content Completion for each file. The processing instruction must be added at the beginning of the document, just after the XML prologue:
<?oxygen RNGSchema="file:/C:/work/relaxng/personal.rng" type="xml"?>
Select menu Content Completion and document validation. The schema is one of the types: XML Schema, DTD, Relax NG, NRL, Schematron.
+ -> or click the toolbar button to open a dialog for selecting a schema used forThis is a dialog helping the user to easily associate a schema file with the edited document . Enables definition of a XML Document Prolog using the system identifier of a XML Schema, DTD, Relax NG (full or compact syntax) schema, NRL (Namespace Routing Language) schema or Schematron schema.
When associating a XML Schema to the edited document if the root element of the document defines a default namespace URI with a "xmlns" attribute the "Associate schema" action adds a xsi:schemaLocation attribute. Otherwise it adds a xsi:noNamespaceSchemaLocation attribute.
The URL combo box contains a predefined set of schemas that are used more often and it also keeps a history of the last used schemas.
<oXygen/> logs the URL of the detected schema in the Status view.
The oxygen processing instruction has the following attributes:
When working with documents that do not specify a schema, or for which the schema is not known or does not exist, <oXygen/> is able to learn and translate it to a DTD, which in turn can be saved to a file in order to provide a DTD for Content Completion and document validation. In addition to being useful for quick creation of a DTD that will be capable of providing an initialization source for the Content Completion assistant. This feature can also be used to produce DTDs for documents containing personal or custom element types.
When it is opened a document that does not specify a schema <oXygen/> automatically learns the document structure and uses it for Content Completion. To disable this feature uncheck the checkbox Learn on open document from Preferences.
Procedure 4.7. To create a DTD:
Open the structured document from which a DTD will be created.
Select menu Ctrl+Shift+L) or click the toolbar button to read the mark-up structure of the current document so that it can be saved as a DTD using the option. <oXygen/> will learn the document structure, when finished displaying words Learn Complete in the Message Pane of the Editor Status bar.
-> (Select menu Ctrl+Shift+S) or click the toolbar button to display the Save Structure dialog, used to name and create DTD documents learnt by the Learn Structure function.
+ -> (The resulting DTD is only valid for documents containing the elements and structures defined by the document used as the input for creating the DTD. If new element types or structures are defined in a document, they must be added to the DTD in order for successful validation.
<oXygen/>'s intelligent Content Completion feature is a content assistant that enables rapid, in-line identification and insertion of structured language elements, attributes and in some cases their parameter options.
If the Content Completion assistant is enabled in user preferences (the option Use Content Completion) it is automatically displayed whenever the < character is entered into a document or by pressing CTRL+Space on a partial element or attribute name. Moving the focus to highlight an element and pressing the Enter key or the Tab key, inserts both the start and end tags of the highlighted element into the document.
The DTD, XML Schema, Relax NG schema or NRL schema used to populate the Content Completion assistant is specified in the following methods, in order of precedence:
The schema specified explicitly in the document. In this case <oXygen/> reads the beginning of the document and resolves the location of the DTD, XML Schema, Relax NG schema or NRL schema.
The default schema rule declared in the Default Schema Associations options which matches the edited document.
For XSLT stylesheets the schema specified in the <oXygen/> Content Completion options. <oXygen/> will read the Content Completion settings when the prolog fails to provide or resolve the location of a DTD, XML Schema or Relax NG schema.
After inserting, the cursor is positioned directly before the > character of the start tag, if the element has attributes, in order to enable rapid insertion of any attributed supported by the element, or after the > char of the start tag if the element has no attributes. Pressing the space bar, directly after element insertion will again display the assistant. In this instance the attributes supported by that element will be displayed. If an attribute supports a fix set of parameters, the assistant will display the list of valid parameter. If the parameter setting is user defined and therefore variable, the assistant will be closed to enable manual insertion. The values of the attributes can be learned from the same elements in the current document.
If you press CTRL + Enter instead of Enter or Tab after inserting the start and end tags in the document <oXygen/> will insert an empty line between the start and end tag and the cursor will be positioned between on the empty line on an indented position with regard to the start tag.
If the feature Add Element Content of Content Completion is enabled all the elements that the new element must contain, as specified in the DTD or XML Schema, are inserted automatically in the document. The Content Completion assistant can also add optional content and first choice particle, as specified in the DTD or XML Schema, for the element if the two options are enabled.
The content assistant can be started at any time by pressing CTRL+Space The effect is that the context-sensitive list of proposals will be shown in the current position of the caret in the edited document if element, attribute or attribute value insertion makes sense. Such positions are: anywhere within a tag name or at the beginning of a tag name in an XML document, XML Schema, DTD or Relax NG (full or compact syntax) schema, anywhere within an attribute name or at the beginning of an attribute name in any XML document with an associated schema, and within attribute values or at the beginning of attribute values in XML documents where lists of possible values have been defined for that element in the schema associated with the document.
The content of the Content Completion assistant is dependent on the element structure specified in the DTD, XML Schema, Relax NG (full or compact syntax) schema or NRL schema associated to the edited document.
The number and type of elements displayed by the assistant is dependent on the current position of the cursor in the structured document . The child elements displayed within a given element are defined by the structure of the specified DTD, XML Schema, Relax NG (full or compact syntax) schema or NRL schema. All elements that can't be child elements of the current element according to the specified schema are not displayed.
Inside Relax NG documents the Content Completion assistant is able to present element values if such values are specified in the Relax NG schema. Also pattern names defined in the Relax NG schema are presented as possible values for pattern references. For example if the schema defines an enumValuesElem element
<element name="enumValuesElem"> <choice> <value>value1</value> <value>value2</value> <value>value3</value> </choice> </element>
in documents based on the schema the Content Completion assistant offers the list of values:
If only one element name must be displayed by the content assistant then the assistant is not displayed any more but this only option is automatically inserted in the document at the current cursor position.
If the schema for the edited document defines attributes of type ID and IDREF the content assistant will display for IDREF attributes a list of all the ID values already present in the document for an easy insertion of a valid ID value at the cursor position in the document. This is available for documents that use DTD, XML Schema and Relax NG schema.
Also values of all the xml:id attributes are treated as ID attributes and collected and displayed by the content completion assistant as possible values for anyURI attributes defined in the schema of the edited document. This works only for XML Schema and Relax NG schemas.
For documents that use an XML Schema or Relax NG schema the content assistant offers proposals for attributes and elements values that have as type an enumeration of tokens. Also if a default value is defined in the schema for an attribute or element that value is offered in the content completion window.
If the edited document is not associated with a schema explicitly using the usual mechanisms for associating a DTD or XML Schema with a document or using a processing instruction introduced by the Associate schema action the content assistant will extract the elements presented in the pop-up window from the default schema.
If the schema for the document is of type XML Schema, Relax NG (full syntax) or DTD and it contains element, attributes or attributes values annotations, these will be presented when the content completion window is displayed, if the option Show annotations is enabled. Also the annotation is presented in a small tooltip window displayed automatically when the mouse hovers over an element or attribute annotated in the associated schema of the edited document.
In an XML Schema annotations are put in an <xs:annotation> element:
<xs:annotation> <xs:documentation> Description of the element. </xs:documentation> </xs:annotation>
If the current element / attribute in the edited document does not have an annotation in the schema and that schema is of the type XML Schema <oXygen/> seeks an annotation in the type definition of the element / attribute or, if no annotation is found there, in the parent type definition of that definition, etc.
In a Relax NG schema any element outside the Relax NG namespace (http://relaxng.org/ns/structure/1.0) is handled as annotation and the text content is displayed in the annotation window together with the content completion window:
For DTD <oXygen/> defines a custom mechanism for annotation using comments enabled from the option Use DTD comments as annotations . The text of a comment with the following format will be presented on content completion:
<!--doc:Description of the element. -->
The operation of the Content Completion assistant is configured by the options available in the group called Content Completion Features.
You can define short names for predefined blocks of code called code templates. The short names are displayed in the content completion window if the word at cursor position is a prefix of such a short name. <oXygen/> comes with a lot of predefined code templates but you can define your own code templates for any type of editor. For more details see the example for XSLT editor code templates.
Information about the current element being edited are also available in the Model panel and Attributes panel, located on the left-hand side of the main window. The Model panel and the Attributes panel combined with the powerful Outliner provide spacial and insight information on the edited document.
The Model panel presents the structure of the current edited tag and tag documentation defined as annotation in the schema of the current document. Open the Model panel from oXygen+Model view -> -> +
The element structure panel shows the structure of the current edited or selected tag in a Tree format.
The information includes the name, model and attributes the currently edited tag may have. The allowed attributes are shown along with any restrictions they might possess.
The Attributes panel presents all the possible attributes of the current element and allows to insert attributes in the current element or change the value of the attributes already used in the element. The attributes already present in the document are painted with a bold font. Clicking on the Value column of a table row will start editing the value of the attribute from the selected row. If the possible values of the attribute are specified as list in the schema associated with the edited document the Value column works as a combo box where you can select one of the possible values to be inserted in the document. The attributes table is sortable, 3 sorting orders being available by clicking on the columns' names. Thus the table's contents can be sorted in ascending order, in descending order or in a custom order, where the used attributes are placed at the beginning of the table as they appear in the element followed by the rest of the allowed elements as they are declared in the associated schema.
The W3C XML specification states that a program should not continue to process an XML document if it finds a validation error. The reason is that XML software should be easy to write, and that all XML documents should be compatible. With HTML it was possible to create documents with lots of errors (like when you forget an end tag). One of the main reasons that HTML browsers are so big and incompatible, is that they have their own ways to figure out what a document should look like when they encounter an HTML error. With XML this should not be possible.
However, when creating an XML document, errors are very easily introduced. When working with large projects or many files, the probability that errors will occur is even greater. Determining that your project is error free can be time consuming and even frustrating. For this reason <oXygen/> provides functions that enable easy error identification and rapid error location.
XML with correct syntax is Well Formed XML.
A Well Formed XML document is a document that conforms to the XML syntax rules.
All XML elements must have a closing tag.
XML tags are case sensitive.
All XML elements must be properly nested.
All XML documents must have a root element.
Attribute values must always be quoted.
With XML, white space is preserved.
If you select menu Ctrl+Shift+W) or click the toolbar button <oXygen/> checks your current document for any deviation from these rules. If any error is found the result is returned to the Message Panel. Each error is one record in the Result List and is accompanied by an error message. Clicking the record will open the document containing the error and highlight the approximate location.
+ -> (Example 4.1. Check XML Form Error Message
In our example we will use the case where an end tag is missing from a Docbook listitem element. In this case running Check XML Form will return the following error.
F The element type "listitem" must be terminated by the matching end-tag "</listitem>".
To resolve the error, click in the result list record which will locate and highlight the errors approximate position. Review the "listitem" elements, identify which is missing an end tag and insert </listitem>.
Also the files contained in the current project and selected with the mouse in the Project view can be checked for well-formedness with one action available on the popup menu of the Project view in the Batch validation submenu:
A Valid XML document is a Well Formed XML document, which also conforms to the rules of a schema which defines the legal elements of an XML document. The schema type can be: XML Schema, Relax NG (full or compact syntax), Schematron, Document Type Definition (DTD) or Namespace Routing Language (NRL).
The purpose of the schema is to define the legal building blocks of an XML document. It defines the document structure with a list of legal elements.
The <oXygen/>
function ensures that your document is compliant with the rules defined by an associated DTD, XML Schema, Relax NG or Schematron schema. XML Schema or Relax NG Schema can embed Schematron rules. For Schematron it is possible to select the validation phase.A line with a validation error or warning will be marked in the editor panel by underlining it with a red color. Also a red sign will mark the position in the document of that line on the right side ruler of the editor panel. The same will happen for a validation warning, only the color will be yellow instead of red.
The ruler on the right of the document is designed to display the errors found during the validation process and also to help the user to locate them more easily. The ruler contains the following areas:
top area containing a success validation indicator that will turn green in case the validation succeeded or red otherwise.
middle area where the errors markers are depicted in red. The number of markers shown can be limited by modifying the setting oXygen/Editor / Document checking+Maximum number of errors reported per document
-> +Clicking on a marker will highlight the corresponding text area in the editor. The error message is displayed both in the tool tip and in the error area on the bottom of the editor panel.
If you don't change the active editor and you don't switch to other application the schema associated to the current document is parsed and cached at the first validate action and is reused by the next Validate document actions without reparsing it. This increases the speed of the validate action starting with the second execution if the schema is large or is located on a remote server on the Web. To reset the cache and reparse the schema you have to use the action.
Use one of the actions for validating the current document:
Select menu Ctrl+Shift+V) or click the button available in the Validate toolbar to return an error result-list in the Message panel. Mark-up of current document is checked to conform with the specified DTD, XML Schema or Relax NG schema rules. It caches the schema and the next execution of the action uses the cached schema.
-> (Select menu Ctrl+Shift+V) or click the button available in the Validate toolbar to reset the cache with the schema and validate the document. It returns an error result-list in the Message panel. Mark-up of current document is checked to conform with the specified DTD, XML Schema or Relax NG schema rules.
-> (Select menu Ctrl+Shift+H) or click the button available in the Validate toolbar to display the External Validation dialog, used to select the external schemas (XML Schema, DTD, Relax NG, NRL,Schematron schema) and to execute the Validation operation on the current document using the selected schemas. Returns an error result-list in the Message panel. Mark-up of current document is checked to conform with the specified schemas rules.
-> (Select contextual menu of Navigator or Package Explorer view, -> to validate all selected files.
Ctrl+Shift+K) or click the toolbar button to clear the error markers added to the Problems view at the last validation of the current edited document.
-> (Also you can select several files in the views like Package Explorer, Navigator and validate them with one click by selecting the action Validate selection or the action Validate selection with ... available from the contextual menu of that view, the submenu Batch Validate.
If there are too many validation errors and the validation process is long you can limit the maximum number of reported errors.
Validation of an XML document against an XML Schema containing a type definition with a minOccurs or maxOccurs attribute having a value larger than 256 limits the value to 256 and issues a warning about this restriction in the Message panel at the bottom of the <oXygen/> window. Otherwise for large values of the minOccurs and maxOccurs attributes the validator fails with an OutOfMemory error which practically makes <oXygen/> unusable without a restart of the entire application.
Status messages from every validation action are logged into the Console view.
<oXygen/> can be configured to mark validation errors in the edited document as you modify it using the keyboard. If you enable the Validate as you type option any validation errors and warnings will be highlighted automatically in the editor panel after the configured delay from the last key typed, with underline markers in the editor panel and small rectangles on the right side ruler of the editor panel, in the same way as for manual validation invoked by the user.
<oXygen/> logs status messages of the validation action into the Console view.
Example 4.2. Validate document error message
In our example we will use the case where a Docbook listitem element
does not match the rules of the docbookx.dtd
. In
this case running Validate document will return the following error.
E The content of element type "listitem" must match"(calloutlist|glosslist|itemizedlist|orderedlist|segmentedlist| simplelist|variablelist| caution|important|note|tip|warning| literallayout|programlisting|programlistingco|screen| screenco|screenshot|synopsis|cmdsynopsis| funcsynopsis|classsynopsis|fieldsynopsis| constructorsynopsis| destructorsynopsis|methodsynopsis|formalpara|para|simpara| address|blockquote|graphic|graphicco|mediaobject| mediaobjectco|informalequation| informalexample| informalfigure|informaltable|equation|example| figure|table|msgset|procedure|sidebar|qandaset|anchor| bridgehead|remark|highlights|abstract|authorblurb|epigraph| indexterm|beginpage)+".
As you can see, this error message is a little more difficult to understand, so understanding of the syntax or processing rules for the Docbook XML DTD's "listitem" element is required. However, the error message does give us a clue as to the source of the problem, but indicating that "The content of element type "listitem" must match".
Luckily most standards based DTD's, XML Schema's and Relax NG schemas are supplied with reference documentation. This enables us to lookup the element and read about it. In this case we would want to learn about the child elements of "listitem" and their nesting rules. Once we have correctly inserted the required child element and nested it in accordance with the XML rules, the document will become valid on the next validation test.
If you need to validate the edited document with other validation engine than the built-in one you have the possibility to configure external validators as custom validation engines in <oXygen/>. After such a custom validator is properly configured in Preferences it can be applied on the current document with just one click on the External Validation toolbar. The document is validated against the schema declared in the document.
Some validators are configured by default:
included in <oXygen/> (Windows edition), associated to XML Editor, able to validate the edited document against XML Schema, Relax NG schema full syntax, DTD or a custom schema type.
not included in <oXygen/>, the jar file and
license key file of Saxon 8 SA must be placed in the lib
subdirectory of the installation directory
and the entry
<library name="lib/saxon8sa.jar"/>
must be copied to the <runtime> section of the
[Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/plugin.xml
file.
After that
Eclipse must be restarted with the
-clean parameter.
It is associated to XML Editor and XSD Editor.
included in <oXygen/> (Windows edition). It is associated to XML Editor, XSD Editor and XSL Editor. It is able to validate the edited document against XML Schema, DTD or a custom schema type.
included in <oXygen/> (Windows edition). It is associated to XML Editor, XSD Editor and XSL Editor. It is able to validate the edited document against XML Schema, DTD or a custom schema type.
not included in <oXygen/>. A Windows
distribution of XSV can be downloaded from:
ftp://ftp.cogsci.ed.ac.uk/pub/XSV/XSV210.EXE
A Linux distribution can be downloaded from
ftp://ftp.cogsci.ed.ac.uk/pub/XSV/XSV-2.10-1.noarch.rpm.
The executable path is
configured already in <oXygen/>
for the installation directory [oXygen-install-dir]/xsv
.
If it is installed in a different directory the predefined executable path must be
corrected in Preferences.
It is associated to XML Editor and XSD Editor. It is able to validate the edited document
against XML Schema or a custom schema type.
not included in <oXygen/>. It can be downloaded
from here
(it comes as a .zip file, at the time of this writing
SQC2.2.1.zip is about 3 megabytes). The executable path and
working directory are configured already
for the SQC installation directory [oXygen-install-dir]/sqc
.
If it is installed in a different directory the predefined
executable path and working directory must be corrected
in Preferences. It is associated to XSD Editor.
It must be used with a Java 1.4 virtual machine because it
does not work with Java 1.5.
Navigating between XML elements located in various parts of the currently edited document is easy due to several powerful features.
XML documents are organized as a tree of elements. When working on a large document you can collapse some elements leaving in the focus only the ones you need to edit. Expanding and collapsing works on individual elements: expanding an element leaves the child elements unchanged.
To toggle the folded state of an element click on the special mark displayed in the left part of the document editor next to the start tag of that element or click on the action
available from the context menuOther menu actions related to folding of XML elements are available from the context menu of the current editor:
Ctrl+NumPad+/) Fold all the sections except the current element.
+ + -> (Ctrl+NumPad+-): Fold the sections indented with one level inside the current element.
+ + -> (Ctrl+NumPad++): Unfold the sections indented with one level inside the current element.
+ + -> (Ctrl+NumPad+*): Unfold all the sections inside the current element.
+ + -> (Ctrl+Alt+Y): Toggles the state of the current fold.
+ + -> (You can use folding by clicking on the special marks displayed in the left part of the document editor.
The Outliner view has the following available functions:
The Outliner displays a general tag overview of the current edited XML Document. It also shows the correct hierarchical dependencies between the tag elements, making it easier for the user to be aware of the document's structure and the way tags are nested.
The Expand all and Collapse all items of the popup menu available on the outliner tree enlarge or reduce the set of nodes of the edited document currently visible in the view. The tree expansion action is a faster alternative to mouse clicks on the plus signs of the tree when one wants to access quickly a node deeply nested in the hierarchy of document nodes. When a large number of nodes become expanded and the document structure is not clear any more the collapsing action clears the view quickly by reducing the depth of the expanded nodes to only one child of the currently selected node.
When editing, the Outliner dynamically follows the modifications introduced by the user, showing in the middle of the panel the node which is currently being modified .This gives the user better insight on location where in the document one is positioned and how the structure of the document is affected by one's modifications.
Entire XML elements can be moved or copied in the edited document using only the mouse in the Outliner view in drag-and-drop operations. If you drag an XML element in the Outliner view and drop it on another one in the same panel then the dragged element will be moved after the drop target element. If you hold the mouse pointer over the drop target for a short time before the drop then the drop element will be expanded first and the dragged element will be moved inside the drop one after its opening tag. If you hold down the CTRL key it will be performed a copy operation instead a move one.
The drag and drop action in the Outliner view can be disabled and reenabled from the Preferences dialog.
The Add Child, Insert - Before and Insert - After submenus of the outline tree popup menu allow to quickly insert new tags in the document at the place of the element currectly selected in the Outline tree. The Add Child submenu lists the names of all the elements which are allowed by the schema associated with the current document as child of the current element. The effect is the same as typing the '<' character and selecting an element name from the popup menu offered by the content completion assistant. The Insert - Before and Insert - After submenus of the Outline tree popup menu list the elements which are allowed by the schema associated with the current document as siblings of the current element inserted immediately before respectively after the current element.
The Toggle comment item of the outline tree popup menu is the same item as in the editor popup menu with the same name. It encloses the currently selected element of the outline tree in an XML comment, if the element is not commented, or uncomments it if it is commented.
The Cut, Copy and Delete items of the popup menu execute the same actions as the Edit menu items with the same name on the elements currently selected in the outline tree (Cut, Copy, Paste).
The Outliner can also be used to search for a specific tag's location and contents in the edited document. Intuitively, by selecting with the left mouse button the desired tag in the Outliner view, the document is scrolled to the position of the selected tag. Moreover, the tag's contents are selected in the document, making it easy to notice the part of the document contained by that specific tag and furthermore to easily copy and paste the tag's contents in other parts of the document or in other documents.
Let's consider the case of documenting a large project. It is likely to be several people involved. The resulting document can be few megabytes in size. How to deal with this amount of data in such a way the work parallelism would not be affected ?
Fortunately, XML provides a solution for this. It can be created a master document, with references to the other document parts, containing the document sections. The users can edit individually the sections, then apply FOP or XSLT over the master and obtain the result files, let say PDF or HTML.
Two conditions must be fulfilled:
The master should declare the DTD to be used and the external entities - the sections. A sample document is:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE book SYSTEM "../xml/docbookx.dtd" [ <!ENTITY testing SYSTEM "testing.xml" > ] > <book> <chapter> ...
At a certain point in the master document there can be inserted the section "testing.xml" entity:
... &testing; ...
The document containing the section must not define again the DTD.
<section> ... here comes the section content ... </section>
The indicated DTD and the element names ( "section", "chapter" ) are used here only for illustrating the inclusion mechanism. You can use any DTD and element names you need.
When splitting a large document and including the separate parts in the master file using external entities, only the master file will contain the Document Type Definition (the DTD) or other type of schema. The included sections can't define again the schema because the main document will not be valid. If you want to validate the parts separately you have to use XInclude for assembling the parts together with the master file.
Open a new document of type XML, with no associated schema.
Make sure that in the Content Completion / Default preferences you have chosen the correct schema. Now you can type in the edited document the root element of your section. For example, if you are using docbook it can be "<chapter></chapter>" or "<section></section>". Now if you are moving the cursor between the tags and press "<", you will see the list of element names that can be inserted.
The validation will not work on a included file, as no DTD is set. The validation can be done only from the master file. At this point you can only check the document to be well-formed.
Procedure 4.8. Create an <oXygen/> XML project
Select Ctrl+N) or press the New toolbar button. The New wizard is displayed which contains the list entry XML Project.
-> -> (Select XML Project in the list of document types and click the
button.Type a name for the new project and click the
button.Select other Eclipse projects that you want to reference in the new project and click the
button.The files are organized in a XML project usually as a collection of folders. They are created and deleted with the usual Eclipse actions.
If the resources from a linked folder in the project have been changed outside the view you can refresh the content of the folder by using the Refresh action from the contextual menu. The action is also performed when selecting the linked resource and pressing F5 key
XInclude is a standard for assembling XML instances into another XML document through inclusion. It enables larger documents to be dynamically created from smaller XML documents without having to physically duplicate the content of the smaller files in the main file. XInclude is targeted as the replacement for External Entities. The advantage of using XInclude is that, unlike the entities method, each of the assembled documents is permitted to contain a Document Type Declaration (DocType Decl.). This means that each file is a valid XML instance and can be independently validated. It also means that the main document to which smaller instances are included can be validated without having to remove or comment the DocType Decl. as is the case with External Entities. This is makes XInclude a more convenient and effective method for managing XML instances that need to be stand-alone documents and part of a much larger work.
The main application for XInclude is in the document orientated content frameworks such as manuals and Web pages. Employing XInclude enables authors and content managers to manage content in a modular fashion that is akin to Object Orientated methods used in languages such as Java, C++ or C#.
The advantages of modular documentation include: reusable content units, smaller file units that are easier to edited, better version control and distributed authoring.
An example: create a chapter file and an article file in the samples
folder of the <oXygen/>
install folder and include the chapter file in the article file using XInclude.
Chapter file introduction.xml:
<?xml version="1.0"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter> <title>Getting started</title> <section> <title>Section title</title> <para>Para text</para> </section> </chapter>
Main article file:
<?xml version="1.0"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.docbook.org/xml/4.3/docbookx.dtd" [ <!ENTITY % xinclude SYSTEM "../frameworks/docbook/dtd/xinclude.mod"> %xinclude; ]> <article> <title>Install guide</title> <para>This is the install guide.</para> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml"> <xi:fallback> <para> <emphasis>FIXME: MISSING XINCLUDE CONTENT</emphasis> </para> </xi:fallback> </xi:include> </article>
In this example the following is of note:
The DocType Decl. defines an entity that references a file containing the information to add the xi namespace to certain elements defined by the Docbook DTD.
The href attribute of the xi:include element specifies that the
introduction.xml
file will replace the
xi:include element when the document is parsed.
If the introduction.xml
file cannot be found the
parse will use the value of the xi:fallback element - a message to
FIXME.
If you want to include only a fragment of other file in the master file the fragment must be contained in a tag having an xml:id attribute and you must use an XPointer expression pointing to the xml:id value. For example if the master file is:
<?xml version="1.0" encoding="UTF-8"?> <?oxygen RNGSchema="test.rng" type="xml"?> <test> <xi:include href="a.xml" xpointer="a1" xmlns:xi="http://www.w3.org/2001/XInclude"/> </test>
and the a.xml
file is:
<?xml version="1.0" encoding="UTF-8"?> <test> <a xml:id="a1">test</a> </test>
after resolving the XPointer reference the document is:
<?xml version="1.0" encoding="UTF-8"?> <?oxygen RNGSchema="test.rng" type="xml"?> <test> <a xml:id="a1" xml:base="a.xml">test</a> </test>
The XInclude support in <oXygen/> is turned off by default. You can turn it on by going to the entry Enable XInclude processing in the menu -> +oXygen / XML / XML Parser When enabled <oXygen/> will be able to validate and transform documents comprised of parts added using XInclude.
When Internet access is not available or the Internet connection is slow the OASIS XML catalogs present in the list maintained in the XML Catalog Preferences panel will be scanned trying to map a remote system ID (at document validation) or a URI reference (at document transformation) pointing to a resource on a remote Web server to a local copy of the same resource. If a match is found then <oXygen/> will use the local copy of the resource instead of the remote one. This enables the XML author to work on his XML project without Internet access or when the connection is slow and waiting until the remote resource is accessed and fetched becomes unacceptable. Also XML catalogs make documents machine independent so that they can be shared by many developers by modifying only the XML catalog mappings related to the shared documents.
<oXygen/> supports any XML catalog file that conforms to one of:
the OASIS Technical Resolution 9401:1997 including the plain-text flavor described in that resolution
User preferences related to XML Catalogs can be configured from -> +oXygen / XML / XML Catalog
The Trang converter allows you to convert a DTD or Relax NG (full or compact syntax) schema or a set of XML files to an equivalent XML Schema, DTD or Relax NG (full or compact syntax) schema. Where perfect equivalence is not possible due to limitations of the target language <oXygen/> will generate an approximation of the source schema.
The conversion functionality is available from Ctrl+Shift+\) and from the toolbar button
-> (A schema being edited can be converted with just one click on a toolbar button if that schema can be the subject of a supported conversion. For example if you press the button
while editing a Relax NG schema or DTD document the following dialog will be displayed:Here you can set the target language of the conversion and the target schema name.
In structured markup languages, the whitespace between elements that is created by use of the Space bar, Tab or multiple line breaks insertion from use of the Enter, is not recognized by the parsing tools. Often this means that when structured markup documents are opened, they are arranged as one long, unbroken line, what seems to be a single paragraph.
While this is perfectly acceptable practice, it makes editing difficult and increases the likelihood of errors being introduced. It also makes the identification of exact error positions difficult. Formatting and Indenting, also called Pretty Print, enables such documents to be neatly arranged, in a manner that is consistent and promotes easier reading on screen and in print output.
Pretty print is in no way associated with the layout or formatting that will be used in the transformed document. This layout and formatting is supplied by the XSL style sheet specified at time of transformation.
Procedure 4.9. To format and indent a document:
Open or focus on the document that is to be formatted and indented.
Select menu Ctrl+Shift+F) or click the toolbar button . While in progress the Status Panel will indicate Pretty print in progress. On completion, this will change to Pretty print successful and the document will be arranged.
-> (Pretty Print can format empty elements as an auto-closing markup tag (ex. <a/>) or as a regular tag (ex. <a></a> ). It can preserve the order or attributes or order them alphabetically. Also the user may specify a list of elements for which white spaces are preserved exactly as before Pretty print and a one with elements for which white space is stripped. These can be configured from -> +Editor / Format.
Pretty Print requires that the structured document is well formed. If the document is not well formed an error message is displayed. The message will usually indicate that a problem has been found in the form and will hint to the problem type. It will not highlight the general position of the error, to do this run the well formed action by selecting -> (Ctrl+Shift+W).
To change the indenting of the current selected text see the action Indent selection .
For user preferences related to formatting and indenting like Detect indent on open and Indent on paste see the corresponding Preferences panel.
XML elements can be excepted from the reformatting performed by the pretty-print operation by including them in the Preserve space elements (XPath) list. That means that when the Format and Indent (pretty-print) action encounters in the document an element with the name contained in this list the whitespace is preserved inside that element. This is useful when most of the elements must be reformatted with the exception of a few ones which are listed here.
For the situation when whitespace should be preserved in most elements with the exception of a few elements, the names of these elements must be added to the Strip space elements (XPath) list.
In addition to simple element names both the Preserve space elements (XPath) list and the Strip space elements (XPath) one accept a restricted set of XPath expressions for covering a pattern of XML elements with only one expression. The allowed types of expressions are:
The value of an xml:space attribute present in the XML document on which the pretty-print operation is applied always takes precedence over the Preserve space elements (XPath) and the Strip space elements (XPath) lists.
Status information generated by the Schema Detection, Validation, Validate as you type and Transformation threads are fed into the Console view allowing the user to monitor how the operation is being executed.
Messages contain a timestamp, the name of the thread that generated it and the actual status information. The number of displayed messages in the console view can be controlled from the options panel.
<oXygen/> offers groups of actions for working on single XML elements. They are available from the the context menu of the main editor panel.
: Turns on line wrapping in the editor panel if it was off and viceversa. It has the same effect as the Line wrap preference.
Ctrl + /): Comment the current selection of the current editor. If the selection already contains a comment the action uncomments the selection. If there is no selection in the current editor and the cursor is not positioned inside a comment the current line is commented. If the cursor is positioned inside a comment then the commented text is uncommented.
-> (The Select actions are enabled when the caret is positioned inside a tag name.
+ -> : Selects the entire current element;
+ -> : Selects the current element, excluding the start tag and end tag;
+ -> : Selects all the attributes of the current element;
+ -> : Selects the parent element of the current element;
+ + -> : Escapes a range of characters by replacing them with the corresponding character entities.
+ + -> : Replaces the character entities with the corresponding characters;
Ctrl + I):Corrects the indentation of the selected block of lines.
+ + -> (+ + -> : Pretty prints the element that surrounds the caret position;
+ + -> : Shows a dialog that allows you to select a list of files as sources for external entities. The DOCTYPE section of your document will be updated with the chosen entities. For instance, if choosing the file chapter1.xml, and chapter2.xml, the following section is inserted in the DOCTYPE:
<!ENTITY chapter1 SYSTEM "chapter1.xml">
<!ENTITY chapter2 SYSTEM "chapter2.xml">
Double click on an element or processing instruction - If the double click is done before the start tag of an element or after the end tag of an element then all the element is selected by the double click action. If it is done after the start tag or before the end tag then only the element content without the start tag and end tag is selected.
line separator with a single space character. It also normalizes the whitespaces by replacing a sequence of such characters with a single space.
-> : The action works on the selection. It joins the lines by replacing the-> : move the cursor to the definition of the current element in the schema associated with the edited XML document (DTD, XML Schema, Relax NG schema).
Ctrl+Shift+.): Copy XPath expression of current element from current editor to clipboard.
-> (Ctrl+Shift+G): Moves the cursor to the end tag that matches the start tag, or vice versa.
+ -> (Ctrl+Close Bracket): Moves the cursor to the end of the next tag.
-> (Ctrl+Open Bracket): Moves the cursor to the end of the previous tag.
-> (Ctrl+Alt+E): Selected Text in the editor is marked with the specified start and end tags.
+ + -> (Ctrl+Alt+/): Selected Text in the editor is marked with start and end tags of the last 'Surround in' action.
+ + -> (Ctrl+Alt+R): The element from the caret position and the elements that have the same name as the current element can be renamed according with the options from the Rename dialog.
+ + -> (+ + -> : The prefix of the element from the caret position and the elements that have the same prefix as the current element can be renamed according with the options from the Rename dialog.
Selecting the Rename current element prefix option the application will recursively traverse the current element and all its children.
For example, to change the xmlns:p1="ns1" association existing in the current element to xmlns:p5="ns1" just select this option and press OK. If the association xmlns:p1="ns1" is applied on the parent of the current element, then <oXygen/> will introduce a new declaration xmlns:p5="ns1" in the current element and will change the prefix from p1 to p5. If p5 is already associated in the current element with another namespace, let's say ns5, then a dialog showing the conflict will be displayed. Pressing the OK button, the prefix will be modified from p1 to p5 without inserting a new declaration xmlns:p5="ns1". On Cancel no modification is made.
Selecting the "Rename current prefix in all document" option the application will apply the change on the entire document.
To apply the action also inside attribute values one must check the Rename also attribute values that start with the same prefix checkbox.
+ + -> : Split the element from the caret position in two identical elements. The caret must be inside the element
+ + -> : Joins the left and the right elements relative to the current caret position. The elements must have the same name, attributes and attributes values.
Ctrl+Alt+X): Deletes the start tag and end tag of the current element.
+ + -> (Ctrl + Alt + ENTER): Move the cursor to the definition of the referenced XML Schema item - element, group, simple or complex type.
+ -> (The actions are available when the current editor is of XML Schema type.
If you want to insert content into an auto closing tag like <tag/> deleting the / character saves some keystrokes by inserting a separate closing tag automatically and placing the cursor between the start and end tags: <tag></tag>
The Hard line wrap option breaks the edited line automatically when its length exceeds the maximum line length defined for the pretty-print operation.
The Smart Enter option inserts an empty line between the start and end tags and places the cursor in an indented position on the empty line automatically when the cursor is between the start and end tag and Enter is pressed.
The syntax highlight scheme of an XML file type allows the configuration of a color per each type of token which can appear in an XML file. Distinguishing between the XML tag tokens based on the namespace prefix brings additional visual help in editing some XML file types. For example in XSLT stylesheets elements from different namespaces like XSLT, XHTML, XSL:FO or XForms are inserted in the same document and the editor panel can become cluttered. Marking tags with different colors based on the namespace prefix allows easier identification of the tags.