Welcome to ElfData XML Editor

 

 The help file for XML Editor

ElfData XML Editor is designed to be a clean fast and integrated editor and validator for XML 1.0. If you have any problems, requests or suggestions about anything XML Editor related, email them to the author at <support@elfdata.com>. The next section below is a listing of all the areas covered in this help file.

 

Topics

  1. Feature list
  2. Instructions on how to use
  3. General tips
  4. Speed tips
  5. Definitions
  6. Purchasing XML Editor
  7. Learning XML in general
  8. Contact us, and find more information

 

 XML Editor feature list: 

Notes: We normally call the "Graphical mode", "Tree-Mode" instead, but used Graphical here for faster comprehension to new comers. In the rest of the documentation the "Graphical mode" will be called the "Tree-Mode".

 

How to use XML Editor:

This section teaches you how to use XML Editor. You can learn much of XML Editor's usage here. Other tips and tricks can be read in the two "tips" sections.

Descriptions for:

  1. Editing XML
  2. Validating XML
  3. Sending files to an XSL / CSS viewer
  4. Holders - Storing and quickly accessing pre-built XML templates.
  5. Find features
  6. OSX Shell Scripts

 

Editing XML

The "Tree-Viewer" is the hierarchical ListBox that occupies the document window in the "Tree-View" mode. You can control and edit this document by using the buttons on the tool bar. To find out what the buttons on the tool bar do, move the mouse over the buttons and read the tool-tip help that appears at the bottom of the tool bar.

To create new elements in the Tree-Viewer, click the "New Element" button, this button has the icon of two blue angled brackets.

When selecting elements, XML Editor doesn't allow you to select elements that are have different parents. This is to make sure that row-moving and other operations will make sense.

The Tree-Viewer and the Source Editor give you many features for editing, viewing and analysing your XML. These features are listed below.

Features of the Tree-Viewer: 

 

Tree-viewer keyboard navigation:

 

Property viewer features:

 

Features of the Source Editor:

 

Validating XML

Validating XML is one of the biggest features of XML Editor. XML Editor has many modes of validation, each designed to be useful for diffecent situations the user could be in, or for differing user needs. Below is a list of the different kinds of validation available.

  1. Once-off validation
  2. Validation after every change
  3. Validation of elements under the mouse
  4. Validation of the selection
  5. Batch validation

 

Once-off validation

To simply check for Well-Formedness, choose "Check Well-Formedness" from the "Tools" menu. If you choose this and there is a DTD, the DTD is ignored. This is one form of "Once-off" validation, there are others also.

To get validation working with DTD, you need to make sure the XML has a reference to the DTD such as: <!DOCTYPE documentRoot PUBLIC "-//identifier//EN" "mydtd.dtd"> at the beginning of the XML, before the main root and after the <?xml version="1.0"?> tag. This is how XML documents should be formed when using a DTD according to the XML 1.0 Specification.  

Validation after change

Validation after change has the same requirements for use, that once-off validation does. You can only enable it if these requirements are met (requirements such as that there is a DOCTYPE tag). To enable it, go to "Validate After Change", in the "Tools" menu. Your XML will be validated against the DTD every time a change is made. For example, dragging XML around, creating a new element, deleting an element, editing the properties.

This also works in the source editor mode. You can choose to have validation occur after your typing stops, so that the the pauses in validating large documents, won't get in the way of your typing. The delay period can be chosing in the preferences. If it is set to 0, then it happens after every change, including every keypress. If validation after change is on, then you can press "Enter" to get the validation happening straight away, instead of having to wait until the delay period is up. This doesn't happen if you press Enter while Validate after Change is off.

Validation of elements under the mouse

You can validate only the element under the mouse, by enabling "Validate Under Mouse" from the "Tools" menu. This allows you to validate an element in isolation from the rest of the document, by moving the mouse over it.

Validation of the selection

