Support for formatting markup in templates, as inspired by Markdown

[jeromesimeon]

Also see: https://github.com/accordproject/cicero/issues/171

[mttrbrts]

We should use the commonmark spec for Markdown, https://commonmark.org/

There is a reference implementation in JS, https://github.com/commonmark/commonmark.js

We also don't currently have any presentation mechanism inside Cicero, so to make this useful we should add a shim to cicero-cli for the markdown renderer. Perhaps something like, cicero render --template ./ --output contract.pdf

[mttrbrts]

To further elaborate on this proposal, here is a possible extension to the Template Specification to allow for semantic formatting inside a template grammar. Note the switch to GFM from commonmark, this is because GFM includes an extension for tables.

---

Other than for variables, formatting follows the GitHub Flavored Markdown Spec. The meaning of Sections, Definitions & References is similar to those used in the Markdown rendering of a Common Form document. Markdown provides a good compromise between expressiveness and legibility of the grammar. Markdown is also widely used by developers and has a rich set of tools for editing and conversion to HTML & PDF for example.

This document does not provide a specification for the rendering of a template that contains formatting marks. This is intentional as different firms and jurisdictions may wish to apply styling in different ways. However, the natural Markdown rendering is provided for convenience.

Sections

Sections in a template define the structure of a document. The # syntax allows multiple levels of nesting as in the example below. Heading marks should be followed by a space to distinguish from the use of # as a number or pound sign.

# Section 1
  Prose here ...
## Sub-section 1
  Prose here ...
## Sub-section 2
  Prose here ...
### Clause 1
  Prose here ...
# Section 2
  Prose here ...

Sections marks imply the heading style in Markdown.

Section 1

Prose here ...

Sub-section 1

Prose here ...

Sub-section 2

Prose here ...

Clause 1

Prose here ...

Section 2

Prose here ...

References

References are links to terms that are defined elsewhere in the same contract. A reference is created by surrounding the name of a term with underscores, _. For example, the following snippet contains a reference to _Liquidity Event_ and _Investor_.

If there is a _Liquidity Event_ before the expiration or termination of this instrument, the _Investor_ will, at its option ...

By default, Markdown will render references in italicized text.

If there is a Liquidity Event before the expiration or termination of this instrument, the Investor will, at its option ...

Definitions

Definitions are reusable terms that can be referenced elsewhere in a contract. Definitions are created by surrounding the name of a definition with double asterisks, **. Note that a Definition is different from the identifier that is used for a variable.

A variable identifier is used refer to the value of a variable in the template logic. The variable identifier does not appear in an instantiated contract. Similarly, the identifier for a Clause is distinct from the textual phrase used to reference a clause. However, a valid template grammar is expected to include Definitions for each Reference in the contract text.

In the following example, **Investor** provides an anchor in the contract that can be used as a Reference elsewhere in the text.

This certifies that in exchange for the payment by [{investorName}] (the **Investor**) 

Or in a definitions section.

4.  **Dissolution Event** means

    1.  a voluntary termination of operations,

    2.  a general assignment for the benefit of the _Company_'s creditors or

    3.  any other liquidation, dissolution or winding up of the _Company_ (excluding a _Liquidity Event_), whether voluntary or involuntary.

Markdown renders text that is surrounded by ** in bold. For example:

4. Dissolution Event means

   1. a voluntary termination of operations,

   2. a general assignment for the benefit of the Company's creditors or

   3. any other liquidation, dissolution or winding up of the Company (excluding a Liquidity Event), whether voluntary or involuntary.

Definitions can also be used to identify a Clause:

3. **Late Delivery and Penalty**. [{clause: ap://latedeliveryandpenalty@0.2.0#hash}]

Would be rendered as:

3. Late Delivery and Penalty. In case of delayed delivery the Seller shall pay to the Buyer for ...

Tables

GitHub Flavored Markdown (GFM), unlike some other Markdown variants, includes support for tables.

| Annual Dollar Volume      | Discount             |
|-------------------------|------------------|
| Less than $[{firstVolume}] million      | [{firstRate}]%                |
| $[{firstVolume}] million to $[{secondVolume}] million | [{secondRate}]%                |
| Greater than $[{secondVolume}] million  | [{thirdRate}]%                |

Note that the vertical bars | do not need to align. However, your table will be easier to read if you do align them.

Page Breaks & Thematic Breaks

GFM allows the insertion of a thematic break, i.e. a horizontal rule, by an empty line followed by a line with 3 * characters.

***

However, contracts often need to define a page break between distinct sections. We extend the Markdown notation to define a page break as a thematic break with 4 or more characters.

****

Note that this is a deviation from the GFM spec which defines a thematic break as a sequence of 3 or more matching -, _, or * characters.

[mttrbrts]

An alternative to extending the GFM spec for page breaks would be to use a HTML tag and rely on a HTML renderer any rendering pipeline.

<div style="page-break-after: always;"></div>

[jphillips-bp3]

I was just thinking the same thing. The clause I am working on has pretty technical wording and calculation examples built in and could really do with formatting to make it more readable.

[jeromesimeon]

A lot of this work is taking place here: https://github.com/accordproject/markdown-editor and here: https://github.com/accordproject/contract-editor

[jeromesimeon]

We now have support for markdown formatting, not just inspired with but directly using CommonMark. Closing.