Merge pull request #1 from ell1e/patch-1

Update README.mdr
fennecdjay · Mar 23, 2024 · 059377c · 059377c
2 parents 8897e0f + 5d8cce7
commit 059377c
Show file tree

Hide file tree

Showing 2 changed files with 108 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -5,23 +5,36 @@
 ![Windows](https://github.com/fennecdjay/mdr/workflows/Windows/badge.svg)
 [![Line Count](https://tokei.rs/b1/github/fennecdjay/mdr)](https://github.com/Gwion/mdr)  
 
+mdr is a **small** *program* and *markup*
+designed to facilitate documentation and testing.
+It can both generate documentation pages and
+generate and actualaly test small code examples
+in your documentation. (This ensures any code
+examples you present to your users actually work.)
 
+![logo](assets/logoreadme.png "The Mdr logo! (WIP)")
 
-mdr is a **small** *program* and *markup*
-designed to facilitate documentation and testing.  
+I started this tool to help with [Gwion](https://github.com/fennecdjay/gwion)'s
+development, but it is not tied in any way to this project.
 
+Let's go over the basic functionality... :smile:
 
-![logo](assets/logoreadme.png "The Mdr logo! (WIP)")
 
-I started it to ease [Gwion](https://github.com/fennecdjay/gwion)'s devellopment,
-but it is not tied in any way to this project.  
+## How to write documentation pages with `mdr`
+
+For how to do a basic documentation
+page, [see this page's original source](
+https://github.com/fennecdjay/mdr/blob/master/README.mdr).
+
 
-Let' walktrough... :smile:
+## How to write code examples with `mdr`
 
-## Hello World
-let's write our first litterate progam.
+Let's write our first code example created from our
+documentation page, which also shows off templating and
+how to have the code automatically compiled and tested.
 
-### Define program structure
+
+### Define a program structure
 
   > hello_world.c
 ``` hello_world.c  
@@ -31,41 +44,42 @@ int main(int argc, char** argv) {
   @[[ Print ]]
 }
 ```  
+We fill in the `Includes` template variable as follows:
 
 
-### Add Headers
-As we need the *puts* function, we need **stdio** headers.
+### Filling in template variables
 
+As we need the *puts* function, we need **stdio** headers.
 
   > Includes
 ``` Includes  
 #include <stdio.h>
 ```  
 
-
-### Print function
+We also fill in the print function we use above:
 
   > Print
 ``` Print  
 puts("Hello, World!");
 ```  
 
 
+### Compiling the example code
 
-### Compile
-let's compile *hello_world.c*.
+Now, let's compile *hello_world.c* to make sure
+this test code owrks.
 
   > exec: cc hello_world.c -o hello_world  
 ```
 ```  
 
-
-Yes, there should be no output, and that good news.
+Yes, there should be no output, and that's good news
+since that means no compilation errors.
 
 
+### Including a code file or other output
 
-### Check
-Let's look at hello_world.c
+Let's look at *hello_world.c*:
 
   > exec: cat hello_world.c  
 ```
@@ -77,22 +91,23 @@ int main(int argc, char** argv) {
 ```  
 
 That's the content of the source file we generated (and compiled).
+You can see how this can be used for arbitrary shell commands
+to generate output.
 
 
+### Testing example code
 
-### Test
-
-Then we run it
+Then we run our test program:
 
   > exec: ./hello_world  
 ```
 Hello, World!
 ```  
 
-
 Do we read *Hello World!* ?
 Assuming yes, let's continue.
 
+
 ### More test
 
   > exec: [ "$(./hello_world)" = "Hello, World!" ] && echo "OK" || echo "NOT_OK"  
@@ -101,7 +116,7 @@ OK
 ```  
 
 
-## Building
+## Building `mdr`
 
 As a C program, it seemed natural to use [make](https://www.gnu.org/software/make)
 as a build system.
@@ -110,20 +125,19 @@ as a build system.
 make
 ```
 
-## Testing
-
-Also using make:
+## Testing `mdr`
+                    
+Also using make:    
 ``` sh
-make test
-```
+make test                 
+```                   
 
 You can also try
 ``` sh
 bash scripts/test.sh
 ```
 
-
-## Installing
+## Installing `mdr`
 
 As easy as before, just type.
 
@@ -133,6 +147,15 @@ make install
 or just copy `mdr` somewhere in your path.
 
 
+## Using `mdr`
+
+To generate this doc page itself, use this command
+in the repository root:
+
+``` sh
+mdr README.mdr
+```
+
 -------
 
 generated from [this file](https://github.com/fennecdjay/mdr/blob/master/README.mdr)

diff --git a/README.mdr b/README.mdr
@@ -5,23 +5,36 @@
 ![Windows](https://github.com/fennecdjay/mdr/workflows/Windows/badge.svg)
 [![Line Count](https://tokei.rs/b1/github/fennecdjay/mdr)](https://github.com/Gwion/mdr)  
 
+mdr is a **small** *program* and *markup*
+designed to facilitate documentation and testing.
+It can both generate documentation pages and
+generate and actualaly test small code examples
+in your documentation. (This ensures any code
+examples you present to your users actually work.)
 
+![logo](assets/logoreadme.png "The Mdr logo! (WIP)")
 
-mdr is a **small** *program* and *markup*
-designed to facilitate documentation and testing.  
+I started this tool to help with [Gwion](https://github.com/fennecdjay/gwion)'s
+development, but it is not tied in any way to this project.
 
+Let's go over the basic functionality... :smile:
 
-![logo](assets/logoreadme.png "The Mdr logo! (WIP)")
 
-I started it to ease [Gwion](https://github.com/fennecdjay/gwion)'s devellopment,
-but it is not tied in any way to this project.  
+## How to write documentation pages with `mdr`
+
+For how to do a basic documentation
+page, [see this page's original source](
+https://github.com/fennecdjay/mdr/blob/master/README.mdr).
+
 
-Let' walktrough... :smile:
+## How to write code examples with `mdr`
 
-## Hello World
-let's write our first litterate progam.
+Let's write our first code example created from our
+documentation page, which also shows off templating and
+how to have the code automatically compiled and tested.
 
-### Define program structure
+
+### Define a program structure
 
 @``` hello_world.c
 @[[Includes]]
@@ -30,60 +43,62 @@ int main(int argc, char** argv) {
   @[[Print]]
 }
 @```
+We fill in the `Includes` template variable as follows:
 
 
-### Add Headers
-As we need the *puts* function, we need **stdio** headers.
+### Filling in template variables
 
+As we need the *puts* function, we need **stdio** headers.
 
 @``` Includes
 #include <stdio.h>
 @```
 
-
-### Print function
+We also fill in the print function we use above:
 
 @``` Print
 puts("Hello, World!");
 @```
 
 
+### Compiling the example code
 
-### Compile
-let's compile *hello_world.c*.
+Now, let's compile *hello_world.c* to make sure
+this test code owrks.
 
 @exec cc hello_world.c -o hello_world
 
-
-Yes, there should be no output, and that good news.
+Yes, there should be no output, and that's good news
+since that means no compilation errors.
 
 
+### Including a code file or other output
 
-### Check
-Let's look at hello_world.c
+Let's look at *hello_world.c*:
 
 @exec cat hello_world.c
 
 That's the content of the source file we generated (and compiled).
+You can see how this can be used for arbitrary shell commands
+to generate output.
 
 
+### Testing example code
 
-### Test
-
-Then we run it
+Then we run our test program:
 
 @exec ./hello_world
 
-
 Do we read *Hello World!* ?
 Assuming yes, let's continue.
 
+
 ### More test
 
 @exec [ "$(./hello_world)" = "Hello, World!" ] && echo "OK" || echo "NOT_OK"
 
 
-## Building
+## Building `mdr`
 
 As a C program, it seemed natural to use [make](https://www.gnu.org/software/make)
 as a build system.
@@ -92,20 +107,19 @@ as a build system.
 make
 ```
 
-## Testing
-
-Also using make:
+## Testing `mdr`
+                    
+Also using make:    
 ``` sh
-make test
-```
+make test                 
+```                   
 
 You can also try
 ``` sh
 bash scripts/test.sh
 ```
 
-
-## Installing
+## Installing `mdr`
 
 As easy as before, just type.
 
@@ -115,6 +129,15 @@ make install
 or just copy `mdr` somewhere in your path.
 
 
+## Using `mdr`
+
+To generate this doc page itself, use this command
+in the repository root:
+
+``` sh
+mdr README.mdr
+```
+
 -------
 
 generated from [this file](https://github.com/fennecdjay/mdr/blob/master/README.mdr)