README.md in clerq-0.3.3 vs README.md in clerq-0.3.4
- old
+ new
@@ -16,16 +16,24 @@
Install it yourself as:
$ gem install clerq
-For Ruby 2.X you should use version 0.3.2:
+## Promo
- $ gem install clerq -v 0.3.2
+
-It's because of keyword arguments changes in Ruby 3
+Inside Clerq there is a demo project that was created and is still used to develop Clerq itself and its script-extensions. You can see the project [here](https://github.com/nvoynov/clerq/tree/master/lib/assets/promo) ([requirements sources](https://github.com/nvoynov/clerq/tree/master/lib/assets/promo/src) and produced documents [Clerq SRS.md](https://github.com/nvoynov/clerq/blob/master/lib/assets/promo/bin/Clerq%20SRS.md), [Clerq SRS.docx](https://github.com/nvoynov/clerq/blob/master/lib/assets/promo/bin/Clerq%20SRS.docx))
+I am sure this project will be useful when you get to know the product. So, I propose to open it now and look inside as you move forward. Do the following in your console:
+
+ $ clerq new promo
+ $ cd promo
+ $ clerq promo
+ $ atom .
+ $ thor list
+
## Usage
The Clerq is entirely based on one single domain entity `Node` that represents a node of tree hierarchy and provides `id`, `title`, `body`, and `metadata` attributes. It supposes the following simple workflow:
* you create files with text content,
@@ -63,11 +71,11 @@
Where
* `#` familiar markdown header that indicates a new `node`;
* `[p1]` is an optional identifier that becomes `node.id`;
* `Part two` is an optional `node.title`;
-* `{{parent: top}}` in an optional metadata section that becomes `node.meta`;
+* `{{parent: top}}` is an optional metadata section that becomes `node.meta`;
* and finally `Body` is an optional `node.body`.
```markdown
# Part two
{{id: p1, parent: top}}
@@ -138,11 +146,11 @@
parent: r}}
```
#### Assets
-When you want to provide some assets or links to something outside the repository you can provide the lint to the assets. Put the asset in the `bin/assets` folder and specify the link.
+When you want to provide some assets or links to something outside the repository you can provide the link to the assets. Put the asset in the `bin/assets` folder and specify the link.
```markdown
# [ent] Entities
The following picture shows something
@@ -235,13 +243,13 @@
Clerq provides the following main service objects:
* `LoadAssembly` loads whole repository to Node class;
* `CheckAssembly` checks the assembly for errors (ids and links);
* `QueryNode` provides ability to query nodes from assembly;
-* `QueryTemplate` return template by the template name;
+* `QueryTemplate` returns template by the template name;
* `CreateNode` crates new node in the repository;
-* `RenderNode` return text rendered by ERB.
+* `RenderNode` returns text rendered by ERB.
The first part of each repository related task is to get repository assembly. It can be performed through `NodeRepository#assemble` or `LoadAssembly.call()`. Each of these methods returns Node that provides [Enumerable](https://ruby-doc.org/core-2.6.5/Enumerable.html) interface.
Let's see an example. Assume that you are developing a "User requirements document" and the project policy requires that each user requirement must have the parameter called `originator`. You can write the policy as followed:
@@ -328,51 +336,44 @@
$ thor mydoc:check_originator
This example is just very basic and your automation scripts could be much more complex.
-Another quick example is [clerq.thor] (https://github.com/nvoynov/clerq/blob/master/clerq.thor) file that was created just to overcome handling curly bracket `{{}}` in Jekyll and now I run `thor clerqsrc:docs` every time after changing this file.
+Another quick example is the [clerq.thor](https://github.com/nvoynov/clerq/blob/master/clerq.thor) file that was created just to overcome handling curly bracket `{{}}` in Jekyll and now I run `thor clerq:src:docs` every time after changing this file.
### Templating
-The Clerq provides the ability to precise adjusting the output for `clerq build` command by erb-templates and gives you two basic templates from the box.
+The output of the `clerq build` command can be precisely adjusted by modifying the corresponding "erb" template.
-* [default.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/default.md.erb) that just combines all nodes to one markdown document;
-* [pandoc.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/pandoc.md.erb) is more advanced, it produces [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) and provides three followed macros for node body:
- * `{{@@list}}` - replaces the macro with the list of child nodes;
- * `{{@@tree}}` - replaces the macro with the tree of child nodes;
- * `{{@@skip}}` - skip all content inside the brackets.
+One can see the standard template in [default.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/default.md.erb). It produced output in [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) format and supports the following macros in node body:
+* `{{@@list}}` - replaces the macro with the list of child nodes;
+* `{{@@tree}}` - replaces the macro with the tree of child nodes;
+* `{{@@eval}}` - eval ruby code inside the brackets;
+* `{{@@skip}}` - skip all content inside the brackets.
+
### Publishing
-In addition to the `clerq build` command in [lib/clerq_doc.thor](https://github.com/nvoynov/clerq/blob/master/lib/assets/lib/clerq_doc.rb) I provided the example of basic documents management tasks (it will be placed in new project `lib` folder). You can find there two example of commands that you can start your own publishing automation.
+In addition to the `clerq build` command one can find an example of basic documents management tasks in the [lib/clerq_doc.thor](https://github.com/nvoynov/clerq/blob/master/lib/assets/lib/clerq_doc.thor) (it will be placed in new project `lib` folder). You can find there two example of commands that you can start your own publishing automation.
* `thor clerq:doc:publish` will create `<project>.docx` and `<project>.html`;
* `thor clerq:doc:grab` will import provided document into the current project repository.
## Known issues
### Thor version
The one issue I certain in is when you are using different version of thor, your custom scripts won't work.
-### Test suite
-
-Because `default.md.erb` and `pandoc.md.erb` have inside the same class `MarkupNode`, sometimes one of `default_spec.rb` or `pandoc_spec.rb` fails.
-
## Some considerations
### Some obvious things
Use modern text editor that provides projects tree. like Atom, Sublime, etc.
Hold your projects in Git.
Use pandoc for generating output in different formats
-
-### MarkupNode
-
-Don't like the current dirty solution with templates and incorporated MarkupNode that does all that stuff with macro. It is the first attempt to provide template that can skip comments.
### Several artifacts
Because Clerq has `-q/--query QUERY_STRING` option you can be interested in developing several different artifacts in one project.