Many of the macros, such as the Link macro, FileLink macro, DirectoryLink macro, Gallery macro, and the Ref macro, 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.
Given a file-path, which may either be a filename, or a relative-path, the algorithm searches the corresponding document as follows:
The document is searched from the current directory by appending the file-path at the end of the current directory.
If the document can not be found, the document is searched similarly from the parent-directories up until to the documentation root-directory.
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.
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.