auto merge of #7632 : gavinb/rust/7484_manpages, r=cmr

This patch updates the existing manpage and creates new pages for all of the rust command line tools. Closes #7484.

6 files changed, 460 insertions, 4 deletions

diff --git a/man/rust.1 b/man/rust.1
new file mode 100644
index 00000000000..66bebb7ebe3
--- /dev/null
+++ b/man/rust.1
@@ -0,0 +1,111 @@
+.TH RUST "1" "July 2013" "rust 0.7" "User Commands"
+.SH NAME
+rust \- a front-end to the Rust toolchain
+.SH SYNOPSIS
+.B rust
+[\fICOMMAND\fR] [\fIOPTIONS\fR] \fIINPUT\fR
+
+.SH DESCRIPTION
+This tool is a front-end for the Rust language, available at
+<\fBhttps://www.rust-lang.org\fR>. It provides commands to
+run, test and package Rust programs.
+
+.SH COMMANDS
+
+.TP
+\fBbuild\fR
+compile rust source files
+.TP
+\fBrun\fR
+build an executable, and run it
+.TP
+\fBtest\fR
+build a test executable, and run it
+.TP
+\fBdoc\fR
+generate documentation from doc comments
+.TP
+\fBpkg\fR
+download, build, install rust packages
+.TP
+\fBsketch\fR
+run a rust interpreter
+.TP
+\fBhelp\fR
+show detailed usage of a command
+
+The build, run and test commands take the same parameters
+as the rustc command.
+
+.SS "BUILD COMMAND"
+
+The \fBbuild\fR command is a shortcut for the \fBrustc\fR command line.
+All options will be passed to the compiler verbatim. For example, to build
+an optimised version:
+
+    $ rust build -O <filename>
+
+.SS "RUN COMMAND"
+
+The \fBrun\fR command is a shortcut for the \fBrustc\fR command line.
+All options will be passed to the compiler verbatim, and if the compilation
+is successful, the resultant executable will be invoked. For example, to
+build and run an optimised version:
+
+    $ rust run -O <filename>
+
+.SS "TEST COMMAND"
+
+The \fBtest\fR command is a shortcut for the command line:
+
+    $ rustc --test <filename> -o <filestem>test~ && ./<filestem>test~
+
+.SS "DOC COMMAND"
+
+The \fBdoc\fR command is an alias for the rustdoc program. It is equivalent to:
+
+    $ rustdoc [options] <cratefile>
+
+.SS "PKG COMMAND"
+
+The \fBpkg\fR command is an alias for the rustpkg program. It is equivalent to:
+
+    $ rustpkg [options] <cratefile>
+
+.SS "SKETCH COMMAND"
+
+The \fBsketch\fR command launches the \fBrusti\fR interactive shell.
+
+.SS "HELP COMMAND"
+
+The \fBhelp\fR command displays a summary of available commands (ie. this text).
+
+.SH "EXAMPLES"
+
+To build an executable (with a main function):
+    $ rust build hello.rs
+
+To build a library from a source file:
+    $ rust build --lib hello-lib.rs
+
+To build and run an executable:
+    $ rust run hello.rs
+
+To build an executable with unit tests and execute the tests:
+    $ rust test hello.rs
+
+To create a package 
+
+.SH "SEE ALSO"
+rustc, rustdoc, rustpkg, rusti
+
+.SH "BUGS"
+See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.
+
+.SH "AUTHOR"
+See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
+<\fIgraydon@mozilla.com\fR> is the project leader.
+
+.SH "COPYRIGHT"
+This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
+file in the rust source distribution.
diff --git a/man/rustc.1 b/man/rustc.1
index 4e76749f707..2298d5e5455 100644
--- a/man/rustc.1
+++ b/man/rustc.1
@@ -86,10 +86,10 @@ Build a test harness
 \fB\-\-target\fR TRIPLE
 Target triple cpu-manufacturer-kernel[-os] to compile for (see
 http://sources.redhat.com/autobook/autobook/autobook_17.html
-for detail)
+for details)
 .TP
 \fB\-\-target-feature\fR TRIPLE
-Target-specific attributes (see llc -mattr=help for detail)
+Target-specific attributes (see llc -mattr=help for details)
 .TP
 \fB\-\-android-cross-path\fR PATH
 The path to the Android NDK
