Fix formatting in release notes

[aaronpuchert]

Summary

Code needs double backticks, while single backticks produce italics.
Lists need to be fully indented and have blank lines around them.
Links are written "text <url>_".

We use links instead of :manpage:, because the latter is meant
more for man pages cross-referencing each other.

[aaronpuchert]

This is for release/15.x.

[aaronpuchert]

Use links instead :manpage:, which is meant for man pages cross-referencing each other.

[thieta]

Thanks for doing this pass! Much appreciated. As long as you tried to build the docs after you changes and it passes without any warnings or errors I am happy for you to commit this directly to release/15.x - just let me know if you do it so I can sync the repos.

[aaron.ballman]

LGTM! I did not test building the docs, but the changes all look correct based on my experience with RST.

[aaronpuchert]

The documentation build (docs-{llvm,clang}-{html,man}) is fine after this, in fact it fixes:

Warning, treated as error:
[...]/build/tools/clang/docs/ReleaseNotes.rst:632:Bullet list ends without a blank line; unexpected unindent.

by adding some indentation.

Thanks for the reviews!

[aaronpuchert]

Landed in 0c5ce1d7fba38948c27ed6b875f962cd60895574.

clang/docs/ReleaseNotes.rst

- Unevaluated lambdas in dependant contexts no longer result in clang crashing.
   and `51641 <https://github.com/llvm/llvm-project/issues/51641>`_.
 - The builtin function __builtin_dump_struct would crash clang when the target
   struct contains a bitfield. It now correctly handles bitfields.
   This fixes Issue `Issue 54462 <https://github.com/llvm/llvm-project/issues/54462>`_.
 - Statement expressions are now disabled in default arguments in general.
   This fixes Issue `Issue 53488 <https://github.com/llvm/llvm-project/issues/53488>`_.
 - According to `CWG 1394 <https://wg21.link/cwg1394>`_ and
   `C++20 [dcl.fct.def.general]p2 <https://timsong-cpp.github.io/cppwp/n4868/dcl.fct.def#general-2.sentence-3>`_,
-  Clang should not diagnose incomplete types in function definitions if the function body is "= delete;".
+  Clang should not diagnose incomplete types in function definitions if the function body is ``= delete;``.
   This fixes Issue `Issue 52802 <https://github.com/llvm/llvm-project/issues/52802>`_.
 - Unknown type attributes with a ``[[]]`` spelling are no longer diagnosed twice.
   This fixes Issue `Issue 54817 <https://github.com/llvm/llvm-project/issues/54817>`_.
 - Clang should no longer incorrectly diagnose a variable declaration inside of
   a lambda expression that shares the name of a variable in a containing
   if/while/for/switch init statement as a redeclaration.
   This fixes `Issue 54913 <https://github.com/llvm/llvm-project/issues/54913>`_.
 - Overload resolution for constrained function templates could use the partial
- Fixed a false positive diagnostic about scoped enumerations being a C++11
   extension in C mode. A scoped enumeration's enumerators cannot be named in C
   because there is no way to fully qualify the enumerator name, so this
   "extension" was unintentional and useless. This fixes
   `Issue 42372 <https://github.com/llvm/llvm-project/issues/42372>`_.
 - Clang will now find and emit a call to an allocation function in a
   promise_type body for coroutines if there is any allocation function
   declaration in the scope of promise_type. Additionally, to implement CWG2585,
   a coroutine will no longer generate a call to a global allocation function