You can validate only the selected elements, by choosing "Validate Selection" from the "Tools" menu. This validates only the selected elements. This can be used very usefully in combination with contextual menus. A contextual menu is accessible from using the control-click short-cut. Control-click on an element, and it will be selected, and a menu will appear. "Validate Selection" is in this menu, so choosing that will validate the element you control-clicked on. All done in one nice easy step.

Batch validation

Batch validation can validate an entire folder of XML, in one go. The results are logged to a window in XML Editor, and also to a log file (optionally). You can drag a folder to the window, instead of clicking the "Choose" button to find the folder. The report will offer results on each file, that tell you if there was a sucess or failiure, and log the reason why, if there was a failiure. It also logs the overall result, and the time taken (in seconds). You can save the report in XML if you want, or in a format that is human readable.

  

Getting XML Editor to find the DTD

There are several methods XML Editor uses find DTD files. If your file can be found by any one of them, then you can validate your document with the DTD. Your DTD only needs to be found by one of these methods, so you can pick one which is easiest for you. XML Editor does not download DTD files from the Internet for validation. This would make XML Editor unusable for modem users, and anyone who can't be connected to the Internet all the time. The file should be accessible over your file system.

 

List of available DTD finding methods:

  1. If the URL in the DTD is a filepath (file://Hard Disk/folder/file.dtd), then XML Editor will attempt to load it, without it needing to the in the DTDs folder. This is useful for DTDs on MacOS X for example.
  2. XML Editor next looks in the "DTDs" folder. If the DTD has an URL which is only a file name, like "myfile.dtd", then XML Editor tries to find the file with this name in the DTDs folder. If the URL is a file path, such as "myfol/myfile.dtd", it attempts to navigate the filepath, starting from the DTDs folder, to find the DTD file
  3. XML Editor next looks next to the file itself. If there is a DTD file with the name requested, next to the XML file, it is chosen. If the URL is a file path, such as "myfol/myfile.dtd", it attempts to navigate the filepath, starting from the folder your XML file is in, to find the DTD file
  4. The DTD Identifier, eg "-//identifier//EN" is used to find the DTD. XML Editor has a list of registered identifier-to-filenames. If you have registered an Identifier to belong to a file name, then this filename is searched for in the DTDs folder. Registering Identifiers is done from the "DTD Matching" window, which is accessible from the "DTD" menu, in the "Tools" menu. There are two ways to add files to the "DTD Matching" window.
    1. Open the DTD Matching window. Click on "Add match", you will see the file added to the list. Then click on the file in the list, and you can edit the Identifier and file path. Scan files won't find files in a sub-folder. To do this, follow instruction 3.2 (the next instruction!).
    2. Drag a file (folders don't work) onto the "DTD Matching" window, and the file is added. You then need to alter its identifer to the identifier you wanted.
  5. If the DTD can't be found, XML Editor asks you to find it. Otherwise the Identifier and file path is automatically added for you. This is maybe the easiest way to add a DTD file to the DTD Matching window.

If the DTD can be found, then press "Validate" from the menu, or click on the "tick" button on the document window. Your document will be validated.

If you find DTD validation is slow, which can happen if you are using the DocBook DTD (around 500k of a DTD file!) then read the "Speed Tips" section. You can escape parsing the DTD by holding down the "Escape" key on the keyboard until the parsing stops. Just pressing it and releasing straight away is unlikely to escape parsing. By using the speed tips, you can get the initial parsing of the DocBook DTD down from 45 seconds to 2 seconds. Subsequent parsing is always almost instant anyhow, even without using the speed tips.

 

Sending files to an XSL / CSS viewer

You can send XML files directly to Internet Explorer, or your preferred XSL / CSS viewer, from the "Show In Browser" menu (Command-Option-B), or just click on the "Show In Browser" button, on the Toolbar. This lets you view the results of your actions very much faster than manually going to your preferred XSL viewer, and choosing "Open...", because it opens instantly. Internet Explorer 5 has good support for XSL and CSS, and is free, so this is the usual choice of an XSL viewer.

You can edit the list of browsers that you want your XML files to be opened in, from the "Edit Browser List" menu, inside the "Show In Browser" button on the toolbar.

XML Editor does not directly display XSL or CSS right now.

 

 Holders 

Holders allow you to quickly enter pre-made XML into your XML document. You can access them via the "Holders" menu. Holder windows stay open between launches, so if you have your holder window open, and quit, the window will be there next time you open XML Editor.

You can create a new holder either by using the "New Holder" menu, or by choosing "DTD To Holder", both from "Holder Tools", in the "Holders" menu. "DTD To Holder" creates a holder, based on the DTD. The holder file will contain entries for every element defined in the DTD, along with their attributes. From the "DTD To Holder" dialog that appears, you can choose elements with which modifiers will be created as sub-children. Ususually, you want to have only necessary elements created as sub-children, that is elements marked with "+", or without any modifier. Eg: "<!ELEMENT tag (subtag1, subtag2+)>" should be turned to a holder, with both it's sub tags created as sub-children.

You can show the folder in the Finder, that the holders exist in, by choosing the "Show Holder Folder" menu. You can rebuild the "Holders" menu by choosing the "Rebuild Holders Menu", this is useful when you add or remove files to the Holders folder in the Finder, and want to tell XML Editor that the files there have changed. You can select holder items by clicking on them, this allows you to do commands on the selected item.

Customising your holders

Using the holder

The holder is used for fast entry of XML. Here are the ways you can use it to enter XML:

 

 Find Features

There are two find modes. One for each viewing mode. The Tree-Find mode is the more powerful find.

You can search for different types of elements, such as empty elements, normal, processing instructions, exclam-elements "<!DOCTYPE>", comments and CData.

Searching is done on the name / value entry field. If the name of an element is the name, then it is matched. If a text/comment/cdata contains the value (not just is the value), then it is matched.

You can enter "****" to match any name / value. This is useful if you only want to search by attribute name / value, or simple want to find all exclam elements in the document.

You can choose to find with case sensitivity or not. If case sensitivity is off, then "a" is matched with "A". Otherwise "a" is not matched to "A".

You can search for attribute names or values, together or separately. To not search attribute names or values, leave the field in question blank. To search attribute names, enter text in the field. If you don't want to find any particular value, then enter "****" into the attribute value, and only the attribute name will be searched for. To search for just an attribute value, enter text into the value field and leave the name blank.

Clicking on any of the results selects it in the Tree View. If the item in the Tree View is in an unexpanded row, then the rows containing the item are expanded to show it.

 

 OSX Shell Scripts

Shell scripts can be executed, from inside XML Editor. You can do this, via the "Scripts" button, on the toolbar. This button appears to have a small "curvy paper" icon. The scripts XML Editor uses, are stored in the "Scripts" folder, next to XML Editor itself. To make a script executable by XML Editor, simply drop the script file inside XML Editor's "Scripts" folder.

XML Editor can set unix environment variables for you. Currently, it has only three unix environment variables. Environment variables are variables, that the shell script can read and use. They appear like this "$myvariable", inside your shell script file. For XML Editor to set the environment variables for you, you will need to alter the script files to read in the variables that XML Editor sets for you.

XML Editor sets these 3 variables for you:

  1. DOCPATH - The path of the file, of the front window.
  2. DOCNAME - The name of the file, of the front window.
  3. DOCBASENAME - The name of the file, minus the extension, of the front window.
  4. DOCPATHPREFIX - The path of the folder that contains the file of the front window.

 

Tips 

  1. Double clicking on a tag marker (< or >), bracket, or brace character, selects the entire group. This works over embedded groups, like "(tag1, (g1 | g2 | g3))". This works in the source editor, the property editor, and the error message viewer.
  2. Create a "Sounds" folder, next to XML Editor itself, and put some sound files there. The files can have the names "bad", "valid", or "wellformed" (case doesn't matter). Try validating some XML, and you'll find you hear sounds! Quite useful when "Validate After Change" is on, in the source mode, because otherwise you don't quite know when a validation has occrured.
  3. Create a "Pictures" folder next to XML Editor, and put in it, a picture called "toolbar.pict". You'll see the picture is put on the tool bar, underneath everything else.

 

Speed Tips

Some things in XML Editor can be sped up. Here are the things that can be sped up, and descriptions of how to do it.

  1. Large XML files. If you have a large XML file, say around 300k and find XML entry is slow, then set the "level of Undos" in the preferences to zero. Undo works by rendering the entire XML to a string and caching that string, which for a large complex file, may be slow. For general to moderately heavy use, you should find XML Editor quite fast however.
  2. Large DTD files. If you are dealing with something incredibly complex like the DocBook DTD, then you may find DTD verification very slow (40 seconds). The DocBook DTD is around 560KB. For XML Editor to parse this the DocBook DTD, it must do an entity mapping (text replacements) over the entire 560k file, for every entity, of which there are thousands in the DocBook DTD, amongst other things. If you have stringent entity parsing on, then things are far more involved for XML Editor. There are several things you can do to speed up DTD Validation:
    1. Go to the preferences, and set the DTD Entities parsing to "fast". It is really very rare that you need the stringent version. The fast version is actually pretty stringent anyhow, and only removes one bottle neck, which is the mapping of new entity combinations that appear after entities have been mapped, over a large file.
    2. Don't alter the DTD file, change the file's modification date, edit / create / delete the internal DTD, or validate XML files that use other DTDs than the DTD you just validated with. XML Editor caches the resulting data from parsing a DTD, so the next validation is near instant. But if you change the DTD (internal and/or external), XML Editor must rebuild the DTD over again. If you validate another file and this file uses a different DTD, then XML Editor replaces the cache with the DTD of that file.
    3. Create a DTD file cache. You can do this, by choosing "Save DTD Cache To File", from the "DTD" menuitem, in the "Tools" menu. This saves the cached DTD, in a "Cache" folder, in the DTDs folder. When XML Editor looks for a DTD and finds one, if it finds a cached version existing in the "Cache" folder, it uses this instead. This can get DTD loading around 23x faster for DocBook.

 

Definitions

White space handling: There are two white space handling modes. You can select your preferred mode from the Preferences menu. The "Ignore unnecessary white space" setting, ignores white space between tags <tag> </tag>), and also, between tags and text <tag> text </tag<), except for 1 white space on either side of the text. It does not do anything to white space contained inside text (a b). This white space is kept "as is", even if it makes the formatting not look "neat". If you want to handle formatting and white-space yourself, then turn "Ignore unnecessary white space" off in the preferences. You can use the "Clean XML" command from the "Tools" menu, to clean the XML source, even if you have "Ignore unnecessary white space" off.

 

Help with purchasing

To purchase XML Editor click here.

 

Learning XML

If you want to learn about XML, here are some good websites to visit. These are especially good for complete beginners: www.w3schools.com/xml/, www.about.com and to learn about DTD, (which is part of XML) visit: www.w3schools.com/dtd/.

If you need the technical specification that defines XML 1.0, visit http://www.w3.org/TR/2000/REC-xml-20001006. The XML 1.0 specification is not aimed at beginners. It is designed to give a thoroughly precise plan describing XML and how it acts, and what it is meant for. It may be of more use to programmers than XML builders.

There are many good books on XML. You can search www.amazon.com for books about XML. "XML Pocket Reference" is a nice book to start with.

 

 Contact and more information

To find more information on the Internet about XML Editor, go to the URL: www.elfdata.com/xmleditor/

If you like XML Editor, tell your XML using friends about it so that more Mac users can enjoy it. If you have a problem with XML Editor, please tell the author about it, so that I can fix it.

Contact: To contact the Author (otherwise known as "Theo"), email: support@elfdata.com.