Rollup merge of #22832 - anguslees:manpage-pedantry, r=brson

Use consistent markup between rust and rustdoc manpages.  Avoid use of
the troublesome unquoted '-' troff character.

man/rustc.1

@@ -7,224 +7,267 @@ rustc \- The Rust compiler
 
 .SH DESCRIPTION
 This program is a compiler for the Rust language, available at
-<\fBhttps://www.rust-lang.org\fR>.
+.UR https://www.rust\-lang.org
+.UE .
 
 .SH OPTIONS
 
 .TP
 \fB\-h\fR, \fB\-\-help\fR
-Display the help message
+Display the help message.
 .TP
-\fB\-\-cfg\fR SPEC
+\fB\-\-cfg\fR \fISPEC\fR
-Configure the compilation environment
+Configure the compilation environment.
 .TP
-\fB\-L\fR [KIND=]PATH
+\fB\-L\fR [\fIKIND\fR=]\fIPATH\fR
-Add a directory to the library search path. The optional KIND can be one of:
+Add a directory to the library search path.
-    dependency = only lookup transitive dependencies here
+The optional \fIKIND\fR can be one of:
-    crate = only lookup local `extern crate` directives here
+.RS
-    native = only lookup native libraries here
-    framework = only look for OSX frameworks here
-    all = look for anything here (the default)
 .TP
-\fB\-l\fR [KIND=]NAME
+\fBdependency\fR
-Link the generated crate(s) to the specified native library NAME. The optional
+only lookup transitive dependencies here
-KIND can be one of, static, dylib, or framework. If omitted, dylib is assumed.
 .TP
-\fB\-\-crate-type\fR [bin|lib|rlib|dylib|staticlib]
+.B crate
-Comma separated list of types of crates for the compiler to emit
+only lookup local `extern crate` directives here
 .TP
-\fB\-\-crate-name NAME\fR
+.B native
-Specify the name of the crate being built
+only lookup native libraries here
 .TP
-\fB\-\-emit\fR [asm|llvm-bc|llvm-ir|obj|link|dep-info]
+.B framework
-Configure the output that rustc will produce
+only look for OSX frameworks here
 .TP
-\fB\-\-print\fR [crate-name|file-names|sysroot]
+.B all
-Comma separated list of compiler information to print on stdout
+look for anything here (the default)
+.RE
+.TP
+\fB\-l\fR [\fIKIND\fR=]\fINAME\fR
+Link the generated crate(s) to the specified native library \fINAME\fR.
+The optional \fIKIND\fR can be one of \fIstatic\fR, \fIdylib\fR, or
+\fIframework\fR.
+If omitted, \fIdylib\fR is assumed.
+.TP
+\fB\-\-crate\-type\fR [bin|lib|rlib|dylib|staticlib]
+Comma separated list of types of crates for the compiler to emit.
+.TP
+\fB\-\-crate\-name\fR \fINAME\fR
+Specify the name of the crate being built.
+.TP
+\fB\-\-emit\fR [asm|llvm\-bc|llvm\-ir|obj|link|dep\-info]
+Configure the output that \fBrustc\fR will produce.
+.TP
+\fB\-\-print\fR [crate\-name|file\-names|sysroot]
+Comma separated list of compiler information to print on stdout.
 .TP
 \fB\-g\fR
-Equivalent to \fI\-C\fR debuginfo=2
+Equivalent to \fI\-C\ debuginfo=2\fR.
 .TP
 \fB\-O\fR
-Equivalent to \fI\-C\fR opt-level=2
+Equivalent to \fI\-C\ opt\-level=2\fR.
 .TP
-\fB\-o\fR FILENAME
+\fB\-o\fR \fIFILENAME\fR
-Write output to <filename>. Ignored if multiple \fI\-\-emit\fR outputs are
+Write output to \fIFILENAME\fR.
-specified.
+Ignored if multiple \fI\-\-emit\fR outputs are specified.
 .TP
-\fB\-\-out\-dir\fR DIR
+\fB\-\-out\-dir\fR \fIDIR\fR
-Write output to compiler-chosen filename in <dir>. Ignored if \fI\-o\fR is
+Write output to compiler\[hy]chosen filename in \fIDIR\fR.
-specified. Defaults to the current directory.
+Ignored if \fI\-o\fR is specified.
+Defaults to the current directory.
 .TP
