Concepts

Back to Understanding Remark

This section introduces the main concepts used in Remark.

Transformation

The action of Remark can be summarized as reading a set of physical files, called the input files, and transforming the documents into a new set of physical files and directories, called the output files.

Documents

A document is any data which can be (uniquely) identified with a file path. The most common kind of documents in Remark are files. However, the document generalizes the concept of a file in that the document and the directories need not physically exist on the hard-disk or anywhere else (although some of them may).

Consider the files and directories on the hard-disk. Since a directory contains a set of files and a set of directories, the directories form a tree-structure. In this structure each directory D has a parent directory, which is the unique directory containing D. The same holds for documents, and we can safely use the same terminology. Therefore, each document has a containing directory, and some filename.

Document tree

The document tree is a tree generated by the parent-child relation between the documents. The information needed to construct the document tree is encoded in the input files, where in some of them the user has specified, either partially or completely, the identity of the parent document. The parent-child relation is both explicitly specified by the user, and implicitly deduced by Remark when the information is not given.

Document tags

Each document is associated with a set of document tags. A document tag is a string identifier which associates to a piece of text. Examples of tags include the parent and description tags which are extracted from the input files. While the parent tag is used to encode the structure of the document tree, the description tag is used to give meaningful link-names between the documents in the document tree.

Remark groups the input files based on similar filenames, and uses the grouping to implicitly deduce parent documents and descriptions. This reduces the need to tag the files.

Document type

A document type encapsulates the concept of transforming a document to a file (or a set of files). Each document has a unique document type, while many documents may have the same document type. An example of a document type would be a transformation of a C++ source code to an html file, where the source code has been highlighted. An example of a document type which works on an abstract document is a transformation of a directory-listing identifier to a html file containing the directory listing.

Summary

The idea behind Remark can be summarized as follows. Files are annotated by document tags to encode information about the parent-child relation between the documents, and to give each document a useful description. Using this information, Remark constructs a document tree, and uses it to transform each document by its document-type. The result is a set of interlinked html documentation files, where the links have been named descriptively.