langref cleanups

 * move the opaque section to after struct, enum, union, and add
   hyperlinks
 * improve the introduction of the zig build system. don't link to the
   wiki.
 * update to the latest zig init-exe example code
 * rename headers to avoid redundant words such as "zig"
 * simplify example code

1 files changed, 78 insertions, 76 deletions

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 0a44203b55..31d3b9b1ec 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -3249,6 +3249,31 @@ fn makeNumber() Number {
 
       {#header_close#}
 
+      {#header_open|opaque#}
+      <p>
+      {#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment.
+      It can contain declarations the same as {#link|structs|struct#}, {#link|unions|union#},
+      and {#link|enums|enum#}.
+      </p>
+      <p>
+      This is typically used for type safety when interacting with C code that does not expose struct details.
+      Example:
+      </p>
+      {#code_begin|test_err|expected type '*Derp', found '*Wat'#}
+const Derp = opaque {};
+const Wat = opaque {};
+
+extern fn bar(d: *Derp) void;
+fn foo(w: *Wat) callconv(.C) void {
+    bar(w);
+}
+
+test "call foo" {
+    foo(undefined);
+}
+      {#code_end#}
+      {#header_close#}
+
       {#header_open|blocks#}
       <p>
       Blocks are used to limit the scope of variable declarations:
@@ -8547,31 +8572,6 @@ fn foo(comptime T: type, ptr: *T) T {
       {#header_close#}
       {#header_close#}
 
-      {#header_open|opaque#}
-      <p>
-      {#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment.
-      It can contain declarations the same as {#link|structs|struct#}, {#link|unions|union#},
-      and {#link|enums|enum#}.
-      </p>
-      <p>
-      This is typically used for type safety when interacting with C code that does not expose struct details.
-      Example:
-      </p>
-      {#code_begin|test_err|expected type '*Derp', found '*Wat'#}
-const Derp = opaque {};
-const Wat = opaque {};
-
-extern fn bar(d: *Derp) void;
-fn foo(w: *Wat) callconv(.C) void {
-    bar(w);
-}
-
-test "call foo" {
-    foo(undefined);
-}
-      {#code_end#}
-      {#header_close#}
-
       {#header_open|Build Mode#}
       <p>
       Zig has four build modes:
@@ -9626,24 +9626,38 @@ test "assert in release fast mode" {
       isolation.
       </p>
       {#header_close#}
-      {#header_open|Zig Build System#}
 
-      <p>Simple programs can be built with {#syntax#}zig
-      build-exe{#endsyntax#} and {#syntax#}zig build-lib{#endsyntax#},
-      but running those commands manually gets tedious and error
-      prone. Zig's build system lets you keep all the command line
-      switches and build modes in one place. It has no external
-      dependencies, so Zig code can be built on any platform without
-      installing more programs.</p>
-      <p>To use the build system, run 
-      <code class="shell">$ zig build [command]</code>
-      where {#syntax#}[command]{#endsyntax#} is an optional target,
-      configured by your build.zig file. There is more detail
-      on <a href="https://github.com/ziglang/zig/wiki/Zig-Build-System">the
-      wiki</a> but here are some example build.zig files to get you
-      started:</p>
+      {#header_open|Zig Build System#}
+      <p>
+      The Zig Build System provides a cross-platform, dependency-free way to declare
+      the logic required to build a project. With this system, the logic to build
+      a project is written in a build.zig file, using the Zig Build System API to
+      declare and configure build artifacts and other tasks.
+      </p>
+      <p>
+      Some examples of tasks the build system can help with:
+      </p>
+      <ul>
+        <li>Creating build artifacts by executing the Zig compiler. This includes
+          building Zig source code as well as C and C++ source code.</li>
+        <li>Capturing user-configured options and using those options to configure
+          the build.</li>
+        <li>Surfacing build configuration as {#link|comptime#} values by providing a
+          file that can be {#link|imported|@import#} by Zig code.</li>
+        <li>Caching build artifacts to avoid unnecessarily repeating steps.</li>
+        <li>Executing build artifacts or system-installed tools.</li>
+        <li>Running tests and verifying the output of executing a build artifact matches
+        the expected value.</li>
+        <li>Running <code>zig fmt</code> on a codebase or a subset of it.</li>
+        <li>Custom tasks.</li>
+      </ul>
+      <p>
+      To use the build system, run <code class="shell">zig build --help</code>
+      to see a command-line usage help menu. This will include project-specific
+      options that were declared in the build.zig script.
+      </p>
       
-      {#header_open|Building a Zig Executable#}
+      {#header_open|Building an Executable#}
       <p>This <code>build.zig</code> file is automatically generated
         by <code>zig init-exe</code>.</p>
       {#code_begin|syntax|build#}
@@ -9660,58 +9674,34 @@ pub fn build(b: *Builder) void {
     // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
     const mode = b.standardReleaseOptions();
 
-    // This line tells the Zig build system where to find the file
-    // that contains main and what to call the executable.
-    const exe = b.addExecutable("main", "src/main.zig");
+    const exe = b.addExecutable("example", "src/main.zig");
     exe.setTarget(target);
     exe.setBuildMode(mode);
     exe.install();
 
     const run_cmd = exe.run();
     run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
 
-    // This will be executed by "zig build run"
     const run_step = b.step("run", "Run the app");
     run_step.dependOn(&run_cmd.step);
 }
-      {#code_end#}{#header_close#}
-
-      {#header_open|Building a C library#}
-      {#code_begin|syntax#}
-      const Builder = @import("std").build.Builder;
-
-      pub fn build(b: *Builder) void {
-          const mode = b.standardReleaseOptions();
-          // Add a target that generates libbadmath, with no Zig source files.
-          const lib = b.addStaticLibrary("badmath", null);
-          lib.setBuildMode(mode);
-          // This particular library exists entirely in src/lib.c.
-          lib.addCSourceFile("src/lib.c", &[_][]const u8{
-              "-Wall",
-              "-Wextra",
-              "-Werror",
-          });
-          // libbadmath.a will be put in this directory, instead of only
-          // living in zig-cache.
-          lib.setOutputDir("obj");
-          lib.install();
-      }
       {#code_end#}
       {#header_close#}
 
-      {#header_open|Extending a C library#}
-      {#code_begin|syntax#}
+      {#header_open|Building a Library#}
+      <p>This <code>build.zig</code> file is automatically generated
+        by <code>zig init-lib</code>.</p>
+      {#code_begin|syntax|build#}
 const Builder = @import("std").build.Builder;
 
 pub fn build(b: *Builder) void {
     const mode = b.standardReleaseOptions();
-    // This line tells the build system to make a static library
-    // called "add" using source from "src/main.zig".
-    const lib = b.addStaticLibrary("add", "src/main.zig");
+    const lib = b.addStaticLibrary("example", "src/main.zig");
     lib.setBuildMode(mode);
-    lib.force_pic = true;
-    // Include the compiler's runtime environment in the static library.
-    lib.bundle_compiler_rt = true;
+    lib.install();
 
     var main_tests = b.addTest("src/main.zig");
     main_tests.setBuildMode(mode);
@@ -9719,7 +9709,19 @@ pub fn build(b: *Builder) void {
     const test_step = b.step("test", "Run library tests");
     test_step.dependOn(&main_tests.step);
 }
-      {#code_end#}{#header_close#}
+      {#code_end#}
+      {#header_close#}
+
+      {#header_open|Compiling C Source Code#}
+      <pre>{#syntax#}
+lib.addCSourceFile("src/lib.c", &[_][]const u8{
+    "-Wall",
+    "-Wextra",
+    "-Werror",
+});
+      {#endsyntax#}</pre>
+      {#header_close#}
+
       {#header_close#}
       {#header_open|C#}
       <p>