Why Sponsor Oils? | source | all docs for version 0.18.0 | all versions | oilshell.org

Oils Reference

A guide to everything in Oils (in progress).

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

Online HTML

Oils consists of two major "modes" for shell:

• OSH Table of Contents - Compatible
• YSH Table of Contents - New and Powerful

They link to 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

The idea is that you can use OSH by itself, YSH by itself, or upgrade OSH to YSH.

• Data Notation Table of Contents - Oils also has data languages.

13. J8 Notation
14. Packle (TODO)

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.
   • It has text with a globally unique name like doc-comment.
   • May apply to OSH, YSH or both.

More terminology:

• Table of Contents - a doc that links to topics, within chapters.
• Card - Topics maybe be exported as help builtin "cards", either as inline text, or a URL to online HTML. A card may also have a URL to POSIX or bash docs.

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:

• chap-option.html#parse_at
• chap-builtin-cmd.html#compgen