<oXygen/> XML Editor User Guide |
In case you are editing document fragments, for instance the chapters from a book each one in a separate file, you can activate the Tag-Insight for these fragments in two ways:
The table available at -> -> Tag-Insight/Default contains a set of rules for associating a schema with the current document when no schema is specified within the document. 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 Tag-Insight 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 Tag-Insight 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.
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 Tag-Insight 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 Tag-Insight 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 tag insight. To disable this feature uncheck the checkbox Learn on open document from Preferences.
Procedure 4.8. 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.
+ -> (![]() | Note |
---|---|
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 Tag-Insight 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 theTag-Insight assistant is enabled in user preferences (the option Use Tag Insight) 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 parts of the highlighted element in to the document. If the feature Add Element Content of Tag-Insight 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 Tag-Insight 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. 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.
The content assistant can be invoked at any time by pressing CTRL+Space and the context-sensitive list of proposals will be shown in any position of the caret in the edited document in which 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 Tag-Insight assistant is dependent on the element structure given in a given DTD, XML Schema, Relax NG (full or compact syntax) schema or NRL schema.
The number and type of elements displayed by the assistant is sensitive to 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 filtered out.
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.
For documents that use a XML Schema or Relax NG schema the content assistant offers proposals for attributes and elements values that have as type an enumeration of tokens.
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.
In a XML Schema annotations are put in a <xs:annotation> element:
<xs:annotation> <xs:documentation> Description of the element. </xs:documentation> </xs:annotation>
In a Relax NG schema any element not in 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 tag insight window:
For DTD <oXygen/> defines a 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 Tag-Insight assistant is configured by the options available in the group called Tag Insight Features.
When the content assistant is invoked by pressing CTRL+Space it also presents a list of code templates specific to the type of the active editor. Such a code template provides a shortcut for inserting a small document fragment at the current caret position. <oXygen/> comes with a large set of ready-to use templates for XSL and XML Schema documents.
Example 4.1. The XSL code template called Template-Match-Mode
Typing t in a XSL document and selecting tmm in the content assistant pop-up window will insert the following template at the caret position in the document:
<xsl:template match="" mode=""> </xsl:template>
Other templates can be easily defined by the user. Also the code templates can be shared with other users.
The DTD, XML Schema, Relax NG schema or NRL schema used to populate the Tag-Insight assistant is specified in the following methods, in order of precedence:
From the file specified in the external subset of the document prolog. In this case <oXygen/> reads the prolog and resolves the location of the DTD, XML Schema, Relax NG schema or NRL schema.
From the file specified in the <oXygen/> Tag-Insight dialog. <oXygen/> will read the Tag-Insight settings when the prolog fails to provide or resolve the location of a DTD, XML Schema or Relax NG schema.
Informations 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.
The Model Panel is comprised of:
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 Annotation View shows the annotations that are present in the used schema for the currently edited or selected tag.
This information can be very useful to persons learning XML because it has small available definitions for each used tag.
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 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.2. 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 "listitems", identify which is missing an end tag and insert </listitem>.
A Valid XML document is a Well Formed XML document, which also conforms to the rules of a Document Type Definition (DTD) or XML Schema, which defines the legal elements of an XML document.
The purpose of a DTD is to define the legal building blocks of an XML document. It defines the document structure with a list of legal elements.
The <oXygen/> Validate document 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.
Use one of the actions for validating the current document:
Select menu Ctrl+Shift+V) or click the toolbar button - 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
+ -> or click the toolbar button to display the External Validation dialog, used to select the external schemas (XML, 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 menu
+ -> or click the toolbar button to open the schema used for validating the current document in a new editor.Select contextual menu of Project Panel, to validate all selected files.
Also you can select several files in the Project panel and validate them with one click by selecting the action Validate selection or the action Validate selection with ... available from the contextual menu of the Project panel.
Example 4.3. 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.
At the XML Schema validation <oXygen/> indicates the specification reference for the XML Schema errors. The error messages contain an Info field that when clicked will open the browser on the "XML Schema Part 1:Structures" specification at exactly the point where the error is described thus allowing you to understand the reason for that error.
Validation of documents of XSLT stylesheets is performed with the help of a XSLT processor configurable from user preferences according to the XSLT version: 1.0 or 2.0. For XSLT 1.0 the options are: Xalan, Saxon 6.5.4, Saxon 8B, Saxon 8SA (if the user installs it as additional package), a JAXP transformer specified by the main Java class. For XSLT 2.0 the options are: Saxon 8B, Saxon 8SA (if the user installs it as additional package), a JAXP transformer specified by the main Java class.
Navigating between XML elements located in various parts of the currently edited document is easy due to several powerful features.
The concept of bookmark is the same as in other IDEs: the user can mark a position in one edited document so that he can quickly return after further editing and browsing through one or more documents opened at the same time. Up to nine distinct bookmarks can be placed in any opened document. Configurable shortcut key strokes are available for placing bookmarks and for quick return to any of the marked positions.
The key strokes can be configured from -> ->Menu shortcut keys.
A bookmark can be placed from F7)->Bookmarks quick creation, by clicking the toolbar button and by clicking in the margin of the editing area, to the left of the line number area, reserved for bookmarks.
-> ->Create, from -> (Quickly switching to a position marked by a bookmark can be done by
-> ->Go to.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.
An unique feature of <oXygen/> is the fact that the folds are persistent: the next time you will open the document the folds are restored to the last state so you won't have to collapse the uninteresting parts again.
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 menu or from the menu + -> The element extent is marked with a grey line displayed in the left part of the edited document. The grey line covers always the lines of text comprised between the start tag and end tag of the element where it is positioned the cursor.Other menu actions related to folding of XML elements are available from the context menu of the current editor or from the menu
-> :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.
+ -> (The Outliner panel 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.
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 panel in drag-and-drop operations. If you drag an XML element in the Outliner panel 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 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 Panel, 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.
These buttons are available in editor's main toolbar:
: Moves the caret to the last modification in any opened document.
:Moves the caret to the previous position.
:Moves the caret to the next position. Enabled after at least one press of "Back" button.
The "Go to" dialog available from Ctrl+L (Cmd+L on Mac)) enables you to go to a precise location in the current edited file specified by line and column or by offset relative to the beginning of the file.
-> (Complete the dialog as follows:
The destination line in the current document.
The destination column in the current document.
The destination offset relative to the beginning of document.
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>
![]() | Note |
---|---|
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 Tag-Insight / 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 inserable element names.
![]() | Note |
---|---|
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. |
The Project panel, located on the left-hand side of the main window, is designed to assist the user in organizing and managing related files grouped in the same XML project. The actions available on the context menu and toolbar associated to this panel enable the creation of XML projects and shortcuts to various operations on the project documents.
To create a new project select
-> or click the toolbar buttonTo open an existing project select Ctrl+F2) or click the toolbar button or select -> (displays a list of recently opened project files, select a project file to open).
-> (To save a project on disk select Ctrl+F3) or click the toolbar button
-> (The files are organized in a XML project usually as a collection of folders. There are two types of folders:
Logical folders - they are marked with a blue icon and do not have any connection with folders on the disk, creating and deleting them in <oXygen/> does not affect the filesystem on disk.
Linked folders - they are marked with a yellow icon and their name and content mirror a real folder existing in the filesystem on disk.
To create a new logical folder select in the contextual menu
or or or click the Project panel toolbar buttonYou can create linked folders by dragging and dropping a folder from the Windows Explorer / Mac OS X Finder over the project tree or by selecting in the contextual menu
To add one or more files to a folder, right click on it, and choose Add files or Add Edited File or click the toolabr button or right-click on the title of an opened editor and select from the popup menu Add to project or Add all to project.
The default target when adding files to a project is the project root. Selecting a folder changes the target to the selected folder. Files may have multiple instances, within the folder system but cannot appear twice within the same folder.
To remove one or more files and/or folders select them with the mouse in the project tree, right-click to invoke the contextual menu and select the Remove action or press the key.
If a project folder contains many documents a certain document can be quickly located in the project tree if the user selects with the mouse the folder containing the desired document (or some arbitrary document in this folder) and types the first characters of the document name. The desired document will be automatically selected as soon as the typed characters uniquely identify its name in the folder. Once selected the document can be opened by pressing the Remove from the context menu.
key or by double-clicking on it or it can be deleted by pressing the key or by choosingThe files from the entire project or from a project folder can be validated against a schema of type Schematron, XML Schema, Relax NG, NRL, or a combination of the later with Schematron with a single button click on This together with the logical folder support of the project allows you to group your files and validate them very easily.
The full path to the project files is hidden by default. Click the toolbar button
to toggle the file path on or off.The files and folders that appear as visible in the Project Panel can be filtered. Click the toolbar button
to set filter patterns for the files you do not want to show.Right-clicking any object in the tree-view displays the Project menu with functions that can be performed on, or from the selected object. Options available from the Project menu are specific to the object type selected in the tree-view.
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
subfolder 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.
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 -> +XML / XML Parser Options When enabled <oXygen/> will be able to validate and transform documents comprised of XIncluded parts.
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 inacceptable. 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 decribed in that resolution
User preferences related to XML Catalogs can be configured from -> +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+Alt+T) from the Project panel contextual menu - the action -> 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.
To generate HTML documentation for a XML Schema document similar with the Javadoc documentation for Java classes use the dialog Schema documentation. It is opened with the action -> (Ctrl+Alt+S) and enables the user to configure a large set of parameters of the process of generating the HTML documentation.
The text field of the Input panel must contain the full path to the XML Schema (XSD) file, if the schema is composed of only one file, or the full path to the main XSD file of the XML Schema document, that is the file that includes or imports other modules of the document.
<oXygen/> is able to include images of the XML Schema components in the final HTML result. The supported image formats are PNG and JPG. The image of an XML Schema component contains the graphical representation of that component as it is rendered in the Schema Diagram panel of the <oXygen/>'s XSD editor panel. The parameters related to images are:
The folder where the images are going to be saved relative to the output file. If there is no folder specified, the images will be saved in the same directory as the output file.
Include in the HTML result the representation of each schema component in the <oXygen/>'s Full Model View of the schema.
Include in the HTML result the representation of each schema component in the <oXygen/>'s Logical Model View of the schema.
One of the PNG or JPG formats.
The Options panel contain parameters for the level of details included in the documentation:
The title displayed at the beginning of the HTML document and in the title bar of the web browser.
If this parameter is set to "true", the schema components are presented sorted by type and name. Otherwise, they are presented in the order that they appear in the schema. By default, this parameter is set to "true."
The generated XHTML document uses JavaScript to hide some details like the underlying schema component XML representation, which can be made to appear with a button press. Since some people have ideological objections to JavaScript, this feature can be turned off. If this parameter is set to "true", JavaScript will be used in the generated documentation. Otherwise, it won't. By default, this parameter is set to "true."
If this parameter is set to "true", xs3p will search for components in "included" schemas when creating links and generating the XML Instance Representation table. When this parameter is set to "true", the "linksFile" parameter must also be set, which is described below. Otherwise, an error will be raised. This search is recursive, so schemas "included" in the current schema's "included" schemas will also be searched.
If this parameter is set to "true", xs3p will search for components in "imported" schemas when creating links and generating the XML Instance Representation table. The above discussion for the "searchIncludedSchemas" parameter also applies to this parameter. Also, when this parameter is set to "true", the "linksFile" parameter must also be set.
The type hierarchy of a global type definition is displayed in its section. If this parameter is set to "true", all super-types of the current type are shown in the type hierarchy. Otherwise, only the immediate parent type is displayed. By default, this parameter is set to "true."
This parameter has a similar concept as printAllSuperTypes. If it is set to "true", all sub-types of the current type are shown in the type hierarchy. Otherwise, only the direct sub-types are displayed. By default, this parameter is set to "true."
If this parameter is set to "true", the Legend section is included. Otherwise, it isn't. By default, this parameter is set to "true."
If this parameter is set to "true", the Glossary section is included. Otherwise, it isn't. By default, this parameter is set to "true."
If this parameter is set to "true", namespace information is provided when displaying sample instances and references. This is done by providing a prefix in front of tags and references, which when clicked, will take the user to the declared namespace. The prefix matches the prefix in the namespace declaration in the schema. If not set to "true", namespace prefixes are not displayed. By default, this parameter is set to "true."
The Output panel contains parameters for the output folder and output file:
The path of the folder containing the HTML result and the image files.
If it is true the HTML result is organized as a main file containing only a table of contents with links to other HTML documents containing descriptions of the schema components. If it is false all the documentation will be stored in one HTML file.
If enabled then the achors and links will be generated using the hashcode of the component identifier instead of using the identifier itself. This is useful when the schema componet names contain characters that are not directly supported by the browsers or by the file system.
It will be generated HTML documentation also for the XML Schemas included or imported by the schema specified in the Input panel.
It will not be generated HTML documentation for the XML Schemas included or imported by the schema specified in the Input panel.
The name of the HTML file containing the documentation of the XML Schema
the file which maps from file locations of "included" and "imported" schemas to the file locations of their xs3p-generated documentation. This file must be provided if either "searchIncludedSchemas" or "searchImportedSchemas" is set to true. If relative addresses are used to specify the location of external xs3p-generated documentation, they must be relative to documentation file currently generated.
![]() | Note |
---|---|
The external documentation files does not need to exist at the time of generating the documentation for the current schema. The mapping is specified in XML. The dtd and schema for this mapping syntax are "links.dtd" and "links.xsd" respectively. |
![]() | Note |
---|---|
The "xmlns" namespace attribute with the correct namespace must be provided in the mapping file for the xs3p stylesheet to work. |
If it is true the HTML result will be opened with the default Internet browser set in Preferences or with the system application for HTML files.
A well-formed XML document can be viewed and edited in <oXygen/> also as a tree of XML elements. This is possible in the Tree Editor perspective available from -> (Ctrl+T) or the toolbar button that provides specially designed views and toolbars and an editable tree allowing you to execute common actions for nodes of a tree like create and delete nodes, edit node names, move nodes with drag and drop.
If you want to be able to edit XML documents that are not well-formed all the time and still have a tree view of the document you should use the Outliner panel in the Editor perspective.
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+P) 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.
-> -> (![]() | Note |
---|---|
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 formatting of just one XML element see the action Pretty print element. 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.
To make a persistent copy of the results displayed in the Results panel from operations like document validation, checking the form of documents, XSLT or FO transformation, find all occurances of a string, applying an XPath expression to the current document use one of the actions:
-> - displays the Save Results dialog, used to save the result-list of the current message tab.
-> - displays the Page Setup dialog used to define the page size and orientation properties for printing the result-list of the current message tab.
For documents with fixed markup such as forms in which the XML tags are not allowed to be modified but only their text content, editing of the XML tag names can be disabled and re-enabled with an action available from
+ -> or from the toolbar buttonMost of the time you want the content of a document displayed on screen with zero transparency. When you want to focus your attention only on editing text content inside XML tags <oXygen/> offers the option of reducing the visibility of the tags by increasing their transparency when they are displayed. There are two levels of tag transparency: semi-transparent markup and transparent markup. For the opposite case, when you want to focus on the tag names, the text transparency can be set to one of two levels: semi-transparent text and transparent text. To change the level of transparency:
Click the toolbar button
to adjust the contrast of markup in Editor perspective.