Migrate content from wiki.

The wiki existed at https://code.google.com/p/crashpad/wiki, but given
Google Code Project Hosting’s impending shutdown[1], it’s prudent to
move wiki documents into the source code repository.

This change moves the existing contents of doc into doc/support, to make
way for documentation in doc. The two existing wiki pages, ProjectStatus
and DevelopingCrashpad, are converted to AsciiDoc format (a fairly
straightforward conversion) and checked in to doc. generate_asciidoc.sh
is updated to produce HTML output from these files. The generated HTML
will show up at http://docs.crashpad.googlecode.com/git/doc/. Note that
generated HTML is still hosted on Google Code Project Hosting, but it’ll
be easy to find a new home for them.

[1]
http://google-opensource.blogspot.com/2015/03/farewell-to-google-code.html

R=rsesek@chromium.org

Review URL: https://codereview.chromium.org/1055523002

crashpad.gyp

@@ -34,7 +34,7 @@
         'util/util_test.gyp:*',
       ],
       'sources': [
-        'doc/crashpad.doxy.h',
+        'doc/support/crashpad.doxy.h',
         'package.h',
       ],
     },

doc/developing.ad

@@ -0,0 +1,213 @@
+// Copyright 2015 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+:doctype: article
+
+= Developing Crashpad
+
+== Status
+
+link:status.html[Project status] information has moved to its own page.
+
+== Introduction
+
+Crashpad is a https://dev.chromium.org/Home[Chromium project]. Most of
+its development practices follow Chromium’s. In order to function on its
+own in other projects, Crashpad uses
+https://chromium.googlesource.com/chromium/mini_chromium/[mini_chromium],
+a small, self-contained library that provides many of Chromium’s useful
+low-level base routines.
+https://chromium.googlesource.com/chromium/mini_chromium/+/master/README[mini_chromium’s
+README] provides more detail.
+
+== Prerequisites
+
+To develop Crashpad, the following tools are necessary, and must be
+present in the `$PATH` environment variable:
+
+ * Chromium’s
+   https://dev.chromium.org/developers/how-tos/depottools[depot_tools].
+ * http://git-scm.com/[Git]. This is provided by Xcode on Mac OS X and by
+   depot_tools on Windows.
+ * https://www.python.org/[Python]. This is provided by the operating system on
+   Mac OS X, and by depot_tools on Windows.
+ * Appropriate development tools. For Mac OS X, this is
+   https://developer.apple.com/xcode/[Xcode], and for Windows, it’s
+   https://www.visualstudio.com/[Visual Studio].
+
+== Getting the Source Code
+
+The main source code repository is a Git repository hosted at
+https://chromium.googlesource.com/crashpad/crashpad. Although it is possible to
+check out this repository directly with `git clone`, Crashpad’s dependencies are
+managed by
+https://dev.chromium.org/developers/how-tos/depottools#TOC-gclient[`gclient`]
+instead of Git submodules, so to work on Crashpad, it is best to use `gclient`
+to get the source code.
+
+`gclient` is part of the
+https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no
+need to install it separately.
+
+=== Initial Checkout
+
+[subs="verbatim,quotes"]
+----
+$ *mkdir \~/crashpad*
+$ *cd ~/crashpad*
+$ *gclient config --unmanaged https://chromium.googlesource.com/crashpad/crashpad*
+$ *gclient sync*
+----
+
+=== Subsequent Checkouts
+
+[subs="verbatim,quotes"]
+----
+$ *cd ~/crashpad/crashpad*
+$ *git pull -r*
+$ *gclient sync*
+----
+
+== Building
+
+Crashpad uses https://gyp.googlecode.com/[GYP] to generate
+https://martine.github.io/ninja/[Ninja] build files. The build is described by
+`.gyp` files throughout the Crashpad source code tree. The
+`build/gyp_crashpad.py` script runs GYP properly for Crashpad, and is also
+called when you run `gclient sync` or `gclient runhooks`.
+
+The Ninja build files and build output are in the `out` directory. Both debug-
+and release-mode configurations are available. The examples below show the debug
+configuration. To build and test the release configuration, substitute `Release`
+for `Debug`.
+
+[subs="verbatim,quotes"]
+----
+$ *cd ~/crashpad/crashpad*
+$ *ninja -C out/Debug*
+----
+
+Ninja is part of the
+https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no
+need to install it separately.
+
+== Testing
+
+Crashpad uses https://googletest.googlecode.com/[Google Test] as its
+unit-testing framework, and some tests use
+https://googlemock.googlecode.com/[Google Mock] as well. Its tests are currently
+split up into several test executables, each dedicated to testing a different
+component. This may change in the future. After a successful build, the test
+executables will be found at `out/Debug/crashpad_*_test`.
+
+[subs="verbatim,quotes"]
+----
+$ *cd ~/crashpad/crashpad*
+$ *out/Debug/crashpad_minidump_test*
+$ *out/Debug/crashpad_util_test*
+----
+
+A script is provided to run all of Crashpad’s tests. It accepts a single
+argument that tells it which configuration to test.
+
+[subs="verbatim,quotes"]
+----
+$ *cd ~/crashpad/crashpad*
+$ *python build/run_tests.py Debug*
+----
+
+== Contributing
+
+Crashpad’s contribution process is very similar to
+https://dev.chromium.org/developers/contributing-code[Chromium’s contribution
+process].
+
+=== Code Review
+
+A code review must be conducted for every change to Crashpad’s source code. Code
+review is conducted on https://codereview.chromium.org/[Chromium’s Rietveld]
+system, and all code reviews must be sent to an appropriate reviewer, with a Cc
+sent to
+https://groups.google.com/a/chromium.org/group/crashpad-dev[crashpad-dev]. The
+`codereview.settings` file specifies this environment to `git-cl`.
+
+`git-cl` is part of the
+https://dev.chromium.org/developers/how-tos/depottools[depot_tools]. There’s no
+need to install it separately.
+
+[subs="verbatim,quotes"]
+----
+$ *cd ~/crashpad/crashpad*
+$ *git checkout -b work_branch origin/master*
+_…do some work…_
+$ *git add …*
+$ *git commit*
+$ *git cl upload*
+----
+
+Uploading a patch to Rietveld does not automatically request a review. You must
+select a reviewer and mail your request to them (with a Cc to crashpad-dev) from
+the Rietveld issue page after running `git cl upload`. If you have lost track of
+the issue page, `git cl issue` will remind you of its URL. Alternatively, you
+can request review when uploading to Rietveld by using `git cl upload
+--send-mail`
+
+Git branches maintain their association with Rietveld issues, so if you need to
+make changes based on review feedback, you can do so on the correct Git branch,
+committing your changes locally with `git commit`. You can then upload a new
+patch set with `git cl upload` and let your reviewer know you’ve addressed the
+feedback.
+
+=== Landing Changes
+
+After code review is complete and “LGTM” (“looks good to me”) has been received
+from all reviewers, project members can commit the patch themselves:
+
+[subs="verbatim,quotes"]
+----
+$ *cd ~/crashpad/crashpad*
+$ *git checkout work_branch*
+$ *git cl land*
+----
+
+Crashpad does not currently have a
+https://dev.chromium.org/developers/testing/commit-queue[commit queue], so
+contributors that are not project members will have to ask a project member to
+commit the patch for them. Project members can commit changes on behalf of
+external contributors by patching the change into a local branch and landing it:
+
+[subs="verbatim,quotes"]
+----
+$ *cd ~/crashpad/crashpad*
+$ *git checkout -b for_external_contributor origin/master*
+$ *git cl patch 12345678*  _# 12345678 is the Rietveld issue number_
+$ *git cl land -c \'External Contributor <external@contributor.org>'*
+----
+
+=== External Contributions
+
+Copyright holders must complete the
+https://developers.google.com/open-source/cla/individual[Individual Contributor
+License Agreement] or
+https://developers.google.com/open-source/cla/corporate[Corporate Contributor
+License Agreement] as appropriate before any submission can be accepted, and
+must be listed in the `AUTHORS` file. Contributors may be listed in the
+`CONTRIBUTORS` file.
+
+== Buildbot
+
+The https://build.chromium.org/p/client.crashpad/[Crashpad Buildbot] performs
+automated builds and tests of Crashpad. Before checking out or updating the
+Crashpad source code, and after checking in a new change, it is prudent to check
+the Buildbot to ensure that “the tree is green.”