-  with the signature (std::size_t, p0, ..., pn).
+  with the signature ``(std::size_t, p0, ..., pn)``.
   This fixes Issue `Issue 54881 <https://github.com/llvm/llvm-project/issues/54881>`_.
 - Implement `CWG 2394 <https://wg21.link/cwg2394>`_: Const class members
   may be initialized with a defaulted default constructor under the same
   conditions it would be allowed for a const object elsewhere.
 - ``__has_unique_object_representations`` no longer reports that ``_BitInt`` types
   have unique object representations if they have padding bits.
 - Unscoped and scoped enumeration types can no longer be initialized from a
   brace-init-list containing a single element of a different scoped enumeration

 - Fix that ``if consteval`` could evaluate to ``true`` at runtime because it was incorrectly
   constant folded. Fixes `Issue 55638 <https://github.com/llvm/llvm-project/issues/55638>`_.
 - Fixed incompatibility of Clang's ``<stdatomic.h>`` with MSVC ``<atomic>``.
   Fixes `MSVC STL Issue 2862 <https://github.com/microsoft/STL/issues/2862>`_.
 - Empty enums and enums with a single enumerator with value zero will be
   considered to have one positive bit in order to represent the underlying
   value. This effects whether we consider the store of the value one to be well
   defined.
-- An operator introduced to the scope via a `using` statement now correctly references this
+- An operator introduced to the scope via a ``using`` statement now correctly references this
   statement in clangd (hover over the symbol, jump to definition) as well as in the AST dump.
   This also fixes `issue 55095 <https://github.com/llvm/llvm-project/issues/#55095>`_ as a
   side-effect.
 - When including a PCH from a GCC style directory with multiple alternative PCH
   files, Clang now requires all defines set on the command line while generating
   the PCH and when including it to match. This matches GCC's behaviour.
   Previously Clang would tolerate defines to be set when creating the PCH but
   missing when used, or vice versa. This makes sure that Clang picks the
- The ``-Wdeprecated`` diagnostic will now warn on out-of-line ``constexpr``
   declarations downgraded to definitions in C++1z, in addition to the
   existing warning on out-of-line ``const`` declarations.
 - ``-Wshift-overflow`` will not warn for signed left shifts in C++20 mode
   (and newer), as it will always wrap and never overflow. This fixes
   `Issue 52873 <https://github.com/llvm/llvm-project/issues/52873>`_.
 - When using class templates without arguments, clang now tells developers
   that template arguments are missing in certain contexts.
   This fixes `Issue 55962 <https://github.com/llvm/llvm-project/issues/55962>`_.
-- Printable Unicode characters within `static_assert` messages are no longer
+- Printable Unicode characters within ``static_assert`` messages are no longer
   escaped.
 - The ``-Winfinite-recursion`` diagnostic no longer warns about
   unevaluated operands of a ``typeid`` expression, as they are now
   modeled correctly in the CFG. This fixes
   `Issue 21668 <https://github.com/llvm/llvm-project/issues/21668>`_.
 - ``-Wself-assign``, ``-Wself-assign-overloaded`` and ``-Wself-move`` will
   suggest a fix if the decl being assigned is a parameter that shadows a data
   member of the contained class.
 - Added ``-Winvalid-utf8`` which diagnoses invalid UTF-8 code unit sequences in
   comments.
 - The ``-Wint-conversion`` warning diagnostic for implicit int <-> pointer
   conversions now defaults to an error in all C language modes. It may be
   downgraded to a warning with ``-Wno-error=int-conversion``, or disabled
   entirely with ``-Wno-int-conversion``.
 
 
 Non-comprehensive list of changes in this release
 -------------------------------------------------
 
-- Improve __builtin_dump_struct:
+- Improve ``__builtin_dump_struct``:
 
   - Support bitfields in struct and union.
-  - Improve the dump format, dump both bitwidth(if its a bitfield) and field
+  - Improve the dump format, dump both bitwidth (if its a bitfield) and field
     value.
   - Remove anonymous tag locations and flatten anonymous struct members.
   - Beautify dump format, add indent for struct members.
   - Support passing additional arguments to the formatting function, allowing
     use with ``fprintf`` and similar formatting functions.
   - Support use within constant evaluation in C++, if a ``constexpr``
     formatting function is provided.
   - Support formatting of base classes in C++.
   - Support calling a formatting function template in C++, which can provide
     custom formatting for non-aggregate types.
 
 - Previously disabled sanitizer options now enabled by default:
