From 863555f4fd9d8b0bd838420f69e4c2d84ac1dff9 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Mon, 30 Sep 2013 13:28:30 -0700
Subject: [PATCH] rustdoc: Update the man page

Closes #9622
---
 man/rustdoc.1             | 77 ++++++++++++++++++++++++++++-----------
 src/librustdoc/rustdoc.rs |  7 ++--
 2 files changed, 60 insertions(+), 24 deletions(-)

diff --git a/man/rustdoc.1 b/man/rustdoc.1
index 93a8f49898cd1..c7cdb8328879c 100644
--- a/man/rustdoc.1
+++ b/man/rustdoc.1
@@ -3,49 +3,84 @@
 rustdoc \- generate documentation from Rust source code
 .SH SYNOPSIS
 .B rustdoc
-[\fIOPTIONS\fR] \fICRATEFILE\fR
+[\fIOPTIONS\fR] \fIINPUT\fR
 
 .SH DESCRIPTION
 This tool generates API reference documentation by extracting comments from
-source code written in the Rust language, available at <\fBhttps://www.rust-
-lang.org\fR>. It provides several output formats for the generated
-documentation.
+source code written in the Rust language, available at
+<\fBhttps://www.rust-lang.org\fR>. It accepts several input formats and provides
+several output formats for the generated documentation.
 
-.SH COMMANDS
+.SH OPTIONS
 
 .TP
---output-dir <val>
-Put documents here (default: .)
+-r --input-format <val>
+html or json (default: inferred)
 .TP
---output-format <val>
-markdown or html (default: html)
+-w --output-format <val>
+html or json (default: html)
 .TP
---output-style <val>
-doc-per-crate or doc-per-mod (default: doc-per-mod)
+-o --output <val>
+where to place the output (default: doc/ for html, doc.json for json)
 .TP
---pandoc-cmd <val>
-Command for running pandoc
+--passes <val>
+space-separated list of passes to run (default: '')
+.TP
+--no-defaults
+don't run the default passes
+.TP
+--plugins <val>
+space-separated list of plugins to run (default: '')
+.TP
+--plugin-path <val>
+directory to load plugins from (default: /tmp/rustdoc_ng/plugins)
+.TP
+-L --library-path <val>
+directory to add to crate search path
 .TP
 -h, --help
 Print help
 
 .SH "OUTPUT FORMATS"
 
-The rustdoc tool can generate documentation in either the Markdown
-or HTML formats. It requires the pandoc tool
-<\fBhttp://johnmacfarlane.net/pandoc/\fR> for conversion features.
+The rustdoc tool can generate output in either an HTML or JSON format.
+
+If using an HTML format, then the specified output destination will be the root
+directory of an HTML structure for all the documentation. Pages will be placed
+into this directory, and source files will also possibly be rendered into it as
+well.
+
+If using a JSON format, then the specified output destination will have the
+rustdoc output serialized as JSON into it. This output format exists to
+pre-compile documentation for crates, and for usage in non-rustdoc tools. The
+JSON output is the following hash:
+
+    {
+        "schema": VERSION,
+        "crate": ...,
+        "plugins": ...,
+    }
+
+The schema version indicates what the structure of crate/plugins will look
+like. Within a schema version the structure will remain the same. The `crate`
+field will contain all relevant documentation for the source being documented,
+and the `plugins` field will contain the output of the plugins run over the
+crate.
 
 .SH "EXAMPLES"
 
 To generate documentation for the source in the current directory:
     $ rustdoc hello.rs
 
-To build documentation into a subdirectory named 'doc' in the Markdown
-format:
-    $ rustdoc --output-dir doc --output-format markdown hello.rs
+List all available passes that rustdoc has, along with default passes:
+    $ rustdoc --passes list
+
+To precompile the documentation for a crate, and then use it to render html at
+a later date:
+    $ rustdoc -w json hello.rs
+    $ rustdoc doc.json
 
-The generated HTML can be viewed with any standard web browser, while
-the Markdown version is well-suited for conversion into other formats.
+The generated HTML can be viewed with any standard web browser.
 
 .SH "SEE ALSO"
 
diff --git a/src/librustdoc/rustdoc.rs b/src/librustdoc/rustdoc.rs
index 96e0464fdde9d..4c7c99d639469 100644
--- a/src/librustdoc/rustdoc.rs
+++ b/src/librustdoc/rustdoc.rs
@@ -95,7 +95,7 @@ pub fn opts() -> ~[groups::OptGroup] {
                  "PASSES"),
         optmulti("", "plugins", "space separated list of plugins to also load",
                  "PLUGINS"),
-        optflag("", "nodefaults", "don't run the default passes"),
+        optflag("", "no-defaults", "don't run the default passes"),
     ]
 }
 
@@ -181,7 +181,7 @@ fn acquire_input(matches: &getopts::Matches) -> Result<Output, ~str> {
 ///
 /// This form of input will run all of the plug/cleaning passes
 fn rust_input(cratefile: &str, matches: &getopts::Matches) -> Output {
-    let mut default_passes = !matches.opt_present("nodefaults");
+    let mut default_passes = !matches.opt_present("no-defaults");
     let mut passes = matches.opt_strs("passes");
     let mut plugins = matches.opt_strs("plugins");
 
@@ -227,7 +227,8 @@ fn rust_input(cratefile: &str, matches: &getopts::Matches) -> Output {
     }
 
     // Load all plugins/passes into a PluginManager
-    let mut pm = plugins::PluginManager::new(Path("/tmp/rustdoc_ng/plugins"));
+    let path = matches.opt_str("plugin-path").unwrap_or(~"/tmp/rustdoc_ng/plugins");
+    let mut pm = plugins::PluginManager::new(Path(path));
     for pass in passes.iter() {
         let plugin = match PASSES.iter().position(|&(p, _, _)| p == *pass) {
             Some(i) => PASSES[i].n1(),