Draft standalone manual (single page).

tmpfs · Aug 7, 2016 · 1c9ed85 · 1c9ed85
1 parent c92d62d
commit 1c9ed85
Show file tree

Hide file tree

Showing 12 changed files with 933 additions and 156 deletions.
diff --git a/README.md b/README.md
@@ -52,6 +52,10 @@ In each case the [trucks.js](https://github.com/tmpfs/trucks/blob/master/example
   - [Core](#core)
   - [Resolvers](#resolvers)
   - [Transforms](#transforms)
+    - [Compilers](#compilers)
+    - [Preprocessors](#preprocessors)
+    - [Styles](#styles)
+    - [Miscellaneous](#miscellaneous)
   - [Generators](#generators)
 - [License](#license)
 

diff --git a/documents/developer.md b/documents/developer.md
@@ -1,92 +1,9 @@
-# Developer
-
-Sources are ES6 code transpiled for `node@4.x` compatibility.
-
-Install [mkdoc][] `npm i -g mkdoc` and then install dependencies for all packages with `npm i && mk install`.
-
-You should now be able to use the scripts and tasks, list tasks with `mk --tasks`.
-
-It is a good idea to run the `build` task before tests; it is recommended that before pushing code the command `mk build test` is run.
-
-At the top-level you run the following commands for all packages:
-
-* `mk install` Install dependencies.
-* `mk test` Run tests.
-* `mk cover` Run code coverage.
-* `mk build` Compile sources.
-* `mk lint` Lint sources.
-* `mk docs` Build top-level documentation
-
-Build a coverage report for all packages with:
-
-```
-mk cover && npm run report
-```
-
-Note that tests are not included in the npm packages you should clone the repository to run the test suites.
+## Developer
 
 ***
 <!-- @toc -->
 ***
 
-## Scripts
-
-In the scope of a package the following scripts are available.
-
-### Build
-
-Convert the ES6 sources for a package:
-
-```
-npm run build
-```
-
-### Test
-
-To run the test suite:
-
-```
-npm test
-```
-
-### Cover
-
-To generate code coverage:
-
-```
-npm run cover
-```
-
-### Lint
-
-Run the source tree through [jshint][] and [jscs][]:
-
-```
-npm run lint
-```
-
-### Clean
-
-Remove generated files:
-
-```
-npm run clean
-```
-
-### Docs
-
-To build all documentation files:
-
-```
-mk docs
-```
-
-### Readme
-
-To build the readme file:
-
-```
-mk readme
-```
+<? @include include/developer.md ?>
 
 <? @include links.md ?>
diff --git a/documents/include/developer.md b/documents/include/developer.md
@@ -0,0 +1,85 @@
+Sources are ES6 code transpiled for `node@4.x` compatibility.
+
+Install [mkdoc][] `npm i -g mkdoc` and then install dependencies for all packages with `npm i && mk install`.
+
+You should now be able to use the scripts and tasks, list tasks with `mk --tasks`.
+
+It is a good idea to run the `build` task before tests; it is recommended that before pushing code the command `mk build test` is run.
+
+At the top-level you run the following commands for all packages:
+
+* `mk install` Install dependencies.
+* `mk test` Run tests.
+* `mk cover` Run code coverage.
+* `mk build` Compile sources.
+* `mk lint` Lint sources.
+* `mk docs` Build top-level documentation
+
+Build a coverage report for all packages with:
+
+```
+mk cover && npm run report
+```
+
+Note that tests are not included in the npm packages you should clone the repository to run the test suites.
+
+### Scripts
+
+In the scope of a package the following scripts are available.
+
+#### Build
+
+Convert the ES6 sources for a package:
+
+```
+npm run build
+```
+
+#### Test
+
+To run the test suite:
+
+```
+npm test
+```
+
+#### Cover
+
+To generate code coverage:
+
+```
+npm run cover
+```
+
+#### Lint
+
+Run the source tree through [jshint][] and [jscs][]:
+
+```
+npm run lint
+```
+
+#### Clean
+
+Remove generated files:
+
+```
+npm run clean
+```
+
+#### Docs
+
+To build all documentation files:
+
+```
+mk docs
+```
+
+#### Readme
+
+To build the readme file:
+
+```
+mk readme
+```
+
diff --git a/documents/include/introduction.md b/documents/include/introduction.md
@@ -0,0 +1,31 @@
+[Web components][webcomponents] are a collection of emerging standards that allow developers to create re-usable custom user interface elements.
+
+The web components specifications are:
+
+* [Shadow DOM][shadow-dom]
+* [Custom Elements][custom-elements]
+* [HTML Imports][html-imports]
+* [HTML Templates][html-templates]
+
+At the time of writing very few browsers support all of these emerging standards so polyfills are required.
+
+There are several problems with the state of the current frameworks.
+
+### Polymer
+
+The [polymer project][polymer] has a large suite of components but these components are all defined using inline scripts and inline styles which is very convenient from an authoring point of view (component encapsulation) but has issues when you need a strict [content security policy][csp] that disables inline styles and scripts.
+
+### Skate
+
+The [skatejs][] project has a very efficient design using a virtual dom that incrementally renders component view changes. It is the smallest of the frameworks and because it does not depend upon [HTML Templates][html-templates] or [HTML Imports][html-imports] a component can be created using javascript and css but this makes it difficult to easily encapsulate a component definition into a single file.
+
+### React
+
+The [react framework][react] is [not tracking the webcomponents standards][react-webcomponents] and therefore for those that prefer to use web standards it's not really an option. But you can compile [skatejs][] component definitions to react components using the [react integration][react-integration] module.
+
+### Trucks
+
+The [trucks][] library aims to bring component encapsulation to [skatejs][] and allow [polymer][] component definitions to be compiled to bypass the [content security policy][csp] problem.
+
+Another benefit of this library is that it converts [HTML Imports][html-imports] to *compile time only* which is important as [Mozilla will not ship HTML Imports][mozilla-webcomponents], one less polyfill!
+
diff --git a/documents/introduction.md b/documents/introduction.md
@@ -1,38 +1,9 @@
 ## Introduction
 
-[Web components][webcomponents] are a collection of emerging standards that allow developers to create re-usable custom user interface elements.
-
-The web components specifications are:
-
-* [Shadow DOM][shadow-dom]
-* [Custom Elements][custom-elements]
-* [HTML Imports][html-imports]
-* [HTML Templates][html-templates]
-
-At the time of writing very few browsers support all of these emerging standards so polyfills are required.
-
-There are several problems with the state of the current frameworks.
-
 ***
 <!-- @toc -->
 ***
 
-### Polymer
-
-The [polymer project][polymer] has a large suite of components but these components are all defined using inline scripts and inline styles which is very convenient from an authoring point of view (component encapsulation) but has issues when you need a strict [content security policy][csp] that disables inline styles and scripts.
-
-### Skate
-
-The [skatejs][] project has a very efficient design using a virtual dom that incrementally renders component view changes. It is the smallest of the frameworks and because it does not depend upon [HTML Templates][html-templates] or [HTML Imports][html-imports] a component can be created using javascript and css but this makes it difficult to easily encapsulate a component definition into a single file.
-
-### React
-
-The [react framework][react] is [not tracking the webcomponents standards][react-webcomponents] and therefore for those that prefer to use web standards it's not really an option. But you can compile [skatejs][] component definitions to react components using the [react integration][react-integration] module.
-
-### Trucks
-
-The [trucks][] library aims to bring component encapsulation to [skatejs][] and allow [polymer][] component definitions to be compiled to bypass the [content security policy][csp] problem.
-
-Another benefit of this library is that it converts [HTML Imports][html-imports] to *compile time only* which is important as [Mozilla will not ship HTML Imports][mozilla-webcomponents], one less polyfill!
+<? @include include/introduction.md ?>
 
 <? @include links.md ?>
diff --git a/documents/standalone.md b/documents/standalone.md
@@ -0,0 +1,31 @@
+# Manual
+
+***
+<!-- @toc -->
+***
+
+## Introduction
+
+<? @include include/introduction.md ?>
+
+## Components
+
+<? @include include/components.md ?>
+
+## Plugins
+
+<? @include include/plugins.md ?>
+
+## Protocols
+
+<? @include include/protocols.md ?>
+
+## Transforms
+
+<? @include include/transforms.md ?>
+
+## Developer
+
+<? @include include/developer.md ?>
+
+<? @include links.md ?>
diff --git a/manual/components.md b/manual/components.md
@@ -4,6 +4,7 @@
 
 - [Components](#components)
   - [Templates](#templates)
+    - [Template Styles](#template-styles)
   - [Style Scopes](#style-scopes)
   - [Dependencies](#dependencies)
   - [Private Dependencies](#private-dependencies)