-  - ASAN_OPTIONS=detect_stack_use_after_return=1 (only on Linux).
-  - MSAN_OPTIONS=poison_in_dtor=1.
+
+  - ``ASAN_OPTIONS=detect_stack_use_after_return=1`` (only on Linux).
+  - ``MSAN_OPTIONS=poison_in_dtor=1``.
 
 - Some type-trait builtins, such as ``__has_trivial_assign``, have been documented
   as deprecated for a while because their semantics don't mix well with post-C++11 type-traits.
   Clang now emits deprecation warnings for them under the flag ``-Wdeprecated-builtins``.
 
 New Compiler Flags
 ------------------
 - Added the ``-fno-knr-functions`` flag to allow users to opt into the C2x
- The ``format`` attribute can now be applied to non-variadic functions. The
   Using the attribute this way emits a GCC compatibility diagnostic.
 
 - Support was added for ``__attribute__((function_return("thunk-extern")))``
   to X86 to replace ``ret`` instructions with ``jmp __x86_return_thunk``. The
   corresponding attribute to disable this,
   ``__attribute__((function_return("keep")))`` was added. This is intended to
   be used by the Linux kernel to mitigate RETBLEED.
 
-- Ignore the `__preferred_name__` attribute when writing for C++20 module interfaces.
+- Ignore the ``__preferred_name__`` attribute when writing for C++20 module interfaces.
   This is a short-term workaround intentionally since clang doesn't take care of the
-  serialization and deserialization of `__preferred_name__`.  See
+  serialization and deserialization of ``__preferred_name__``.  See
   https://github.com/llvm/llvm-project/issues/56490 for example.
 
 Windows Support
 ---------------
 
 - Add support for MSVC-compatible ``/JMC``/``/JMC-`` flag in clang-cl (supports
   X86/X64/ARM/ARM64). ``/JMC`` could only be used when ``/Zi`` or ``/Z7`` is
   turned on. With this addition, clang-cl can be used in Visual Studio for the

 - Fixed mangling of nested dependent names such as ``T::a::b``, where ``T`` is a
   template parameter, to conform to the Itanium C++ ABI and be compatible with
   GCC. This breaks binary compatibility with code compiled with earlier versions
   of clang; use the ``-fclang-abi-compat=14`` option to get the old mangling.
 - Preprocessor character literals with a ``u8`` prefix are now correctly treated as
   unsigned character literals. This fixes `Issue 54886 <https://github.com/llvm/llvm-project/issues/54886>`_.
 - Stopped allowing constraints on non-template functions to be compliant with
   dcl.decl.general p4.
-- Improved ``copy elision`` optimization. It's possible to apply ``NRVO`` for an object if at the moment when
-  any return statement of this object is executed, the ``return slot`` won't be occupied by another object.
+- Improved `copy elision` optimization. It's possible to apply `NRVO` for an object if at the moment when
+  any return statement of this object is executed, the `return slot` won't be occupied by another object.
 
 
 C++20 Feature Support
 ^^^^^^^^^^^^^^^^^^^^^
 - Diagnose consteval and constexpr issues that happen at namespace scope. This
   partially addresses `Issue 51593 <https://github.com/llvm/llvm-project/issues/51593>`_.
 - No longer attempt to evaluate a consteval UDL function call at runtime when
   it is called through a template instantiation. This fixes
- Implemented `P2290R3 Delimited escape sequences <https://wg21.link/P2290R3>`_.
   This feature is available as an extension in all C and C++ language modes.
 - Implemented `P2071R2 Named universal character escapes <https://wg21.link/P2290R2>`_.
   This feature is available as an extension in all C and C++ language modes.
 - Implemented `P2327R1 De-deprecating volatile compound operations <https://wg21.link/P2327R1>`_
 
 CUDA/HIP Language Changes in Clang
 ----------------------------------
 
-- Added `__noinline__` as a keyword to avoid diagnostics due to usage of
-  `__attribute__((__noinline__))` in CUDA/HIP programs.
+- Added ``__noinline__`` as a keyword to avoid diagnostics due to usage of
+  ``__attribute__((__noinline__))`` in CUDA/HIP programs.
 
 Objective-C Language Changes in Clang
 -------------------------------------
 
 OpenCL C Language Changes in Clang
 ----------------------------------
 
 ...

 The ``_Float16`` type requires SSE2 feature and above due to the instruction
 limitations. When using it on i386 targets, you need to specify ``-msse2``
 explicitly.
 
 For targets without F16C feature or above, please make sure:
 
 - Use GCC 12.0 and above if you are using libgcc.
 - If you are using compiler-rt, use the same version with the compiler.
   Early versions provided FP16 builtins in a different ABI. A workaround is to use
   a small code snippet to check the ABI if you cannot make sure of it.
 - If you are using downstream runtimes that provide FP16 conversions, update
   them with the new ABI.
 
 DWARF Support in Clang
 ----------------------
 
 - clang now adds DWARF information for inline strings in C/C++ programs,
   allowing ``line:column`` symbolization of strings. Some debugging programs may
   require updating, as this takes advantage of DWARF ``DW_TAG_variable``
   structures *without* a ``DW_AT_name`` field, which is valid DWARF, but may be
   handled incorrectly by some software (e.g. new failures with incorrect
   assertions).
 
 Arm and AArch64 Support in Clang
 --------------------------------
 
 - clang now supports the Cortex-M85 CPU, which can be chosen with
-  `-mcpu=cortex-m85`. By default, this has PACBTI turned on, but it can be
-  disabled with `-mcpu=cortex-m85+nopacbti`.
+  ``-mcpu=cortex-m85``. By default, this has PACBTI turned on, but it can be
+  disabled with ``-mcpu=cortex-m85+nopacbti``.
 - clang now supports using C/C++ operators on sizeless SVE vectors such as
-  `svint32_t`. The set of supported operators is shown in the table Vector
+  ``svint32_t``. The set of supported operators is shown in the table Vector
   Operations found in the :ref:`Clang Language Extensions <Vector Operations>`
   document.
 
 Floating Point Support in Clang
 -------------------------------
 
 Internal API Changes
 --------------------

 
 - clang-extdef-mapping now accepts .ast files as input. This is faster than to
   recompile the files from sources when extracting method definitons. This can
   be really beneficial when creating .ast files for input to the clang-static-analyzer.
 
 libclang
 --------
 
-- Introduce new option `CLANG_FORCE_MATCHING_LIBCLANG_SOVERSION` that defaults to ON.
+- Introduce new option ``CLANG_FORCE_MATCHING_LIBCLANG_SOVERSION`` that defaults to ON.
   This means that by default libclang's SOVERSION matches the major version of LLVM.
   Setting this to OFF makes the SOVERSION be the ABI compatible version (currently 13).
-  See `discussion<https://discourse.llvm.org/t/rationale-for-removing-versioned-libclang-middle-ground-to-keep-it-behind-option/64410>`_
+  See `discussion <https://discourse.llvm.org/t/rationale-for-removing-versioned-libclang-middle-ground-to-keep-it-behind-option/64410>`_
   here.
 
 Static Analyzer
 ---------------
 - `New CTU implementation
   <https://discourse.llvm.org/t/rfc-much-faster-cross-translation-unit-ctu-analysis-implementation/61728>`_
   that keeps the slow-down around 2x compared to the single-TU analysis, even
   in case of complex C++ projects. Still, it finds the majority of the "old"
   CTU findings. Besides, not more than ~3% of the bug reports are lost compared
   to single-TU analysis, the lost reports are highly likely to be false
   positives.
 
 - Added a new checker ``alpha.unix.cstring.UninitializedRead`` this will check for uninitialized reads
