From f5536cc0cabf7ccb437663e78f486d0b19204f3c Mon Sep 17 00:00:00 2001
From: d-e-v-esh <59534570+d-e-v-esh@users.noreply.github.com>
Date: Sun, 21 Mar 2021 16:31:29 +0530
Subject: [PATCH] docs(README): outdated MD-CLI documentation - #363

Signed-off-by: d-e-v-esh <59534570+d-e-v-esh@users.noreply.github.com>
---
 packages/markdown-cli/README.md | 245 +++++++++++++++++++++++++-------
 1 file changed, 193 insertions(+), 52 deletions(-)

diff --git a/packages/markdown-cli/README.md b/packages/markdown-cli/README.md
index 487bb166..2058dbe8 100644
--- a/packages/markdown-cli/README.md
+++ b/packages/markdown-cli/README.md
@@ -1,24 +1,23 @@
-# Markdown Transform CLI
 
-Command line tool to debug and use markdown transformations.
+# Command Line
 
-## Installation
+Install the `@accordproject/markdown-cli` npm package to access the Markdown Transform command line interface (CLI). After installation you can use the `markus` command and its sub-commands as described below.
 
-```
+To install the Markdown CLI:
+
+```bash
 npm install -g @accordproject/markdown-cli
 ```
 
 ## Usage
 
-The command-line is called `markus` and offers the following commands:
+`markus` is a command line tool to debug and use markdown transformations.
 
-```
+```md
 markus <cmd> [args]
 
 Commands:
-  markus parse      parse and transform a sample markdown, pdf or docx file
-  markus draft      create markdown text from data
-  markus normalize  normalize a sample markdown (parse & redraft)
+  markus transform  transform between two formats
 
 Options:
   --version      Show version number                                   [boolean]
@@ -26,72 +25,214 @@ Options:
   --help         Show help                                             [boolean]
 ```
 
-### Parse from Markdown
+## `markus transform`
 
-The `parse` command lets you parse markdown and create a document object model from it.
+The `markus transform` command lets you transform between any two of the supported formats
 
-```
-markus parse
+```md
+markus transform
 
-parse and transform a sample markdown
+transform between two formats
 
 Options:
   --version      Show version number                                   [boolean]
   --verbose, -v  verbose output                       [boolean] [default: false]
   --help         Show help                                             [boolean]
-  --sample       path to the markdown text, pdf, docx                   [string]
+  --input        path to the input                                      [string]
+  --from         source format                    [string] [default: "markdown"]
+  --to           target format                  [string] [default: "commonmark"]
+  --via          intermediate formats                      [array] [default: []]
+  --roundtrip    roundtrip transform                  [boolean] [default: false]
   --output       path to the output file                                [string]
