Editing XML tutorial

This article or section is currently under construction

In principle, someone is working on it and there should be a better version in a not so distant future.
If you want to modify this page, please discuss it with the person working on it (see the "history")

Introduction

This is a beginners tutorial for XML editing made from slides

Objectives

• Be able to read schemas and find other documentation
• Understand the necessity of using an XML editor
• Be able to edit XML without hand-editing tags, profit from DTD and Schema awareness
• Be able to check well-formedness and validate
• Be able to fix errors

Prerequisites

• Some idea what XML is about
• XML namespaces (some, have a look at the XML namespace article)
• HTML and CSS (some)

Next steps

• DTD tutorial
• XSLT tutorial
• XPath tutorial - basics
• XQuery tutorial - basics (if you have interest in XML databases)
• PHP - MySQL - XML tutorial - basics (shows how to display an XML result-set retrieved form MySQL with XSLT)

XML Principles

Let's recall some principles that you also may have read in the XML article.

Structure of an XML document

An XML document usually includes:

1. Processing instructions (at least an XML declaration on top !)
2. Declarations (in particular a DTD)
3. Element markup with or without contents (mandatory), i.e. elements delimited by tags: <start_tag>conents </endtag> or without contents like: <self_closing_tag/>
4. Attribute markup (optionally), i.e. attributes
5. Entities (i.e. symbols that are subsituted by other contents at runtime)
6. comments: '

XML documents are trees

For a computer person, an XML document is a tree (“boxes within boxes”). Inside a browser or most other clients, the document is represented as a tree-based data structure, the so-called Document Object Model (DOM)

Below is a CALS table example:

 <TABLE>  
   <TBODY>
     <TR> <TD>Pierre Muller</TD> <TD>http://pm.com/</TD> </TR>
     <TR> <TD>Elisabeth Dupont</TD> <TD></TD> </TR> 
   </TBODY> 
 </TABLE>

[[Image:]]

Well-formed and valid XML documents

Well-formed” XML documents must obey the following rules:

(1) A document must start with an XML declaration (including version number !)

<?xml version="1.0"?>

You may specify and encoding (default is utf-8). Of course this means that you'll have to stick to an encoding ! Make sure to check your editor's settings.

<?xml version="1.0" encoding="ISO-8859-1"?> 

(2) XML structure must be hierarchical

start-tags and end-tags must match

no cross-overs: ...... ....

pay attention to case sensitivity, e.g. "LI" is not "li"

"EMPTY" tags must use "self-closing" syntax:

e.g.

should be written as
, a lonely "
" would be illegal

(3) Attributes must have values and values are quoted:

e.g. <a href="http://scholar.google.com"> or <person status="employed">

e.g. <input type="radio" checked="checked">

(4) A single root element per document

Root element opens and closes content

The root element should not appear in any other element

(5) Special characters (!!) : <, &, >,", ’

Use < & > &aquot; ' instead of <, &, >,", ’

Applies also to URLs !!

bad:  http://truc.unige.ch/programme?bla&machin
good: http://truc.unige.ch/programme?bla&machin

Example of minimal well-formed XML document:

 <?xml version="1.0" ?>
 <page updated="jan 2007">
  <title>Hello friend</title>
  <content> Here is some content :) </content> 
  <comment> Written by DKS/Tecfa </comment>
 </page>
 <hello> Hello <important>dear</important> reader ! </hello>

This example:

• has an XML declaration on top
• has a root element (i.e. page)
• Elements are nested and tags are closed
• Attribute has quoted value

XML names and CDATA Sections

• Names used for elements should start with a letter and only use letters, numbers, the underscore, the hyphen and the period (no other punctuation marks) !

Good: <driversLicenceNo> <drivers_licence_no>

Bad: <driver’s_licence_number> <driver’s_licence_#> <drivers licence number>

• When you want to display data that includes "XMLish" things like the < sign that should not be interpreted, then you can use so called CDATA Sections:

 <example> 
  '''<!CDATA[ ''' (x < y) is an expression
    <svg xmls="http://www.w3.org/2000/svg">
 ''']]> '''</example>

Valid XML documents

Un valid document must be

1. “well-formed” (see above)
2. conform to a grammar (also called "schema"), .e.g. only use tags defined by the grammar and respect nesting, ordering and other constraints defined by that grammar.

Kinds of XML grammars:

