Home

What is CommonMark Help?

The goal of the CommonMark Help project is to create an on-screen help system that can provide usage instructions for desktop applications. Text contents in the help files is written in Markdown format conformant to the CommonMark specification. To do so, several aspects will be covered:

• A file format definition describes how a CommonMark Help file is structured and what contents it can include.
• A compiler can generate a CommonMark Help file from a set of content files.
• A viewer can display a CommonMark Help file to end users.

Why does it exist?

In the "old days" of Windows 3.11 until approximately Windows 98, most Windows applications used to come with a help file. The help file could be browsed as a whole by means of a topic hierarchy and a searchable keyword list, and specific topics could be opened directly from appropriate locations within the application. All of this happened in a relatively standardized user interface, so users would not need to re-learn how to use the help system for each application.

The help system available back then, Microsoft's WinHelp, has since been discontinued. Various possible alternatives have found somewhat widespread adoption since then. However, each of them has its drawbacks, which CommonMark Help hopes to address:

MS Compiled HTML Help

The successor of WinHelp is a good replacement in certain circumstances, but has some issues when used across network drives. Furthermore, properly providing help content written with some non-Latin character sets can be problematic.

MS Help 2

This format never really seemed to be used a lot beyond MS Visual Studio and MS Office and has meanwhile been discontinued.

MS Help Viewer

This format is meant to be the successor of MS Help 2, but rather than an actual viewer application, it forwards help content to the user's web browser. While this may be appropriate for huge modular documentation packages such as API documentation, it deviates from the simplicity of a compact help file that can be opened with a desktop application that provides most of the navigation user interface and that is independent of the user's other open processes.

PDF files

PDF files conveniently allow for packaging rich content with internal links in a compact file. However, they are designed for representing printable output, and the fixed layout of pre-defined page sizes lacks some of the advantages of resizeable help viewer windows whose contents adapts to the current window size in a fluid way.

HTML files

HTML files can be opened on virtually every device and allow for styled, linked content. However, they do not normally come as a packaged help archive, but as a set of many interdependent files, which makes them less convenient to manage, should a user want to do anything with a help file (rename, copy, download, ...). Moreover, any means of navigation (contents tree, searchable index, ...) needs to be defined entirely by the HTML files, and will therefore, if at all present, look and feel differently for each application on the user's machine.

Why base it upon Markdown according to the CommonMark specification?

Markdown was chosen as the underlying document format for the following reasons:

• Featuring only minimal markup or other inline command structures, Markdown is relatively easy to learn.
• As Markdown is used on an increasing number of development-related websites, it is somewhat known among software developers. Likewise, due to being somewhat widespread, Markdown parsers are available for various languages, thus simplifying the creation of custom CommonMark Help viewer applications and other tools.
• Markdown provides basic means of text formatting without supplying elaborate ways to customize formatting and restyle content, which is beneficial for creating uniformly structured help files.
• Markdown can be written relatively quickly and without much set-up time. As writing end-user documentation is a development task that is often perceived to be (too) cumbersome, it is beneficial to reduce at least the purely operational obstacles as far as possible.

With these points in mind, the CommonMark project produces a Markdown specification that strives for being syntactically unambiguous, which is beneficial for integration in a clearly specified format such as CommonMark Help.