Algorithm
=========

[[Parent]]: implementation.txt

This section describes the algorithm Remark uses to generate the
resulting web-pages. 

Constructing the document tree
------------------------------

### Gathering files and directories

This step gathers a linear list of those files that are located
in the input directory or its sub-directories. Files are identified 
with their location relative to the input directory (called a _relative name_).
Only those files are accepted which have an associated document
type or are explicitly specified at the invocation of Remark. 

After the files have been gathered, their containing directories
are gathered. If a directory is gathered, then so is its parent 
directory (unless the directory is the input directory). 
This set of directories is useful when one wants to generate
a directory view.

### Parsing for tags

Each document is parsed for tags by using its [document-type][DocumentType].
The purpose of this phase is to find out for a file its parent 
document, description, and a detailed description.

[DocumentType]: [[Ref]]: document_types.txt

### Resolving explicit parent links

If a document specifies a parent document, then it is used to
construct a part of the document tree. The parent is specified
with a path which is given to the 
[file-searching algorithm][Searching].

[Searching]: [[Ref]]: file_searching_algorithm.txt

### Resolving implicit parent links

If a file does not have a parent document at this point, it
is attempted to give an [implicit parent][Implicit].

### Linking orphans

If a document does not have parent document even after implicit linking,
it is linked to a special [orphan][Orphan] document. This guarantees that each
document has a parent document. By generating a web-page that contains all 
the orphans, the user has a useful list of those document which are not 
linked to the documentation.

[Implicit]: [[Ref]]: implicit_rules.txt
[Orphan]: [[Ref]]: Orphan_DocumentType.txt

Adding virtual documents
------------------------

Using the list of involved directories, a [`directory.remark-index`][Index] 
document is generated to each sub-directory of the document tree. In addition,
an [`orphan.remark-orphan`][Orphan] document is generated to the root directory 
of the document tree.

[Index]: [[Ref]]: Index_Macro.txt

Generating output
-----------------

Each document in the document-tree is converted by its document-type.

Copying files
-------------

At the end, Remark copies some files to the `remark_files` directory 
of the output directory. These include Javascript files for mathematics
and image viewing, and CSS files for styling.