-  --cicero       further transform to CiceroMark      [boolean] [default: false]
-  --slate        further transform to Slate DOM       [boolean] [default: false]
-  --html         further transform to HTML            [boolean] [default: false]
+  --model        array of concerto model files                           [array]
+  --template     template grammar                                       [string]
+  --contract     contract template                    [boolean] [default: false]
+  --currentTime  set current time                       [string] [default: null]
+  --plugin       path to a parser plugin                                [string]
+  --sourcePos    enable source position               [boolean] [default: false]
+  --offline      do not resolve external models       [boolean] [default: false]
 ```
 
-### Generate markdown from data
+### Example
 
-The `draft` command lets you take a document object model and generate markdown text from it.
+For example, you can use the `transform` command on the `README.md` file from the [Hello World](https://github.com/accordproject/cicero-template-library/blob/master/src/helloworld) template:
 
+```bash
+markus transform --input README.md
 ```
-markus draft
 
-create markdown text from data
+returns:
+
+```json
+{
+  "$class": "org.accordproject.commonmark.Document",
+  "xmlns": "http://commonmark.org/xml/1.0",
+  "nodes": [
+    {
+      "$class": "org.accordproject.commonmark.Heading",
+      "level": "1",
+      "nodes": [
+        {
+          "$class": "org.accordproject.commonmark.Text",
+          "text": "Hello World"
+        }
+      ]
+    }, 
+    {
+      "$class": "org.accordproject.commonmark.Paragraph",
+      "nodes": [
+        {
+          "$class": "org.accordproject.commonmark.Text",
+          "text": "This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string "
+        }, 
+        {
+          "$class": "org.accordproject.commonmark.Code",
+          "text": "Hello"
+        }, 
+        {
+          "$class": "org.accordproject.commonmark.Text",
+          "text": " prepended to text that is passed in the request."
+        }
+      ]
+    }
+  ]
+}
+```
 
-Options:
-  --version      Show version number                                   [boolean]
-  --verbose, -v  verbose output                       [boolean] [default: false]
-  --help         Show help                                             [boolean]
-  --data         path to the data                                       [string]
-  --output       path to the output file                                [string]
-  --cicero       input data is a CiceroMark DOM       [boolean] [default: false]
-  --slate        input data is a Slate DOM            [boolean] [default: false]
-  --html         input data is HTML                   [boolean] [default: false]
-  --noWrap       do not wrap CiceroMark variables as XML tags
-                                                      [boolean] [default: false]
-  --noIndex      do not index ordered lists           [boolean] [default: false]
+### `--from` and `--to` options
+
+You can indicate the source and target formats using the `--from` and `--to` options. For instance, the following transforms from `markdown` to `html`:
+
+```bash
+markus transform --from markdown --to html
+```
+
+returns:
+
+```md
+<html>
+<body>
+<div class="document">
+<h1>Hello World</h1>
+<p>This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string <code>Hello</code> prepended to text that is passed in the request.</p>
+</div>
+</body>
+</html>
 ```
 
-### Normalize the markdown
+### `--via` option
 
-The `normalize` command lets you parse markdown and re-draft it from its document object model.
+When there are several paths between two formats, you can indicate an intermediate format using the `--via` option. The following transforms from `markdown` to `html` *via* `slate`:
 
+```bash
+markus transform --from markdown --via slate --to html
 ```
-markus normalize
 
-normalize a sample markdown (parse & redraft)
+returns:
+
+```md
+<html>
+<body>
+<div class="document">
+<h1>Hello World</h1>
+<p>This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string <code>Hello</code> prepended to text that is passed in the request.</p>
+</div>
+</body>
+</html>
+```
 
-Options:
-  --version      Show version number                                   [boolean]
-  --verbose, -v  verbose output                       [boolean] [default: false]
-  --help         Show help                                             [boolean]
-  --sample       path to the markdown text                              [string]
-  --output       path to the output file                                [string]
-  --cicero       further transform to CiceroMark      [boolean] [default: false]
-  --slate        further transform to Slate DOM       [boolean] [default: false]
-  --html         further transform to HTML            [boolean] [default: false]
-  --noWrap       do not wrap variables as XML tags    [boolean] [default: false]
-  --noIndex      do not index ordered lists           [boolean] [default: false]
+### `--roundtrip` option
+
+When the transforms allow, you can roundtrip between two formats, i.e., transform from a source to a target format and back to the source target. For instance, the following transform from `markdown` to `slate` and back to markdown:
+
+```md
+markus transform --from markdown --to slate --input README.md --roundtrip
 ```
 
-## License <a name="license"></a>
-Accord Project source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file. Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0), available at http://creativecommons.org/licenses/by/4.0/.
+returns:
 
-© 2017-2019 Clause, Inc.
+```bash
+Hello World
+====
+
+This is the Hello World of Accord Project Templates. Executing the clause will simply echo back the text that occurs after the string `Hello` prepended to text that is passed in the request.
+```
+
+
+
+Roundtripping might result in small changes in the source markdown, but should always be semantically equivalent. In the above example the source ATX heading `# Hello World` has been transformed into a Setext heading equivalent.
+
+
+
+### `--model` `--contract` options
+
+When handling [TemplateMark](https://docs.accordproject.org/docs/markdown-templatemark), one has to provide a model using the `--model` option and whether the template is a clause (default) or a contract (using the `--contract` option).
+
+For instance the following converts markdown with the template extension to a TemplateMark document object model:
+
+```bash
+markus transform --from markdown_template --to templatemark --model model/model.cto --input text/grammar.tem.md
+```
+
+returns:
+
+```json
+{
+  "$class": "org.accordproject.commonmark.Document",
+  "xmlns": "http://commonmark.org/xml/1.0",
+  "nodes": [
+    {
+      "$class": "org.accordproject.templatemark.ClauseDefinition",
+      "name": "top",
+      "elementType": "org.accordproject.helloworld.HelloWorldClause",
+      "nodes": [
+        {
+          "$class": "org.accordproject.commonmark.Paragraph",
+          "nodes": [
+            {
+              "$class": "org.accordproject.commonmark.Text",
+              "text": "Name of the person to greet: "
+            }, 
+            {
+              "$class": "org.accordproject.templatemark.VariableDefinition",
+              "name": "name",
+              "elementType": "String"
+            }, 
+            {
+              "$class": "org.accordproject.commonmark.Text",
+              "text": "."
+            }, 
+            {
+              "$class": "org.accordproject.commonmark.Softbreak"
+            }, 
+            {
+              "$class": "org.accordproject.commonmark.Text",
+              "text": "Thank you!"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `--template` option
+
+Parsing or drafting contract text using a template can be done using the `--template` option, usually with the corresponding `--model` option to indicate the template model.
+
+For instance, the following parses a markdown with CiceroMark extension to get the correspond contract data:
+
+```bash
+markus transform --from markdown_cicero --to data --template text/grammar.tem.md --model model/model.cto --input text/sample.md 
+```
+
+returns:
+
+```json
+{
+  "$class": "org.accordproject.helloworld.HelloWorldClause",
+  "name": "Fred Blogs",
+  "clauseId": "fc345528-2604-420c-9e02-8d85e03cb65b"
+}
+```