From the NannyMUD documentation

LAST CHANGE

2000-12-20

TOPIC

NAME
        adding - Adding new XML documentation.


DESCRIPTION
	INTRODUCTION

	This document is of little interest unless you are part of the
	MUDs admin, or for some other reason will be adding
	documentation under /doc/xml.
	
	Adding new documentation contains several step described in
	detail below:
	
	+ Write the documentation.
	+ Validate the documents.
	+ Add the new documentation to the system.


	WRITE THE DOCUMENTATION
	When you write new documentation, you must ensure that you
	produce a valid XML document. This means that the docuemnt has
	to follow certain conventions. If it does not, the XML
	standard says that the parser must abort the parsing. It is
	allowed to generate an error message, too.

	This means that if you manage to add a faulty XML doc to the
	NannyMUD documentation, you will disrupt the system.

	A valid XML document:
	+ follows a DTD, Document Type Definition, and
	+ is well-formed.

	The DTD specifies what XML tags can be used, and the allowed
	structure of the document. It also specifies what entities
	are allowed.

	To be well-formed, the XML document must follow the following
	rules:
	+ The XML declaration must begin the document.
	+ The DTD declaration must appear right after the XML
	  declaration. 
	+ Elements that contain data must have both start end end
	  tags.
	+ Elements that do not contain data and use only a single tag
	  must end with />.
	+ The document must contain exactly one element which
	  completely contains all other elements.
	+ Elements may nest, but shall not overlap.
	+ Attribute values must be quoted.
	+ The characters < and & must only ge used to start
	  elements and entity references respectively.
	+ The only entity references which appear are
	  &,
	  <,
	  >,
	  ', and
	  ".


	VALIDATE YOUR DOCUMENT
	To test if your document really is a valid XML document, you
	need to run it through a validator which can use the
	associated DTD. There are several such validators available on
	the internet. Here are the URL of two of them:
	
	+ http://www.stg.brown.edu/service/xmlvalid/
	+ http://www.hcrc.ed.ac.uk/~richard/xml-check.html

	There are also validators available in various programming
	languages, such as Perl, Python, Java, ...


	ADD THE NEW DOCUMENTATION TO THE SYSTEM.
	Now when you know that your documents will work in the system,
	add it to the docs under /doc/xml. If you are doing this from
	a Lysator account, make sure the file protections are
	correct.


NOTE
        The presentation of XML here is by necessity brief and
        incomplete. For a complete and in-depth presentation of the
        subject, you will have to read some books. There is of course
        a lot of material available on-line, too. A good place to
        start would be www.w3c.org.


SEE ALSO
        xmand in xdoc/xmand


SEE ALSO
        xmanmod in xdoc/xmanmod