doc/status.ad

@@ -0,0 +1,42 @@
+// Copyright 2015 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+:doctype: article
+
+= Project Status
+
+== Completed
+
+Crashpad currently consists of a crash-reporting client and some related tools
+for Mac OS X. The core client work for Mac OS X is substantially complete.
+Crashpad has become the crash reporter client for
+https://dev.chromium.org/Home[Chromium] on Mac OS X as of
+https://chromium.googlesource.com/chromium/src/+/d413b2dcb54d523811d386f1ff4084f677a6d089[March
+2015].
+
+== In Progress
+
+Crashpad is actively being bootstrapped on
+https://code.google.com/p/crashpad/issues/detail?id=1[Windows]. With the
+exception of the snapshot library, most major components are now working on
+Windows, and work is progressing on the Windows snapshot implementation.
+
+== Future
+
+There are plans to bring Crashpad clients to other operating systems in the
+future, including
+https://code.google.com/p/crashpad/issues/detail?id=30[Android] and, more
+generically, Linux. There are also plans to implement a
+https://code.google.com/p/crashpad/issues/detail?id=29[crash report processor]
+as part of Crashpad. No timeline for completing this work has been set yet.

doc/support/asciidoc.conf

@@ -19,15 +19,20 @@ newline=\n
 # The default AsciiDoc lang-en.conf uses docdate and doctime for the
 # last-updated line in footer-text. These attributes are taken from the file’s
 # mtime and cannot be overridden. For a git-based project, the date of the last
