1  # `exfmt` - format shell examples in documentation
 2  
 3  `exfmt` formats a Markdown file with examples of shell commands so that
 4  the examples are formatted and the output from executing them is included.
 5  
 6  ## Example
 7  
 8  ````````
 9  ```exfmt
10  - command: echo hello world
11  - command: pwd
12  ```
13  ````````
14  
15  This would be replaced in output as:
16  
17  ````````
18  ```
19  <blockquote class="shell-example">
20  <div class="shell">
21  <code class="prompt">$</code>
22  <span class="user">echo hello world</span>
23  <br/>
24  <span class="stdout">
25  hello, world
26  </span>
27  </div>
28  </blockquote>
29  ```
30  ````````
31  
32  The output is HTML so that it can be styled with CSS.
33  
34  ## Formatted example
35  
36  The HTML code from above is included below in the Markdown for this
37  `README` file to show that the approach works.
38  
39  <blockquote class="shell-example">
40  <div class="shell">
41  <code class="prompt">$</code>
42  <span class="user">echo hello world</span>
43  <br/>
44  <span class="stdout">
45  hello, world
46  </span>
47  </div>
48  </blockquote>
49  
50  ## Overview of operation
51  
52  Simplest usage (there will be other options):
53  
54  ```
55  exfmt [INPUT...] [-o OUTPUT]
56  ```
57  
58  What this does:
59  
60  * read and parse input files (stdin if not named)
61  * for every fenced code block tagged `exfmt`:
62    - parse as YAML
63    - execute specified commands
64    - generate HTML to replace block for output
65  * write output file (stdout if not named)
66  
67  It is up to the user to integrate this into their document building
68  workflow. `exfmt` won't overwrite an existing output file, for safety.
69  
70  The commands are run as if the user runs them. This is dangerous! It's
71  best to safeguard by running `exfmt` in a safe and secure environment.
72  
73  ## `exfmt` fenced code block
74  
75  A fenced code block tagged `exfmt` contains YAML list with objects
76  with the following keys:
77  
78  - **command** - the shell command to run; this run using `bash -c`
79    with `set -euo pipefail`
80  - **exit** - the expected exit code; this is optional and defaults
81    to 0; set to something else to have a command that fails
82  
83  ## On formatting
84  
85  `exfmt` will allow you to style at least the following, by setting a
86  class on the generated HTML element:
87  
88  * the prompt
89  * the command that is run
90  * output to stdout
91  * output to stderr
92  * a message after the command if exit code is zero
93  * a message after the command if exit code is non-zero
94  * line number in the example