FindBISON: Improve documentation formatting

Modules/FindBISON.cmake

@@ -2,60 +2,70 @@
 # FindBISON
 # ---------
 #
-# Find bison executable and provides macros to generate custom build rules
+# Find ``bison`` executable and provide a macro to generate custom build rules.
 #
 # The module defines the following variables:
 #
-# ::
+# ``BISON_EXECUTABLE``
+#   path to the ``bison`` program
 #
-#   BISON_EXECUTABLE - path to the bison program
+# ``BISON_VERSION``
-#   BISON_VERSION - version of bison
+#   version of ``bison``
-#   BISON_FOUND - true if the program was found
 #
+# ``BISON_FOUND``
+#   true if the program was found
 #
+# The minimum required version of ``bison`` can be specified using the
+# standard CMake syntax, e.g.  ``find_package(BISON 2.1.3)``.
 #
-# The minimum required version of bison can be specified using the
+# If ``bison`` is found, the module defines the macro::
-# standard CMake syntax, e.g.  find_package(BISON 2.1.3)
 #
-# If bison is found, the module defines the macros:
+#   BISON_TARGET(<Name> <YaccInput> <CodeOutput>
+#                [COMPILE_FLAGS <flags>]
+#                [VERBOSE <file>]
+#                )
 #
-# ::
+# which will create a custom rule to generate a parser.  ``<YaccInput>`` is
-#
+# the path to a yacc file.  ``<CodeOutput>`` is the name of the source file
-#   BISON_TARGET(<Name> <YaccInput> <CodeOutput> [VERBOSE <file>]
-#               [COMPILE_FLAGS <string>])
-#
-# which will create a custom rule to generate a parser.  <YaccInput> is
-# the path to a yacc file.  <CodeOutput> is the name of the source file
 # generated by bison.  A header file is also be generated, and contains
-# the token list.  If COMPILE_FLAGS option is specified, the next
+# the token list.
-# parameter is added in the bison command line.  if VERBOSE option is
-# specified, <file> is created and contains verbose descriptions of the
-# grammar and parser.  The macro defines a set of variables:
 #
-# ::
+# The options are:
 #
-#   BISON_${Name}_DEFINED - true is the macro ran successfully
+# ``COMPILE_FLAGS <flags>``
-#   BISON_${Name}_INPUT - The input source file, an alias for <YaccInput>
+#   Specify flags to be added to the ``bison`` command line.
-#   BISON_${Name}_OUTPUT_SOURCE - The source file generated by bison
-#   BISON_${Name}_OUTPUT_HEADER - The header file generated by bison
-#   BISON_${Name}_OUTPUTS - The sources files generated by bison
-#   BISON_${Name}_COMPILE_FLAGS - Options used in the bison command line
 #
+# ``VERBOSE <file>``
+#   Tell ``bison`` to write verbose descriptions of the grammar and
+#   parser to the given ``<file>``.
 #
+# The macro defines the following variables:
 #
-# ::
+# ``BISON_<Name>_DEFINED``
+#   true is the macro ran successfully
 #
-#   ====================================================================
+# ``BISON_<Name>_INPUT``
-#   Example:
+#   The input source file, an alias for <YaccInput>
 #
+# ``BISON_<Name>_OUTPUT_SOURCE``
+#   The source file generated by bison
 #
+# ``BISON_<Name>_OUTPUT_HEADER``
+#   The header file generated by bison
 #
-# ::
+# ``BISON_<Name>_OUTPUTS``
+#   The sources files generated by bison
 #
-#    find_package(BISON)
+# ``BISON_<Name>_COMPILE_FLAGS``
-#    BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
+#   Options used in the ``bison`` command line
-#    add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
+#
-#   ====================================================================
+# Example usage:
+#
+# .. code-block:: cmake
+#
+#   find_package(BISON)
+#   BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
+#   add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
 
 #=============================================================================
 # Copyright 2009 Kitware, Inc.