XDoc

XDoc: executable documents

XDoc stands for eXecutable Document and it is a generic container for various types of documents. Essentially, it is a Zip archive containing both content and a bit of metadata through which a player can decide how to present the content.

Currently, we support two types of contents:

  1. The contents of a Playground are serialized.
  2. Documenter documents like this one.

Every time a Playground, on every execution, is automatically serialized as an XDoc. Here is how it looks.

A Playground serialized automatically as XDoc
A Playground serialized automatically as XDoc

In this case, the contents of the Playground are serialized as a JSON.

In the case of a document like this one, we serialize both the original Pillar sources of the document and potentially multiple previews.

Example of an XDoc document
Example of an XDoc document

For example, a document is also exported in HTML form so that it can be previews on the web.

XDoc containing an HTML preview
XDoc containing an HTML preview

The format is generically described in a manifest.json with enough information so that a tool can interpret how it can react to the content. For example, the current XDoc looks as follows:

{
	"description" : "XDoc stands for eXecutable Document and it is a generic container for various types of documents.",
	"author" : "Tudor Girba",
	"documents" : [
		{
			"components" : [
				{
					"link" : "1"
				},
				{
					"link" : "2"
				},
				{
					"link" : "3"
				},
				{
					"link" : "4"
				}
			],
			"type" : "documenter"
		},
		{
			"components" : [
				{
					"link" : "5"
				},
				{
					"link" : "2"
				},
				{
					"link" : "3"
				},
				{
					"link" : "4"
				}
			],
			"type" : "html"
		},
		{
			"components" : [
				{
					"link" : "2"
				}
			],
			"type" : "preview"
		}
	],
	"attachments" : [
		{
			"filename" : "index.pillar",
			"size" : 1468,
			"id" : "1"
		},
		{
			"filename" : "pictures/gtr-xdoc-playground-preview.png",
			"size" : 995415,
			"id" : "2"
		},
		{
			"filename" : "pictures/gtr-xdoc.png",
			"size" : 960562,
			"id" : "3"
		},
		{
			"filename" : "pictures/gtr-xdoc-spotter.png",
			"size" : 843778,
			"id" : "4"
		},
		{
			"filename" : "index.html",
			"size" : 1947,
			"id" : "5"
		}
	],
	"title" : "XDoc: executable documents"
}

XDoc provides a simple bridge between the environment and the external world. A direct use case is that of sharing narratives created within the environment to the web. For example, this very document was created in Glamorous Toolkit and can be viewed on blog.feenk.com. Moreover, it can later be reloaded back into Glamorous Toolkit.

Pasting an XDoc url into Spotter shows a preview
Pasting an XDoc url into Spotter shows a preview