Skip to content

Latest commit

 

History

History
135 lines (95 loc) · 3.25 KB

index.md

File metadata and controls

135 lines (95 loc) · 3.25 KB
Raw
default_highlighter preserve_anchor_case
oils-sh
true

Oils Reference

<style> .highlight { background-color: #eee; padding-top: 0.2em; padding-bottom: 0.2em; padding-left: 1em; padding-right: 1em; } </style>

A guide to everything in Oils (in progress).

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

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.
    • 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: