About Mallard

What Mallard is

Mallard is a markup language used to write topic-oriented documentation that can easily be integrated into a Linux application. You can write and edit Mallard documents with a text editor, but raw Mallard documents can only be displayed instantaneously in Yelp, the GNOME help viewer. However, Mallard documents can be manually transformed to HTML, XHTML and ePUB using Yelp developer tools.

Mallard uses the topic as the basic building block of a help document instead of imposing a top-down order from a table of contents. This focus on topics allows many contributors to help with documenting their modules for users without needing to understand the entire documentation structure. Using Mallard also makes your documentation highly extensible. When an application is updated, new topic pages can be added without changing the structure of the existing documentation. This also allows plugin help to be dropped into place when a plugin is installed.

Topic-oriented documentation is inherently modular, so topics can be re-used in different documents. Each topic is independent and requires little to no background information to write. To make the documentation cohesive, stand-alone topic pages can be associated with background information that a user may want to understand, with a sub-topic, or with further topics that may interest them.

What Mallard is not

Mallard is not designed for reference documentation, and it is not the best tool for writing a novel. It is custom-designed for making topic-based user help attached to GUI software and currently has tools that have been tested and work well under Linux platforms.

Mallard is also not a layout tool for making printed or print-like manuals or books. Although the HTML it produces is clean and effective, Mallard does not handle large amounts of conceptual data well.