[clang][docs] Use `option` directive in User's Manual

[kawashima-fj]

Summary

Sphinx has the option directive. Most option descriptions in clang/docs/UsersManual.rst used it but some didn't. This commit changes the remaining option descriptions to use the option directive. This makes a consistent view in HTML.

The option directive automatically creates a cross-reference target. So labeling by .. _opt_XXX: is almost unnecessary. However, options with and without no- (e.g. -fno-show-column/-fshow-column) cannot be distinguish for the cross-reference. So some required .. _opt_XXX: directives are kept unremoved.

[aaron.ballman]

Thank you for this cleanup! In general, I thin this looks correct. However, I know we've had to fix a bunch of options that cause the sphinx build to fail (IIRC, oftentimes due to duplicate options) and our precommit CI doesn't test the documentation build. Did you try building the docs locally to ensure there are no new warnings/errors from Sphinx?

[kawashima-fj]

In D138088#3937680, @aaron.ballman wrote:

Thank you for this cleanup! In general, I thin this looks correct. However, I know we've had to fix a bunch of options that cause the sphinx build to fail (IIRC, oftentimes due to duplicate options) and our precommit CI doesn't test the documentation build. Did you try building the docs locally to ensure there are no new warnings/errors from Sphinx?

Yes. I confirmed no new warnings/errors with the following commands. I used Sphinx packaged by distributions (Ubuntu 22.04 and Debian GNU/Linux 11). Is it sufficient? If no, let me know.

cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=clang -DLLVM_ENABLE_SPHINX=ON -DLLVM_INCLUDE_DOCS=ON [other unrelated options ...]
ninja docs-clang-html

[aaron.ballman]

In D138088#3938687, @kawashima-fj wrote:

In D138088#3937680, @aaron.ballman wrote:

Thank you for this cleanup! In general, I thin this looks correct. However, I know we've had to fix a bunch of options that cause the sphinx build to fail (IIRC, oftentimes due to duplicate options) and our precommit CI doesn't test the documentation build. Did you try building the docs locally to ensure there are no new warnings/errors from Sphinx?

Yes. I confirmed no new warnings/errors with the following commands. I used Sphinx packaged by distributions (Ubuntu 22.04 and Debian GNU/Linux 11). Is it sufficient? If no, let me know.

cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=clang -DLLVM_ENABLE_SPHINX=ON -DLLVM_INCLUDE_DOCS=ON [other unrelated options ...]
ninja docs-clang-html

Excellent, thank you! This LGTM!

clang/docs/OpenCLSupport.rst

 
 Missing features or with limited support
 ========================================
 
 - For general issues and bugs with OpenCL in clang refer to `the GitHub issue
   list
   <https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl>`__.
 
