Documentation for opt: reformat

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168919 91177308-0d34-0410-b5e6-96231b3b80d8

docs/CommandGuide/opt.rst

@@ -1,183 +1,143 @@
 opt - LLVM optimizer
 ====================
 
-
 SYNOPSIS
 --------
 
-
-**opt** [*options*] [*filename*]
-
+:program:`opt` [*options*] [*filename*]
 
 DESCRIPTION
 -----------
 
+The :program:`opt` command is the modular LLVM optimizer and analyzer.  It
+takes LLVM source files as input, runs the specified optimizations or analyses
+on it, and then outputs the optimized file or the analysis results.  The
+function of :program:`opt` depends on whether the :option:`-analyze` option is
+given.
 
-The **opt** command is the modular LLVM optimizer and analyzer.  It takes LLVM
-source files as input, runs the specified optimizations or analyses on it, and then
-outputs the optimized file or the analysis results.  The function of
-**opt** depends on whether the **-analyze** option is given.
-
-When **-analyze** is specified, **opt** performs various analyses of the input
-source.  It will usually print the results on standard output, but in a few
-cases, it will print output to standard error or generate a file with the
-analysis output, which is usually done when the output is meant for another
+When :option:`-analyze` is specified, :program:`opt` performs various analyses
+of the input source.  It will usually print the results on standard output, but
+in a few cases, it will print output to standard error or generate a file with
+the analysis output, which is usually done when the output is meant for another
 program.
 
-While **-analyze** is *not* given, **opt** attempts to produce an optimized
-output file.  The optimizations available via **opt** depend upon what
-libraries were linked into it as well as any additional libraries that have
-been loaded with the **-load** option.  Use the **-help** option to determine
-what optimizations you can use.
-
-If *filename* is omitted from the command line or is *-*, **opt** reads its
-input from standard input. Inputs can be in either the LLVM assembly language
-format (.ll) or the LLVM bitcode format (.bc).
+While :option:`-analyze` is *not* given, :program:`opt` attempts to produce an
+optimized output file.  The optimizations available via :program:`opt` depend
+upon what libraries were linked into it as well as any additional libraries
+that have been loaded with the :option:`-load` option.  Use the :option:`-help`
+option to determine what optimizations you can use.
 
-If an output filename is not specified with the **-o** option, **opt**
-writes its output to the standard output.
+If ``filename`` is omitted from the command line or is "``-``", :program:`opt`
+reads its input from standard input.  Inputs can be in either the LLVM assembly
+language format (``.ll``) or the LLVM bitcode format (``.bc``).
 
+If an output filename is not specified with the :option:`-o` option,
+:program:`opt` writes its output to the standard output.
 
 OPTIONS
 -------
 
+.. option:: -f
 
+ Enable binary output on terminals.  Normally, :program:`opt` will refuse to
+ write raw bitcode output if the output stream is a terminal.  With this option,
+ :program:`opt` will write raw bitcode regardless of the output device.
 
-**-f**
-
- Enable binary output on terminals.  Normally, **opt** will refuse to
- write raw bitcode output if the output stream is a terminal. With this option,
- **opt** will write raw bitcode regardless of the output device.
-
-
-
-**-help**
+.. option:: -help
 
  Print a summary of command line options.
 
-
-
-**-o** *filename*
+.. option:: -o <filename>
 
  Specify the output filename.
 
-
-
-**-S**
+.. option:: -S
 
  Write output in LLVM intermediate language (instead of bitcode).
 
+.. option:: -{passname}
 
+ :program:`opt` provides the ability to run any of LLVM's optimization or
+ analysis passes in any order.  The :option:`-help` option lists all the passes
+ available.  The order in which the options occur on the command line are the
+ order in which they are executed (within pass constraints).
 
-**-{passname}**
-
- **opt** provides the ability to run any of LLVM's optimization or analysis passes
- in any order. The **-help** option lists all the passes available. The order in
- which the options occur on the command line are the order in which they are
- executed (within pass constraints).
-
-
-
-**-std-compile-opts**
+.. option:: -std-compile-opts
 
  This is short hand for a standard list of *compile time optimization* passes.
