more

3 files changed, 123 insertions, 62 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..2d19fc7
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+*.html
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..37326fa
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,12 @@
+PANDOC_FLAGS = --toc --number-sections
+all: vue-notes.html
+
+%.html: %.md
+	pandoc --standalone -f markdown -t html $(PANDOC_FLAGS) < $< > $@
+
+clean:
+	rm -f -- *.html
+
+.PHONY: all clean
+.SECONDARY:
+.DELETE_ON_ERROR:
diff --git a/vue-notes.md b/vue-notes.md
index 4c8fe41..9eadaf8 100644
--- a/vue-notes.md
+++ b/vue-notes.md
@@ -1,22 +1,25 @@
 ---
 LocalWords: Vue DOM JS
+title: "LukeShu's Guide to Vue"
+author:
+ - Luke T. Shumaker
+abstract: |
+  There are 4 primary pieces to the official Vue documentation:
+
+   1. Guide
+   2. API
+   3. Style Guide
+   4. Examples
+
+  The "Guide" is where concepts get introduced and explained; but fairly
+  little of the underlying machinery or details are explained; or it is
+  hard to find.  The "API" is where the machinery and details are
+  explained, but the concepts of how that fits together is missing; it
+  links to the Guide.
+
+  I think it's silly that those are 2 separate documents.
 ---
 
-There are 4 primary pieces to the official Vue.js documentation:
-
- 1. Guide
- 2. API
- 3. Style Guide
- 4. Examples
-
-The "Guide" is where concepts get introduced and explained; but fairly
-little of the underlying machinery or details are explained; or it is
-hard to find.  The "API" is where the machinery and details are
-explained, but the concepts of how that fits together is missing; it
-links to the Guide.
-
-I think it's silly that those are 2 separate documents.
-
 # Introduction
 
 	import Vue from 'vue';
@@ -49,11 +52,10 @@ In addition to those objects:
    us to write markup such that Vue knows how to make it *reactive*.
    It's just plain HTML, but with (1) user-defined custom elements
    (via *components*), and (2) Vue-defined and user-defined custom
-   attributes (via *directives*; the built-in Vue directives all start
-   with `v-`).  If you don't like writing raw HTML, that's fine, you
-   could write it via PUG or any other compile-to-HTML language, since
-   Vue templates are *just HTML*.  From the JavaScript, they are just
-   plain strings.
+   attributes (via *directives*).  If you don't like writing raw HTML,
+   that's fine, you could write it via PUG or any other
+   compile-to-HTML language, since Vue templates are *just HTML*.
+   From the JavaScript, they are just plain strings.
 
  - *Render functions*: Ultimately, *templates* compile to render
    functions.  If your application design and toolchain
@@ -76,20 +78,7 @@ gives us the tools to effectively write dope-ass parts of a
 user-interface, without requiring is to use Vue to do the entire
 interface (though you could).
 
-# IDK what section this belongs in.
-
-Components don't work by literally registering custom elements with
-the browser (though a W3C spec exists for allowing that, it isn't
-(yet?) widely implemented).  Instead, it's the *template language*
-that knows about them, the custom element names are registered with
-the template compiler, and the compiler then knows that when it
-encounters a node with that element name, it needs to emit a render
-function that instantiates that component.  Ditto for directives.
-
-THE ABOVE IS FALSE.  The render function calls
-`something.createElement("element-name")`, the components are
-registered with the `createElement`; the compiler doesn't need to know
-this.
+# Major topics
 
 ## Reactivity
 
@@ -107,26 +96,6 @@ with a couple of silly magic functions to work around this limitation:
    ensures that the deletion triggers view updates, working around the
    limitation that Vue can't detect attribute deletions.
 
-## Configuration
-
- - Global: `Vue.config`
-   * Development Settings
-     * `Vue.config.silent` Bool
-     * `Vue.config.devtools` Bool
-	 * `Vue.config.warnHandler` Function
-     * `Vue.config.performance` Bool
-     * `Vue.config.productionTip` Bool
-   * For-reals Settings
-     * `Vue.config.optionMergeStrategies` Map<String,Function>
-     * `Vue.config.errorHandler` Function
-     * `Vue.config.ignoredElements` Array<String|RegExp>
-	 * `Vue.config.keyCodes` Map<String,Number|Array<Number>>
-
-
- > Unfortunately, that's custom `<element></element>`s; with Vue
- > components, we can't use the `<element />` shorthand, or
- > implied-closing (like with `<li>`).
-
 ## Root Vue Instance
 
 	var vm = new Vue({ ... });
