[llvm-commits] [llvm] r168926 - /llvm/trunk/docs/CommandGuide/FileCheck.rst

[Dmitri Gribenko]

Author: gribozavr
Date: Thu Nov 29 13:21:02 2012
New Revision: 168926

URL: http://llvm.org/viewvc/llvm-project?rev=168926&view=rev
Log:
Documentation for FileCheck: use 'option' and 'program' directives.

This enables option cross-referencing and now '--' in option names are no more turned into en dashes.

Modified:
    llvm/trunk/docs/CommandGuide/FileCheck.rst

Modified: llvm/trunk/docs/CommandGuide/FileCheck.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CommandGuide/FileCheck.rst?rev=168926&r1=168925&r2=168926&view=diff
==============================================================================
--- llvm/trunk/docs/CommandGuide/FileCheck.rst (original)
+++ llvm/trunk/docs/CommandGuide/FileCheck.rst Thu Nov 29 13:21:02 2012
@@ -4,57 +4,57 @@
 SYNOPSIS
 --------
 
-**FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
+:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
 
 DESCRIPTION
 -----------
 
-**FileCheck** reads two files (one from standard input, and one specified on the
-command line) and uses one to verify the other.  This behavior is particularly
-useful for the testsuite, which wants to verify that the output of some tool
-(e.g. llc) contains the expected information (for example, a movsd from esp or
-whatever is interesting).  This is similar to using grep, but it is optimized
-for matching multiple different inputs in one file in a specific order.
+:program:`FileCheck` reads two files (one from standard input, and one
+specified on the command line) and uses one to verify the other.  This
+behavior is particularly useful for the testsuite, which wants to verify that
+the output of some tool (e.g. :program:`llc`) contains the expected information
+(for example, a movsd from esp or whatever is interesting).  This is similar to
+using :program:`grep`, but it is optimized for matching multiple different
+inputs in one file in a specific order.
 
-The *match-filename* file specifies the file that contains the patterns to
+The ``match-filename`` file specifies the file that contains the patterns to
 match.  The file to verify is always read from standard input.
 
 OPTIONS
 -------
 
-**-help**
+.. option:: -help
 
  Print a summary of command line options.
 
-**--check-prefix** *prefix*
+.. option:: --check-prefix prefix
 
- FileCheck searches the contents of *match-filename* for patterns to match.  By
- default, these patterns are prefixed with "``CHECK:``".  If you'd like to use a
- different prefix (e.g. because the same input file is checking multiple
- different tool or options), the **--check-prefix** argument allows you to specify
- a specific prefix to match.
+ FileCheck searches the contents of ``match-filename`` for patterns to match.
+ By default, these patterns are prefixed with "``CHECK:``".  If you'd like to
+ use a different prefix (e.g. because the same input file is checking multiple
+ different tool or options), the :option:`--check-prefix` argument allows you
+ to specify a specific prefix to match.
 
-**--input-file** *filename*
+.. option:: --input-file filename
 
   File to check (defaults to stdin).
 
-**--strict-whitespace**
+.. option:: --strict-whitespace
 
  By default, FileCheck canonicalizes input horizontal whitespace (spaces and
  tabs) which causes it to ignore these differences (a space will match a tab).
- The **--strict-whitespace** argument disables this behavior.
+ The :option:`--strict-whitespace` argument disables this behavior.
 
-
-**-version**
+.. option:: -version
 
  Show the version number of this program.
 
 EXIT STATUS
 -----------
 
-If **FileCheck** verifies that the file matches the expected contents, it exits
-with 0.  Otherwise, if not, or if an error occurs, it will exit with a non-zero
-value.
+If :program:`FileCheck` verifies that the file matches the expected contents,
+it exits with 0.  Otherwise, if not, or if an error occurs, it will exit with a
+non-zero value.
 
 TUTORIAL
 --------
@@ -67,7 +67,6 @@
 
    ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
 
-
 This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe
 that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``.  This
 means that FileCheck will be verifying its standard input (the llc output)
@@ -93,7 +92,6 @@
            ret void
    }
 
-
 Here you can see some "``CHECK:``" lines specified in comments.  Now you can
 see how the file is piped into ``llvm-as``, then ``llc``, and the machine code
 output is what we are verifying.  FileCheck checks the machine code output to
@@ -114,9 +112,10 @@
 The FileCheck -check-prefix option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The FileCheck ``-check-prefix`` option allows multiple test configurations to be
-driven from one .ll file.  This is useful in many circumstances, for example,
-testing different architectural variants with llc.  Here's a simple example:
+The FileCheck :option:`-check-prefix` option allows multiple test
+configurations to be driven from one `.ll` file.  This is useful in many
+circumstances, for example, testing different architectural variants with
+:program:`llc`.  Here's a simple example:
 
 .. code-block:: llvm
 
@@ -194,7 +193,6 @@
    ; CHECK: ret i8
    }
 
-
 FileCheck Pattern Matching Syntax
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -252,16 +250,14 @@
 matches, this allows you to define two separate "``CHECK``" lines that match on
 the same line.
 
-
 FileCheck Expressions
 ~~~~~~~~~~~~~~~~~~~~~
 
-
-Sometimes there's a need to verify output which refers line numbers of the match
-file, e.g. when testing compiler diagnostics. This introduces a certain
-fragility of the match file structure, as CHECK: lines contain absolute line
-numbers in the same file, which have to be updated whenever line numbers change
-due to text addition or deletion.
+Sometimes there's a need to verify output which refers line numbers of the
+match file, e.g. when testing compiler diagnostics.  This introduces a certain
+fragility of the match file structure, as "``CHECK:``" lines contain absolute
+line numbers in the same file, which have to be updated whenever line numbers
+change due to text addition or deletion.
 
 To support this case, FileCheck allows using ``[[@LINE]]``,
 ``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These