-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathconcepts.txt
83 lines (65 loc) · 3.3 KB
/
concepts.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
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.