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.
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.
For example, a document is also exported in HTML form so that it can be previews on the web.
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.
