/ README.html
README.html
1 <!DOCTYPE html> 2 <html xmlns="http://www.w3.org/1999/xhtml" lang xml:lang> 3 <head> 4 <meta charset="utf-8" /> 5 <meta name="generator" content="pandoc" /> 6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> 7 <title>README</title> 8 <style> 9 html { 10 color: #1a1a1a; 11 background-color: #fdfdfd; 12 } 13 body { 14 margin: 0 auto; 15 max-width: 36em; 16 padding-left: 50px; 17 padding-right: 50px; 18 padding-top: 50px; 19 padding-bottom: 50px; 20 hyphens: auto; 21 overflow-wrap: break-word; 22 text-rendering: optimizeLegibility; 23 font-kerning: normal; 24 } 25 @media (max-width: 600px) { 26 body { 27 font-size: 0.9em; 28 padding: 12px; 29 } 30 h1 { 31 font-size: 1.8em; 32 } 33 } 34 @media print { 35 html { 36 background-color: white; 37 } 38 body { 39 background-color: transparent; 40 color: black; 41 font-size: 12pt; 42 } 43 p, h2, h3 { 44 orphans: 3; 45 widows: 3; 46 } 47 h2, h3, h4 { 48 page-break-after: avoid; 49 } 50 } 51 p { 52 margin: 1em 0; 53 } 54 a { 55 color: #1a1a1a; 56 } 57 a:visited { 58 color: #1a1a1a; 59 } 60 img { 61 max-width: 100%; 62 } 63 svg { 64 height: auto; 65 max-width: 100%; 66 } 67 h1, h2, h3, h4, h5, h6 { 68 margin-top: 1.4em; 69 } 70 h5, h6 { 71 font-size: 1em; 72 font-style: italic; 73 } 74 h6 { 75 font-weight: normal; 76 } 77 ol, ul { 78 padding-left: 1.7em; 79 margin-top: 1em; 80 } 81 li > ol, li > ul { 82 margin-top: 0; 83 } 84 blockquote { 85 margin: 1em 0 1em 1.7em; 86 padding-left: 1em; 87 border-left: 2px solid #e6e6e6; 88 color: #606060; 89 } 90 code { 91 font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace; 92 font-size: 85%; 93 margin: 0; 94 hyphens: manual; 95 } 96 pre { 97 margin: 1em 0; 98 overflow: auto; 99 } 100 pre code { 101 padding: 0; 102 overflow: visible; 103 overflow-wrap: normal; 104 } 105 .sourceCode { 106 background-color: transparent; 107 overflow: visible; 108 } 109 hr { 110 background-color: #1a1a1a; 111 border: none; 112 height: 1px; 113 margin: 1em 0; 114 } 115 table { 116 margin: 1em 0; 117 border-collapse: collapse; 118 width: 100%; 119 overflow-x: auto; 120 display: block; 121 font-variant-numeric: lining-nums tabular-nums; 122 } 123 table caption { 124 margin-bottom: 0.75em; 125 } 126 tbody { 127 margin-top: 0.5em; 128 border-top: 1px solid #1a1a1a; 129 border-bottom: 1px solid #1a1a1a; 130 } 131 th { 132 border-top: 1px solid #1a1a1a; 133 padding: 0.25em 0.5em 0.25em 0.5em; 134 } 135 td { 136 padding: 0.125em 0.5em 0.25em 0.5em; 137 } 138 header { 139 margin-bottom: 4em; 140 text-align: center; 141 } 142 #TOC li { 143 list-style: none; 144 } 145 #TOC ul { 146 padding-left: 1.3em; 147 } 148 #TOC > ul { 149 padding-left: 0; 150 } 151 #TOC a:not(:hover) { 152 text-decoration: none; 153 } 154 code{white-space: pre-wrap;} 155 span.smallcaps{font-variant: small-caps;} 156 div.columns{display: flex; gap: min(4vw, 1.5em);} 157 div.column{flex: auto; overflow-x: auto;} 158 div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} 159 160 ul.task-list[class]{list-style: none;} 161 ul.task-list li input[type="checkbox"] { 162 font-size: inherit; 163 width: 0.8em; 164 margin: 0 0.8em 0.2em -1.6em; 165 vertical-align: middle; 166 } 167 .display.math{display: block; text-align: center; margin: 0.5rem auto;} 168 </style> 169 </head> 170 <body> 171 <nav id="TOC" role="doc-toc"> 172 <ul> 173 <li><a href="#exfmt---format-shell-examples-in-documentation" id="toc-exfmt---format-shell-examples-in-documentation"><code>exfmt</code> 174 - format shell examples in documentation</a> 175 <ul> 176 <li><a href="#example" id="toc-example">Example</a></li> 177 <li><a href="#formatted-example" id="toc-formatted-example">Formatted 178 example</a></li> 179 <li><a href="#overview-of-operation" id="toc-overview-of-operation">Overview of operation</a></li> 180 <li><a href="#exfmt-fenced-code-block" id="toc-exfmt-fenced-code-block"><code>exfmt</code> fenced code 181 block</a></li> 182 <li><a href="#on-formatting" id="toc-on-formatting">On 183 formatting</a></li> 184 </ul></li> 185 </ul> 186 </nav> 187 <h1 id="exfmt---format-shell-examples-in-documentation"><code>exfmt</code> - 188 format shell examples in documentation</h1> 189 <p><code>exfmt</code> formats a Markdown file with examples of shell 190 commands so that the examples are formatted and the output from 191 executing them is included.</p> 192 <h2 id="example">Example</h2> 193 <pre><code>```exfmt 194 - command: echo hello world 195 - command: pwd 196 ```</code></pre> 197 <p>This would be replaced in output as:</p> 198 <pre><code>``` 199 <blockquote class="shell-example"> 200 <div class="shell"> 201 <code class="prompt">$</code> 202 <span class="user">echo hello world</span> 203 <br/> 204 <span class="stdout"> 205 hello, world 206 </span> 207 </div> 208 </blockquote> 209 ```</code></pre> 210 <p>The output is HTML so that it can be styled with CSS.</p> 211 <h2 id="formatted-example">Formatted example</h2> 212 <p>The HTML code from above is included below in the Markdown for this 213 <code>README</code> file to show that the approach works.</p> 214 <blockquote class="shell-example"> 215 <div class="shell"> 216 <p><code class="prompt">$</code> <span class="user">echo hello 217 world</span> <br /> <span class="stdout"> hello, world </span></p> 218 </div> 219 </blockquote> 220 <h2 id="overview-of-operation">Overview of operation</h2> 221 <p>Simplest usage (there will be other options):</p> 222 <pre><code>exfmt [INPUT...] [-o OUTPUT]</code></pre> 223 <p>What this does:</p> 224 <ul> 225 <li>read and parse input files (stdin if not named)</li> 226 <li>for every fenced code block tagged <code>exfmt</code>: 227 <ul> 228 <li>parse as YAML</li> 229 <li>execute specified commands</li> 230 <li>generate HTML to replace block for output</li> 231 </ul></li> 232 <li>write output file (stdout if not named)</li> 233 </ul> 234 <p>It is up to the user to integrate this into their document building 235 workflow. <code>exfmt</code> won’t overwrite an existing output file, 236 for safety.</p> 237 <p>The commands are run as if the user runs them. This is dangerous! 238 It’s best to safeguard by running <code>exfmt</code> in a safe and 239 secure environment.</p> 240 <h2 id="exfmt-fenced-code-block"><code>exfmt</code> fenced code 241 block</h2> 242 <p>A fenced code block tagged <code>exfmt</code> contains YAML list with 243 objects with the following keys:</p> 244 <ul> 245 <li><strong>command</strong> - the shell command to run; this run using 246 <code>bash -c</code> with <code>set -euo pipefail</code></li> 247 <li><strong>exit</strong> - the expected exit code; this is optional and 248 defaults to 0; set to something else to have a command that fails</li> 249 </ul> 250 <h2 id="on-formatting">On formatting</h2> 251 <p><code>exfmt</code> will allow you to style at least the following, by 252 setting a class on the generated HTML element:</p> 253 <ul> 254 <li>the prompt</li> 255 <li>the command that is run</li> 256 <li>output to stdout</li> 257 <li>output to stderr</li> 258 <li>a message after the command if exit code is zero</li> 259 <li>a message after the command if exit code is non-zero</li> 260 <li>line number in the example</li> 261 </ul> 262 </body> 263 </html>