From the NannyMUD documentation

LAST CHANGE

2000-12-17

TOPIC

NAME
        XML doc system - NannyMUD documentation in XML.


DESCRIPTION
	INTRODUCTION

	The XML documentation system was created to solve certain
	problems, detected in the fall of 2000, with the ihelp
	system.

	+ The amount of documentation.
	The documentation is immense. The sheer amount of text that
	needs to be processed to index things has long ago passed the
	limits where it is unsuitable to do so using LPC.
	
	+ The lack of structure in the dokumentation.
	The format of the documentation files has been improved
	through the years, but it still has too little
	meta-information to be used efficiently. For example, it is
	very hard to extract subtopics and property descriptions from
	the files describing standard lib objects.

	+ Conversions to other formats.
	The format of the documentation files is not easy to convert
	to other formats, such as HTML or Microsoft help format. We
	would like to do that, allowing our wizards to download and
	read the documentation off-line.

	+ Technical problems.
	The ihelp system has been changed and patched so many times,
	that the code has reached the point where it is hard to
	maintain. Further changes are problematic, but needed. For
	example, it cannot handle if the same subtopic exists in more
	than one place.

	SYSTEM OVERVIEW

	The documentation is stored in text files with the suffix xml,
	and they follow a DTD which is available from NannyMUD's WWW
	page. The full URL is specified in the xml-files.

	An external Perl program parses the xml files, producing files
	with the suffix r2r (eady-to-read), and four index files. The
	r2r files are parsed as far as is possible without knowing the
	settings of the players inside the MUD.

	The Perl parser is run from a cron job on the MUD-host. It
	will keep track of what files needs to be updated by checking
	the last modification time of the xml and r2r files, as well
	as itself. If the parser has been modified, all r2r files are
	updated. The index files are updated at each run.

	The index files are read by a daemon, /obj/util/xmand, which
	caches the data. It keeps track of when it needs to re-read
	the index files. The daemon offers an API towards a client
	object (feel free to write your own client).

	The daemon is used by the client object. The client available
	so far is a module to the wizmod. It is named 'xmanmod'.

	LIMITATIONS
	The XML doc contains only the documentation for wizards, and
	then only the parts available under /doc/xml. It does not
	support topics added by creations of wizards. In particular,
	it does not support topics added using eval() syntax.

	FUTURE EXTENSIONS
	The following is a short list of possible future extensions
	that could be implemented.
	+ Interactive traversal of the help tree, much like ihelp's.


SEE ALSO
        xmand in xdoc/xmand


SEE ALSO
        xmanmod in xdoc/xmanmod