-  from common memory copy/manipulation functions such as ``memcpy``, ``mempcpy``, ``memmove``, ``memcmp``, `
-  `strcmp``, ``strncmp``, ``strcpy``, ``strlen``, ``strsep`` and many more. Although
+  from common memory copy/manipulation functions such as ``memcpy``, ``mempcpy``, ``memmove``, ``memcmp``,
+  ``strcmp``, ``strncmp``, ``strcpy``, ``strlen``, ``strsep`` and many more. Although
   this checker currently is in list of alpha checkers due to a false positive.
 
 - Added a new checker ``alpha.unix.Errno``. This can find the first read
   of ``errno`` after successful standard function calls, such use of ``errno``
   could be unsafe.
 
 - Deprecate the ``-analyzer-store region`` and
   ``-analyzer-opt-analyze-nested-blocks`` analyzer flags.

 A wide variety of additional information is available on the `Clang web
 page <https://clang.llvm.org/>`_. The web page contains versions of the
 API documentation which are up-to-date with the Git version of
 the source code. You can access versions of these documents specific to
 this release by going into the "``clang/docs/``" directory in the Clang
 tree.
 
 If you have any questions or comments about Clang, please feel free to
-contact us on the Discourse forums (Clang Frontend category)
+contact us on the `Discourse forums (Clang Frontend category)
 <https://discourse.llvm.org/c/clang/6>`_.

llvm/docs/ReleaseNotes.rst

 to build LLVM. The new requirements are as follows:
 
 * GCC >= 7.1
 * Clang >= 5.0
 * Apple Clang >= 9.3
 * Visual Studio 2019 >= 16.7
 
 In LLVM 15.x these requirements will be "soft" requirements and the version
-check can be skipped by passing -DLLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN=ON
+check can be skipped by passing ``-DLLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN=ON``
 to CMake.
 
 With the release of LLVM 16.x these requirements will be hard and LLVM developers
 can start using C++17 features, making it impossible to build with older
 versions of these toolchains.
 
 Changes to the LLVM IR
 ----------------------
 
 * LLVM now uses `opaque pointers <OpaquePointers.html>`__. This means that
   different pointer types like ``i8*``, ``i32*`` or ``void()**`` are now
   represented as a single ``ptr`` type. See the linked document for migration
   instructions.
 * Renamed ``llvm.experimental.vector.extract`` intrinsic to ``llvm.vector.extract``.
 * Renamed ``llvm.experimental.vector.insert`` intrinsic to ``llvm.vector.insert``.
 * The constant expression variants of the following instructions have been
   removed:
+
   * ``extractvalue``
   * ``insertvalue``
   * ``udiv``
   * ``sdiv``
   * ``urem``
   * ``srem``
   * ``fadd``
   * ``fsub``
   * ``fmul``
   * ``fdiv``
   * ``frem``
+
 * Added the support for ``fmax`` and ``fmin`` in ``atomicrmw`` instruction. The
   comparison is expected to match the behavior of ``llvm.maxnum.*`` and
   ``llvm.minnum.*`` respectively.
 * ``callbr`` instructions no longer use ``blockaddress`` arguments for labels.
   Instead, label constraints starting with ``!`` refer directly to entries in
   the ``callbr`` indirect destination list.
 
 .. code-block:: llvm
* Removed the deprecation of ARMv8-A T32 Complex IT blocks. No deprecation
   warnings will be generated and -mrestrict-it is now always off by default.
   Previously it was on by default for Armv8 and off for all other architecture
   versions.
 * Added a pass to workaround Cortex-A57 Erratum 1742098 and Cortex-A72
   Erratum 1655431. This is enabled by default when targeting either CPU.
 * Implemented generation of Windows SEH unwind information.
 * Switched the MinGW target to use SEH instead of DWARF for unwind information.
 * Added support for the Cortex-M85 CPU.
