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

157 lines, 116 significant
1---
2in_progress: yes
3all_docs_url: -
4---
5
6All Docs
7========
8
9Oils is **our upgrade path from bash** to a better language and runtime. This
10page links to all the documentation.
11
12<div id="toc">
13</div>
14
15&dagger; means a doc is not ready to read yet.
16
17## Preliminaries
18
19- [INSTALL](INSTALL.html). How do I install Oils? This text file is also in the
20 tarball. <!-- TODO: C++ tarball -->
21- [Getting Started](getting-started.html). How do I use the shell?
22- [FAQ on Documentation](faq-doc.html). **Look here if you can't find
23 something**.
24
25## Reference
26
27Like many other docs, the reference is still in progress:
28
29- [Oils Reference](ref/index.html) &dagger; - These docs underlie `help` builtin, and
30 are also published online.
31- Links to topics within each chapter:
32 - [OSH Table of Contents](ref/toc-osh.html) &dagger;
33 - [YSH Table of Contents](ref/toc-ysh.html) &dagger;
34 - [Data Notation Table of Contents](ref/toc-data.html) &dagger;
35- [Style Guide](style-guide.html) gives coding recommendations.
36
37## Interactive Shell
38
39- [Headless Mode](headless.html). For alternative UIs on top of YSH.
40- [Completion](completion.html) &dagger;. We emulate bash completion.
41
42## OSH is a Compatible Shell
43
44These docs are for advanced users:
45
46- [Known Differences Between OSH and Other Shells](known-differences.html)
47- [OSH Quirks](quirks.html) for compatibility.
48- [Shell Language Idioms](shell-idioms.html) has some advice for using any
49 shell, not just Oils.
50
51## YSH is a Shell with Structured Data
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). Common questions about the
59 language.
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<!-- TODO: proc-func.html -- Informal guide to procs and funcs -->
104
105## Data Languages Avoid Ad-Hoc Parsing
106
107YSH programs "talk about" these data languages, also called interchange formats
108or protocols. In-memory data structures are *in service* of data languages on
109the wire, **not** the other way around.
110
111- [J8 Notation](j8-notation.html). An upgrade of JSON to bytes, strings,
112 lines, and structured data.
113 - [JSON](json.html). Some usage details.
114 - [Framing](framing.html)
115
116TODO:
117
118- Packle &dagger;
119
120## The Shared Oils Runtime
121
122- [YSH Fixes Shell's Error Handling (`errexit`)](error-handling.html)
123- [Oils Error Catalog, With Hints](error-catalog.html)
124- [Tracing Execution](xtrace.html). YSH enhances shell's `set -x`.
125- [Options](options.html) &dagger;. Parsing and runtime options turn OSH into YSH.
126
127Internal details:
128
129- [Interpreter State](interpreter-state.html) &dagger;. What's inside a shell
130 interpreter?
131- [Process Model](process-model.html) &dagger;. The shell language is a thin
132 layer over the Unix kernel.
133
134## For Contributors
135
136- [README.md](oils-repo/README.html). If you want to modify Oils, start here.
137 We welcome contributions!
138- [Doc Toolchain](doc-toolchain.html) and [Doc Plugins](doc-plugins.html).
139- [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki)
140- [Old Docs](old/index.html). Drafts that may be deleted.
141
142Internal Architecture:
143
144- [Notes on Oils Architecture](architecture-notes.html)
145 - [Parser Architecture](parser-architecture.html)
146- [Pretty Printing](pretty-printing.html) - March 2024 design notes.
147- [mycpp/README](oils-repo/mycpp/README.html) - How we translate typed Python to
148 C++.
149
150## More
151
152- [Github Wiki for oilshell/oil](https://github.com/oilshell/oil/wiki).
153- [The blog](https://www.oilshell.org/blog/) has useful background information,
154 although older posts are more likely to have incorrect information.
155- [The home page](https://www.oilshell.org/) has links to docs for new users.
156
157<!-- vim: set sw=2: -->