Convert specification to AsciiDoc format (from LaTeX) (#30)

- Mostly a straight conversion (typos, phrasings, bugs, and all)
   - Some minor re-arrangement in order to regularize the presentation
     of examples, and specify the grammars in actual EBNF
   - There are almost certainly transcription errors...
- Builds both PDF and HTML output
   - PDF theming has had a bit of work on it
   - HTML theme/style is the AsciiDoc default; could use work

Author: jpschorr

.gitignore

@@ -1,11 +1,12 @@
 /.vscode/
 
-*.tex-e
-*.log
-*.pdf
-*.aux
-*.out
-*.gz
-*.fls
-*.toc
-*.fdb_latexmk
+# build
+build
+
+# environment assets
+fonts
+
+# ruby stuff
+.ruby-version
+.ruby-gemset
+Gemfile.lock

Gemfile

@@ -0,0 +1,20 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+
+gem 'asciidoctor'
+gem 'asciidoctor-pdf'
+gem 'asciidoctor-mathematical'
+gem 'prawn'
+gem 'prawn-table', github: 'prawnpdf/prawn-table'
+gem 'prawn-svg'
+
+gem 'pygments.rb'
+
+gem 'rghost'
+
+gem 'guard'
+gem 'guard-shell'
+
+gem 'pry'
+gem 'pry-byebug'

Guardfile

@@ -0,0 +1,21 @@
+# See https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
+
+Bundler.require :default
+
+guard 'shell' do
+  watch(/^.*\.adoc$/) {|m|
+    `bundle exec rake spec:build`
+  }
+  watch(/^images\/.*$/) {|m|
+    `bundle exec rake spec:build`
+  }
+  watch(/^hello-aws\/.*\.adoc$/) {|m|
+    `bundle exec rake spec:build`
+  }
+  watch(/^.*\.yml$/) {|m|
+    `bundle exec rake spec:build`
+  }
+  watch(/^themes\/.*\.yml$/) {|m|
+    `bundle exec rake spec:build`
+  }
+end

Makefile

@@ -0,0 +1,111 @@
+= PartiQL Language Specification
+
+This is the link:https://asciidoc.org/[AsciiDoc] source for the link:https://partiql.org/[PartiQL] specification.
+
+== Editing
+
+AsciiDoc is supported by link:https://docs.asciidoctor.org/asciidoctor/latest/tooling[major repository hosting providers and many IDEs].
+
+== How to Build the Spec
+
+=== Pre-requisites
+
+1. Install link:https://github.com/rbenv/rbenv#installation[rbenv]
++
+[source, shell]
+.terminal
+```
+brew install rbenv
+rbenv init
+```
+
+2. Install the latest version of ruby
++
+[source, shell]
+.terminal
+```
+rbenv install $(rbenv install -l | grep -v - | tail -1)
+```
+
+3. Install rbenv shell integration (replace .zshrc with .bash_profile if you use bash)
++
+[source,shell]
+.terminal
+```
+echo "\n# rbenv integration" >> ~/.zshrc
+echo "eval \"\$(rbenv init -)\"" >> ~/.zshrc
+source ~/.zshrc
+```
+
+4. Install Vollkorn & Iosevka fonts (Open Font License)
++
+[source,shell]
+.terminal
+```
+mkdir fonts
+curl -L -o fonts/vollkorn.zip http://vollkorn-typeface.com/download/vollkorn-4-105.zip
+unzip fonts/vollkorn.zip -d fonts/vollkorn
+curl -L -o fonts/iosevka.zip https://github.com/be5invis/Iosevka/releases/download/v16.0.2/ttf-iosevka-term-slab-16.0.2.zip
+unzip fonts/iosevka.zip -d fonts/iosevka
+
+```
+
+5. Install fonts and such needed by AsciiMath
++
+[source,shell]
+.terminal
+```
+brew tap homebrew/cask-fonts 
+brew install glib gdk-pixbuf cairo pango cmake font-computer-modern
+
+cd ~/Library/Fonts
+curl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \
+     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \
+     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \
+     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \
+     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \
+     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \
+     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \
+     -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf
+
+```
+
+=== Setup
+
+Set the spec to use the latest ruby, and install required gems
+
+[source, shell]
+.terminal
+```
+cd <spec>
+rbenv local $(rbenv install -l | grep -v - | tail -1)
+bundle install
+```
+
+=== Building
+
+Output will be built to
+  - build/PartiQL-Specification.html
+  - build/PartiQL-Specification.pdf
+
+To watch sources for changes and auto-rebuild `HTML` and quick `PDF`
+[sourc,shell]
+.terminal
+```
+bundle exec rake spec:watch
+```
+
+
+To build `HTML` and optimized `PDF`
+[sourc,shell]
+.terminal
+```
+bundle exec rake
+```
+
+
+
+
+= License
+
+This library is licensed under the link:LICENSE[PartiQL Specification License].

README.adoc

@@ -0,0 +1,62 @@
+version_string = `git describe --tag | cut  -d "-" -f 1,2 | tr - .`.chomp
+if version_string.empty?
+  version_string = '0'
+end
+date_string = Time.now.strftime("%Y-%m-%d")
+params = "--attribute revnumber='#{version_string}' --attribute revdate='#{date_string}'"
+
+image_files = Rake::FileList.new("src/images/*.png", "src/images/*.svg") do |fl|
+  fl.exclude("~*")
+  fl.exclude(/^scratch\//)
+end
+
+namespace :spec do
+  directory 'build/images'
+
+  desc 'copy images to build dir'
+  task :images => 'build/images'
+
+  image_files.each do |source|
+    target = source.sub(/^src\/images/, 'build/images')
+    file target => source do
+      cp source, target, :verbose => true
+      `pngquant -f #{target}`
+    end
+    desc "copies all data files"
+    task :images => target
+  end
+
+  task :prereqs => [:images]
+  
+  desc 'build basic spec formats'
+  task :html => :prereqs do
+    begin
+      puts "Converting to HTML..."
+      `bundle exec asciidoctor -b html5 #{params} src/main.adoc -o build/PartiQL-Specification.html`
+    end
+  end
+
+  task :pdf => :prereqs do
+    begin
+      theming = "-a pdf-themesdir=src/themes -a pdf-theme=basic -a pdf-fontsdir=fonts"
+      stem = "-r asciidoctor-mathematical -a mathematical-format=svg"
+      pdf_params = "-a compress"
+      puts "Converting to PDF..."
+      `bundle exec asciidoctor-pdf -v #{params} #{theming} #{stem} #{pdf_params} src/main.adoc -o build/PartiQL-Specification.pdf --trace`
+    end
+  end
+
+  task :build => [:html, :pdf]
+
+  task :watch do
+    begin
+      `bundle exec guard`
+    end
+  end
+
+  require 'rake/clean'
+  CLEAN.include('build/*')
+  CLOBBER.include('build/*')
+end
+
+task :default => "spec:build"