-# revision is desirable, so change this to use revdate, an attribute that can be
-# computed and passed in by the script that runs AsciiDoc. For man pages, use
+# revision is desirable, so change this to use git_date, an attribute that can
+# be computed and passed in by the script that runs AsciiDoc. For man pages, use
 # the mansource and manversion attributes instead of the hard-coded “Version”
 # string and revnumber attribute, so that the version will appear as “Crashpad
 # 0.7.0” as it does in “man” output.
 ifdef::basebackend-html[]
 [footer-text]
+ifdef::doctype-manpage[]
 {mansource=Version} {manversion={revnumber}}{basebackend-xhtml11?<br />}{basebackend-xhtml11=<br>}
-Last updated {revdate}
+endif::doctype-manpage[]
+ifndef::doctype-manpage[]
+Version {revnumber}{basebackend-xhtml11?<br />}{basebackend-xhtml11=<br>}
+endif::doctype-manpage[]
+Last updated {git_date}
 endif::basebackend-html[]
 
 # The man_link macro was inspired by git’s linkgit macro. See

doc/support/generate_asciidoc.sh

@@ -21,14 +21,17 @@ set -e
 # toolchain including docbook-xml and docbook-xsl is also required.
 
 # Run from the Crashpad project root directory.
-cd "$(dirname "${0}")/.."
+cd "$(dirname "${0}")/../.."
 
-output_dir=out/doc/man
+output_dir=out/doc
 
-rm -rf "${output_dir}"
-mkdir -p \
-    "${output_dir}/html" \
+rm -rf \
+    "${output_dir}/doc" \
     "${output_dir}/man"
+mkdir -p \
+    "${output_dir}/doc/html" \
+    "${output_dir}/man/html" \
+    "${output_dir}/man/man"
 
 # Some extensions of command-line tools behave differently on different systems.
 # $sed_ext should be a sed invocation that enables extended regular expressions.
@@ -53,10 +56,23 @@ esac
 # Get the version from package.h.
 version=$(${sed_ext} -n -e 's/^#define PACKAGE_VERSION "(.*)"$/\1/p' package.h)
 
-for input in \
-    handler/mac/crashpad_handler.ad \
-    tools/*.ad \
-    tools/mac/*.ad; do
+generate() {
+  input="$1"
+  type="$2"
+
+  case "${type}" in
+    doc)
+      doctype="article"
+      ;;
+    man)
+      doctype="manpage"
+      ;;
+    *)
+      echo "${0}: unknown type ${type}" >& 2
+      exit 1
+      ;;
+  esac
+
   echo "${input}"
 
   base=$(${sed_ext} -e 's%^.*/([^/]+)\.ad$%\1%' <<< "${input}")
@@ -70,30 +86,44 @@ for input in \
       --attribute mansource=Crashpad \
       --attribute manversion="${version}" \
       --attribute manmanual="Crashpad Manual" \
-      --attribute revdate="${git_date}" \
-      --conf-file doc/asciidoc.conf \
-      --doctype manpage \
+      --attribute git_date="${git_date}" \
+      --conf-file doc/support/asciidoc.conf \
+      --doctype "${doctype}" \
       --backend html5 \
-      --attribute stylesheet="${PWD}/doc/asciidoc.css" \
-      --out-file "${output_dir}/html/${base}.html" \
+      --attribute stylesheet="${PWD}/doc/support/asciidoc.css" \
+      --out-file "${output_dir}/${type}/html/${base}.html" \
       "${input}"
 
