OILS / doc / doc-plugins.md View on Github | oilshell.org

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