• DTDs are part of the XML standard
• XML Schema (XSD) is a more recent W3C standard, used to express stronger constraints
• Relax NG (RNG,RNC) is a OASIS standard (made by well known XML experts and who don’t like XML Schema ...)
• Schematron. A complementary standard that is used to define additional constraints that can't be expressed with either XML Schema or Relax NG

Name spaces

It is possible to use several vocabularies within a well-formed document. If the markup language says so, such documents also can be validated

E.g. XHtml + SVG + MathML

However, the problem is then that the client application would not know which tags belong to which XML language. Also, there could be so-called naming conflicts (e.g. "title" does not means the same thing in XHTML and SVG).

To adress these problems one can prefix element and attribute names with a so-called name space

Declaring additional vocabularies

The "xmlns:name_space" attribute allows to introduce a new vocabulary. It tells that all elements or attributes prefixed by "name_space" belong to a different vocabulary

xmlns:name_space="URL_name_of_name_space"

SVG within XHTML example

 <html '''xmlns:svg'''="http://www.w3.org/2000/svg">
    <svg:rect x="50" y="50" rx="5" ry="5" width="200" height="100" ....

xmlns:svg = "..." means that svg: prefixed elements are part of SVG

Xlink example:

XLink is a language to define links (only works with Firefox-based browsers)

 <RECIT '''xmlns:xlink'''="http://www.w3.org/1999/xlink">
 <INFOS>
   <Date>30 octobre 2003 - </Date>
   <Auteur>DKS - </Auteur>
   <A '''xlink:href'''="http://jigsaw.w3.org/css-validator/check/referer"
      '''xlink:type'''="simple">CSS Validator</A>
  </INFOS>

Namespace declaration for the main vocabulary

The main vocabulary can be introduced by an attribute like:

 xmlns="URL_name_of_name_space"

Some specifications (e.g. SVG) require a name space declaration in any case (even if you do not use any other vocabulary) !

SVG namespace example

 <svg xmlns="http://www.w3.org/2000/svg">
    <rect x="50" y="50" rx="5" ry="5" width="200" height="100" ....

What are Namespace URLs ?

URLs that define namespaces are just names, there doesn’t need to be a real link. E.g. for your own puporses you can very well make up something like:

 <account xmls:pein = "http://joe.miller.com/pein">
   <pein:name>Joe</pein:name>
 </account>

... and the URL http://joe.miller.com/pein doesn’t need to exist.

Using DTDs (Document Type Definitions)

DTD grammars are just a set of rules that define:

• a set of elements (tags) and their attributes that can be used;
• how elements can be embedded;
• different sorts of entities (reusable fragments, special characters).

DTDs can’t define what the character data (element contents) and most attribute values look like.

Specification of a markup language. Is a DTD enough ?

The most important part in a specification (e.g. for XHTML) is usually the DTD, but in addition other constraints can be added ! In particular:

• The DTD does not identify the root element ! You have to tell the users what elements can be root elements
• Since DTDs can’t express data constraints, you may write out additional ones in a specification document

e.g. "the value of length attribute is a string composed of a number one of "inch", "em"

<size length="10cm">