- This is typically used to optimize the output from the llvm-gcc front end. It
- might be useful for other front end compilers as well. To discover the full set
- of options available, use the following command:
-
+ This is typically used to optimize the output from the llvm-gcc front end.  It
+ might be useful for other front end compilers as well.  To discover the full
+ set of options available, use the following command:
 
  .. code-block:: sh
 
      llvm-as < /dev/null | opt -std-compile-opts -disable-output -debug-pass=Arguments
 
+.. option:: -disable-inlining
 
+ This option is only meaningful when :option:`-std-compile-opts` is given.  It
+ simply removes the inlining pass from the standard list.
 
+.. option:: -disable-opt
 
-**-disable-inlining**
-
- This option is only meaningful when **-std-compile-opts** is given. It simply
- removes the inlining pass from the standard list.
-
-
-
-**-disable-opt**
-
- This option is only meaningful when **-std-compile-opts** is given. It disables
- most, but not all, of the **-std-compile-opts**. The ones that remain are
- **-verify**, **-lower-setjmp**, and **-funcresolve**.
+ This option is only meaningful when :option:`-std-compile-opts` is given.  It
+ disables most, but not all, of the :option:`-std-compile-opts`.  The ones that
+ remain are :option:`-verify`, :option:`-lower-setjmp`, and
+ :option:`-funcresolve`.
 
-
-
-**-strip-debug**
+.. option:: -strip-debug
 
  This option causes opt to strip debug information from the module before
- applying other optimizations. It is essentially the same as **-strip** but it
- ensures that stripping of debug information is done first.
-
-
-
-**-verify-each**
-
- This option causes opt to add a verify pass after every pass otherwise specified
- on the command line (including **-verify**).  This is useful for cases where it
- is suspected that a pass is creating an invalid module but it is not clear which
- pass is doing it. The combination of **-std-compile-opts** and **-verify-each**
- can quickly track down this kind of problem.
+ applying other optimizations.  It is essentially the same as :option:`-strip`
+ but it ensures that stripping of debug information is done first.
 
+.. option:: -verify-each
 
+ This option causes opt to add a verify pass after every pass otherwise
+ specified on the command line (including :option:`-verify`).  This is useful
+ for cases where it is suspected that a pass is creating an invalid module but
+ it is not clear which pass is doing it.  The combination of
+ :option:`-std-compile-opts` and :option:`-verify-each` can quickly track down
+ this kind of problem.
 
-**-profile-info-file** *filename*
+.. option:: -profile-info-file <filename>
 
- Specify the name of the file loaded by the -profile-loader option.
+ Specify the name of the file loaded by the ``-profile-loader`` option.
 
-
-
-**-stats**
+.. option:: -stats
 
  Print statistics.
 
-
-
-**-time-passes**
+.. option:: -time-passes
 
  Record the amount of time needed for each pass and print it to standard
  error.
 
+.. option:: -debug
 
+ If this is a debug build, this option will enable debug printouts from passes
+ which use the ``DEBUG()`` macro.  See the `LLVM Programmer's Manual
+ <../ProgrammersManual.html>`_, section ``#DEBUG`` for more information.
 
-**-debug**
-
- If this is a debug build, this option will enable debug printouts
- from passes which use the *DEBUG()* macro.  See the **LLVM Programmer's
- Manual**, section *#DEBUG* for more information.
-
-
-
-**-load**\ =\ *plugin*
-
- Load the dynamic object *plugin*.  This object should register new optimization
- or analysis passes. Once loaded, the object will add new command line options to
- enable various optimizations or analyses.  To see the new complete list of
- optimizations, use the **-help** and **-load** options together. For example:
+.. option:: -load=<plugin>
 
+ Load the dynamic object ``plugin``.  This object should register new
+ optimization or analysis passes.  Once loaded, the object will add new command
+ line options to enable various optimizations or analyses.  To see the new
+ complete list of optimizations, use the :option:`-help` and :option:`-load`
+ options together.  For example:
 
  .. code-block:: sh
 
      opt -load=plugin.so -help
 
-
-
-
-**-p**
+.. option:: -p
 
  Print module after each transformation.
 
-
-
-
 EXIT STATUS
 -----------
 
-
-If **opt** succeeds, it will exit with 0.  Otherwise, if an error
+If :program:`opt` succeeds, it will exit with 0.  Otherwise, if an error
 occurs, it will exit with a non-zero value.
+