doc: Add documentation-generating scripts to the Crashpad tree.

R=rsesek@chromium.org

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

crashpad.gyp

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

doc/asciidoc.conf

@@ -0,0 +1,31 @@
+# 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.
+
+[miscellaneous]
+# AsciiDoc uses \r\n by default.
+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
+# 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]
+{mansource=Version} {manversion={revnumber}}{basebackend-xhtml11?<br />}{basebackend-xhtml11=<br>}
+Last updated {revdate}
+endif::basebackend-html[]

doc/asciidoc.css

@@ -0,0 +1,20 @@
+/* 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. */
+
+/* The default AsciiDoc asciidoc.css specifies fuchsia as the visited link
+ * color. This has a dated appearance. Replace it with blue, the same color used
+ * for unvisited links. */
+a:visited {
+  color: blue;
+}

doc/crashpad.doxy

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = out
+OUTPUT_DIRECTORY       = out/doc/doxygen
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -799,8 +799,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = out \
-                         third_party
+EXCLUDE                = third_party
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -816,7 +815,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = out*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

doc/generate_asciidoc.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+
+# 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.
+
+set -e
+
+# Generating AsciiDoc documentation requires AsciiDoc,
+# http://www.methods.co.nz/asciidoc/. For “man” and PDF output, a DocBook
+# toolchain including docbook-xml and docbook-xsl is also required.
+
+# Run from the Crashpad project root directory.
+cd "$(dirname "${0}")/.."
+
+output_dir=out/doc/man
+
+rm -rf "${output_dir}"
+mkdir -p \
+    "${output_dir}/html" \
+    "${output_dir}/man"
+
+# Some extensions of command-line tools behave differently on different systems.
+# $sed_ext should be a sed invocation that enables extended regular expressions.
+# $date_time_t should be a date invocation that causes it to print the date and
+# time corresponding to a time_t string that immediately follows it.
+uname_s="$(uname -s)"
+case "${uname_s}" in
+  Darwin)
+    sed_ext="sed -E"
+    date_time_t="date -r"
+    ;;
+  Linux)
+    sed_ext="sed -r"
+    date_time_t="date -d@"
+    ;;
+  *)
+    echo "${0}: unknown operating system" >& 2
+    exit 1
+    ;;
+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
+  echo "${input}"
+
+  base=$(${sed_ext} -e 's%^.*/([^/]+)\.ad$%\1%' <<< "${input}")
+
+  # Get the last-modified date of $input according to Git, in UTC.
+  git_time_t="$(git log -1 --format=%at "${input}")"
+  git_date="$(LC_ALL=C ${date_time_t}"${git_time_t}" -u '+%B %-d, %Y')"
+
+  # Create HTML output.
+  asciidoc \
+      --attribute mansource=Crashpad \
+      --attribute manversion="${version}" \
+      --attribute manmanual="Crashpad Manual" \
+      --attribute revdate="${git_date}" \
+      --conf-file doc/asciidoc.conf \
+      --doctype manpage \
+      --backend html5 \
+      --attribute stylesheet="${PWD}/doc/asciidoc.css" \
+      --out-file "${output_dir}/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}" \
+      --doctype manpage \
+      --format manpage \
+      --destination-dir "${output_dir}/man" \
+      "${input}"
+
+  # For PDF output, use an a2x command like the one above, with these options:
+  # --format pdf --fop --destination-dir "${output_dir}/pdf"
+done

doc/generate_doxygen.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+
+# 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.
+
+set -e
+
+# Generating Doxygen documentation requires Doxygen, http://www.doxygen.org/.
+
+# Run from the Crashpad project root directory.
+cd "$(dirname "${0}")/.."
+
+output_dir=out/doc/doxygen
+
+rm -rf "${output_dir}"
+mkdir -p "${output_dir}"
+
+doxygen doc/crashpad.doxy

handler/mac/crashpad_handler.ad

@@ -64,4 +64,4 @@ catch_exception_tool(1),
 generate_dump(1),
 run_with_crashpad(1)
 
-include::../../tools/man_footer.ad[]
+include::../../doc/man_footer.ad[]

tools/generate_dump.ad

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

tools/mac/catch_exception_tool.ad

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

tools/mac/exception_port_tool.ad

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

tools/mac/on_demand_service_tool.ad

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

tools/mac/run_with_crashpad.ad

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