Xdoc is a simple documentation language for software projects. It focuses on, but is not limited to, Eclipse plugin projects, generating a fully functional Eclipse help plugin. We support code chunks and also code references to java classes in the class path. Error markers in the editor show the developers if any links to classes are broken.
In various projects the documentation is a rather tedious task. Choosing a language like LaTeX, it is possible to generate neat PDF documents. But as Latex is a rather complicated language, you have to learn it before you can actually write your documentation. In addition LaTeX is optimized for printed documents and does not feature HTML output. Of course there exists tooling for generating HTML documents, the structure of those was simply not what we where looking for.
Another possibility would be to use a language like textile. HTML can be generated easily. It is also possible to generate PDF or docbook XML files. It gives the writer of the documentation much freedom in formatting, like changing font color for paragraphs, changing the text alignment or even controlling the output HTML indirectly by setting spans’ attributes like id or class. These freedoms can be nice, but for a concise documentation languages they are not needed. They can even have a negative influence as an inconsistent style in a documentation can distract the reader.
So we started to develop a language with several concepts in mind. First: No freedom. The language is easy and simple. You can not adjust the design of the output in an Xdoc file. We think design should be made using CSS and also provide two ready to use CSS files, one to adjust the look of code blocks, the other to adjust the rest (e.g. headlines, tables, lists, …). PDF files are generated via LaTeX. This way you don’t need to layout the documents yourself as LaTeX is a highly optimized typesetting language. Currently we use Koma Script as documentclass, providing a modern layout for the documents. HTML files are generated directly. We also generate a toc.xml and a plugin.xml. This way the project can be exported directly as an Eclipse help plugin.
A description of the basic concepts follows.
Xdoc files can contain different top level elements, allowing to split up documents over different files. Top level elements can be:
document[title] defining a document with the given title that can be compiled
chapter:id[title] a chapter that can be referenced by chapter-ref[id]
section:id[title] a section that can be referenced by section-ref[id]
section2:id[title] a section2 that can be referenced by section2-ref[id]
Of course you are not forced to use this concepts and can write all your chapters and sections in one file. The maximum depth for sections is section4:id[title].
If you want to start a new paragraph use two newlines.
I said, we don’t allow for formatting. But Xdoc features the emphasis concept. Using em[some text] you can denote parts that have to be emphasized. This does not mean, that it will be nessecarily set in italics.
Typically in the documentation of a software project you drop a line of code here and there. To support this we have the code[language][some code] concept. Like in textile the style is guessed from the input. If you write it it in one line it will be typeset as inline (i.e. span in HTML). If you have newlines in your code it will be typeset as a block. The language of a code element can be defined at the beginning of the document as a list of keywords. Keywords occurring in a code block will be highlit in the output.
We also allow for code references to Java. These are real links and break when a referenced class name is changed. This behaviour enforces a consistent documentation and is of course supported by the tooling.
Of course we have lists and tables. Lists can be ordered (ol[<items>]) or unordered (ul[<items>]). Both contain some items which can be enumerated with <code>item[some item text].
A table is defined by table[<rows>] and contains rows (tr[<cells>] which in turn contain the table data entries (td[some text]). Each row must contain the same number of data entries.
Like in HTML we support for hyperlinks (link[<url>][some text], the text can also be obmitted if you want the link to be directly readable) and references (ref:id[some text]</text>, where text can be omitted again to autoinsert some alias for the referenced element, e.g., section §2). References can be seen as internal links and can target any kind of element that has an id. Those are all section types, images and anchors (<code>a[id]. Anchors are special elements that do not contribute to the visible output but only serve as reference targets.
For the PDF output to be meaningful when it is printed we add a list of links at the end of the document.
As another concept we also added TODOs. These are ignored in Eclipse help output but inserted as orange boxes in the PDF. Also a list of TODOs is inserted at the end of the document. You can switch the typesetting of TODOs on and off.
Xdoc is based on Xtext 2.0 git master branch (git://git.eclipse.org/gitroot/tmf/org.eclipse.xtext.git). As Xtext 2.0 is currently under development Xdoc can be subject to API changes. If you want to import Xdoc to your Eclipse workspace I recommend you follow the workspace setup guide at the Xtext homepage .
This project is funded by the Federal Ministry of Education and Research, Germany.