A simple DTD example

 <!ELEMENT page  (title, content, comsment?)>
 <!ELEMENT title (#PCDATA)>
 <!ELEMENT content (#PCDATA)>
 <!ELEMENT comment (#PCDATA)>

A DTD document contains just definition of rules .... nothing else (see later for explanations)

Using a DTD with an XML document

A valid XML document my include a declaration that identifies a DTD to be used. Therefore, the <!DOCTYPE...> declaration is part of the XML file, not of the DTD ....

Example of an XML file with a DTD declaration

 <?xml version="1.0" encoding="ISO-8859-1" ?>
 <!DOCTYPE hello SYSTEM "hello.dtd">

There are four ways of using a DTDs

(1) No DTD (XML document will just be well-formed)

(2) DTD rules are defined inside the XML document

In that case, we get a "standalone" document (the XML document is self-sufficient)

(3) Private/System" DTDs, the DTD is located on the system (own computer or the Internet)

That’s what you are going to use when you write your own DTDs

(4) Public DTDs, i.e. we use an official name for the DTD.

This implies that both your XML editor and the user software knows the DTD. It's a strategy used for common Web technology DTDs like XHTML, SVG, MathML, etc.

Where to insert the DTD?

A DTD is always declared on top of the file after the XML declaration.

All XML declarations, DTD declaration etc. are part of the so-called prologue.

Syntax of the DTD declaration in the XML document

Every DTD declaration must start with

<!DOCTYPE .... >

The, the root element must be specified next. Remember that DTDs don’t know their root element, root is defined in the XML document ! DTDs must define this root element just like any other element ! In some cases, DTDs are meant to be used in different ways, i.e. several elements could be used as root elements.

 <!DOCTYPE hello .... >

The next elements of the DTD declaration are different according to the DTD type (public or private)

(1) Syntax for internal DTDs (only !). DTD rules are inserted between brackets [ ... ] <!DOCTYPE hello [

 <!ELEMENT hello (#PCDATA)>
]>

(2) Syntax to define "private" external DTDs: The DTD is identified by the URL after the "SYSTEM" keyword

<!DOCTYPE hello SYSTEM "hello.dtd">

(3) Syntax for public DTDs:

after the "PUBLIC" keyword you have to specify an official name and a backup URL that a validator could use.

<!DOCTYPE rss PUBLIC "-//Netscape Communications//DTD RSS 0.91//EN"
 "http://my.netscape.com/publish/formats/rss-0.91.dtd">

Recall

The DTD file itself does not contain any DTD declaration, just rules !!

Some examples of XML documents with DTD declarations:

Hello XML without DTD

<?xml version="1.0" standalone="yes"?>
<hello> Hello XML et hello cher lecteur ! </hello>

Hello XML with an internal DTD

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE hello [
   <!ELEMENT hello (#PCDATA)>
   ]>
<hello> Hello XML et hello chère lectrice ! </hello>

Hello XML with an external DTD

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE hello SYSTEM "hello.dtd">
<hello> Hello XèMèLè et hello cher lectrice ! </hello>

That’s what you should with your own home-made DTDs

XML with a public external DTD (RSS 0.91)

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE rss PUBLIC "-//Netscape Communications//DTD RSS 0.91//EN"
 "http://my.netscape.com/publish/formats/rss-0.91.dtd">

Understanding DTDs by example

Hello text with XML

http://tecfa.unige.ch/guides/xml/examples/simple/

A simple XML document of type <page>

<page>
 <title>Hello friend</title>
 <content>
      Here is some content :)
 </content> 
 <comment>
      Written by DKS/Tecfa, adapted from S.M./the Cocoon samples
 </comment>
</page>

A DTD that would validate the document[[Image:]]

A recipe list in XML

Source: Introduction to XML by Jay Greenspan (now dead URL)

<?xml version="1.0"?>
<!DOCTYPE list SYSTEM "simple_recipe.dtd"> 
<list>
 <recipe>
   <author>Carol Schmidt</author>
   <recipe_name>Chocolate Chip Bars</recipe_name>
   <meal>Dinner
     <course>Dessert</course>
   </meal>
   <ingredients>
     <item>2/3 C butter</item>      <item>2 C brown sugar</item>
     <item>1 tsp vanilla</item>     <item>1 3/4 C unsifted all-purpose flour</item>
     <item>1 1/2 tsp baking powder</item>
     <item>1/2 tsp salt</item>      <item>3 eggs</item>
     <item>1/2 C chopped nuts</item>
     <item>2 cups (12-oz pkg.) semi-sweet choc. chips</item>
   </ingredients>
   <directions>
Preheat oven to 350 degrees. Melt butter; combine with brown sugar and vanilla in large mixing bowl. Set aside to cool.  Combine flour, baking powder, and salt; set aside. Add eggs to cooled sugar mixture; beat well. Stir in reserved dry  ingredients, nuts, and chips.
Spread in greased 13-by-9-inch pan. Bake for 25 to 30 minutes until golden brown; cool.  Cut into squares.
   </directions>
 </recipe>
</list>

Contents of the DTD (simple_recipe.dtd)

[[Image:]]

A simple story grammar

[[Image:]]

Lone family DTD

family.dtd

[[Image:]]

A valid XML file

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE family SYSTEM "family.dtd">
<family>
  <person name="Joe Miller" gender="male" 
          type="father" id="123.456.789"/>
  <person name="Josette Miller" gender="female" 
          type="girl" id="123.456.987"/>
</family>

RSS

There are several RSS standards. RSS 0.91 is Netscape’s original (still being used)

<!ELEMENT rss (channel)>
<!ATTLIST rss version CDATA #REQUIRED> 
<!ELEMENT channel (title | description | link | language | item+ | rating? | image? | textinput? | copyright? | pubDate? | lastBuildDate? | docs? | managingEditor? | webMaster? | skipHours? | skipDays?)*>
<!ELEMENT title (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT link (#PCDATA)>
<!ELEMENT image (title | url | link | width? | height? | description?)*>
<!ELEMENT url (#PCDATA)>
<!ELEMENT item (title | link | description)*>
<!ELEMENT textinput (title | description | name | link)*>
<!ELEMENT name (#PCDATA)>
<!ELEMENT rating (#PCDATA)>
<!ELEMENT language (#PCDATA)>
<!ELEMENT width (#PCDATA)>
<!ELEMENT height (#PCDATA)>
<!ELEMENT copyright (#PCDATA)>
<!ELEMENT pubDate (#PCDATA)>
<!ELEMENT lastBuildDate (#PCDATA)>
<!ELEMENT docs (#PCDATA)>
<!ELEMENT managingEditor (#PCDATA)>
<!ELEMENT webMaster (#PCDATA)>
<!ELEMENT hour (#PCDATA)>
<!ELEMENT day (#PCDATA)>
<!ELEMENT skipHours (hour+)>
<!ELEMENT skipDays (day+)>

Possible XML document for RSS

<?xml version="1.0" encoding="ISO-8859-1" ?>

<!DOCTYPE rss SYSTEM "rss-0.91.dtd">

Summary syntax of element definitions

We will come back to this when we will learn how to write our own DTDs (don’t worry too much about unexplained details ....)

syntax element	short explanation	Example
,	: order of elements	<!ELEMENT Name (First, Middle, Last)>
?	: optional element	MiddleName?
+	: at least one element	movie+
*	: zero or more elements	item*
	: pick one (or operator)	law
()	: grouping construct	(A,B,C)

Entities

Most professional DTDs use entities.

Entities are just symbols that contain some information which substitutes when the symbol is used ...

2 kinds: XML entities and DTD entities

DTD entities

Some more complex DTD use the same structures all over. Instead of typing these several times one can use a ENTITY construction like this:

<!ENTITY % Content "(Para | List | Listing)*">

Later in the DTD we then can have Element definitions like this:

<!ELEMENT Intro (Title, %Content; ) >
<!ELEMENT Goal (Title, %Content; ) >

The computer will then simply translate these into:

<!ELEMENT Intro (Title, (Para | List | Listing)*) >
<!ELEMENT Goal (Title, (Para | List | Listing)* ) >

... think of these entities as shortcuts.

Choosing and using an XML Editor

There a lots of XML editors and there is no easy choice !

Depending on your needs you may choose a different editor:

To edit strongly structured data (i.e. data-centric XML) a sort of "tree" or "boxed" view is practical

To edit text-centric data (e.g. an article) you either want a text-processor like tool are a structure editor.

Really good XML editors cost a lot ...

Here is my own little comparison of XML editors:

http://edutechwiki.unige.ch/en/XML_editor

Minimal things your XML editor should be able to do

Check for XML well-formedness

Check for validity against several kinds of XML grammars (DTD, Relax NG, XML Schema)

Highlight errors (of all sorts)

Suggest available XML tags (in a given context). Also clearly show which ones are mandatory and which ones are optional, and display them in the right order.

Allow the user to move/split/join elements in a more or less ergonomic way (although it is admitted that these operations need some training)

Include support for XSLT and XQuery (However, if you have installation skills you can easily compensate lack of support by installing a processor like Saxon

Additional criteria depending on the kind of XML:

For data-centric XML:

Allow viewing and editing of XML documents in a tree view or boxed view (or both together)

Provide a context-dependent choice of XML tags and attributes (DTD/XSD awareness)

For text-centric XML:

Allow editing of XML documents in a structure view

Allow editing of XML documents in somewhat WYSIWYG view. Such a view can be based on an associated CSS (most common solution) or XSLFO (I am dreaming here) or use some proprietary format (which is not very practical for casual users!). Also allow users to switch on/off tags or element boundary markers.

Provide a context-dependent choice of XML tags and attributes (DTD/XSD awareness). The user should be able to right-click within the XML text and not in some distant tree representation.

Automatically insert all mandatory sub-elements when an element is created.

Automatically complete XML Tags when working without a DTD or other schema.

Indent properly (and assist users to indent single lines as well as the whole document)

Suggested free editors

Exchanger XML Lite V3.2:

http://www.freexmleditor.com/

I suggest to try this editor first, try the other one if you are unhappy with it or if you plan to edit "data-centric" XML documents.

Hints for editing

To insert an element or attribute:

In the contents window press Ctrl-T to insert an element.

Pressing "<" in the editing window gives more options and you can do it in any place.

To insert an attribute, position the cursor after the element name and press the space bar

Alternatively (and better if you don't know your DTD): Select the Helper pane to the left. Then (in the editing window) click on the element tag you wish to edit or put your cursor in a location between child elements. The helper pane will then display the structure of the current parent element and list available elements on which you can click to insert.

XMLmind Standard Edition:

http://www.xmlmind.com/xmleditor/download.shtml

Hints for editing

Element manipulation is trough the "tree view"

After selecting an element

you can insert elements either by selecting (tiny) before/after/within buttons in the top right elements pane

or use shortcuts: (ctrl-h = insert before, ctrl-i = insert within, ctrl-j = insert after). Same principle for the attributes pane.

Alternatives

Firstly, any XML editor is difficult to learn (because XML editing is not so easy). So make an effort to learn the interface, e.g. read the help !

Programmers also may consider using a programmer’s editor. However make sure:

that there is an XML plugin

that the editor is "DTD aware" (can show elements to insert in a given context)

that it can validate.

... otherwise forget it !!

About Java

Most XML editors are written in Java an rely on the "Java RunTime engine".

Both websites give you a choice: Download an editor with or without Java. If you don't have Java installed on your own PC, I suggest taking it first from:

http://www.java.com/ ... and always download the "no java vm" versions

To test if you have java, open a command terminal and type "Java".

To open a command terminal: Start Menu -> Execute and then type "cmd".

Next steps

Reading

These slides may not be enough to understand, so please read:

Carey (pp. 1-21, pp. 28-39)

Optional: 1 or 2 case problems

Next modules

Module 2

Display XML data with CSS in a web browser

Module 3

How to write a DTD

Homework: mini-project 1

Due: Monday March 29 9:00h

Task

Edit an XML document with the suggested DTDs below

Respect the semantics of the elements and the attributes

Validate your document

Try to use as many different elements as you can (if appropriate)

Follow additional directions for each suggested DTD

Add comments in the DTD or the XML file

You can choose among the DTDs availabe at:

http://tecfa.unige.ch/guides/xml/examples/dtd-examples/

Some DTDs commented

DTD (difficulty)	Purpose	file name	Additional directions
Recipe DTD (easy)	Write simple recipes	recipe.dtd	Use all tags. Write at least one recipe. Make sure that there is enough information to really use it.
Recipe Markup Language (medium)	Write complex recipes	recipeml.dtd	As above, but only use appropriate tags. Hint: find the website of its creator
RSS 0.92 (medium)	News syndication (usually machine generated)	rss-0-92.dtd	Use enough tags to display this in an aggregator. Enter at least 4 URLs. Hint: look at a RSS news feed first !
Simple Docbook (hard)	Write "real" articles	sdocbook.dtd	Do not use all tags, only the needed ones. Copy/paste from a text you already have.
StepbyStep (medium)	Write "how-to" instructions	stepbystep03.dtd	Make up a good "how-to problem". Only use tags you need..
Story grammar (medium)	Write simple fairy tales	story-grammar.dtd	Write a nice fairy tale. Doesn’t need to be your own.

Approximate evaluation grid

Minimal work required:	Probable grade
Wellformed (but not valid) document using the DTD’s elements	D
Valid (minimalistic) document	C
Valid document with an interesting content	B
Extra features:	Probable bonus (depends on quality)
Inserted useful comments in the XML and/or the DTD	+
You produce some interesting content	+ .. ++
Respect of the DTDs semantics	+
Write a 1-2 page report that discusses the architecture of the DTD and your opinion of it, e.g. describe architecture of the DTD (without going into detailed description of every element !) discuss what you would like to improve, what you liked/disliked, your difficulties, etc.	+ .. +++

Examples:

To get a B+ / A-: Firstly produce a valid document, then (a) either write a nice report or (b) document XML/DTD code and produce a nicely filled-in XML document

To get an A: do all of the above very well

Submission format and procedure.

Electronic copies: https://worldclassroom.webster.edu/Please make sure to name files according to the following rules:

File name	Example	when ?
your_name.xml	vasta.xml	This is a mandatory file !
xxx_your_name.dtd	vasta-sdocbook.dtd	only if you add comments to the DTD
pdf|html}	vasta.pdf	only if you decide to write a report