@@ -163,8 +132,15 @@ We define a component like
 
 	var MyComponent = Vue.extend({ ... });
 
+The things that go in the `...` are a superset of the things that we
+can pass to `new Vue({ ... })`.
+
 But that doesn't give it a name!  We'll need to register our component
-with an HTML tag name.  We can do that globally with:
+with an HTML tag name.
+
+### Global registration
+
+We register a component globally with:
 
 	Vue.component('tag-name', MyComponent);
 	
@@ -186,30 +162,101 @@ we can use for convenience:
  > fact that component creation and registration are two distinct
  > operations.  Lame shorthand!
  
- If we want to be able to retrieve a component that we know is
- registered, but the current code doesn't have an object for, we can
- get it like:
+If we want to be able to retrieve a component that we know is
+registered, but the current code doesn't have an object for, we can
+get it like:
  
 	// returns the component previously registered to 'tag-name'
 	var MyComponent = Vue.component('tag-name'); 
 
+### Scoped registration
+
+Of course, you may have had drilled in to your head "globals are
+bad".  We can also register components locally to a Vue instance.
+
+TODO.
+
 ## Directives
 
+Unlike components, which are a specific object type that had to be
+created with `Vue.extend(...)`, directives are implemented as plain
+map objects.
+
+Which is a little confusing, since it means that directive
+registration looks like directive creation, and puts wrong notions in
+your head.
+
+### Global registration
+
+Anyway, a directive can be registered globally:
+
+	Vue.directive('directive-name', { ... });
+
+The resulting attribute name always has a `v-` prefix; the above
+results in needing to set `v-directive-name="foo"`.
+
+### Scoped registration
+
+TODO
+
 ## Mixins
 
-# other
+## Templates
+
+ > Unfortunately, that's custom `<element></element>`s; with Vue
+ > components, we can't use the `<element />` shorthand, or
+ > implied-closing (like with `<li>`).
+
+# Built-in ("core") directives
+
+TODO
+
+# Configuration
+
+ - Global: `Vue.config`
+   * Development Settings
+     * `Vue.config.silent` Bool
+     * `Vue.config.devtools` Bool
+	 * `Vue.config.warnHandler` Function
+     * `Vue.config.performance` Bool
+     * `Vue.config.productionTip` Bool
+   * For-reals Settings
+     * `Vue.config.optionMergeStrategies` Map<String,Function>
+     * `Vue.config.errorHandler` Function
+     * `Vue.config.ignoredElements` Array<String|RegExp>
+	 * `Vue.config.keyCodes` Map<String,Number|Array<Number>>
+
+# Bonus: Single File Components (SFC's)
+
+TODO
+
+# misc
+
+Components don't work by literally registering custom elements with
+the browser (though a W3C spec exists for allowing that, it isn't
+(yet?) widely implemented).  Instead, it's the *template language*
+that knows about them, the custom element names are registered with
+the template compiler, and the compiler then knows that when it
+encounters a node with that element name, it needs to emit a render
+function that instantiates that component.  Ditto for directives.
+
+THE ABOVE IS FALSE.  The render function calls
+`something.createElement("element-name")`, the components are
+registered with the `createElement`; the compiler doesn't need to know
+this.
+
+I'm a big advocate of learning about things by reading the source.  Be
+aware that Vue is written in a JavaScript superset language called
+[Flow][] that adds typechecking, similar to TypeScript.
 
  * Global API
    - `Vue.nextTick`
-   - `Vue.directive`
    - `Vue.filter`
    - `Vue.use`
    - `Vue.mixin`
 
    - `Vue.version` return the Vue version as a String
 
-
-
 Vue instances may have a "render" function, or a "template".  I
 believe that templates compile to a render function (via
 `vue-template-compiler`), either at run-time, or at bundle-time if
@@ -217,3 +264,4 @@ possible.
 
 [MVVM]: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel
 [W3C Custom Elements]: https://www.w3.org/TR/custom-elements/#concepts
+[Flow]: https://flow.org/