OILS / doc / index.md View on Github | oilshell.org

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