-  # Create “man” output.
-  #
-  # AsciiDoc 8.6.9 produces harmless incorrect warnings each time this is run:
-  # “a2x: WARNING: --destination-dir option is only applicable to HTML based
-  # outputs”. https://github.com/asciidoc/asciidoc/issues/44
-  a2x \
-      --attribute mansource=Crashpad \
-      --attribute manversion="${version}" \
-      --attribute manmanual="Crashpad Manual" \
-      --attribute revdate="${git_date}" \
-      --asciidoc-opts=--conf-file=doc/asciidoc.conf \
-      --doctype manpage \
-      --format manpage \
-      --destination-dir "${output_dir}/man" \
-      "${input}"
+  if [[ "${type}" = "man" ]]; then
+    # Create “man” output.
+    #
+    # AsciiDoc 8.6.9 produces harmless incorrect warnings each time this is run:
+    # “a2x: WARNING: --destination-dir option is only applicable to HTML based
+    # outputs”. https://github.com/asciidoc/asciidoc/issues/44
+    a2x \
+        --attribute mansource=Crashpad \
+        --attribute manversion="${version}" \
+        --attribute manmanual="Crashpad Manual" \
+        --attribute git_date="${git_date}" \
+        --asciidoc-opts=--conf-file=doc/support/asciidoc.conf \
+        --doctype "${doctype}" \
+        --format manpage \
+        --destination-dir "${output_dir}/${type}/man" \
+        "${input}"
+  fi
 
   # For PDF output, use an a2x command like the one above, with these options:
-  # --format pdf --fop --destination-dir "${output_dir}/pdf"
+  # --format pdf --fop --destination-dir "${output_dir}/${type}/pdf"
+}
+
+for input in \
+    doc/*.ad; do
+  generate "${input}" "doc"
+done
+
+for input in \
+    handler/mac/crashpad_handler.ad \
+    tools/*.ad \
+    tools/mac/*.ad; do
+  generate "${input}" "man"
 done

doc/support/generate_doxygen.sh

@@ -19,11 +19,11 @@ set -e
 # Generating Doxygen documentation requires Doxygen, http://www.doxygen.org/.
 
 # Run from the Crashpad project root directory.
-cd "$(dirname "${0}")/.."
+cd "$(dirname "${0}")/../.."
 
 output_dir=out/doc/doxygen
 
 rm -rf "${output_dir}"
 mkdir -p "${output_dir}"
 
-doxygen doc/crashpad.doxy
+doxygen doc/support/crashpad.doxy

handler/mac/crashpad_handler.ad

@@ -105,4 +105,4 @@ man_link:crashpad_database_util[1],
 man_link:generate_dump[1],
 man_link:run_with_crashpad[1]
 
-include::../../doc/man_footer.ad[]
+include::../../doc/support/man_footer.ad[]

tools/crashpad_database_util.ad

@@ -148,4 +148,4 @@ Failure, with a message printed to the standard error stream.
 
 man_link:crashpad_handler[8]
 
-include::../../doc/man_footer.ad[]
+include::../doc/support/man_footer.ad[]

tools/generate_dump.ad

@@ -93,4 +93,4 @@ Failure, with a message printed to the standard error stream.
 
 man_link:catch_exception_tool[1]
 
-include::../doc/man_footer.ad[]
+include::../doc/support/man_footer.ad[]

tools/mac/catch_exception_tool.ad

@@ -114,4 +114,4 @@ Failure, with a message printed to the standard error stream.
 man_link:exception_port_tool[1],
 man_link:on_demand_service_tool[1]
 
-include::../../doc/man_footer.ad[]
+include::../../doc/support/man_footer.ad[]

tools/mac/exception_port_tool.ad

@@ -185,4 +185,4 @@ The program specified by 'COMMAND' could not be found.
 man_link:catch_exception_tool[1],
 man_link:on_demand_service_tool[1]
 
-include::../../doc/man_footer.ad[]
+include::../../doc/support/man_footer.ad[]

tools/mac/on_demand_service_tool.ad

@@ -99,4 +99,4 @@ man_link:catch_exception_tool[1],
 man_link:exception_port_tool[1],
 launchctl(1)
 
-include::../../doc/man_footer.ad[]
+include::../../doc/support/man_footer.ad[]

tools/mac/run_with_crashpad.ad

@@ -109,4 +109,4 @@ The program specified by 'COMMAND' could not be found.
 man_link:crashpad_handler[8],
 man_link:exception_port_tool[1]
 
-include::../../doc/man_footer.ad[]
+include::../../doc/support/man_footer.ad[]