-- Command-line flag :ref:`-cl-ext <opencl_cl_ext>` (used to override extensions/
+- Command-line flag :option:`-cl-ext` (used to override extensions/
   features supported by a target) is missing support of some functionality i.e. that is
   implemented fully through libraries (see :ref:`library-based features and
   extensions <opencl_ext_libs>`).
 
 Internals Manual
 ================
 
 This section acts as internal documentation for OpenCL features design

 This will add the macro automatically and also add a field in the target
 options ``clang::TargetOptions::OpenCLFeaturesMap`` to control the exposure
 of the new extension during the compilation.
 
 Note that by default targets like `SPIR-V`, `SPIR` or `X86` expose all the OpenCL
 extensions. For all other targets the configuration has to be made explicitly.
 
 Note that the target extension support performed by clang can be overridden
-with :ref:`-cl-ext <opencl_cl_ext>` command-line flags.
+with :option:`-cl-ext` command-line flags.
 
 .. _opencl_ext_libs:
 
 **Library functionality**
 
 If an extension adds functionality that does not modify standard language
 parsing it should not require modifying anything other than header files and
 ``OpenCLBuiltins.td`` detailed in :ref:`OpenCL builtins <opencl_builtins>`.

 .. _opencl_300:
 
 OpenCL C 3.0 Usage
 ==================
 
 OpenCL C 3.0 language standard makes most OpenCL C 2.0 features optional. Optional
 functionality in OpenCL C 3.0 is indicated with the presence of feature-test macros
 (list of feature-test macros is `here <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html#features>`__).
-Command-line flag :ref:`-cl-ext <opencl_cl_ext>` can be used to override features supported by a target.
+Command-line flag :option:`-cl-ext` can be used to override features supported by a target.
 
 For cases when there is an associated extension for a specific feature (fp64 and 3d image writes)
 user should specify both (extension and feature) in command-line flag:
 
    .. code-block:: console
 
      $ clang -cl-std=CL3.0 -cl-ext=+cl_khr_fp64,+__opencl_c_fp64 ...
      $ clang -cl-std=CL3.0 -cl-ext=-cl_khr_fp64,-__opencl_c_fp64 ...

clang/docs/UsersManual.rst

 new users that first come to Clang. However, different people have
 different preferences, and sometimes Clang is driven not by a human,
 but by a program that wants consistent and easily parsable output. For
 these cases, Clang provides a wide range of options to control the exact
 output format of the diagnostics that it generates.
 
 .. _opt_fshow-column:
 
-**-f[no-]show-column**
+.. option:: -f[no-]show-column
+
    Print column number in diagnostic.
 
    This option, which defaults to on, controls whether or not Clang
    prints the column number of a diagnostic. For example, when this is
    enabled, Clang will print something like:
 
    ::
 
          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
          #endif bad
                 ^
                 //
 
    When this is disabled, Clang will print "test.c:28: warning..." with
    no column number.
 
    The printed column numbers count bytes from the beginning of the
    line; take care if your source contains multibyte characters.
 
 .. _opt_fshow-source-location:
 
-**-f[no-]show-source-location**
+.. option:: -f[no-]show-source-location
+
    Print source file/line/column information in diagnostic.
 
    This option, which defaults to on, controls whether or not Clang
    prints the filename, line number and column number of a diagnostic.
    For example, when this is enabled, Clang will print something like:
 
    ::
 
          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
          #endif bad
                 ^
                 //
 
    When this is disabled, Clang will not print the "test.c:28:8: "
    part.
 
 .. _opt_fcaret-diagnostics:
 
-**-f[no-]caret-diagnostics**
+.. option:: -f[no-]caret-diagnostics
+
    Print source line and ranges from source code in diagnostic.
    This option, which defaults to on, controls whether or not Clang
    prints the source line, source ranges, and caret when emitting a
    diagnostic. For example, when this is enabled, Clang will print
    something like:
 
    ::
 
          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
          #endif bad
                 ^
                 //
 
-**-f[no-]color-diagnostics**
+.. option:: -f[no-]color-diagnostics
+
    This option, which defaults to on when a color-capable terminal is
    detected, controls whether or not Clang prints diagnostics in color.
 
    When this option is enabled, Clang will use colors to highlight
    specific parts of the diagnostic, e.g.,
 
    .. nasty hack to not lose our dignity
 
.. option:: -f[no-]color-diagnostics
 
    ::
 
          test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
          #endif bad
                 ^
                 //
 
-**-fansi-escape-codes**
+.. option:: -fansi-escape-codes
+
    Controls whether ANSI escape codes are used instead of the Windows Console
    API to output colored diagnostics. This option is only used on Windows and
    defaults to off.
 
 .. option:: -fdiagnostics-format=clang/msvc/vi
 
    Changes diagnostic output format to better match IDEs and command line tools.
 
.. option:: -fdiagnostics-format=clang/msvc/vi
 
    **vi**
        ::
 
            t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
 
 .. _opt_fdiagnostics-show-option:
 
-**-f[no-]diagnostics-show-option**
+.. option:: -f[no-]diagnostics-show-option
+
    Enable ``[-Woption]`` information in diagnostic line.
 
    This option, which defaults to on, controls whether or not Clang
    prints the associated :ref:`warning group <cl_diag_warning_groups>`
    option name when outputting a warning diagnostic. For example, in
    this output:
 
    ::
 
          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
          #endif bad
                 ^
                 //
 
    Passing **-fno-diagnostics-show-option** will prevent Clang from
-   printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
+   printing the [:option:`-Wextra-tokens`] information in
    the diagnostic. This information tells you the flag needed to enable
    or disable the diagnostic, either from the command line or through
    :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
 
-.. _opt_fdiagnostics-show-category:
-
 .. option:: -fdiagnostics-show-category=none/id/name
 
    Enable printing category information in diagnostic line.
 
    This option, which defaults to "none", controls whether or not Clang
    prints the category associated with a diagnostic when emitting it.
    Each diagnostic may or many not have an associated category, if it
    has one, it is listed in the diagnostic categorization field of the
-  .. _opt_fsave_optimization_record_yaml:
 
       ``-fsave-optimization-record=yaml``: A structured YAML format.
 
    -  .. _opt_fsave_optimization_record_bitstream:
 
       ``-fsave-optimization-record=bitstream``: A binary format based on LLVM
       Bitstream.
 
-   The output file is controlled by :ref:`-foptimization-record-file <opt_foptimization-record-file>`.
+   The output file is controlled by :option:`-foptimization-record-file`.
 
    In the absence of an explicit output file, the file is chosen using the
    following scheme:
 
    ``<base>.opt.<format>``
 
    where ``<base>`` is based on the output file of the compilation (whether
    it's explicitly specified through `-o` or not) when used with `-c` or `-S`.
.. option:: -f[no-]save-optimization-record[=<format>]
    * ``out.dSYM/Contents/Resources/Remarks/out``
 
    Darwin-only: compiling for multiple architectures will use the following
    scheme:
 
    ``<base>-<arch>.opt.<format>``
 
    Note that this is incompatible with passing the
-   :ref:`-foptimization-record-file <opt_foptimization-record-file>` option.
+   :option:`-foptimization-record-file` option.
 
-.. _opt_foptimization-record-file:
+.. option:: -foptimization-record-file
 
-**-foptimization-record-file**
    Control the file to which optimization reports are written. This implies
    :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`.
 
     On Darwin platforms, this is incompatible with passing multiple
     ``-arch <arch>`` options.
 
-.. _opt_foptimization-record-passes:
+.. option:: -foptimization-record-passes
 
-**-foptimization-record-passes**
    Only include passes which match a specified regular expression.
 
    When optimization reports are being output (see
    :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`), this
    option controls the passes that will be included in the final report.
 
    If this option is not used, all the passes are included in the optimization
    record.
 
 .. _opt_fdiagnostics-show-hotness:
 
-**-f[no-]diagnostics-show-hotness**
+.. option:: -f[no-]diagnostics-show-hotness
+
    Enable profile hotness information in diagnostic line.
 
    This option controls whether Clang prints the profile hotness associated
    with diagnostics in the presence of profile-guided optimization information.
    This is currently supported with optimization remarks (see
    :ref:`Options to Emit Optimization Reports <rpass>`). The hotness information
    allows users to focus on the hot optimization remarks that are likely to be
    more relevant for run-time performance.
 
    For example, in this output, the block containing the callsite of `foo` was
    executed 3000 times according to the profile data:
 
    ::
 
          s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline]
            sum += foo(x, x - 2);
                   ^
 
    This option is implied when
    :ref:`-fsave-optimization-record <opt_fsave-optimization-record>` is used.
    Otherwise, it defaults to off.
 
