| 1 | ---
|
| 2 | in_progress: yes
|
| 3 | ---
|
| 4 |
|
| 5 | Examples of HTML Plugins
|
| 6 | ========================
|
| 7 |
|
| 8 | This file is essentially a unit test for [doctools/oils_doc.py]($oils-src), which
|
| 9 | contains all the HTML plugins.
|
| 10 |
|
| 11 | Related: [How We Build Oils Documentation](doc-toolchain.html).
|
| 12 |
|
| 13 | <div id="toc">
|
| 14 | </div>
|
| 15 |
|
| 16 | ## Link Shortcuts with `$`
|
| 17 |
|
| 18 | - `$xref`: [bash]($xref)
|
| 19 | - `$blog-tag`: [oils-release]($blog-tag)
|
| 20 | - `$oilshell-blog-tag`: [zephyr-asdl]($oilshell-blog-tag)
|
| 21 |
|
| 22 | Links to Github:
|
| 23 |
|
| 24 | - `$oils-src`: [INSTALL.txt]($oils-src), [INSTALL.txt]($oils-src:INSTALL.txt)
|
| 25 | - `$oils-blog-code-src`: [interactive-shell/README.md]($oils-blog-code-src)
|
| 26 | - `$oils-issue`: [issue 11]($oils-issue:11)
|
| 27 | - `$oils-commit`: [this commit]($oils-commit:a1dad10d53b1fb94a164888d9ec277249ae98b58)
|
| 28 | - `$oils-wiki`: [Surveys and Comparisons]($oils-wiki)
|
| 29 |
|
| 30 | Links to the Oils Refernce:
|
| 31 |
|
| 32 | - `$oils-doc`: [J8 Notation]($oils-doc:j8-notation.html)
|
| 33 | - `$chap-type-method`: [Str]($chap-type-method:Str)
|
| 34 |
|
| 35 |
|
| 36 | ## Syntax Highlighting Specified In Front matter
|
| 37 |
|
| 38 | If every `pre` block in a document needs the same highlighter, you can specify
|
| 39 | it in the front matter like this:
|
| 40 |
|
| 41 | ---
|
| 42 | default_highlighter: oils-sh
|
| 43 | ---
|
| 44 |
|
| 45 | My Title
|
| 46 | ========
|
| 47 |
|
| 48 | ## Syntax Highlighting With Fenced Code Blocks
|
| 49 |
|
| 50 | ### sh-prompt
|
| 51 |
|
| 52 | Highlights the `$` line. For example, this input
|
| 53 |
|
| 54 | ```sh-prompt
|
| 55 | $ echo hi # comment
|
| 56 | hi
|
| 57 | ```
|
| 58 |
|
| 59 | produces
|
| 60 |
|
| 61 | ```sh-prompt
|
| 62 | $ echo hi # comment
|
| 63 | hi
|
| 64 | ```
|
| 65 |
|
| 66 | ### oils-sh
|
| 67 |
|
| 68 | A generic formatter that works for both shell and YSH code. It's used in
|
| 69 | [idioms.html](idioms.html), [known differences](known-differences.html), and is
|
| 70 | now the default for the Oils blog.
|
| 71 |
|
| 72 | (Detail: it's the same as `sh-prompt` for now. We might want to do something
|
| 73 | smarter.)
|
| 74 |
|
| 75 | ### none (Explicit Override)
|
| 76 |
|
| 77 | To override the default highlighter with none:
|
| 78 |
|
| 79 | ```none
|
| 80 | $ echo 'no syntax highlighting'
|
| 81 | ```
|
| 82 |
|
| 83 | Result:
|
| 84 |
|
| 85 | ```none
|
| 86 | $ echo 'no syntax highlighting'
|
| 87 | ```
|
| 88 |
|
| 89 | ### Pygments Lexers
|
| 90 |
|
| 91 | Use any pygments lexer:
|
| 92 |
|
| 93 | ```python
|
| 94 | x = 42
|
| 95 | print(x, file=sys.stderr)
|
| 96 | ```
|
| 97 |
|
| 98 | produces
|
| 99 |
|
| 100 | ```python
|
| 101 | x = 42
|
| 102 | print(x, file=sys.stderr)
|
| 103 | ```
|
| 104 |
|
| 105 | ### Plugins We Should Have
|
| 106 |
|
| 107 | - ysh and osh. *A Tour of YSH* could use it to show which code blocks can be
|
| 108 | extracted and run.
|
| 109 | - Side-by-side sh and YSH
|
| 110 | - Side-by-side PCRE and Eggex
|
| 111 | - sh-session - How to replace the data?
|
| 112 |
|
| 113 | A shell session could look like this:
|
| 114 |
|
| 115 | ```session-bash
|
| 116 | $ echo one
|
| 117 | one
|
| 118 |
|
| 119 | $ for x in foo bar; do
|
| 120 | > echo $x
|
| 121 | > done
|
| 122 | foo
|
| 123 | bar
|
| 124 | ```
|
| 125 |
|
| 126 | or
|
| 127 |
|
| 128 | ```session-ysh
|
| 129 | $ echo one
|
| 130 | one
|
| 131 |
|
| 132 | $ for x in foo bar {
|
| 133 | > echo $x
|
| 134 | > }
|
| 135 | foo
|
| 136 | bar
|
| 137 | ```
|
| 138 |
|
| 139 | <!--
|
| 140 | Workflow:
|
| 141 | - You should write this directly in Markdown. Even the output. So you know
|
| 142 | what you expect.
|
| 143 | - Syntax highlighter:
|
| 144 | - $ and > lines prefixes in bold, with the code in blue
|
| 145 | - the rest of the output in black
|
| 146 | - Verifier
|
| 147 | - Will extract:
|
| 148 | 1. sequences of lines that begin with $ and continue with >
|
| 149 | 2. expected output (not beginning with $ or >)
|
| 150 | - It will run those in a CLEAN working directory, one after the other
|
| 151 | - maybe it inserts 'echo __MAGIC_DELIMITER__ between them?
|
| 152 | - Or you could use the headless shell! To preserve state!
|
| 153 | - And then it will diff the actual output vs. the expected output
|
| 154 |
|
| 155 | Another idea: PS2 should lead with the same number of spaces as PS1:
|
| 156 |
|
| 157 | ysh$ for x in foo bar {
|
| 158 | . echo $x
|
| 159 | . }
|
| 160 | foo
|
| 161 | bar
|
| 162 |
|
| 163 | This looks cleaner.
|
| 164 | -->
|
| 165 |
|
| 166 | Embeddings:
|
| 167 |
|
| 168 | - Embed Image Preview of Web Page?
|
| 169 | - Embed Github Commit?
|
| 170 | - hashdiv has this for stories
|
| 171 | - Graphviz
|
| 172 | - LaTeX (although I don't really use it)
|
| 173 |
|