@@ -128,6 +128,9 @@ To build either with a crate (.rc) file:
 To build an executable with debug info (experimental):
     $ rustc -Z debug-info -o hello hello.rs
 
+.SH "SEE ALSO"
+
+rust, rustdoc, rustpkg, rusti
 
 .SH "BUGS"
 See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.
diff --git a/man/rustdoc.1 b/man/rustdoc.1
new file mode 100644
index 00000000000..93a8f49898c
--- /dev/null
+++ b/man/rustdoc.1
@@ -0,0 +1,63 @@
+.TH RUSTDOC "1" "July 2013" "rustdoc 0.7" "User Commands"
+.SH NAME
+rustdoc \- generate documentation from Rust source code
+.SH SYNOPSIS
+.B rustdoc
+[\fIOPTIONS\fR] \fICRATEFILE\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.
+
+.SH COMMANDS
+
+.TP
+--output-dir <val>
+Put documents here (default: .)
+.TP
+--output-format <val>
+markdown or html (default: html)
+.TP
+--output-style <val>
+doc-per-crate or doc-per-mod (default: doc-per-mod)
+.TP
+--pandoc-cmd <val>
+Command for running pandoc
+.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.
+
+.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
+
+The generated HTML can be viewed with any standard web browser, while
+the Markdown version is well-suited for conversion into other formats.
+
+.SH "SEE ALSO"
+
+rust, rustc, rustpkg, rusti
+
+.SH "BUGS"
+See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.
+
+.SH "AUTHOR"
+See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
+<\fIgraydon@mozilla.com\fR> is the project leader.
+
+.SH "COPYRIGHT"
+This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
+file in the rust source distribution.
diff --git a/man/rusti.1 b/man/rusti.1
new file mode 100644
index 00000000000..9f7d1733c65
--- /dev/null
+++ b/man/rusti.1
@@ -0,0 +1,82 @@
+.TH RUSTI "1" "July 2013" "rusti 0.7" "User Commands"
+\" Macros
+..
+.de Vb \" Begin verbatim text                                                   
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text                                                     
+.ft R
+.fi
+..
+.SH NAME
+rusti \- Rust interactive shell
+
+.SH SYNOPSIS
+.B rusti
+
+.SH DESCRIPTION
+
+This program is a REPL (Read-Eval-Print Loop) for the Rust language, available
+at <\fBhttps://www.rust-lang.org\fR>. It provides an interactive shell to
+evaluate Rust expressions, functions and code snippets, and to experiment with
+Rust code.
+
+.B WARNING:
+The Rust REPL is experimental and may be unstable. If you encounter problems,
+please use the compiler instead.
+
+.SH OPTIONS
+
+Currently none.
+
+.SH SPECIAL COMMANDS
+
+The interactive shell evaluates all input as a sequence of Rust expressions,
+except for a set of special commands prefixed by a colon ':'. These special
+commands are described below:
+
+.TP
+\fB:help\fR
+Display a summary of available commands.
+.TP
+\fB:{\\n ..lines.. \\n:}\\n\fR
+execute multiline command
+.TP
+\fB:load <crate> ...\fR
+loads given crates as dynamic libraries
+.TP
+\fB:clear\fR
+clear the bindings
+.TP
+\fB:exit\fR
+exit from the repl
+
+.SH "EXAMPLES"
+
+A simple example session, declaring a variable, defining a function,
+evaluating an expression and printing the result:
+
+.PP
+.Vb
+\&	\fBrusti>\fR let x = 42;
+\&	\fBrusti>\fR fn square(n: int) -> int { n*n }
+\&	\fBrusti>\fR println(fmt!("%d squared is %d", x, square(x)));
+\&	42 squared is 1764
+.Ve
+
+.SH "SEE ALSO"
+
+rust, rustc, rustdoc, rustpkg
+
+.SH "BUGS"
+See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.
+
+.SH "AUTHOR"
+See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
+<\fIgraydon@mozilla.com\fR> is the project leader.
+
+.SH "COPYRIGHT"
+This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
+file in the rust source distribution.
diff --git a/man/rustpkg.1 b/man/rustpkg.1
new file mode 100644
index 00000000000..a3178e616c6
--- /dev/null
+++ b/man/rustpkg.1
@@ -0,0 +1,194 @@
+.TH RUSTPKG "1" "July 2013" "rustpkg 0.7" "User Commands"
+.SH NAME
+rustpkg \- package manager for Rust applications
+.SH SYNOPSIS
+.B rustpkg
+[\fICOMMAND\fR] [\fIOPTIONS\fR] \fIINPUT\fR
+
+.SH DESCRIPTION
+
+This tool is a package manager for applications written in the Rust language,
+available at <\fBhttps://www.rust-lang.org\fR>. It provides commands to build,
+install and test Rust programs.
+
+.SH COMMANDS
+
+.TP
+\fBbuild\fR
+Searches for a package with the specified name and builds it in the workspace in
+which it is found.
+.TP
+\fBclean\fR
+Remove all generated files from the \fIbuild\fR directory in the target's workspace.
+.TP
+\fBinstall\fR
+Builds the specified target, and all its dependencies, and then installs the
+build products into the \fIlib\fR and \fIbin\fR directories of their respective
+workspaces.
+.TP
+\fBtest\fR
+Builds the module called \fItest.rs\fR in the specified workspace, and then runs
+the resulting executable in test mode.
+
+.SS "BUILD COMMAND"
+
+    rustpkg build \fI[pkgname]\fR
+
+The \fBbuild\fR command searches for a package with specified package name and
+builds it in any workspace(s) where it finds one. Any dependent packages are
+also built. The output files produced by the build phase are stored in the
+\fIbuild\fR subdirectories of each package. The executables and libraries are
+not copied to the 'bin' or 'lib' directories; that is the purpose of the
+\fBinstall\fR command.
+
+.SS "CLEAN COMMAND"
+
+    rustpkg clean \fI[pkgname]\fR
+
+deletes the contents of package's build directory.
+
+.SS "INSTALL COMMAND"
+
+    rustpkg install \fI[url]\fR
+
+builds the libraries and/or executables that are targets for the specified
+package name or URL, and then installs them either into package's \fIlib\fR
+and \fIbin\fR directories, or into the \fIlib\fR and \fIbin\fR subdirectories
+of the first entry in RUST_PATH.
+
+Examples:
+
+    $ rustpkg install git://github.com/mozilla/servo.git#1.2
+    $ rustpkg install rust-glfw
+
+.SS "TEST COMMAND"
+
+    rustpkg test \fI[pkgname]\fR
+
+The test command is a shortcut for the command line:
+
+    $ rustc --test <filename> -o <filestem>test~ && ./<filestem>test~
+
+Note the suffix on the output filename (the word "test" followed by a tilde),
+which should ensure the file does not clash with a user-generated files.
+
+.SH "ENVIRONMENT"
+
+.TP
+RUST_PATH
+A colon-separated (semicolon-separated) list of paths denoting workspaces
+to search for Rust source files. See the section \fBPATHS\fR for full details.
+
+.SH "PATHS"
+
+The \fBrustpkg\fR tool searches for packages in the folders specified by the
+\fBRUST_PATH\fR environment variable. Each folder constitutes a
+\fIworkspace\fR, which contains one or more modules available to import.
+
+In addition to the RUST_PATH settings, the following implicit paths are
+\fIalways\fR searched, in the following order:
+
+1. Any folders named ".rust" in the current directory, \fIand every parent\fR
+of the curent directory, up to the filesystem root;
+
+2. The system path "/usr/local" on Unix-style systems, or the equivalent on
+Windows; and
+
+3. A folder named ".rust" in the user's home directory (ie. "~/.rust" on Unix-
+style systems or the equivalent on Windows).
+
+.SH "PACKAGE STRUCTURE"
+
+A valid workspace must contain each of the following subdirectories:
+
+.TP
+\fBsrc/\fR
+Contains the Rust source code, with one subdirectory per package. Each
+subdirectory contains source files for a given package.
+.TP
+\fBlib/\fR
+"rustpkg install" installs libraries into a target-specific subdirectory of this directory.
+.TP
+\fBbin/\fR
+"rustpkg install" installs executable binaries into a target-specific subdirectory of this directory.
+.TP
+\fBbuild/\fR
+"rustpkg build" stores temporary build artifacts in a target-specific subdirectory of this directory.
+
+For example, if "foo" is a workspace containing the package "bar", then
+"foo/src/bar/main.rs" would be the "main" entry point for building a "bar"
+executable.
+
+.SH "PACKAGE IDENTIFIERS"
+
+A package identifier uniquely identifies a package. A package can be stored in
+a workspace on the local file system, or on a remote Web server, in which case
+the package ID resembles a URL.
+
+For example, \fIgithub.com/mozilla/rust\fR is a package ID
+that would refer to the git repository browsable at \fIhttp://github.com/mozilla/rust\fR.
+
+A package ID can also specify a version, like:
+\fIgithub.com/mozilla/rust#0.3\fR. In this case, \fBrustpkg\fR will check that
+the repository \fIgithub.com/mozilla/rust\fR has a tag named \fI0.3\fR, and
+report an error otherwise.
+
+.SH "SPECIAL MODULES"
+
+\fBrustpkg\fR searches for four different known filenames in the src directory
+in order to determine which crates to build:
+
+.TP
+\fBmain.rs\fR
+Assumed to be a main entry point for building an executable (install destination is 'bin' directory).
+.TP
+\fBlib.rs\fR
+Assumed to be a library crate (install destination is 'lib' directory).
+.TP
+\fBtest.rs\fR
+Assumed to contain tests declared with the \fI#[test]\fR attribute.
+.TP
+\fBbench.rs\fR
+Assumed to contain benchmarks declared with the \fI#[bench]\fR attribute.
+
+.SH "CRATE VERSIONS"
+
+\fBrustpkg\fR packages do not need to declare their versions with an attribute
+inside one of the source files, because rustpkg infers it from the version
+control system. When building a package that is in a git repository,
+rustpkg assumes that the most recent tag specifies the current version. When
+building a package that is not under version control, or that has no tags,
+rustpkg defaults the version to 0.1.
+
+.SH "DEPENDENCIES"
+
+rustpkg infers dependencies from "extern mod" directives. Thus, there should
+be no need to pass a "-L" flag to rustpkg to tell it where to find a library.
+(In the future, it will also be possible to write an "extern mod" directive
+referring to a remote package.)
+
+.SH "CUSTOM BUILD SCRIPTS"
+
+A file called \fIpkg.rs\fR at the root level in a workspace is called a \fIpackage
+script\fR. If a package script exists, rustpkg executes it to build the
+package rather than inferring crates as described previously.
+
+Inside \fIpkg.rs\fR, it's possible to call back into rustpkg to finish up the
+build. The \fIrustpkg::api\fR module contains functions to build, install, or
+clean libraries and executables in the way rustpkg normally would without
+custom build logic.
+
+.SH "SEE ALSO"
+
+rust, rustc, rustdoc, rusti
+
+.SH "BUGS"
+See <\fBhttps://github.com/mozilla/rust/issues\fR> for issues.
+
+.SH "AUTHOR"
+See \fBAUTHORS.txt\fR in the rust source distribution. Graydon Hoare
+<\fIgraydon@mozilla.com\fR> is the project leader.
+
+.SH "COPYRIGHT"
+This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
+file in the rust source distribution.
diff --git a/mk/install.mk b/mk/install.mk
index 6745535fbca..2eb2ad47db4 100644
--- a/mk/install.mk
+++ b/mk/install.mk
@@ -150,8 +150,11 @@ install-host: $(CSREQ$(ISTAGE)_T_$(CFG_BUILD_TRIPLE)_H_$(CFG_BUILD_TRIPLE))
 	$(Q)$(call INSTALL_LIB,$(LIBRUSTDOC_GLOB_$(CFG_BUILD_TRIPLE)))
 	$(Q)$(call INSTALL,$(HL),$(PHL),$(CFG_RUNTIME_$(CFG_BUILD_TRIPLE)))
 	$(Q)$(call INSTALL,$(HL),$(PHL),$(CFG_RUSTLLVM_$(CFG_BUILD_TRIPLE)))
-	$(Q)$(call INSTALL,$(S)/man, \
-	     $(PREFIX_ROOT)/share/man/man1,rustc.1)
+	$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rust.1)
+	$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustc.1)
+	$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustdoc.1)
+	$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rusti.1)
+	$(Q)$(call INSTALL,$(S)/man, $(PREFIX_ROOT)/share/man/man1,rustpkg.1)
 
 install-targets: $(INSTALL_TARGET_RULES)