README.md in markdown_exec-0.1.3 vs README.md in markdown_exec-0.2.0
- old
+ new
@@ -1,15 +1,17 @@
# MarkdownExec
This gem allows you to interactively select and run code blocks in markdown files.
-* Code blocks can be named.
+* Code blocks may be named.
* Named blocks can be required by other blocks.
-* The selected code block, and all required blocks, are collected in the order they appear in the markdown file.
+* The user-selected code block, and all required blocks, are arranged in the order they appear in the markdown file.
+* The code is presented for approval prior to execution.
+
## Installation
Install:
$ gem install markdown_exec
@@ -18,26 +20,84 @@
`mde --help`
Displays help information.
`mde`
-Process `README.md` file in the current directory. Displays all the blocks in the file and allows you to select using [up], [down], and [return]. Press [ctrl]-c to abort selection.
+Process `README.md` file in the current folder. Displays all the blocks in the file and allows you to select using [up], [down], and [return]. Press [ctrl]-c to abort selection.
`mde -f my.md`
-Process `my.md` file in the current directory.
+Select a block to execute from `my.md`.
-`mde -p child`
-Process markdown files in the `child` directory.
+`mde -p .`
+Select a markdown file in the current folder. Select a block to execute from that file.
`mde --list-blocks`
-List all blocks in the selected files.
+List all blocks in the all the markdown documents in the current folder.
`mde --list-docs`
-List all markdown documents in the selected folder.
+List all markdown documents in the current folder.
-## License
+## Behavior
+* If no file and no folder are specified, blocks within `./README.md` are presented.
+* If a file is specified, its blocks are presented.
+* If a folder is specified, its files are presented. When a file is selected, its blocks are presented.
+## Configuration
+
+While starting up, reads the YAML configuration file `.mde.yml` in the current folder if it exists.
+
+e.g. Use to set the default file for the current folder.
+
+* `filename: CHANGELOG.md` sets the file to open.
+* `folder: documents` sets the folder to search for default or specified files.
+
+# Example blocks
+
+When prompted, select either the `awake` or `asleep` block. The standard output confirms which required were blocks were included. Naming "hidden" blocks with parentheses "(" and ")" is a convention used here to re-inforce the purpose of the named blocks.
+
+``` :(day)
+# block named "(day)", required by other blocks
+export MYTIME=early
+```
+
+``` :(night)
+# block named "(night)", required by other blocks
+export MYTIME=late
+```
+
+``` :awake +(day) +(report)
+# block named "awake", select to see result
+export ACTIVITY=awake
+```
+
+``` :asleep +(night) +(report)
+# block named "asleep", select to see result
+export ACTIVITY=asleep
+```
+
+``` :(report)
+# block named "(report)", required by other blocks
+echo "time: $MYTIME, activity: $ACTIVITY"
+```
+
+## Example blocks
+
+
+## Selecting a file
+
+
+## Selecting a block
+
+
+## Approving code
+
+
+## Output
+
+
+# License
+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-## Code of Conduct
+# Code of Conduct
Everyone interacting in the MarkdownExec project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/markdown_exec/blob/master/CODE_OF_CONDUCT.md).