-\fB\-\-explain\fR OPT
+\fB\-\-explain\fR \fIOPT\fR
-Provide a detailed explanation of an error message
+Provide a detailed explanation of an error message.
 .TP
 \fB\-\-test\fR
-Build a test harness
+Build a test harness.
 .TP
-\fB\-\-target\fR TRIPLE
+\fB\-\-target\fR \fITRIPLE\fR
-Target triple cpu-manufacturer-kernel[-os] to compile for (see chapter 3.4 of
+Target triple \fIcpu\fR\-\fImanufacturer\fR\-\fIkernel\fR[\-\fIos\fR]
-http://www.sourceware.org/autobook/ for details)
+to compile for (see chapter 3.4 of
+.UR http://www.sourceware.org/autobook/
+.UE
+for details).
 .TP
-\fB\-W\fR help
+\fB\-W help\fR
-Print 'lint' options and default settings
+Print 'lint' options and default settings.
 .TP
-\fB\-W\fR OPT, \fB\-\-warn\fR OPT
+\fB\-W\fR \fIOPT\fR, \fB\-\-warn\fR \fIOPT\fR
-Set lint warnings
+Set lint warnings.
 .TP
-\fB\-A\fR OPT, \fB\-\-allow\fR OPT
+\fB\-A\fR \fIOPT\fR, \fB\-\-allow\fR \fIOPT\fR
-Set lint allowed
+Set lint allowed.
 .TP
-\fB\-D\fR OPT, \fB\-\-deny\fR OPT
+\fB\-D\fR \fIOPT\fR, \fB\-\-deny\fR \fIOPT\fR
-Set lint denied
+Set lint denied.
 .TP
-\fB\-F\fR OPT, \fB\-\-forbid\fR OPT
+\fB\-F\fR \fIOPT\fR, \fB\-\-forbid\fR \fIOPT\fR
-Set lint forbidden
+Set lint forbidden.
 .TP
-\fB\-C\fR FLAG[=VAL], \fB\-\-codegen\fR FLAG[=VAL]
+\fB\-C\fR \fIFLAG\fR[=\fIVAL\fR], \fB\-\-codegen\fR \fIFLAG\fR[=\fIVAL\fR]
-Set a codegen-related flag to the value specified. Use "-C help" to print
+Set a codegen\[hy]related flag to the value specified.
-available flags. See CODEGEN OPTIONS below
+Use \fI\-C help\fR to print available flags.
+See CODEGEN OPTIONS below.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
-Print version info and exit
+Print version info and exit.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Use verbose output
+Use verbose output.
 .TP
-\fB\-\-extern\fR NAME=PATH
+\fB\-\-extern\fR \fINAME\fR=\fIPATH\fR
-Specify where an external rust library is located
+Specify where an external rust library is located.
 .TP
-\fB\-\-sysroot\fR PATH
+\fB\-\-sysroot\fR \fIPATH\fR
-Override the system root
+Override the system root.
 .TP
-\fB\-Z\fR FLAG
+\fB\-Z\fR \fIFLAG\fR
-Set internal debugging options. Use "-Z help" to print available options.
+Set internal debugging options.
+Use \fI\-Z help\fR to print available options.
 .TP
 \fB\-\-color\fR auto|always|never
 Configure coloring of output:
-    auto = colorize, if output goes to a tty (default);
+.RS
-    always = always colorize output;
+.TP
-    never = never colorize output
+.B auto
+colorize, if output goes to a tty (default);
+.TP
+.B always
+always colorize output;
+.TP
+.B never
+never colorize output.
+.RE
 
 .SH CODEGEN OPTIONS
 
 .TP
-\fBar\fR=/path/to/ar
+\fBar\fR=\fI/path/to/ar\fR
 Path to the archive utility to use when assembling archives.
 .TP
-\fBlinker\fR=/path/to/cc
+\fBlinker\fR=\fI/path/to/cc\fR
 Path to the linker utility to use when linking libraries, executables, and
 objects.
 .TP
-\fBlink-args\fR='-flag1 -flag2'
+\fBlink\-args\fR='\fI\-flag1 \-flag2\fR'
-A space-separated list of extra arguments to pass to the linker when the linker
+A space\[hy]separated list of extra arguments to pass to the linker when the linker
 is invoked.
 .TP
 \fBlto\fR
-Perform LLVM link-time optimizations.
+Perform LLVM link\[hy]time optimizations.
 .TP
-\fBtarget-cpu\fR=help
+\fBtarget\-cpu\fR=\fIhelp\fR
-Selects a target processor. If the value is 'help', then a list of available
+Selects a target processor.
-CPUs is printed.
+If the value is 'help', then a list of available CPUs is printed.
 .TP
-\fBtarget-feature\fR='+feature1,-feature2'
+\fBtarget\-feature\fR='\fI+feature1\fR,\fI\-feature2\fR'
-A comma-separated list of features to enable or disable for the target. A
+A comma\[hy]separated list of features to enable or disable for the target.
-preceding '+' enables a feature while a preceding '-' disables it. Available
+A preceding '+' enables a feature while a preceding '\-' disables it.
-features can be discovered through target-cpu=help.
+Available features can be discovered through \fItarget\-cpu=help\fR.
 .TP
-\fBpasses\fR=list
+\fBpasses\fR=\fIval\fR
-A space-separated list of extra LLVM passes to run. A value of 'list' will
+A space\[hy]separated list of extra LLVM passes to run.
-cause rustc to print all known passes and exit. The passes specified are
+A value of 'list' will cause \fBrustc\fR to print all known passes and
-appended at the end of the normal pass manager.
+exit.
+The passes specified are appended at the end of the normal pass manager.
 .TP
-\fBllvm-args\fR='-arg1 -arg2'
+\fBllvm\-args\fR='\fI\-arg1\fR \fI\-arg2\fR'
-A space-separated list of arguments to pass through to LLVM.
+A space\[hy]separated list of arguments to pass through to LLVM.
 .TP
-\fBsave-temps\fR
+\fBsave\-temps\fR
-If specified, the compiler will save more files (.bc, .o, .no-opt.bc) generated
+If specified, the compiler will save more files (.bc, .o, .no\-opt.bc) generated
 throughout compilation in the output directory.
 .TP
 \fBrpath\fR
 If specified, then the rpath value for dynamic libraries will be set in
 either dynamic library or executable outputs.
 .TP
-\fBno-prepopulate-passes\fR
+\fBno\-prepopulate\-passes\fR
-Suppresses pre-population of the LLVM pass manager that is run over the module.
+Suppresses pre\[hy]population of the LLVM pass manager that is run over the module.
 .TP
-\fBno-vectorize-loops\fR
+\fBno\-vectorize\-loops\fR
 Suppresses running the loop vectorization LLVM pass, regardless of optimization
 level.
 .TP
-\fBno-vectorize-slp\fR
+\fBno\-vectorize\-slp\fR
 Suppresses running the LLVM SLP vectorization pass, regardless of optimization
 level.
 .TP
-\fBsoft-float\fR
+\fBsoft\-float\fR
 Generates software floating point library calls instead of hardware
 instructions.
 .TP
-\fBprefer-dynamic\fR
+\fBprefer\-dynamic\fR
 Prefers dynamic linking to static linking.
 .TP
-\fBno-integrated-as\fR
+\fBno\-integrated\-as\fR
 Force usage of an external assembler rather than LLVM's integrated one.
 .TP
-\fBno-redzone\fR
+\fBno\-redzone\fR
 Disable the use of the redzone.
 .TP
-\fBrelocation-model\fR=[pic,static,dynamic-no-pic]
+\fBrelocation\-model\fR=[pic,static,dynamic\-no\-pic]
-The relocation model to use. (Default: pic)
+The relocation model to use.
+(Default: \fIpic\fR)
 .TP
-\fBcode-model\fR=[small,kernel,medium,large]
+\fBcode\-model\fR=[small,kernel,medium,large]
 Choose the code model to use.
 .TP
-\fBmetadata\fR=val
+\fBmetadata\fR=\fIval\fR
 Metadata to mangle symbol names with.
 .TP
-\fBextra-filename\fR=val
+\fBextra\-filename\fR=\fIval\fR
 Extra data to put in each output filename.
 .TP
-\fBcodegen-units\fR=val
+\fBcodegen\-units\fR=\fIn\fR
-Divide crate into N units to optimize in parallel.
+Divide crate into \fIn\fR units to optimize in parallel.
 .TP
-\fBremark\fR=val
+\fBremark\fR=\fIval\fR
 Print remarks for these optimization passes (space separated, or "all").
 .TP
-\fBno-stack-check\fR
+\fBno\-stack\-check\fR
-Disable checks for stack exhaustion (a memory-safety hazard!).
+Disable checks for stack exhaustion (a memory\[hy]safety hazard!).
 .TP
-\fBdebuginfo\fR=val
+\fBdebuginfo\fR=\fIval\fR
 Debug info emission level:
-    0 = no debug info;
+.RS
-    1 = line-tables only (for stacktraces and breakpoints);
-    2 = full debug info with variable and type information.
 .TP
-\fBopt-level\fR=val
+.B 0
-Optimize with possible levels 0-3
+no debug info;
+.TP
+.B 1
+line\[hy]tables only (for stacktraces and breakpoints);
+.TP
+.B 2
+full debug info with variable and type information.
+.RE
+.TP
+\fBopt\-level\fR=\fIVAL\fR
+Optimize with possible levels 0\[en]3
 
 .SH "EXAMPLES"
 To build an executable from a source file with a main function:
-    $ rustc -o hello hello.rs
+    $ rustc \-o hello hello.rs
 
 To build a library from a source file:
-    $ rustc --crate-type=lib hello-lib.rs
+    $ rustc \-\-crate\-type=lib hello\-lib.rs
 
 To build either with a crate (.rs) file:
     $ rustc hello.rs
 
 To build an executable with debug info:
-    $ rustc -g -o hello hello.rs
+    $ rustc \-g \-o hello hello.rs
 
 .SH "SEE ALSO"
 
-rustdoc
+.BR rustdoc (1)
 
 .SH "BUGS"
-See <\fBhttps://github.com/rust-lang/rust/issues\fR> for issues.
+See
+.UR https://github.com/rust\-lang/rust/issues
+.UE
+for issues.
 
 .SH "AUTHOR"
-See \fBAUTHORS.txt\fR in the Rust source distribution.
+See \fIAUTHORS.txt\fR in the Rust source distribution.
 
 .SH "COPYRIGHT"
-This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
+This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
-file in the rust source distribution.
+See \fICOPYRIGHT\fR file in the rust source distribution.

man/rustdoc.1

@@ -8,76 +8,79 @@ rustdoc \- generate documentation from Rust source code
 .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 accepts several input formats and provides
+.UR https://www.rust\-lang.org
-several output formats for the generated documentation.
+.UE .
+It accepts several input formats and provides several output formats
+for the generated documentation.
 
 .SH OPTIONS
 
 .TP
--r --input-format <val>
+\fB\-r\fR, \fB\-\-input\-format\fR \fIFORMAT\fR
 html or json (default: inferred)
 .TP
--w --output-format <val>
+\fB\-w\fR, \fB\-\-output\-format\fR \fIFORMAT\fR
 html or json (default: html)
 .TP
--o --output <val>
+\fB\-o\fR, \fB\-\-output\fR \fIOUTPUT\fR
-where to place the output (default: doc/ for html, doc.json for json)
+where to place the output (default: \fIdoc/\fR for html,
+\fIdoc.json\fR for json)
 .TP
---passes <val>
+\fB\-\-passes\fR \fILIST\fR
-space-separated list of passes to run (default: '')
+space\[hy]separated list of passes to run (default: '')
 .TP
---no-defaults
+\fB\-\-no\-defaults\fR
 don't run the default passes
 .TP
---plugins <val>
+\fB\-\-plugins\fR \fILIST\fR
 space-separated list of plugins to run (default: '')
 .TP
---plugin-path <val>
+\fB\-\-plugin\-path\fR \fIDIR\fR
-directory to load plugins from (default: /tmp/rustdoc_ng/plugins)
+directory to load plugins from (default: \fI/tmp/rustdoc_ng/plugins\fR)
 .TP
---target <val>
+\fB\-\-target\fR \fITRIPLE\fR
 target triple to document
 .TP
---crate-name <val>
+\fB\-\-crate\-name\fR \fINAME\fR
 specify the name of this crate
 .TP
--L --library-path <val>
+\fB\-L\fR, \fB\-\-library\-path\fR \fIDIR\fR
 directory to add to crate search path
 .TP
---cfg <val>
+\fB\-\-cfg\fR \fISPEC\fR
-pass a --cfg to rustc
+pass a \fI\-\-cfg\fR to rustc
 .TP
---extern <val>
+\fB\-\-extern\fR \fIVAL\fR
-pass an --extern to rustc
+pass an \fI\-\-extern\fR to rustc
 .TP
---test
+\fB\-\-test\fR
 run code examples as tests
 .TP
---test-args <val>
+\fB\-\-test\-args\fR \fIARGS\fR
 pass arguments to the test runner
 .TP
---html-in-header <val>
+\fB\-\-html\-in\-header\fR \fIFILE\fR
 file to add to <head>
 .TP
---html-before-content <val>
+\fB\-\-html\-before\-content\fR \fIFILE\fR
 file to add in <body>, before content
 .TP
---html-after-content <val>
+\fB\-\-html\-after\-content\fR \fIFILE\fR
 file to add in <body>, after content
 .TP
---markdown-css <val>
+\fB\-\-markdown\-css\fR \fIFILE\fR
 CSS files to include via <link> in a rendered Markdown file
 .TP
---markdown-playground-url <val>
+\fB\-\-markdown\-playground\-url\fR \fIURL\fR
 URL to send code snippets to
 .TP
---markdown-no-toc
+\fB\-\-markdown\-no\-toc\fR
 don't include table of contents
 .TP
--h, --help
+\fB\-h\fR, \fB\-\-help\fR
 Print help
 .TP
--V, --version
+\fB\-V\fR, \fB\-\-version\fR
 Print rustdoc's version
 
 .SH "OUTPUT FORMATS"
@@ -85,14 +88,15 @@ Print rustdoc's version
 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
+directory of an HTML structure for all the documentation.
-into this directory, and source files will also possibly be rendered into it as
+Pages will be placed into this directory, and source files will also
-well.
+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
+rustdoc output serialized as JSON into it.
-pre-compile documentation for crates, and for usage in non-rustdoc tools. The
+This output format exists to pre\[hy]compile documentation for crates,
-JSON output is the following hash:
+and for usage in non\[hy]rustdoc tools.
+The JSON output is the following hash:
 
     {
         "schema": VERSION,
@@ -100,11 +104,12 @@ JSON output is the following hash:
         "plugins": ...,
     }
 
-The schema version indicates what the structure of crate/plugins will look
+The schema version indicates what the structure of crate/plugins will
-like. Within a schema version the structure will remain the same. The `crate`
+look like.
-field will contain all relevant documentation for the source being documented,
+Within a schema version the structure will remain the same.
-and the `plugins` field will contain the output of the plugins run over the
+The \fIcrate\fR field will contain all relevant documentation for the
-crate.
+source being documented, and the \fIplugins\fR field will contain the
+output of the plugins run over the crate.
 
 .SH "EXAMPLES"
 
@@ -112,25 +117,28 @@ To generate documentation for the source in the current directory:
     $ rustdoc hello.rs
 
 List all available passes that rustdoc has, along with default passes:
-    $ rustdoc --passes list
+    $ 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 \-w json hello.rs
     $ rustdoc doc.json
 
 The generated HTML can be viewed with any standard web browser.
 
 .SH "SEE ALSO"
 
-rustc
+.BR rustc (1)
 
 .SH "BUGS"
-See <\fBhttps://github.com/rust-lang/rust/issues\fR> for issues.
+See
+.UR https://github.com/rust\-lang/rust/issues
+.UE
+for issues.
 
 .SH "AUTHOR"
-See \fBAUTHORS.txt\fR in the Rust source distribution.
+See \fIAUTHORS.txt\fR in the Rust source distribution.
 
 .SH "COPYRIGHT"
-This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
+This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
-file in the rust source distribution.
+See \fICOPYRIGHT\fR file in the rust source distribution.