Concepts
========

[[Parent]]: understanding.txt

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][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.

[Tags]: [[Ref]]: tags.txt

Document type
-------------

A [_document type_][DocumentType] 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][CppCode], 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][Index].

[DocumentType]: [[Ref]]: document_types.txt
[CppCode]: [[Ref]]: CppCode_Macro.txt
[Index]: [[Ref]]: Index_Macro.txt

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.