-.. _opt_fdiagnostics-hotness-threshold:
+.. option:: -fdiagnostics-hotness-threshold
 
-**-fdiagnostics-hotness-threshold**
    Prevent optimization remarks from being output if they do not have at least
    this hotness value.
 
    This option, which defaults to zero, controls the minimum hotness an
    optimization remark would need in order to be output by Clang. This is
    currently supported with optimization remarks (see :ref:`Options to Emit
    Optimization Reports <rpass>`) when profile hotness information in
    diagnostics is enabled (see
    :ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
 
 .. _opt_fdiagnostics-fixit-info:
 
-**-f[no-]diagnostics-fixit-info**
+.. option:: -f[no-]diagnostics-fixit-info
+
    Enable "FixIt" information in the diagnostics output.
 
    This option, which defaults to on, controls whether or not Clang
    prints the information on how to fix a specific diagnostic
    underneath it when it knows. For example, in this output:
 
    ::
 
          test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
          #endif bad
                 ^
                 //
 
    Passing **-fno-diagnostics-fixit-info** will prevent Clang from
    printing the "//" line at the end of the message. This information
    is useful for users who may not understand what is wrong, but can be
    confusing for machine parsing.
 
 .. _opt_fdiagnostics-print-source-range-info:
 
-**-fdiagnostics-print-source-range-info**
+.. option:: -fdiagnostics-print-source-range-info
+
    Print machine parsable information about source ranges.
    This option makes Clang print information about source ranges in a machine
    parsable format after the file/line/column number information. The
    information is a simple sequence of brace enclosed ranges, where each range
    lists the start and end line/column locations. For example, in this output:
 
    ::
 

 
 .. _cl_diag_warning_groups:
 
 Individual Warning Groups
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 TODO: Generate this from tblgen. Define one anchor per warning group.
 
-.. _opt_wextra-tokens:
-
 .. option:: -Wextra-tokens
 
    Warn about excess tokens at the end of a preprocessor directive.
 
    This option, which defaults to on, enables warnings about extra
    tokens at the end of preprocessor directives. For example:
 
    ::
#. A categorization of the diagnostic as a note, warning, error, or
    fatal error.
 #. A text string that describes what the problem is.
 #. An option that indicates how to control the diagnostic (for
    diagnostics that support it)
    [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
    for clients that want to group diagnostics by class (for diagnostics
    that support it)
-   [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
+   [:option:`-fdiagnostics-show-category`].
 #. The line of source code that the issue occurs on, along with a caret
    and ranges that indicate the important locations
    [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
 #. "FixIt" information, which is a concise explanation of how to fix the
    problem (when Clang is certain it knows)
    [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
 #. A machine-parsable representation of the ranges involved (off by
    default)

 ^^^^^^^^^^^^^^^^^^^^^
 
 Though not shown by default, diagnostics may each be associated with a
 high-level category. This category is intended to make it possible to
 triage builds that produce a large number of errors or warnings in a
 grouped way.
 
 Categories are not shown by default, but they can be turned on with the
-:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
+:option:`-fdiagnostics-show-category` option.
 When set to "``name``", the category is printed textually in the
 diagnostic output. When it is set to "``id``", a category number is
 printed. The mapping of category names to category id's can be obtained
 by running '``clang   --print-diagnostic-categories``'.
 
 Controlling Diagnostics via Command Line Flags
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
.. option:: -fdenormal-fp-math=<value>
    Valid values are:
 
    * ``ieee`` - IEEE 754 denormal numbers
    * ``preserve-sign`` - the sign of a flushed-to-zero number is preserved in the sign of 0
    * ``positive-zero`` - denormals are flushed to positive zero
 
    Defaults to ``ieee``.
 
-.. _opt_fstrict-float-cast-overflow:
-
-**-f[no-]strict-float-cast-overflow**
+.. option:: -f[no-]strict-float-cast-overflow
 
    When a floating-point value is not representable in a destination integer
    type, the code has undefined behavior according to the language standard.
    By default, Clang will not guarantee any particular result in that case.
    With the 'no-strict' option, Clang will saturate towards the smallest and
    largest representable integer values instead. NaNs will be converted to zero.
 
-.. _opt_fmath-errno:
-
-**-f[no-]math-errno**
+.. option:: -f[no-]math-errno
 
    Require math functions to indicate errors by setting errno.
    The default varies by ToolChain.  ``-fno-math-errno`` allows optimizations
    that might cause standard C math functions to not set ``errno``.
    For example, on some systems, the math function ``sqrt`` is specified
    as setting ``errno`` to ``EDOM`` when the input is negative. On these
    systems, the compiler cannot normally optimize a call to ``sqrt`` to use
    inline code (e.g. the x86 ``sqrtsd`` instruction) without additional
    checking to ensure that ``errno`` is set appropriately.
    ``-fno-math-errno`` permits these transformations.
 
    On some targets, math library functions never set ``errno``, and so
    ``-fno-math-errno`` is the default. This includes most BSD-derived
    systems, including Darwin.
 
-.. _opt_ftrapping-math:
-
-**-f[no-]trapping-math**
+.. option:: -f[no-]trapping-math
 
    Control floating point exception behavior. ``-fno-trapping-math`` allows optimizations that assume that floating point operations cannot generate traps such as divide-by-zero, overflow and underflow.
 
 - The option ``-ftrapping-math`` behaves identically to ``-ffp-exception-behavior=strict``.
 - The option ``-fno-trapping-math`` behaves identically to ``-ffp-exception-behavior=ignore``.   This is the default.
 
 .. option:: -ffp-contract=<value>
 
.. option:: -ffp-contract=<value>
 
    Valid values are:
 
    * ``fast`` (fuse across statements disregarding pragmas, default for CUDA)
    * ``on`` (fuse in the same statement unless dictated by pragmas, default for languages other than CUDA/HIP)
    * ``off`` (never fuse)
    * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP)
 
-.. _opt_fhonor-infinities:
-
-**-f[no-]honor-infinities**
+.. option:: -f[no-]honor-infinities
 
    If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
    has the same effect as specifying ``-ffinite-math-only``.
 
-.. _opt_fhonor-nans:
-
-**-f[no-]honor-nans**
+.. option:: -f[no-]honor-nans
 
    If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
    has the same effect as specifying ``-ffinite-math-only``.
 
-.. _opt_fapprox-func:
-
-**-f[no-]approx-func**
+.. option:: -f[no-]approx-func
 
    Allow certain math function calls (such as ``log``, ``sqrt``, ``pow``, etc)
    to be replaced with an approximately equivalent set of instructions
    or alternative math function calls. For example, a ``pow(x, 0.25)``
    may be replaced with ``sqrt(sqrt(x))``, despite being an inexact result
    in cases where ``x`` is ``-0.0`` or ``-inf``.
    Defaults to ``-fno-approx-func``.
 
-.. _opt_fsigned-zeros:
-
-**-f[no-]signed-zeros**
+.. option:: -f[no-]signed-zeros
 
    Allow optimizations that ignore the sign of floating point zeros.
    Defaults to ``-fno-signed-zeros``.
 
-.. _opt_fassociative-math:
-
-**-f[no-]associative-math**
+.. option:: -f[no-]associative-math
 
   Allow floating point operations to be reassociated.
   Defaults to ``-fno-associative-math``.
 
-.. _opt_freciprocal-math:
-
-**-f[no-]reciprocal-math**
+.. option:: -f[no-]reciprocal-math
 
   Allow division operations to be transformed into multiplication by a
   reciprocal. This can be significantly faster than an ordinary division
   but can also have significantly less precision. Defaults to
   ``-fno-reciprocal-math``.
 
-.. _opt_funsafe-math-optimizations:
-
-**-f[no-]unsafe-math-optimizations**
+.. option:: -f[no-]unsafe-math-optimizations
 
    Allow unsafe floating-point optimizations. Also implies:
 
    * ``-fassociative-math``
    * ``-freciprocal-math``
    * ``-fno-signed-zeroes``
    * ``-fno-trapping-math``.
 
    Defaults to ``-fno-unsafe-math-optimizations``.
 
-.. _opt_ffinite-math-only:
-
-**-f[no-]finite-math-only**
+.. option:: -f[no-]finite-math-only
 
    Allow floating-point optimizations that assume arguments and results are
    not NaNs or +-Inf.  This defines the ``__FINITE_MATH_ONLY__`` preprocessor macro.
    Also implies:
 
    * ``-fno-honor-infinities``
    * ``-fno-honor-nans``
 
    Defaults to ``-fno-finite-math-only``.
 
-.. _opt_frounding-math:
-
-**-f[no-]rounding-math**
+.. option:: -f[no-]rounding-math
 
 Force floating-point operations to honor the dynamically-set rounding mode by default.
 
 The result of a floating-point operation often cannot be exactly represented in the result type and therefore must be rounded.  IEEE 754 describes different rounding modes that control how to perform this rounding, not all of which are supported by all implementations.  C provides interfaces (``fesetround`` and ``fesetenv``) for dynamically controlling the rounding mode, and while it also recommends certain conventions for changing the rounding mode, these conventions are not typically enforced in the ABI.  Since the rounding mode changes the numerical result of operations, the compiler must understand something about it in order to optimize floating point operations.
 
 Note that floating-point operations performed as part of constant initialization are formally performed prior to the start of the program and are therefore not subject to the current rounding mode.  This includes the initialization of global variables and local ``static`` variables.  Floating-point operations in these contexts will be rounded using ``FE_TONEAREST``.
 
 - The option ``-fno-rounding-math`` allows the compiler to assume that the rounding mode is set to ``FE_TONEAREST``.  This is the default.

 .. _controlling-code-generation:
 
 Controlling Code Generation
 ---------------------------
 
 Clang provides a number of ways to control code generation. The options
 are listed below.
 
-**-f[no-]sanitize=check1,check2,...**
+.. option:: -f[no-]sanitize=check1,check2,...
+
    Turn on runtime checks for various forms of undefined or suspicious
    behavior.
 
    This option controls whether Clang adds runtime checks for various
    forms of undefined or suspicious behavior, and is disabled by
    default. If a check fails, a diagnostic message is produced at
    runtime explaining the problem. The main checks are:
 
.. option:: -f[no-]sanitize=check1,check2,...
 
    The ``-fsanitize=`` argument must also be provided when linking, in
    order to link to the appropriate runtime library.
 
    It is not possible to combine more than one of the ``-fsanitize=address``,
    ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
    program.
 
-**-f[no-]sanitize-recover=check1,check2,...**
+.. option:: -f[no-]sanitize-recover=check1,check2,...
 
-**-f[no-]sanitize-recover[=all]**
+.. option:: -f[no-]sanitize-recover[=all]
 
    Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
    If the check is fatal, program will halt after the first error
    of this kind is detected and error report is printed.
 
    By default, non-fatal checks are those enabled by
    :doc:`UndefinedBehaviorSanitizer`,
    except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some
    sanitizers may not support recovery (or not support it by default
    e.g. :doc:`AddressSanitizer`), and always crash the program after the issue
    is detected.
 
    Note that the ``-fsanitize-trap`` flag has precedence over this flag.
    This means that if a check has been configured to trap elsewhere on the
    command line, or if the check traps by default, this flag will not have
    any effect unless that sanitizer's trapping behavior is disabled with
    ``-fno-sanitize-trap``.
 
    For example, if a command line contains the flags ``-fsanitize=undefined
    -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
    will have no effect on its own; it will need to be accompanied by
    ``-fno-sanitize-trap=alignment``.
 
-**-f[no-]sanitize-trap=check1,check2,...**
+.. option:: -f[no-]sanitize-trap=check1,check2,...
 
-**-f[no-]sanitize-trap[=all]**
+.. option:: -f[no-]sanitize-trap[=all]
 
    Controls which checks enabled by the ``-fsanitize=`` flag trap. This
    option is intended for use in cases where the sanitizer runtime cannot
    be used (for instance, when building libc or a kernel module), or where
    the binary size increase caused by the sanitizer runtime is a concern.
 
    This flag is only compatible with :doc:`control flow integrity
    <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer`
    checks other than ``vptr``.
 
    This flag is enabled by default for sanitizers in the ``cfi`` group.
 
 .. option:: -fsanitize-ignorelist=/path/to/ignorelist/file
 
    Disable or modify sanitizer checks for objects (source files, functions,
    variables, types) listed in the file. See
    :doc:`SanitizerSpecialCaseList` for file format description.
 
 .. option:: -fno-sanitize-ignorelist
 
    Don't use ignorelist file, if it was specified earlier in the command line.
 
-**-f[no-]sanitize-coverage=[type,features,...]**
+.. option:: -f[no-]sanitize-coverage=[type,features,...]
 
    Enable simple code coverage in addition to certain sanitizers.
    See :doc:`SanitizerCoverage` for more details.
 
-**-f[no-]sanitize-address-outline-instrumentation**
+.. option:: -f[no-]sanitize-address-outline-instrumentation
 
    Controls how address sanitizer code is generated. If enabled will always use
    a function call instead of inlining the code. Turning this option on could
    reduce the binary size, but might result in a worse run-time performance.
 
    See :doc: `AddressSanitizer` for more details.
 
-**-f[no-]sanitize-stats**
+.. option:: -f[no-]sanitize-stats
 
    Enable simple statistics gathering for the enabled sanitizers.
    See :doc:`SanitizerStats` for more details.
 
 .. option:: -fsanitize-undefined-trap-on-error
 
    Deprecated alias for ``-fsanitize-trap=undefined``.
 
.. option:: -mcompact-branches=[values]
    Control the usage of compact branches for MIPSR6.
 
    Valid values are: ``never``, ``optimal`` and ``always``.
    The default value is ``optimal`` which generates compact branches
    when a delay slot cannot be filled. ``never`` disables the usage of
    compact branches and ``always`` generates compact branches whenever
    possible.
 
-**-f[no-]max-type-align=[number]**
+.. option:: -f[no-]max-type-align=[number]
+
    Instruct the code generator to not enforce a higher alignment than the given
    number (of bytes) when accessing memory via an opaque pointer or reference.
    This cap is ignored when directly accessing a variable or when the pointee
    type has an explicit “aligned” attribute.
 
    The value should usually be determined by the properties of the system allocator.
    Some builtin types, especially vector types, have very high natural alignments;
    when working with values of those types, Clang usually wants to use instructions
.. option:: -faddrsig, -fno-addrsig
    Controls whether Clang emits an address-significance table into the object
    file. Address-significance tables allow linkers to implement `safe ICF
    <https://research.google.com/pubs/archive/36912.pdf>`_ without the false
    positives that can result from other implementation techniques such as
    relocation scanning. Address-significance tables are enabled by default
    on ELF targets when using the integrated assembler. This flag currently
    only has an effect on ELF targets.
 
-**-f[no]-unique-internal-linkage-names**
+.. option:: -f[no]-unique-internal-linkage-names
 
    Controls whether Clang emits a unique (best-effort) symbol name for internal
    linkage symbols.  When this option is set, compiler hashes the main source
    file path from the command line and appends it to all internal symbols. If a
    program contains multiple objects compiled with the same command-line source
    file path, the symbols are not guaranteed to be unique.  This option is
    particularly useful in attributing profile information to the correct
    function when multiple functions with the same private linkage name exist
    in the binary.
 
    It should be noted that this option cannot guarantee uniqueness and the
    following is an example where it is not unique when two modules contain
    symbols with the same private linkage name:
 
    .. code-block:: console
 
      $ cd $P/foo && clang -c -funique-internal-linkage-names name_conflict.c
      $ cd $P/bar && clang -c -funique-internal-linkage-names name_conflict.c
      $ cd $P && clang foo/name_conflict.o && bar/name_conflict.o
 
-**-fbasic-block-sections=[labels, all, list=<arg>, none]**
+.. option:: -fbasic-block-sections=[labels, all, list=<arg>, none]
 
   Controls how Clang emits text sections for basic blocks. With values ``all``
   and ``list=<arg>``, each basic block or a subset of basic blocks can be placed
   in its own unique section. With the "labels" value, normal text sections are
   emitted, but a ``.bb_addr_map`` section is emitted which includes address
   offsets for each basic block in the program, relative to the parent function
   address.
 
.. code-block:: console
      $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl
 
 
 Many flags used for the compilation for C sources can also be passed while
 compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc.
 
 Some extra options are available to support special OpenCL features.
 
-.. _opencl_cl_no_stdinc:
-
 .. option:: -cl-no-stdinc
 
 Allows to disable all extra types and functions that are not native to the compiler.
 This might reduce the compilation speed marginally but many declarations from the
 OpenCL standard will not be accessible. For example, the following will fail to
 compile.
 
    .. code-block:: console

 .. _opencl_header:
 
 OpenCL Header
 -------------
 
 By default Clang will include standard headers and therefore most of OpenCL
 builtin functions and types are available during compilation. The
 default declarations of non-native compiler types and functions can be disabled
-by using flag :ref:`-cl-no-stdinc <opencl_cl_no_stdinc>`.
+by using flag :option:`-cl-no-stdinc`.
 
 The following example demonstrates that OpenCL kernel sources with various
 standard builtin functions can be compiled without the need for an explicit
 includes or compiler flags.
 
    .. code-block:: console
 
      $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl