AROSAmiga Research OS

Previous Next Top of Manual blank.gif

AROS - The Amiga Research OS

    Old News
    Coding Style
    HIDD Intro
    HIDD Model
    Random Ideas
1. XML Rules
1.1 Basic markup rules
1.2 User specific entities

1. XML Rules

These are rules for XML files for AROS. XML does not rule :-) There are various reasons why XML sucks:

  1. To process XML, you must have several MB worth of software installed (parser with encodings, a processor and all must work together).
  2. This huge software usually has bugs (encodings which don't work, XPaths which work with one processor and not with another, different versions of the standard, etc).
  3. Writing DTDs (which define how a document must look like) is simple but DTDs are not very powerful (Just try to simulate our <code> element which is terminated by "</code>" and not by the next element which is usally part of an if()).
  4. Exesise for the curious reader: Write a DTD which has an element <duration>. The <duration> element has an attribute time which can have the following values: 4, 8 and "One Day" (note the space).
  5. Writing transformers with XSL T is clumsy and mistakes (frustration) are common.
  6. If XML is simple, why is it explained in a 800 page tome ?

To make a long story short, Aaron "Optimizer" Digulla has defined a subset of XML which is used in AROS to document things. The goal was to have something which is close enough to XML to eventually allow to convert it into full fledged XML (so XSL processing would be an option if someone was insane enough to try) but flexible enough to be used by humans (as opposed to XML which is meant to be created by software and read by software without any human intervention). This way, the best of both worlds should be available

1.1 Basic markup rules

AROS' version of XML uses the same rules for elements as the normal XML. Since XML needs < and > to delimit elements, you must write "&lt;" and "&gt;" (without the quotes) respectively. To get an &, you must write "&amp;". And to complete things, the XML encoding for " (&quot;) is also supported. These things are called entities.

A tag is something between < and >. <code> is a tag with the name "code". </code> is also a tag as is <code/>. They all have the same name but slightly different meanings.

This is the beginning of an element.
This is the end of an element.
This is an empty element.

An element is something between two tags with the same name. <p>Some text<p> is an element with the name "p" and the contents "Some text". <br/> is an element with the name "br" and no contents.

In addition to contents, an element can have attributes. Attributes are added the the start tag of an element and look like this: name="value". So <p align="center">Some text<p> is an element with the name "p", the attribute "align" and the contents "Some text". The attribute "align" has the value "center". Note that the value of an attribute must be quoted.

Unlike HTML, elements must always be complete. So you must either write <p></p> or <p/> but you must not omit the end tag.

Also note that every document must have exactly one element which contains all other elements. This element is referred to as "root element".

To put a comment in XML, use "<!--". The comment is terminated with "-->". The XML parser looks exactly for this string and will ignore anything else.

1.2 User specific entities

An additon to &lt;, &gt;, &amp; and &quot;, one can add other, user specific entities to AROS' XML parser. Basically, an entity must be a piece of XML which will be inserted at the current position. So defining an entity with the contents ".</p>" does not work.


Since AROS doesn't use a real DTD, parsing is much more flexible but explaining what elements can be used where is more complicated :-) Most elements can be used everywhere. Here is a table:

Element Explanation Usage info
p Used for paragraphs. Can contain text and most other elements.
ul Unordered list. Use <li> elements as children. Can only contain <li> elements.
li This is a list item which is used in all types of lists. ul, ol, description
strong Mark some text as important (bold)
i Italics
a A link (<a href="url">text</a>) or an anchor (<a name="id"/>).
tt Use a typewriter font for the contents
img An inline image: <img src="url" width="..." height="..." alt="..."/>
ol A numbered (ordered) list
br An empty element which starts a new line (BReak).
chapter Usually the root element of the documentation files. It has one attribute "title" which is the title of the chapter.
section This is a section of something larger. Usually used in a <chapter> element. It has one attribute "title" which is the title of the section. chapter
subsection A part of a <section> element. It has one attribute "title" which is the title of the subsection. section
email Describes an email address. Give the email address you want to describe as contents. It has the optional attribute "subject" which should be the subject of the mail sent to the address and "body" which should be the text in the email.
example An example is an element which contains fixed lines of text which make up an example. The only valid children of an <example> element are <line> elements.
user A <user> element contains something which the user must enter and possible modiy, for example: To copy a file, use "cp <file1> <file2>". Often used in <example> elements
shell This is something which the computer will display, for example the prompt the the shell or output of a program which the user has run. It's usually used as a guideline for the user what he should see on the screen as the result of something he has done. Often used in <example> elements
prompt Use this empty element if you need a shell prompt. Often used in <example> elements
code The <code> element is used to mark source code (C source in this case). An HTML converter can use syntax highlighting on the contents, for example. The element can contain arbitrary text and must be terminated with a </code> element. The XML parser will just look for the string "</code>" ignoring everything else.
filename Use to mark a path or a filename. An HTML converter could replace this with a link to the file.
class The name of an OOP class
idea This is something like a section. It has an attribute "title" and an attribute "by" which should specify who had the idea (in case you want to ask specific questions). Besides all normal elements, you can use <comment> elements to add comments to an idea.
comment This is a comment to an idea. It has an attribute "by" to specify who made that comment.
description A list of descriptions. Every description is a <li> element which must start with an <item>element. Can only contain <li> elements.
insert Insert something here (for example, the list of developers). The contents of the element describe what to insert.
tree A recursive tree of items. Can be used to describe a hierarchy of things. A tree can only contain <item> elements which can in turn contain <tree> elements and text which describes the item.
item An item is used an several places. It can be used in a <li> element of a description list to specify what is described (contents of the <item> element). And it can be used in a <tree> element to describe a recursive tree. In a tree, an <item> element has an attribute "title". description, tree
autodoc Contains an AutoDoc description if there is no source file from which one can be extracted. Must contain <name>, <function>, <input> and <result>. Can contain <notes>, <bugs> and <seealso>.
name Describes what this <autodoc> element is about autodoc
function Explain this <autodoc> element. autodoc
input If this is a function, explain the input parameters with <parameter> elements. autodoc, can only contain <parameter> elements
parameter Explain a parameter of a function in an <autodoc> element. The attribute "name" specifies the name of the parameter. The contents contain the explanation. input
result Explains the result(s) of this <autodoc> element. autodoc
seealso A list of items which are related to this <autodoc> element. autodoc, can only contain items
table A HTML table
tr A row of a <table> element table, can contain th and td
th A heading for a table column tr
td A cell of a table tr

Previous Next Top of Manual blank.gif

Amiga® is a trademark of Amiga Inc. All other trademarks belong to their respective owners.

Copyright © AROS - The Amiga Research OS
All Rights Reserved
Comments to webmaster:
Generated: Sun Sep 2, 2001