commit 9c0e29c7583c18e259d688474c5383a5dec625d5
parent 270057f78ad6251c608ca74a7d4d9f5de36c33c6
Author: Oscar Benedito <oscar@oscarbenedito.com>
Date: Tue, 23 Jun 2020 14:21:25 +0200
Reformat Markdown files
Diffstat:
| M | README.md | | | 93 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------- |
1 file changed, 78 insertions(+), 15 deletions(-)
diff --git a/README.md b/README.md
@@ -1,10 +1,17 @@
# Markion
-Markion is a Python script to allow writing literate programs using Markdown. Markion retrieves the tangled code in a file and written it to the specified files in the output directory. This README file is an example of a file that Markion can process, indeed, this file will give you Markion itself!
+
+Markion is a Python script to allow writing literate programs using Markdown.
+Markion retrieves the tangled code in a file and written it to the specified
+files in the output directory. This README file is an example of a file that
+Markion can process, indeed, this file will give you Markion itself!
## Using Markion
### Creating the input file
-To use Markion, create a Mardown file normally, and insert code snippets as you would typically with Markdown. If you want to use that code for your output files, you should use the following syntax:
+
+To use Markion, create a Mardown file normally, and insert code snippets as you
+would typically with Markdown. If you want to use that code for your output
+files, you should use the following syntax:
<pre>
```[language] block|file blockid|filename
@@ -12,22 +19,34 @@ code snippet
```
</pre>
-Specifing the language is optional (but you should put a space between the <code>```</code> and either "block" or "file"). The next word specifies wether the code is a block or it is the content of a file, and the last word represents the block ID (to include it in other snippets) or the output file name (where the code will be written) respectively. You may add comments if desired at the end of the line, both Markdown and Markion will ignore them.
+Specifing the language is optional (but you should put a space between the
+<code>```</code> and either "block" or "file"). The next word specifies wether
+the code is a block or it is the content of a file, and the last word represents
+the block ID (to include it in other snippets) or the output file name (where
+the code will be written) respectively. You may add comments if desired at the
+end of the line, both Markdown and Markion will ignore them.
### Prerequisites
+
In order to run the program, you will need Python version 3.6 or later.
### Running the program
+
To run the program, execute the file `markion.py` followed by the input file.
```
python3 markion.py file
```
-There is an addition option `--output-directory` (or `-d`) to specify an output directory and you can also run the program with `--help` (or `-h`) to get help about the program's usage.
+There is an addition option `--output-directory` (or `-d`) to specify an output
+directory and you can also run the program with `--help` (or `-h`) to get help
+about the program's usage.
## Explanation of the program
-First of all, we will make it executable, we'll write the license notice and import all the required libraries.
+
+First of all, we will make it executable, we'll write the license notice and
+import all the required libraries.
+
```python file markion.py
#!/usr/bin/env python3
[[ include license ]]
@@ -35,41 +54,65 @@ import os, sys, re, argparse
```
### Program arguments
-We will use Python's `argparse` package to deal with our program's arguments. We initialize the parser with a brief description of the program's utility.
+
+We will use Python's `argparse` package to deal with our program's arguments. We
+initialize the parser with a brief description of the program's utility.
+
```python file markion.py
parser = argparse.ArgumentParser(description='Markion is a simple scripts that retrieves tangled code from Markdown.')
```
+
One of the arguments is the name of the input file:
+
```python file markion.py
parser.add_argument('file', metavar='file', type=str, nargs=1, help='Input file.')
```
+
Another optional argument lets the user specify the output directory.
+
```python file markion.py
parser.add_argument('-d', '--output-directory', dest='out_dir', type=str, default=os.getcwd(), help='Change the output directory.')
```
-The other argument is also optional and it lets the program automatically detect the output directory (based on the file's directory). This option will override the `--output-directory` option.
+
+The other argument is also optional and it lets the program automatically detect
+the output directory (based on the file's directory). This option will override
+the `--output-directory` option.
+
```python file markion.py
parser.add_argument('-D', '--auto-directory', dest='auto_dir', action='store_true', help='Auto detect output directory.')
```
-To calculate the directory automatically, we simply check the input file's directory.
+
+To calculate the directory automatically, we simply check the input file's
+directory.
+
```python block auto_dir
if args.auto_dir:
args.out_dir = os.path.dirname(args.file[0])
```
-Finally we assign the arguments' values to the `args` variable to use it later on.
+
+Finally we assign the arguments' values to the `args` variable to use it later
+on.
+
```python file markion.py
args = parser.parse_args()
```
### Reading the input file
+
We read the input file and copy the contents to a variable `inp`.
+
```python file markion.py
with open(args.file[0], 'r') as f:
inp = f.read()
```
### Extracting the tangled code
-We extract the important pieces of code from the `inp` variable. To do so there are two regular expressions, one that matches the blocks and one that matches the content to output in the files. We get all the snippets and save them into the variables `blocks` and `files`.
+
+We extract the important pieces of code from the `inp` variable. To do so there
+are two regular expressions, one that matches the blocks and one that matches
+the content to output in the files. We get all the snippets and save them into
+the variables `blocks` and `files`.
+
```python file markion.py
r_block = '```[\w\-.]*\s+block\s+([\w.-]+).*?\n(.*?)\n```\s*?\n'
r_file = '```[\w\-.]*\s+file\s+([\w.-]+).*?\n(.*?\n)```\s*?\n'
@@ -78,7 +121,10 @@ files = re.findall(r_file, inp, flags = re.DOTALL)
```
### Resolving includes in the tangled code
-For each file specified in the input, we resolve all the blocks that are included (recursively). To do so we use the function `resolve`.
+
+For each file specified in the input, we resolve all the blocks that are
+included (recursively). To do so we use the function `resolve`.
+
```python file markion.py
[[ include resolve ]]
block_content = { b[0] : [False, b[1]] for b in blocks }
@@ -88,7 +134,11 @@ for f in files:
file_content[f[0]] = ''
file_content[f[0]] += resolve(f[1], block_content)
```
-The following code is the function resolve included in the last code fragment, it won't be directly written on the file, but be included when the `[[ include resolve ]]` is called. As you can see it indents the whole block.
+
+The following code is the function resolve included in the last code fragment,
+it won't be directly written on the file, but be included when the
+`[[ include resolve ]]` is called. As you can see it indents the whole block.
+
```python block resolve
r_include = re.compile('([ \t]*)\[\[\s*include\s+([\w\-.]+)\s*\]\]', flags = re.DOTALL)
def resolve(content, blocks):
@@ -107,13 +157,20 @@ def resolve(content, blocks):
```
### Writing the output to the corresponding files
-Finally, if there weren't any errors, we write the output code into the respective files. To do so, we assign the directory automatically if the option has been delcared, otherwise, we create the output directory if not already created:
+
+Finally, if there weren't any errors, we write the output code into the
+respective files. To do so, we assign the directory automatically if the option
+has been delcared, otherwise, we create the output directory if not already
+created:
+
```python file markion.py
[[ include auto_dir ]]
if not os.path.exists(args.out_dir):
os.mkdirs(args.out_dir)
```
+
And we write the output.
+
```python file markion.py
for fn, fc in file_content.items():
with open(args.out_dir + '/' + fn, 'w') as f:
@@ -121,9 +178,13 @@ for fn, fc in file_content.items():
```
## License
-The program is licensed under the GNU General Public License version 3 (available [here](https://www.gnu.org/licenses/gpl-3.0.html)).
-In order to make sure there is no missunderstanding, we will include the following license notice on our file.
+The program is licensed under the GNU General Public License version 3
+(available [here][gpl]).
+
+In order to make sure there is no missunderstanding, we will include the
+following license notice on our file.
+
```python block license
# Copyright (C) 2019 Oscar Benedito
#
@@ -146,3 +207,5 @@ In order to make sure there is no missunderstanding, we will include the followi
## Author
- **Oscar Benedito** - oscar@oscarbenedito.com
+
+[gpl]: <https://www.gnu.org/licenses/gpl-3.0.html> "The GNU General Public License v3.0"
