Improve docs (#1196)

Docs.md

-# Deno Docs
+# Deno Documentation
+
+## Disclaimer
+
+A word of caution: Deno is very much under development. We encourage brave early
+adopters, but expect bugs large and small. The API is subject to change without
+notice.
+
+[Bug reports](https://github.com/denoland/deno/issues) do help!
 
 ## Install
 
-Deno works on OSX, Linux, and Windows. We provide binary download scripts:
+Deno works on OSX, Linux, and Windows. Deno is a single binary executable. It
+has no external dependencies.
 
-With Python:
+[deno_install](https://github.com/denoland/deno_install) provides convenience
+scripts to download and install the binary.
+
+Using Python:
 
 ```
 curl -sSf https://raw.githubusercontent.com/denoland/deno_install/master/install.py | python
 ```
 
-See also [deno_install](https://github.com/denoland/deno_install).
-
-With PowerShell:
+Or using PowerShell:
 
 ```powershell
 iex (iwr https://raw.githubusercontent.com/denoland/deno_install/master/install.ps1)
@@ -22,10 +32,15 @@ _Note: Depending on your security settings, you may have to run
 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` first to allow downloaded
 scripts to be executed._
 
+Deno can also be installed manually, by downloading a tarball or zip file at
+[github.com/denoland/deno/releases](https://github.com/denoland/deno/releases).
+These packages contain just a single executable file. You will have to set the
+executable bit on Mac and Linux.
+
 Try it:
 
 ```
-> deno http://deno.land/thumb.ts
+> deno https://deno.land/thumb.ts
 ```
 
 ## API Reference
@@ -34,58 +49,186 @@ To get an exact reference of deno's runtime API, run the following in the
 command line:
 
 ```
-deno --types
+> deno --types
 ```
 
-In case you don't have it installed yet, but are curious, here is an out-of-date
-copy of the output: https://gist.github.com/78855aeeaddeef7c1fce0aeb8ffef8b2
+Or see the [doc website](https://deno.land/typedoc/index.html).
 
-(We do not yet have an HTML version of this. See
-https://github.com/denoland/deno/issues/573)
+If you are embedding deno in a Rust program, see
+[the rust docs](https://deno.land/rustdoc/deno/index.html).
 
-## Examples
+## Tutorial
 
-### Example: An implementation of the unix "cat" program
+### An implementation of the unix "cat" program
 
-The copy here is actually zero-copy. That is, it reads data from the socket and
-writes it back to it without ever calling a memcpy() or similar.
+In this program each command-line argument is assumed to be a filename, the file
+is opened, and printed to stdout.
 
 ```ts
 import * as deno from "deno";
 
-for (let i = 1; i < deno.args.length; i++) {
-  let filename = deno.args[i];
-  let file = await deno.open(filename);
-  await deno.copy(deno.stdout, file);
-}
+(async () => {
+  for (let i = 1; i < deno.args.length; i++) {
+    let filename = deno.args[i];
+    let file = await deno.open(filename);
+    await deno.copy(deno.stdout, file);
+    file.close();
+  }
+})();
 ```
 
-### Example: A TCP Server echo server
+The `copy()` function here actually makes no more than the necessary kernel ->
+userspace -> kernel copies. That is, the same memory from which data is read
+from the file, is written to stdout. This illustrates a general design goal for
+I/O streams in Deno.
 
-The copy here is actually zero-copy. That is, it reads data from the socket and
-writes it back to it without ever calling a memcpy() or similar.
+Try the program:
+
+```
+> deno https://deno.land/x/examples/cat.ts /etc/passwd
+```
+
+### TCP echo server
+
+This is an example of a simple server which accepts connections on port 8080,
+and returns to the client anything it sends.
 
 ```ts
 import { listen, copy } from "deno";
-const listener = listen("tcp", ":8080");
-while (true) {
-  const conn = await listener.accept();
-  copy(conn, conn);
-}
-// TODO top level await doesn't work yet.
+
+(async () => {
+  const addr = "0.0.0.0:8080";
+  const listener = listen("tcp", addr);
+  console.log("listening on", addr);
+  while (true) {
+    const conn = await listener.accept();
+    copy(conn, conn);
+  }
+})();
+```
+
+When this program is started, the user is prompted for permission to listen on
+the network:
+
+```
+> deno https://deno.land/x/examples/echo_server.ts
+deno requests network access to "listen". Grant? [yN] y
+listening on 0.0.0.0:8080
+```
+
+For security reasons, deno does not allow programs to access the network without
+explicit permission. To avoid the console prompt, use a command-line flag:
+
+```
+> deno https://deno.land/x/examples/echo_server.ts --allow-net
+```
+
+To test it, try sending a HTTP request to it by using curl. The request gets
+written directly back to the client.
+
 ```
+> curl http://localhost:8080/
+GET / HTTP/1.1
+Host: localhost:8080
+User-Agent: curl/7.54.0
+Accept: */*
+```
+
+It's worth noting that like the `cat.ts` example, the `copy()` function here
+also does not make unnecessary memory copies. It receives a packet from the
+kernel and sends back, without further complexity.
+
+### Linking to third party code
 
-### Example: Url imports
+In the above examples, we saw that Deno could execute scripts from URLs. Like
+browser JavaScript, Deno can import libraries directly from URLs. This example
+uses a URL to import a test runner library:
 
 ```ts
-import { printHello } from "https://raw.githubusercontent.com/denoland/deno/master/tests/subdir/print_hello.ts";
-printHello();
+import { test, assertEqual } from "https://deno.land/x/testing/testing.ts";
+
+test(function t1() {
+  assertEqual("hello", "hello");
+});
+
+test(function t2() {
+  assertEqual("world", "world");
+});
+```
+
+Try running this:
+
+```
+> deno https://deno.land/x/examples/example_test.ts
+Compiling /Users/rld/src/deno_examples/example_test.ts
+Downloading https://deno.land/x/testing/testing.ts
+Downloading https://deno.land/x/testing/util.ts
+Compiling https://deno.land/x/testing/testing.ts
+Compiling https://deno.land/x/testing/util.ts
+running 2 tests
+test t1
+... ok
+test t2
+... ok
+
+test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 ```
 
-The next time you import the same file from same uri it will use the cached
-resource instead of downloading it again.
+Note that we did not have to provide the `--allow-net` flag for this program,
+and yet it accessed the network. The runtime has special access to download
+imports and cache them to disk.
+
+Deno caches remote imports in a special directory specified by the `$DENO_DIR`
+environmental variable. It default to `$HOME/.deno` if `$DENO_DIR` is not
+specified. The next time you run the program, no downloads will be made. If the
+program hasn't changed, it won't be recompiled either.
+
+**But what if `https://deno.land/` goes down?** Relying on external servers is
+convenient for development but brittle in production. Production software should
+always bundle its dependencies. In Deno this is done by checking the `$DENO_DIR`
+into your source control system, and specifying that path as the `$DENO_DIR`
+environmental variable at runtime.
+
+**How do you import to a specific version?** Simply specify the version in the
+URL. For example, this URL fully specifies the code being run:
+`https://unpkg.com/liltest@0.0.5/dist/liltest.js`. Combined with the
+aforementioned technique of setting `$DENO_DIR` in production to stored code,
+one can fully specify the exact code being run, and execute the code without
+network access.
+
+**It seems unwieldy to import URLs everywhere. What if one of the URLs links to
+a subtly different version of a library? Isn't it error prone to maintain URLs
+everywhere in a large project?** The solution is to import and re-export your
+external libraries in a central `package.ts` file (which serves the same purpose
+as Node's `package.json` file). For example, let's say you were using the above
+testing library across a large project. Rather than importing
+`"https://deno.land/x/testing/testing.ts"` everywhere, you could create a
+`package.ts` file the exports the third-party code:
+
+```ts
+export { test, assertEqual } from "https://deno.land/x/testing/testing.ts";
+```
 
-## How to Profile Deno
+And throughout project one can import from the `package.ts` and avoid having
+many references to the same URL:
+
+```ts
+import { test, assertEqual } from "./package.ts";
+```
+
+This design circumvents a plethora of complexity spawned by package management
+software, centralized code repositories, and superfluous file formates.
+
+## Useful command line flags
+
+V8 has many many command-line flags, that you can see with `--v8-options`. Here
+are a few particularly useful ones:
+
+```
+--async-stack-traces
+```
+
+## How to Profile deno
 
 ```sh
 # Make sure we're only building release.
@@ -108,11 +251,11 @@ isolate-0x7fad98242400-v8.log
 
 ### Prerequisites:
 
-To ensure reproducible builds, Deno has most of its dependencies in a git
+To ensure reproducible builds, deno has most of its dependencies in a git
 submodule. However, you need to install separately:
 
 1. [Rust](https://www.rust-lang.org/en-US/install.html)
-2. [Node](http://nodejs.org/)
+2. [Node](https://nodejs.org/)
 3. Python 2.
    [Not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578).
 4. [ccache](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/ccache)
@@ -175,7 +318,7 @@ Environment variables: `DENO_BUILD_MODE`, `DENO_BUILD_PATH`, `DENO_BUILD_ARGS`,
 
 ### Internal: libdeno API.
 
-Deno's privileged side will primarily be programmed in Rust. However there will
+deno's privileged side will primarily be programmed in Rust. However there will
 be a small C API that wraps V8 to 1) define the low-level message passing
 semantics, 2) provide a low-level test target, 3) provide an ANSI C API binding
 interface for Rust. V8 plus this C API is called "libdeno" and the important
@@ -239,9 +382,9 @@ V8's GC will lead to difficult contention problems down the road.
 The V8Worker2 binding/concept is being ported to a new C++ library called
 libdeno. libdeno will include the entire JS runtime as a V8 snapshot. It still
 follows the message passing paradigm. Rust will be bound to this library to
-implement the privileged part of Deno. See deno2/README.md for more details.
+implement the privileged part of deno. See deno2/README.md for more details.
 
-V8 Snapshots allow Deno to avoid recompiling the TypeScript compiler at startup.
+V8 Snapshots allow deno to avoid recompiling the TypeScript compiler at startup.
 This is already working.
 
 When the rewrite is at feature parity with the Go prototype, we will release
@@ -253,20 +396,18 @@ https://github.com/denoland/deno/tree/golang
 
 https://www.youtube.com/watch?v=M3BM9TB-8yA
 
-http://tinyclouds.org/jsconf2018.pdf
+https://tinyclouds.org/jsconf2018.pdf
 
 ### 2007-2017 / Prehistory
 
 https://github.com/ry/v8worker
 
-http://libuv.org/
+https://libuv.org/
 
-http://tinyclouds.org/iocp-links.html
+https://tinyclouds.org/iocp-links.html
 
 https://nodejs.org/
 
 https://github.com/nodejs/http-parser
 
-http://tinyclouds.org/libebb/
-
-https://en.wikipedia.org/wiki/Merb
+https://tinyclouds.org/libebb/

website/index.html

@@ -2,20 +2,23 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>deno</title>
+  <title>Deno</title>
   <link rel="stylesheet" href="https://unpkg.com/c3@0.6.7/c3.min.css">
   <link rel="stylesheet" href="style.css">
   <meta content='width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0' name='viewport' />
 </head>
 <body>
   <main>
-    <h1>deno</h1>
+    <h1>Deno</h1>
+
+    <p>Deno is program for executing JavaScript and TypeScript outside of the
+    web browser.
 
     <p> <a href="https://github.com/denoland/deno">github.com/denoland/deno</a>
 
-    <p> <a href="https://github.com/denoland/deno/blob/master/Docs.md">Intro</a>
-    <p> <a href="typedoc/index.html">TypeScript API</a>
-    <p> <a href="rustdoc/deno/index.html">Rust API</a>
+    <p> <a href="https://github.com/denoland/deno/blob/master/Docs.md">Documentation</a>
+
+    <p> <a href="typedoc/index.html">API Reference</a>
 
     <h2>Execution time</h2>
     This shows how much time total it takes to run a few simple deno programs: