Oils Reference

A guide to everything in Oils (in progress).

Go back to All Docs on Oils for design docs and tutorials.

Table of Contents
Online HTML
help builtin command
More About This Reference
Terminology
Directory Structures

Online HTML

Oils has two major "modes" for shell:

OSH Table of Contents - Compatible

YSH Table of Contents - New and Powerful

You can use OSH by itself, YSH by itself, or upgrade OSH to YSH.

Those two docs link to dozens of topics within these 12 chapters:

  1. Front End
  2. Command Language
  3. Word Language
  4. OSH Assignment
  5. Mini Languages
  6. Builtin Commands
  7. Global Shell Options
  8. Special Variables
  9. Plugins and Hooks
  10. YSH Expression Language
  11. YSH Types and Methods
  12. Builtin Functions

Data Notation Table of Contents - Languages for data are complementary to shell programs.

Topics in these 3 chapters:

  1. JSON / J8 Notation
  2. Packle (TODO)
  3. Errors

help builtin command

When you type help in OSH or YSH, the command shows some of this material, and prints hyperlinks to it.

More About This Reference

Terminology

There are 3 levels in this tree of docs, which underlies the help builtin:

  1. Chapter - An HTML doc that's part of the reference. May apply to OSH, YSH or both.
  2. Section - An <h2> heading in a chapter
  3. Topic - An <h3> heading in a chapter.

More terminology:

Directory Structures

The source code is simply a tree of Markdown files:

doc/
  release-index.md     # /release/$VERSION/

  index.md             # All Docs on Oils, /release/$VERSION/doc/
  getting-started.md
  ...

  ref/
    index.md           # this page, the Oils Reference
    toc-osh.md       # link to OSH topics
    toc-ysh.md       # link to YSH topics
    toc-data.md

    chap-cmd-lang.md   # chapter on the command language
    ...

And the URLs basically mirror the source code:

/release/$VERSION/
  index.html
  doc/
    index.html
    getting-started.html
    ...

    ref/
      index.html
      toc-osh.html
      toc-ysh.html
      toc-data.html

      chap-cmd-lang.html
      ...

You can link to topics with internal anchors:


Generated on Sun, 04 Feb 2024 00:32:22 -0500