Draft of Oil Quick Reference.

Remove osh-quick-ref.txt file.

build/doc.sh

@@ -54,10 +54,12 @@ _quick-ref() {
  build/quick_ref.py "$@"
}

osh-quick-ref() {
  local html_out=_build/doc/osh-quick-ref.html
  local text_out_dir=_build/osh-quick-ref
  local py_out=_devbuild/osh_help.py
x-quick-ref() {
  local prog=$1

  local html_out=_build/doc/$prog-quick-ref.html
  local text_out_dir=_build/$prog-quick-ref
  local py_out=_devbuild/${prog}_help.py

  mkdir -p _build/doc $text_out_dir _devbuild
  touch _devbuild/__init__.py  # so osh_help is importable
@@ -97,10 +99,10 @@ osh-quick-ref() {
    </p>
EOF

    _quick-ref toc doc/osh-quick-ref-toc.txt
    _quick-ref toc doc/${prog}-quick-ref-toc.txt

    # Also generate _build/osh-quick-ref/ dir
    _quick-ref pages doc/osh-quick-ref-pages.txt $text_out_dir $py_out
    _quick-ref pages doc/${prog}-quick-ref-pages.txt $text_out_dir $py_out

    _build-timestamp
    cat <<EOF
@@ -110,6 +112,14 @@ EOF
  } > $html_out
}

osh-quick-ref() {
  x-quick-ref osh "$@"
}

oil-quick-ref() {
  x-quick-ref oil "$@"
}

markdown2html() {
  local src=$1
  local out=$2

doc/oil-quick-ref-pages.txt

@@ -0,0 +1,250 @@
## OSH Quick Reference with Examples

## This file gets converted to HTML and do a directory of .txt files for use in
## OSH.

## Format of this file
## 
## Lines that begin with two or more # signs are special.
##
## 2: comment that is omitted
## 3, 4, 5: three levels of sections.
##
## These are turned into <h2> <h3> <h4> tags in HTML, with <a> anchors.
## In help text.


## Meta-variables for
##   foo        :  string
##   out.txt    :  output file
##   input.txt  : input file
##   /some/dir/ : file system path
##   $myvar     : var
##   echo, ls   : a command
## 
##   echo foo >out.txt
##   read myvar <input.txt

## Sections on help
## - usage line (auto-generated?)
##   read [options] [VARNAME ...]  # default variable is REPLY
## - list of flags
## - EXAMPLES 
## - ADVICE / STYLE
##   - Don't use this.  Use something else.
##   - also: conversion to Oil!
##     - [[ is preferred, but 'test [' is also valid

##### <INTRO> Introduction

#### <Overview> Overview

### <overview>

OSH is a shell.


#### <Usage> Usage

### <osh-usage> Usage of the OSH Binary
Usage: osh [OPTION]... SCRIPT [ARG]...
       osh [OPTION]... -c COMMAND [ARG]...

osh accepts POSIX sh flags, with the following differences:

  -n             only validate the syntax.  Also prints the AST.
  --show-ast     print the AST in addition to executing.
  --ast-format   what format the AST should be in

## Same as osh --help, man osh

### <oil-usage> Usage of the Oil Binary
Usage: oil MAIN_NAME [ARG]...
       MAIN_NAME [ARG]...

oil behaves like busybox.  If it's invoked through a symlink, e.g. 'osh', then
it behaves like that binary.  Otherwise the binary name can be passed as the
first argument, e.g.:

    oil osh -c 'echo hi'

## Same as oil --help, man oil

##### <COMMAND-LANGUAGE> Command Language

The command language is specified by the POSIX shell grammar.

#### <Commands> Commands

### <simple-command> Simple Commands
Simple commands are separated by words:
    ls /

Redirects can also appear anywhere
    echo hi 1>&2

### <semicolon> Semi-colon  ;
;  -- separate statements

#### <Conditional> Conditional Constructs

### <case> case
### <if> if

### <true false colon :>

### <bang !>

### <and && or ||>

### <dbracket [[>
For conditionals.

#### <Conditional> Iteration Constructs

### <while until>

### <for for-expr>

#### <Grouping> Grouping Constructs

### <function>

### <block>

### <subshell>

#### <Concurrency>

### <pipe>

### <ampersand &>

#### <Redirects>

### <redir-file>

### <redir-desc>

### <here-doc>

#### <Other> Other Commands

### <dparen ((>

### <time>

### <coproc>


##### <ASSIGNING-VARIABLES> Assigning Variables

#### <Keywords> Assignment Keywords

#### <Operators> Assignment Operators

#### <Compound-Data> Compound Data Structures


##### <WORD-LANGUAGE> Word Language

#### <Quotes>

#### <Substitutions>

#### <Special-Vars> Special Variables

#### <Var-Ops> Operations on Variables


##### <OTHER-SHELL-SUBLANGUAGES> Other Shell Sublanguages

#### <Arithmetic> 

#### <Boolean> 

#### <Patterns> 

#### <Brace-Expand> Brace Expansion

##### <BUILTIN-COMMANDS> Builtin Commands

OSH aims to have almost all of the builtins that bash does.  Here they are,
divided into sections.

#### <I/O> I/O Builtins

These builtins take input and output.  They are often used with redirects[1].

[1] help redirects

### <read> read
Usage: read -p 

Or maybe get rid of #END -- it can just go until the next # command.  It's a
little bit like the spec tests honestly.  Can copy sh_specpy

#### <Run-Code> Run Code
source .   eval

#### <Set-Options> Set Shell Options
set   X shopt

#### <Working-Dir> Builtins - Working Dir
cd   pwd   pushd   popd   dirs

#### <Completion> Completion
complete   X compgen   X compopt

#### <Shell-Process> Shell Process Control
exec   exit   X logout 
umask   X ulimit   X trap   X times

#### <Child-Process> Child Process Control
jobs   wait   ampersand &
X fg   X bg   X disown 

#### <Introspection> Builtins That Introspect

### <help> help
Usage:
  help <topic>   -- show help on a given topic
  help toc       -- list help topics
  help osh-usage -- same as osh --help
  help oil-usage -- same as oil --help

View on the web: http://www.oilshell.org/$VERSION/doc/osh-quick-ref.html

### <hash> hash

### <caller> caller

### <type> type

#### <External> Builtins That Are Like External Commands

External: bash has builtins that replace these external commands, but OSH
doesn't)

### <getopt> getopt

use /usr/bin/getopt

### <kill> kill

bash accepts job control syntax

### <enable> enable

Bash has this, but OSH won't implement it.

##### <SHELL-OPTIONS> Shell Options


#### <Parsing> Parsing Options

#### <Execution> Execution Options

#### <OSH-Options> Options Only in OSH