Skip to content

Commit

Permalink
docs(README): outdated MD-CLI documentation - #363
Browse files Browse the repository at this point in the history 
Signed-off-by: d-e-v-esh <[email protected]>
  • Loading branch information
@d-e-v-esh @jeromesimeon
d-e-v-esh authored and jeromesimeon committed Apr 2, 2021
1 parent 9b64a11 commit bde0694
Showing 1 changed file with 193 additions and 52 deletions.
245 changes: 193 additions & 52 deletions packages/markdown-cli/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,97 +1,238 @@
# 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]
--verbose, -v [default: false]
--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"
}
```

0 comments on commit bde0694

Please sign in to comment.