1 | ---
|
2 | in_progress: yes
|
3 | all_docs_url: -
|
4 | ---
|
5 |
|
6 | All Docs
|
7 | ========
|
8 |
|
9 | This page links to all docs. A dagger † means a doc isn't finished.
|
10 |
|
11 | See [Published Docs](published.html) for those that are ready to read.
|
12 |
|
13 |
|
14 | <!--
|
15 | <div id="toc">
|
16 | </div>
|
17 | -->
|
18 |
|
19 | ## Good Places to Start
|
20 |
|
21 | - [A Tour of YSH](ysh-tour.html)
|
22 | - [YSH vs. Shell Idioms](idioms.html)
|
23 | - [**Oils Reference**](ref/index.html) - underlies the [help][] builtin
|
24 | - [FAQ on Docs](faq-doc.html). **Look here if you can't find
|
25 | something**.
|
26 |
|
27 | [help]: ref/chap-builtin-cmd.html#help
|
28 |
|
29 | ## Preliminaries
|
30 |
|
31 | - [INSTALL](INSTALL.html). How do I install Oils? This text file is also in
|
32 | the `oils-for-unix` tarball.
|
33 | - [Portability](portability.html)
|
34 | - [Getting Started](getting-started.html). How do I use the shell?
|
35 |
|
36 | ## Interactive Shell
|
37 |
|
38 | - [Headless Mode](headless.html). For alternative UIs on top of YSH.
|
39 | - [Completion](completion.html) †. We emulate bash completion.
|
40 |
|
41 | ## OSH is a Compatible Shell
|
42 |
|
43 | - [Shell Language Idioms](shell-idioms.html) has some advice for using any
|
44 | shell, not just Oils.
|
45 | - [OSH Standard Library](lib-osh.html) †. Small but useful enhancements.
|
46 |
|
47 | For sophisticated users:
|
48 |
|
49 | - [Known Differences Between OSH and Other Shells](known-differences.html)
|
50 | - [OSH Quirks](quirks.html) for compatibility.
|
51 |
|
52 | ## YSH is a New, Powerful Shell
|
53 |
|
54 | - [A Tour of YSH](ysh-tour.html). Explains YSH from scratch, without referring
|
55 | to shell's legacy.
|
56 | - [What Breaks When You Upgrade to YSH](upgrade-breakage.html). When you turn
|
57 | on YSH, there are some shell constructs you can no longer use. We try to
|
58 | minimize the length of this list.
|
59 | - [YSH Language FAQ](ysh-faq.html)
|
60 | - [YSH Style Guide](style-guide.html)
|
61 |
|
62 | ### Comparisons
|
63 |
|
64 | - [YSH vs. Shell Idioms](idioms.html). A list of code snippets.
|
65 | - [YSH vs. Shell](ysh-vs-shell.html). High-level descriptions: how does YSH
|
66 | differ from Bourne/POSIX shell?
|
67 | - [YSH Expressions vs. Python](ysh-vs-python.html). The expression language is
|
68 | borrowed from Python, with a few tweaks.
|
69 | - [Novelties in OSH and YSH](novelties.html). May be helpful for experienced
|
70 | programmers.
|
71 |
|
72 | ### Design Concepts
|
73 |
|
74 | - [YSH Language Influences](language-influences.html) - Shell, Python,
|
75 | JavaScript, Lisp, ...
|
76 | - Syntax
|
77 | - [A Feel For YSH Syntax](syntax-feelings.html)
|
78 | - [Syntactic Concepts](syntactic-concepts.html) may help you remember the
|
79 | language.
|
80 | - [Command vs. Expression Mode](command-vs-expression-mode.html).
|
81 | - [Warts](warts.html). Mostly for compatibility.
|
82 |
|
83 | YSH has 3 main sublanguages:
|
84 |
|
85 | - **Command** language, which now consistently uses `{ }` for blocks.
|
86 | - [Hay - Custom Languages for Unix Systems](hay.html). Use Ruby-like
|
87 | blocks to declare data and interleaved code.
|
88 | - **Word** language.
|
89 | - [Simple Word Evaluation](simple-word-eval.html). Written for shell
|
90 | experts.
|
91 | - **Expression** language on typed data.
|
92 | - [Egg Expressions](eggex.html). A new regex syntax, abbreviated *eggex*.
|
93 | - [YSH Regex API](ysh-regex-api.html). Convenient and powerful.
|
94 |
|
95 | Features:
|
96 |
|
97 | - [Guide to YSH Error Handling](ysh-error.html)
|
98 | - [Guide to Procs and Funcs](proc-func.html)
|
99 | - [Block Literals](block-literals.html) †
|
100 | - [Streams, Tables, Processes - awk, R, xargs](stream-table-process.html) †
|
101 |
|
102 | Crosscutting design issues:
|
103 |
|
104 | - [Variable Declaration, Mutation, and Scope](variables.html)
|
105 | - [Strings: Quotes, Interpolation, Escaping, and Buffers](strings.html) †
|
106 | - [Unicode](unicode.html) †. Oils supports and prefers UTF-8.
|
107 | - [YSH I/O Builtins](io-builtins.html) †
|
108 |
|
109 | ## Data Languages Avoid Ad-Hoc Parsing
|
110 |
|
111 | YSH programs "talk about" these data languages, also called interchange formats
|
112 | or protocols. In-memory data structures are *in service* of data languages on
|
113 | the wire, **not** the other way around.
|
114 |
|
115 | - [J8 Notation](j8-notation.html). An upgrade of JSON to bytes, strings,
|
116 | lines, and structured data.
|
117 | - [JSON](json.html). Some usage details.
|
118 | - [Framing](framing.html) †
|
119 | - [BYO Protocols](byo.html) - for testing and completion.
|
120 |
|
121 | ## The Shared Oils Runtime
|
122 |
|
123 | - [YSH Fixes Shell's Error Handling (`errexit`)](error-handling.html)
|
124 | - [Oils Error Catalog, With Hints](error-catalog.html)
|
125 | - [Tracing Execution](xtrace.html). YSH enhances shell's `set -x`.
|
126 | - [Options](options.html) †. Parsing and runtime options turn OSH into YSH.
|
127 |
|
128 | Internal details:
|
129 |
|
130 | - [Interpreter State](interpreter-state.html) †. What's inside a shell
|
131 | interpreter?
|
132 | - [Process Model](process-model.html) †. The shell language is a thin
|
133 | layer over the Unix kernel.
|
134 |
|
135 | ## For Contributors
|
136 |
|
137 | - [README.md](oils-repo/README.html). If you want to modify Oils, start here.
|
138 | We welcome contributions!
|
139 | - [Doc Toolchain](doc-toolchain.html) and [Doc Plugins](doc-plugins.html).
|
140 | - [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki)
|
141 | - [Old Docs](old/index.html). Drafts that may be deleted.
|
142 |
|
143 | Internal Architecture:
|
144 |
|
145 | - [Notes on Oils Architecture](architecture-notes.html)
|
146 | - [Parser Architecture](parser-architecture.html)
|
147 | - [Pretty Printing](pretty-printing.html) - March 2024 design notes.
|
148 | - [mycpp/README](oils-repo/mycpp/README.html) - How we translate typed Python to
|
149 | C++.
|
150 |
|
151 | ## More
|
152 |
|
153 | - [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki).
|
154 | - [The blog](https://www.oilshell.org/blog/) has useful background information,
|
155 | although older posts are more likely to have incorrect information.
|
156 | - [The home page](https://www.oilshell.org/) has links to docs for new users.
|
157 |
|
158 | Old:
|
159 |
|
160 | - [INSTALL-old](INSTALL-old.html) for the slow `oil-$VERSION` tarball, based on
|
161 | CPython.
|
162 |
|
163 | <!-- vim: set sw=2: -->
|