XML Files

From HLKitWiki
Revision as of 09:39, 22 November 2008 by Rob (talk | contribs)
Jump to navigationJump to search

Context: HL Kit … Basic Concepts and Terminology 

Overview

All HL data files are stored as XML files, as are saved portfolios and most other files intended for user access. Consequently, you'll need to be familiar with the structure of these files in order to manipulate them appropriately. This section outlines the details you'll need to know for this purpose.

If you are not already familiar with XML, it is quite easy to learn, since XML uses simple text files that can be easily created or modified. For additional information on XML, there have been countless books published on the topic and there are extensive resources available on the internet. The official site can be found at the following link. http://www.w3.org/XML/

HL utilizes only the basic mechanisms of the XML standard, so HL files are quite simple to work with. Since XML and HTML both derive from the same set of standards, anyone even tacitly familiar with HTML will be able to pick up XML very readily – at least to the complexity level employed by Hero Lab (or the lack of complexity, actually).

There are numerous commercial, shareware, and freeware tools available for easily editing XML files. Each has advantages and disadvantages, so you will need to make the determination of which tool is "better" for yourself. It's also perfectly reasonable to edit XML files with a simple text editor, although you'll want an editor that at least offers line numbers, since errors are reported with line numbers to allow easy correction of problems.

Basic XML Terminology

You are assumed to be familiar with XML before attempting to write data files for HL. However, it's quite likely that you may be reviewing this documentation before deciding whether you want to try your hand at writing data files, in which case you might not know XML yet. So we've provided very basic definitions of a few fundamental XML terms below to help you better understand the Kit documentation.

Element HL data files are comprised of XML elements that define all of the information for a particular game system.
Attribute When creating data files, almost all information is conveyed through the use of attributes within the XML file format. Each XML element contains an assortment of zoro or more attributes, where each attribute defines a specific piece of information about the element.
PCDATA When a block of free-form text is required for an element within Hero Lab data files, that text is specified via the use of XML PCDATA. When using PCDATA, remember that you must enclose the entire text within a CDATA block as a wrapper if you utilize any of the XML reserved characters. The list of Reserved XML Characters is defined separately.
CDATA If you need to include special formatting and/or reserved XML characters within a PCDATA region, you will want to wrap your text within a CDATA block. A CDATA block simply prepends the text with the character sequence "<![CDATA[" and terminates the block with the sequence "]]>". The list of Reserved XML Characters is defined separately.
DTD Every XML file must be assigned a formalized structure for its contents. The formal specification of an XML file's structure is via a DTD (short for Data Type Definition). An appropriate DTD should be included with this documentation for every public HL file format.

Topics

The following topics are explained in the sections linked below.