From c10a5d752e4704f0a4cf65397a5915b05cf590d3 Mon Sep 17 00:00:00 2001
From: James Henderson <jh7370@my.bristol.ac.uk>
Date: Thu, 27 Jun 2019 13:24:46 +0000
Subject: [PATCH] [docs][tools] Add missing "program" tags to rst files
Sphinx allows for definitions of command-line options using
`.. option <name>` and references to those options via `:option:<name>`.
However, it looks like there is no scoping of these options by default,
meaning that links can end up pointing to incorrect documents. See for
example the llvm-mca document, which contains references to -o that,
prior to this patch, pointed to a different document. What's worse is
that these links appear to be non-deterministic in which one is picked
(on my machine, some references end up pointing to opt, whereas on the
live docs, they point to llvm-dwarfdump, for example).
The fix is to add the .. program <name> tag. This essentially namespaces
the options (definitions and references) to the named program, ensuring
that the links are kept correct.
Reviwed by: andreadb
Differential Revision: https://reviews.llvm.org/D63873
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@364538 91177308-0d34-0410-b5e6-96231b3b80d8
---
docs/CommandGuide/FileCheck.rst | 2 ++
docs/CommandGuide/bugpoint.rst | 2 ++
docs/CommandGuide/dsymutil.rst | 2 ++
docs/CommandGuide/lit.rst | 2 ++
docs/CommandGuide/llc.rst | 7 +++++++
docs/CommandGuide/lli.rst | 2 ++
docs/CommandGuide/llvm-ar.rst | 1 +
docs/CommandGuide/llvm-as.rst | 2 ++
docs/CommandGuide/llvm-bcanalyzer.rst | 2 ++
docs/CommandGuide/llvm-build.rst | 1 +
docs/CommandGuide/llvm-config.rst | 1 +
docs/CommandGuide/llvm-cov.rst | 2 ++
docs/CommandGuide/llvm-cxxfilt.rst | 2 ++
docs/CommandGuide/llvm-cxxmap.rst | 2 ++
docs/CommandGuide/llvm-diff.rst | 1 +
docs/CommandGuide/llvm-dis.rst | 1 +
docs/CommandGuide/llvm-dwarfdump.rst | 2 ++
docs/CommandGuide/llvm-exegesis.rst | 2 ++
docs/CommandGuide/llvm-extract.rst | 2 ++
docs/CommandGuide/llvm-lib.rst | 1 +
docs/CommandGuide/llvm-link.rst | 2 ++
docs/CommandGuide/llvm-lipo.rst | 2 ++
docs/CommandGuide/llvm-mca.rst | 7 +++++++
docs/CommandGuide/llvm-nm.rst | 2 ++
docs/CommandGuide/llvm-objdump.rst | 2 ++
docs/CommandGuide/llvm-pdbutil.rst | 2 ++
docs/CommandGuide/llvm-profdata.rst | 2 ++
docs/CommandGuide/llvm-readobj.rst | 2 ++
docs/CommandGuide/llvm-stress.rst | 2 ++
docs/CommandGuide/llvm-symbolizer.rst | 2 ++
docs/CommandGuide/opt.rst | 2 ++
docs/CommandGuide/tblgen.rst | 2 ++
docs/WritingAnLLVMPass.rst | 4 +++-
33 files changed, 71 insertions(+), 1 deletion(-)
diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst
index 36f517ef62a..a424606d4ce 100644
--- a/docs/CommandGuide/FileCheck.rst
+++ b/docs/CommandGuide/FileCheck.rst
@@ -1,6 +1,8 @@
FileCheck - Flexible pattern matching file verifier
===================================================
+.. program:: FileCheck
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/bugpoint.rst b/docs/CommandGuide/bugpoint.rst
index 8c2a0d12498..4a8ce933e1a 100644
--- a/docs/CommandGuide/bugpoint.rst
+++ b/docs/CommandGuide/bugpoint.rst
@@ -1,6 +1,8 @@
bugpoint - automatic test case reduction tool
=============================================
+.. program:: bugpoint
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/dsymutil.rst b/docs/CommandGuide/dsymutil.rst
index ceaa54019a8..79925a73a8c 100644
--- a/docs/CommandGuide/dsymutil.rst
+++ b/docs/CommandGuide/dsymutil.rst
@@ -1,6 +1,8 @@
dsymutil - manipulate archived DWARF debug symbol files
=======================================================
+.. program:: dsymutil
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/lit.rst b/docs/CommandGuide/lit.rst
index e0d09ae977d..bcaa5c66c8c 100644
--- a/docs/CommandGuide/lit.rst
+++ b/docs/CommandGuide/lit.rst
@@ -1,6 +1,8 @@
lit - LLVM Integrated Tester
============================
+.. program:: lit
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llc.rst b/docs/CommandGuide/llc.rst
index aaf7e2e6b77..bf62957b5c9 100644
--- a/docs/CommandGuide/llc.rst
+++ b/docs/CommandGuide/llc.rst
@@ -1,6 +1,8 @@
llc - LLVM static compiler
==========================
+.. program:: llc
+
SYNOPSIS
--------
@@ -41,6 +43,11 @@ End-user Options
Print a summary of command line options.
+.. option:: -o <filename>
+
+ Use ``<filename>`` as the output filename. See the summary above for more
+ details.
+
.. option:: -O=uint
Generate code at different optimization levels. These correspond to the
diff --git a/docs/CommandGuide/lli.rst b/docs/CommandGuide/lli.rst
index 1132ac3e6be..6d8cb4b36b5 100644
--- a/docs/CommandGuide/lli.rst
+++ b/docs/CommandGuide/lli.rst
@@ -1,6 +1,8 @@
lli - directly execute programs from LLVM bitcode
=================================================
+.. program:: lli
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-ar.rst b/docs/CommandGuide/llvm-ar.rst
index d10ec919795..2d82abcc370 100644
--- a/docs/CommandGuide/llvm-ar.rst
+++ b/docs/CommandGuide/llvm-ar.rst
@@ -1,6 +1,7 @@
llvm-ar - LLVM archiver
=======================
+.. program:: llvm-ar
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-as.rst b/docs/CommandGuide/llvm-as.rst
index 1b499bbe970..77b1568a9e4 100644
--- a/docs/CommandGuide/llvm-as.rst
+++ b/docs/CommandGuide/llvm-as.rst
@@ -1,6 +1,8 @@
llvm-as - LLVM assembler
========================
+.. program:: llvm-as
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-bcanalyzer.rst b/docs/CommandGuide/llvm-bcanalyzer.rst
index 7254088ec94..369ea5eb7d9 100644
--- a/docs/CommandGuide/llvm-bcanalyzer.rst
+++ b/docs/CommandGuide/llvm-bcanalyzer.rst
@@ -1,6 +1,8 @@
llvm-bcanalyzer - LLVM bitcode analyzer
=======================================
+.. program:: llvm-bcanalyzer
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-build.rst b/docs/CommandGuide/llvm-build.rst
index f788f7c5a83..d0331cad21a 100644
--- a/docs/CommandGuide/llvm-build.rst
+++ b/docs/CommandGuide/llvm-build.rst
@@ -1,6 +1,7 @@
llvm-build - LLVM Project Build Utility
=======================================
+.. program:: llvm-build
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-config.rst b/docs/CommandGuide/llvm-config.rst
index 34075d0b308..caee955c5fe 100644
--- a/docs/CommandGuide/llvm-config.rst
+++ b/docs/CommandGuide/llvm-config.rst
@@ -1,6 +1,7 @@
llvm-config - Print LLVM compilation options
============================================
+.. program:: llvm-config
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-cov.rst b/docs/CommandGuide/llvm-cov.rst
index 7d696c9e353..d4649762168 100644
--- a/docs/CommandGuide/llvm-cov.rst
+++ b/docs/CommandGuide/llvm-cov.rst
@@ -1,6 +1,8 @@
llvm-cov - emit coverage information
====================================
+.. program:: llvm-cov
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-cxxfilt.rst b/docs/CommandGuide/llvm-cxxfilt.rst
index aad1ccda9d6..1b6f9c665e2 100644
--- a/docs/CommandGuide/llvm-cxxfilt.rst
+++ b/docs/CommandGuide/llvm-cxxfilt.rst
@@ -1,6 +1,8 @@
llvm-cxxfilt - LLVM symbol name demangler
=========================================
+.. program:: llvm-cxxfilt
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-cxxmap.rst b/docs/CommandGuide/llvm-cxxmap.rst
index 7293f60b55d..b0bf1c49fc2 100644
--- a/docs/CommandGuide/llvm-cxxmap.rst
+++ b/docs/CommandGuide/llvm-cxxmap.rst
@@ -1,6 +1,8 @@
llvm-cxxmap - Mangled name remapping tool
=========================================
+.. program:: llvm-cxxmap
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-diff.rst b/docs/CommandGuide/llvm-diff.rst
index 991d4fece04..b858b981ed2 100644
--- a/docs/CommandGuide/llvm-diff.rst
+++ b/docs/CommandGuide/llvm-diff.rst
@@ -1,6 +1,7 @@
llvm-diff - LLVM structural 'diff'
==================================
+.. program:: llvm-diff
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-dis.rst b/docs/CommandGuide/llvm-dis.rst
index 85cdca85ecd..aaba1280b8a 100644
--- a/docs/CommandGuide/llvm-dis.rst
+++ b/docs/CommandGuide/llvm-dis.rst
@@ -1,6 +1,7 @@
llvm-dis - LLVM disassembler
============================
+.. program:: llvm-dis
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-dwarfdump.rst b/docs/CommandGuide/llvm-dwarfdump.rst
index b8ebc8aad89..e2cec42cea3 100644
--- a/docs/CommandGuide/llvm-dwarfdump.rst
+++ b/docs/CommandGuide/llvm-dwarfdump.rst
@@ -1,6 +1,8 @@
llvm-dwarfdump - dump and verify DWARF debug information
========================================================
+.. program:: llvm-dwarfdump
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-exegesis.rst b/docs/CommandGuide/llvm-exegesis.rst
index cbb900914cf..8f9ec1eed52 100644
--- a/docs/CommandGuide/llvm-exegesis.rst
+++ b/docs/CommandGuide/llvm-exegesis.rst
@@ -1,6 +1,8 @@
llvm-exegesis - LLVM Machine Instruction Benchmark
==================================================
+.. program:: llvm-exegesis
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-extract.rst b/docs/CommandGuide/llvm-extract.rst
index d0e9c1c255a..345496b9456 100644
--- a/docs/CommandGuide/llvm-extract.rst
+++ b/docs/CommandGuide/llvm-extract.rst
@@ -1,6 +1,8 @@
llvm-extract - extract a function from an LLVM module
=====================================================
+.. program:: llvm-extract
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-lib.rst b/docs/CommandGuide/llvm-lib.rst
index ecd0a7db7e3..87687be785f 100644
--- a/docs/CommandGuide/llvm-lib.rst
+++ b/docs/CommandGuide/llvm-lib.rst
@@ -1,6 +1,7 @@
llvm-lib - LLVM lib.exe compatible library tool
===============================================
+.. program:: llvm-lib
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-link.rst b/docs/CommandGuide/llvm-link.rst
index 3bcfa68c259..761997928c2 100644
--- a/docs/CommandGuide/llvm-link.rst
+++ b/docs/CommandGuide/llvm-link.rst
@@ -1,6 +1,8 @@
llvm-link - LLVM bitcode linker
===============================
+.. program:: llvm-link
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-lipo.rst b/docs/CommandGuide/llvm-lipo.rst
index ebc540a2ae8..13f56347836 100644
--- a/docs/CommandGuide/llvm-lipo.rst
+++ b/docs/CommandGuide/llvm-lipo.rst
@@ -1,6 +1,8 @@
llvm-lipo - LLVM tool for manipulating universal binaries
=========================================================
+.. program:: llvm-lipo
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-mca.rst b/docs/CommandGuide/llvm-mca.rst
index 847a043fe7a..a02103337dc 100644
--- a/docs/CommandGuide/llvm-mca.rst
+++ b/docs/CommandGuide/llvm-mca.rst
@@ -1,6 +1,8 @@
llvm-mca - LLVM Machine Code Analyzer
=====================================
+.. program:: llvm-mca
+
SYNOPSIS
--------
@@ -64,6 +66,11 @@ option specifies "``-``", then the output will also be sent to standard output.
Print a summary of command line options.
+.. option:: -o <filename>
+
+ Use ``<filename>`` as the output filename. See the summary above for more
+ details.
+
.. option:: -mtriple=<target triple>
Specify a target triple string.
diff --git a/docs/CommandGuide/llvm-nm.rst b/docs/CommandGuide/llvm-nm.rst
index 85e66d75e81..6268b15d082 100644
--- a/docs/CommandGuide/llvm-nm.rst
+++ b/docs/CommandGuide/llvm-nm.rst
@@ -1,6 +1,8 @@
llvm-nm - list LLVM bitcode and object file's symbol table
==========================================================
+.. program:: llvm-nm
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-objdump.rst b/docs/CommandGuide/llvm-objdump.rst
index 3a4549e6160..be4d07c94d0 100644
--- a/docs/CommandGuide/llvm-objdump.rst
+++ b/docs/CommandGuide/llvm-objdump.rst
@@ -1,6 +1,8 @@
llvm-objdump - LLVM's object file dumper
========================================
+.. program:: llvm-objdump
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-pdbutil.rst b/docs/CommandGuide/llvm-pdbutil.rst
index 29d487e0e74..95535318711 100644
--- a/docs/CommandGuide/llvm-pdbutil.rst
+++ b/docs/CommandGuide/llvm-pdbutil.rst
@@ -1,6 +1,8 @@
llvm-pdbutil - PDB File forensics and diagnostics
=================================================
+.. program:: llvm-pdbutil
+
.. contents::
:local:
diff --git a/docs/CommandGuide/llvm-profdata.rst b/docs/CommandGuide/llvm-profdata.rst
index 7f5887ae9d3..bc0a0066aac 100644
--- a/docs/CommandGuide/llvm-profdata.rst
+++ b/docs/CommandGuide/llvm-profdata.rst
@@ -1,6 +1,8 @@
llvm-profdata - Profile data tool
=================================
+.. program:: llvm-profdata
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-readobj.rst b/docs/CommandGuide/llvm-readobj.rst
index d533ae57e53..7c3b946508e 100644
--- a/docs/CommandGuide/llvm-readobj.rst
+++ b/docs/CommandGuide/llvm-readobj.rst
@@ -1,6 +1,8 @@
llvm-readobj - LLVM Object Reader
=================================
+.. program:: llvm-readobj
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-stress.rst b/docs/CommandGuide/llvm-stress.rst
index fb006f562b1..7f23681d644 100644
--- a/docs/CommandGuide/llvm-stress.rst
+++ b/docs/CommandGuide/llvm-stress.rst
@@ -1,6 +1,8 @@
llvm-stress - generate random .ll files
=======================================
+.. program:: llvm-stress
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/llvm-symbolizer.rst b/docs/CommandGuide/llvm-symbolizer.rst
index 98f25540eeb..7f3a8a4e27e 100644
--- a/docs/CommandGuide/llvm-symbolizer.rst
+++ b/docs/CommandGuide/llvm-symbolizer.rst
@@ -1,6 +1,8 @@
llvm-symbolizer - convert addresses into source code locations
==============================================================
+.. program:: llvm-symbolizer
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/opt.rst b/docs/CommandGuide/opt.rst
index 2b2fffa063a..10eff31d4c1 100644
--- a/docs/CommandGuide/opt.rst
+++ b/docs/CommandGuide/opt.rst
@@ -1,6 +1,8 @@
opt - LLVM optimizer
====================
+.. program:: opt
+
SYNOPSIS
--------
diff --git a/docs/CommandGuide/tblgen.rst b/docs/CommandGuide/tblgen.rst
index 3105e0c8076..372d1b2a730 100644
--- a/docs/CommandGuide/tblgen.rst
+++ b/docs/CommandGuide/tblgen.rst
@@ -1,6 +1,8 @@
tblgen - Target Description To C++ Code Generator
=================================================
+.. program:: tblgen
+
SYNOPSIS
--------
diff --git a/docs/WritingAnLLVMPass.rst b/docs/WritingAnLLVMPass.rst
index 9e857fb9657..7e2cabb9e8f 100644
--- a/docs/WritingAnLLVMPass.rst
+++ b/docs/WritingAnLLVMPass.rst
@@ -2,6 +2,8 @@
Writing an LLVM Pass
====================
+.. program:: opt
+
.. contents::
:local:
@@ -264,7 +266,7 @@ documentation to users of :program:`opt`. Now that you have a working pass,
you would go ahead and make it do the cool transformations you want. Once you
get it all working and tested, it may become useful to find out how fast your
pass is. The :ref:`PassManager <writing-an-llvm-pass-passmanager>` provides a
-nice command line option (:option:`--time-passes`) that allows you to get
+nice command line option (:option:`-time-passes`) that allows you to get
information about the execution time of your pass along with the other passes
you queue up. For example:
--
2.40.0