-* Added support for a new -mframe-chain=(none|aapcs|aapcs+leaf) command-line
+* Added support for a new ``-mframe-chain=(none|aapcs|aapcs+leaf)`` command-line
   option, which controls the generation of AAPCS-compliant Frame Records.
 
 Changes to the AVR Backend
 --------------------------
 
 * ...
 
 Changes to the DirectX Backend
* Add ``LLVMGetAggregateElement`` function as a wrapper for
   representation. The ``LLVMGetElementAsConstant`` function is deprecated in
   favor of the new function, which works on all constant aggregates, rather than
   only instances of ``ConstantDataSequential``.
 
 * The following functions for creating constant expressions have been removed,
   because the underlying constant expressions are no longer supported. Instead,
   an instruction should be created using the ``LLVMBuildXYZ`` APIs, which will
   constant fold the operands if possible and create an instruction otherwise:
+
   * ``LLVMConstExtractValue``
   * ``LLVMConstInsertValue``
   * ``LLVMConstUDiv``
   * ``LLVMConstExactUDiv``
   * ``LLVMConstSDiv``
   * ``LLVMConstExactSDiv``
   * ``LLVMConstURem``
   * ``LLVMConstSRem``
   * ``LLVMConstFAdd``
   * ``LLVMConstFSub``
   * ``LLVMConstFMul``
   * ``LLVMConstFDiv``
   * ``LLVMConstFRem``
 
 * Add ``LLVMDeleteInstruction`` function which allows deleting instructions that
   are not inserted into a basic block.
 
 * As part of the opaque pointer migration, the following APIs are deprecated and
   will be removed in the next release:
+
   * ``LLVMBuildLoad`` -> ``LLVMBuildLoad2``
   * ``LLVMBuildCall`` -> ``LLVMBuildCall2``
   * ``LLVMBuildInvoke`` -> ``LLVMBuildInvoke2``
   * ``LLVMBuildGEP`` -> ``LLVMBuildGEP2``
   * ``LLVMBuildInBoundsGEP`` -> ``LLVMBuildInBoundsGEP2``
   * ``LLVMBuildStructGEP`` -> ``LLVMBuildStructGEP2``
   * ``LLVMBuildPtrDiff`` -> ``LLVMBuildPtrDiff2``
   * ``LLVMConstGEP`` -> ``LLVMConstGEP2``
   * ``LLVMConstInBoundsGEP`` -> ``LLVMConstInBoundsGEP2``
   * ``LLVMAddAlias`` -> ``LLVMAddAlias2``
 
 * Refactor compression namespaces across the project, making way for a possible
   introduction of alternatives to zlib compression in the llvm toolchain.
   Changes are as follows:
+
   * Relocate the ``llvm::zlib`` namespace to ``llvm::compression::zlib``.
   * Remove crc32 from zlib compression namespace, people should use the ``llvm::crc32`` instead.
 
 Changes to the Go bindings
 --------------------------
 
 
 Changes to the FastISel infrastructure

 Changes to the Debug Info
 ---------------------------------
 
 During this release ...
 
 Changes to the LLVM tools
 ---------------------------------
 
-* (Experimental) :manpage:`llvm-symbolizer(1)` now has ``--filter-markup`` to
+* (Experimental) :doc:`llvm-symbolizer <CommandGuide/llvm-symbolizer>` now has ``--filter-markup`` to
   filter :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` into human-readable
   form.
 * :doc:`llvm-objcopy <CommandGuide/llvm-objcopy>` has removed support for the legacy ``zlib-gnu`` format.
 * :doc:`llvm-objcopy <CommandGuide/llvm-objcopy>` now allows ``--set-section-flags src=... --rename-section src=tst``.
   ``--add-section=.foo1=... --rename-section=.foo1=.foo2`` now adds ``.foo1`` instead of ``.foo2``.
 * The LLVM gold plugin now ignores bitcode from the ``.llvmbc`` section of ELF
   files when doing LTO.  https://github.com/llvm/llvm-project/issues/47216