file_searching_algorithm.txt

File searching algorithm
========================

[[Parent]]: understanding.txt

Many of the macros, such as the [[Link: Link_Macro.txt]], 
[[Link: FileLink_Macro.txt]], [[Link: DirectoryLink_Macro.txt]], 
[[Link: Gallery_Macro.txt]], and the [[Link: Ref_Macro.txt]],
use the same file-searching algorithm to match a given file 
path to a unique file in the document tree. We specify that algorithm
here. 

Algorithm
--------- 

Given a file-path, which may either be a filename, or a 
relative-path, the algorithm searches the corresponding document as 
follows:

 1. The document is searched from the current directory by appending
 the file-path at the end of the current directory.
 
 2. If the document can not be found, the document is searched similarly 
 from the parent-directories up until to the documentation root-directory.
 
 3. If the document still can not be found, the file-path is searched 
 across all the path-suffixes of the relative-paths of the documents in
 the document-tree. In case there are multiple matching documents, Remark 
 picks one arbitrarily and emits a warning about the ambiguity.
 
Notes
-----

The filename is the minimum amount of information, and the full 
relative-path is the maximum amount of information that can be used
to locate a given document. The relative-path-suffixes are somewhere
between these extremes. Specifying the minimal amount of information
to disambiguate a given search makes the documentation more robust 
to directory changes. With this in mind, Remark emits a warning 
whenever a shorter path-suffix would suffice for the given search.