Merge branch '__rultor'

README.md

@@ -25,7 +25,38 @@ Read
 [_PDD in Action_](http://www.yegor256.com/2017/04/05/pdd-in-action.html)
 and watch [this webinar](https://www.youtube.com/watch?v=nsYGC2aUwfQ).
 
-You should have [Ruby installed](https://www.ruby-lang.org/en/documentation/installation/).
+## Installation
+<details><summary>
+
+### Prerequisites: `Ruby installed` and `Libmagic`
+</summary>
+<details><summary>
+
+#### Ruby version 2.7+
+</summary>
+
+[Ruby installation instruction](https://www.ruby-lang.org/en/documentation/installation/)
+</details>
+<details>
+<summary>
+
+#### Libmagic library
+</summary>
+
+**For Debian/Ubuntu:**
+```bash
+$ apt install libmagic-dev
+```
+**For Mac**
+```bash
+$ brew install libmagic
+```
+**For Windows**
+Unfortunately, there is no easy way to install, please use WSL
+
+</details>
+</details>
+
 Then, install our gem:
 
 ```bash
@@ -38,35 +69,59 @@ Run it locally and read its output:
 $ pdd --help
 ```
 
+## Usage
 You can exclude & include certain number of files from the search via these options:
 
-```
-$ pdd --exclude=glob
+```bash
+$ pdd --exclude glob
 ```
 
 You can skip any file(s) with a name suffix that matches the pattern glob, using wildcard matching; 
 a name suffix is either the whole path and name, or reg expr, for example:
 
 ```bash
-$ pdd --exclude=src/**/*.java --exclude=target/**/*
-$ pdd --exclude=src/**/*.java # exclude .java files in src/
-$ pdd --exclude=src/**/* # exclude all files in src/
+$ pdd --exclude src/**/*.java --exclude target/**/*
+$ pdd --exclude src/**/*.java # exclude .java files in src/
+$ pdd --exclude src/**/* # exclude all files in src/
 ```
 
 You can include too:
 
-```
-$ pdd --include=glob
+```bash
+$ pdd --include glob
 ```
 
 Search only files whose name matches glob, using wildcard matching as described under ``--exclude``. 
 If contradictory ``--include`` and ``--exclude`` options are given, the last matching one wins. 
 If no ``--include`` or ``--exclude`` options are given, all files from working directory are included, example:
 
 ```bash
-$ pdd --include=src/**/*.py # include only .py files in src/
-$ pdd --include=src/**/* # include all files in src/
+$ pdd --include src/**/*.py # include only .py files in src/
+$ pdd --include src/**/* # include all files in src/
+```
+
+Full command format is (all parameters are optional):
+```bash
+$ pdd [--verbose] [--quiet] [--remove] [--skip-gitignore] [--skip-errors] \
+      [--source <project_dir_path>] [--file puzzles_file.xml] [--include src/**/*.py] \
+      [--format xml|html] [--rule min-words:5] [--exclude src/**/*.java]
 ```
+| Parameter               | Description                                                                           |
+|-------------------------|---------------------------------------------------------------------------------------|
+| --verbose               | Enable verbose (debug) mode. --file must be used in case of using this option         |
+| --quiet                 | Disable logs                                                                          |
+| --remove                | Remove all found puzzles from the source code                                         |
+| --skip-gitignore        | Don't look into .gitignore for excludes                                               |
+| --skip-errors           | Suppress error as warning and skip badly formatted puzzles (do not skip broken rules) |
+| --source <project-path> | Source directory to parse ("." by default)                                            |
+| --file puzzles.xml      | File to save report into (xml of html) (displayed in console by default)              |
+| --include *.py          | Glob pattern to include (can be used several times)                                   |
+| --exclude *.java        | Glob pattern to exclude (can be used several times)                                   |
+| --format xml            | Format of the report xml or html  (xml is default)                                    |
+| --rule min-words:5      | Rule to apply (can be used several times), described later                            |
+
+:bulb: There is an option to create a .pdd file in your project and save all required parameters in it.
+File example you can see in this project.
 
 ## How to Format?
 
@@ -80,9 +135,9 @@ to the leading space in every consecutive line):
 [related code]
 ```
 
-`[]` - Replace with apropriate data (see text enclosed in brackets)
+`[]` - Replace with appropriate data (see text enclosed in brackets)
 
-`<>` - Omitable (enclosed data can be left out)
+`<>` - Optional (enclosed data can be left out)
 
 Example:
 
@@ -142,8 +197,8 @@ and put a dummy `#1` marker everywhere.
 You can specify post-parsing rules for your puzzles, in command line,
 for example:
 
-```
-$ pdd --rule=min-estimate:60 --rule=max-estimate:120
+```bash
+$ pdd --rule min-estimate:60 --rule max-estimate:120
 ```
 
 These two parameters will add two post-parsing rules `min-estimate`
@@ -167,7 +222,7 @@ Here is a list of rules available now:
   This rule is used by default and you can't configure it at the moment,
   it must always be set to `1`.
 
-You can put all command line options into `.pdd` file. The options from the
+:bulb: You can put all command line options into `.pdd` file. The options from the
 file will be used first. Command line options may be added on top of them.
 See, how it is done in [yegor256/0pdd](https://github.com/yegor256/0pdd/blob/master/.pdd).
 
@@ -214,16 +269,16 @@ The most interesting parts of each puzzle are:
 
 Read [these guidelines](https://www.yegor256.com/2014/04/15/github-guidelines.html).
 Make sure your build is green before you contribute
-your pull request. You will need to have [Ruby](https://www.ruby-lang.org/en/) 2.3+ and
+your pull request. You will need to have [Ruby](https://www.ruby-lang.org/en/) 2.7+ and
 [Bundler](https://bundler.io/) installed. Then:
 
-```
+```bash
 $ bundle install
 $ bundle exec rake
 ```
 
 Next, install and run overcommit to install hooks (required once)
-```
+```bash
 $ gem install overcommit -v '=0.58.0'
 $ overcommit --install
 ```