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

157 lines, 115 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- [Guide to YSH Error Handling](ysh-error.html)
99- [Variable Declaration, Mutation, and Scope](variables.html)
100- [Strings: Quotes, Interpolation, Escaping, and Buffers](strings.html) &dagger;
101 - [Unicode](unicode.html) &dagger;. Oils supports and prefers UTF-8.
102- [YSH I/O Builtins](io-builtins.html) &dagger;
103
104## Data Languages Avoid Ad-Hoc Parsing
105
106YSH programs "talk about" these data languages, also called interchange formats
107or protocols. In-memory data structures are *in service* of data languages on
108the wire, **not** the other way around.
109
110- [J8 Notation](j8-notation.html). An upgrade of JSON to bytes, strings,
111 lines, and structured data.
112 - [JSON](json.html). Some usage details.
113 - [Framing](framing.html) &dagger;
114
115## The Shared Oils Runtime
116
117- [YSH Fixes Shell's Error Handling (`errexit`)](error-handling.html)
118- [Oils Error Catalog, With Hints](error-catalog.html)
119- [Tracing Execution](xtrace.html). YSH enhances shell's `set -x`.
120- [Options](options.html) &dagger;. Parsing and runtime options turn OSH into YSH.
121
122Internal details:
123
124- [Interpreter State](interpreter-state.html) &dagger;. What's inside a shell
125 interpreter?
126- [Process Model](process-model.html) &dagger;. The shell language is a thin
127 layer over the Unix kernel.
128
129## For Contributors
130
131- [README.md](oils-repo/README.html). If you want to modify Oils, start here.
132 We welcome contributions!
133- [Doc Toolchain](doc-toolchain.html) and [Doc Plugins](doc-plugins.html).
134- [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki)
135- [Old Docs](old/index.html). Drafts that may be deleted.
136
137Internal Architecture:
138
139- [Notes on Oils Architecture](architecture-notes.html)
140 - [Parser Architecture](parser-architecture.html)
141- [Pretty Printing](pretty-printing.html) - March 2024 design notes.
142- [mycpp/README](oils-repo/mycpp/README.html) - How we translate typed Python to
143 C++.
144
145## More
146
147- [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki).
148- [The blog](https://www.oilshell.org/blog/) has useful background information,
149 although older posts are more likely to have incorrect information.
150- [The home page](https://www.oilshell.org/) has links to docs for new users.
151
152Old:
153
154- [INSTALL-old](INSTALL-old.html) for the slow `oil-$VERSION` tarball, based on
155 CPython.
156
157<!-- vim: set sw=2: -->