Skip to content

Commit 22a0c18

Browse files
jeromesimeonjeromesimeon
committed
chore(0.22) Tag new 0.22 documentation
Signed-off-by: Jerome Simeon <[email protected]>
1 parent f6d05c8 commit 22a0c18

12 files changed

+5178
-0
lines changed

‎website/versioned_docs/version-0.22/markup-preliminaries.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
id: version-0.22-markup-preliminaries
3+
title: Preliminaries
4+
original_id: markup-preliminaries
5+
---
6+
7+
## Markdown & CommonMark
8+
9+
The text for Accord Project templates is written using markdown. It builds on the [CommonMark](https://commonmark.org) standard so that any CommonMark document is valid text for a template or contract.
10+
11+
As with other markup languages, CommonMark can express the document structure (e.g., headings, paragraphs, lists) and formatting useful for readability (e.g., italics, bold, quotations).
12+
13+
The main reference is the [CommonMark Specification](https://spec.commonmark.org/0.29/) but you can find an overview of CommonMark main features in the [CommonMark](markup-commonmark) Section of this guide.
14+
15+
## Accord Project Extensions
16+
17+
Accord Project uses two extensions to CommonMark: CiceroMark for the contract text, and TemplateMark for the template grammar.
18+
19+
### Lexical Conventions
20+
21+
Accord Project contract or template text is a string of `UTF-8` characters.
22+
23+
:::note
24+
By convention, CiceroMark files have the `.md` extensions, and TemplateMark files have the `.tem.md` extension.
25+
:::
26+
27+
The two sequences of characters `{{` and `}}` are reserved and used for the CiceroMark and TemplateMark extensions to CommonMark. There are three kinds of extensions:
28+
1. Variables (written `{{variableName}}`) which may include an optional formatting (written `{{variableName as "FORMAT"}}`).
29+
2. Formulas (written `{{% expression %}}`).
30+
3. Blocks which may contain additional text or markdown. Blocks come in two flavors:
31+
1. Blocks corresponding to [markdown inline elements](https://spec.commonmark.org/0.29/#inlines) which may contain only other markdown inline elements (e.g., text, emphasis, links). Those have to be written on a single line as follows:
32+
```
33+
{{#blockName variableName}} ... text or markdown ... {{/blockName}}
34+
```
35+
2. Blocks corresponding to [markdown container elements](https://spec.commonmark.org/0.29/#container-blocks) which may contain arbitrary markdown elements (e.g., paragraphs, lists, headings). Those have to be written with each opening and closing tags on their own line as follows:
36+
```
37+
{{#blockName variableName}}
38+
... text or markdown ...
39+
{{/blockBane}}
40+
```
41+
42+
### CiceroMark
43+
44+
CiceroMark is used to express the natural language text for legal clauses or contracts. It uses two specific extensions to CommonMark to facilitate contract parsing:
45+
1. Clauses within a contract can be identified using a `clause` block:
46+
```
47+
{{#clause clauseName}}
48+
text of the clause
49+
{{/clause}}
50+
```
51+
2. The result of formulas within a contract or clause can be identified using:
52+
```
53+
{{% result_of_the_formula %}}
54+
```
55+
56+
For instance, the following CiceroMark for a loan between `John Smith` and `Jane Doe` includes a title (`Loan agreement`) followed by some text, followed by a fixed rate interest clause. The clause contains the terms for the loan and the result of calculating the monthly payment.
57+
```tem
58+
# Loan agreement
59+
60+
This is a loan agreement between "John Smith" and "Jane Doe", which shall be entered into
61+
by the parties on January 21, 2021 - 3 PM, except in the event of a force majeure.
62+
63+
{{#clause fixedRate}}
64+
## Fixed rate loan
65+
66+
This is a _fixed interest_ loan to the amount of £100,000.00
67+
at the yearly interest rate of 2.5%
68+
with a loan term of 15,
69+
and monthly payments of {{%£667.00%}}
70+
{{/clause}}
71+
```
72+
73+
More information and examples can be found in the [CiceroMark](markup-ciceromark) part of this guide.
74+
75+
### TemplateMark
76+
77+
TemplateMark is used to describe families of contracts or clauses with some variable parts. It is based on CommonMark with several extensions to indicate those variables parts:
78+
1. _Variables_: e.g., `{{loanAmount}}` indicates the amount for a loan.
79+
2. _Template Blocks_: e.g., `{{#if forceMajeure}}, except in the event of a force majeure{{/if}}` indicates some optional text in the contract.
80+
3. _Formulas_: e.g., `{{% monthlyPaymentFormula(loanAmount,rate,loanDuration) %}}` calculates a monthly payment based on the `loanAmount`, `rate`, and `loanDuration` variables.
81+
82+
For instance, the following TemplateMark for a loan between a `borrower` and a `lender` includes a title (`Loan agreement`) followed by some text, followed by a fixed rate interest clause. This template allows for either taking force majeure into account or not, and calls into a formula to calculate the monthly payment.
83+
```tem
84+
# Loan agreement
85+
86+
This is a loan agreement between {{borrower}} and {{lender}}, which shall be entered into
87+
by the parties on {{date as "MMMM DD, YYYY - h A"}}{{#if forceMajeure}}, except in the event of a force majeure{{/if}}.
88+
89+
{{#clause fixedRate}}
90+
## Fixed rate loan
91+
92+
This is a _fixed interest_ loan to the amount of {{loanAmount as "K0,0.00"}}
93+
at the yearly interest rate of {{rate}}%
94+
with a loan term of {{loanDuration}},
95+
and monthly payments of {{% monthlyPaymentFormula(loanAmount,rate,loanDuration) as "K0,0.00" %}}
96+
{{/clause}}
97+
```
98+
99+
More information and examples can be found in the [TemplateMark](markup-templatemark) part of this guide.
100+
101+
## Dingus
102+
103+
You can test your template or contract text using the [TemplateMark Dingus](https://templatemark-dingus.netlify.app), an online tool which lets you edit the markdown and see it rendered as HTML, or as a document object model.
104+
105+
![TemplateMark Dingus](assets/dingus1.png)
106+
107+
You can select whether to parse your text as pure CommonMark (i.e., according to the CommonMark specification), or with the CiceroMark or TemplateMark extensions.
108+
109+
![TemplateMark Dingus](assets/dingus2.png)
110+
111+
You can also inspect the HTML source, or the document object model (abstract syntax tree or AST), even see a pdf rendering for your template.
112+
113+
![TemplateMark Dingus](assets/dingus3.png)
114+
115+
For instance, you can open the TemplateMark from the loan example on this page by clicking [this link](https://templatemark-dingus.netlify.app/#md3=%7B%22source%22%3A%22%23%20Loan%20agreement%5Cn%5CnThis%20is%20a%20loan%20agreement%20between%20%7B%7Bborrower%7D%7D%20and%20%7B%7Blender%7D%7D%2C%20which%20shall%20be%20entered%20into%5Cnby%20the%20parties%20on%20%7B%7Bdate%20as%20%5C%22MMMMM%20DD%2C%20YYYY%20-%20hhA%5C%22%7D%7D%7B%7B%23if%20forceMajeure%7D%7D%2C%20except%20in%20the%20event%20of%20a%20force%20majeure%7B%7B%2Fif%7D%7D.%5Cn%5Cn%7B%7B%23clause%20fixedRate%7D%7D%5Cn%23%23%20Fixed%20rate%20loan%5Cn%5CnThis%20is%20a%20_fixed%20interest_%20loan%20to%20the%20amount%20of%20%7B%7BloanAmount%20as%20%5C%22K0%2C0.00%5C%22%7D%7D%5Cnat%20the%20yearly%20interest%20rate%20of%20%7B%7Brate%7D%7D%25%5Cnwith%20a%20loan%20term%20of%20%7B%7BloanDuration%7D%7D%2C%5Cnand%20monthly%20payments%20of%20%7B%7B%25%20monthlyPaymentFormula%28loanAmount%2Crate%2CloanDuration%29%20as%20%5C%22K0%2C0.00%5C%22%20%25%7D%7D%5Cn%7B%7B%2Fclause%7D%7D%5Cn%22%2C%22defaults%22%3A%7B%22templateMark%22%3Atrue%2C%22ciceroMark%22%3Afalse%2C%22html%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22html%22%7D%7D).
116+
117+
![TemplateMark Dingus](assets/dingus4.png)
118+

0 commit comments

Comments
 (0)