FindBISON: Update documentation

- Updated and synced module documentation with other similar find
  modules.
- Documented bison_target() command indented relative to the title.
- Command arguments described as a list separately.
- Used "command" instead of "macro".
- Used lowercase style across the docs.
- Extended examples section.

Help/policy/CMP0088.rst

@@ -6,8 +6,8 @@ CMP0088
 :module:`FindBISON` runs bison in :variable:`CMAKE_CURRENT_BINARY_DIR`
 when executing.
 
-The module provides a ``BISON_TARGET`` macro which generates BISON output.
-In CMake 3.13 and below the macro would generate a custom command that runs
+The module provides a ``bison_target()`` command which generates BISON output.
+In CMake 3.13 and below the command would generate a custom build rule that runs
 ``bison`` in the source directory.  CMake 3.14 and later prefer to run it
 in the build directory and use :variable:`CMAKE_CURRENT_BINARY_DIR` as the
 ``WORKING_DIRECTORY`` of its :command:`add_custom_command` invocation.
@@ -17,7 +17,7 @@ tree rather than the source.
 This policy provides compatibility for projects that have not been updated
 to expect the new behavior.
 
-The ``OLD`` behavior for this policy is for ``BISON_TARGET`` to use
+The ``OLD`` behavior for this policy is for ``bison_target()`` to use
 the current source directory for the ``WORKING_DIRECTORY`` and where
 to generate implicit files. The ``NEW`` behavior of this policy is to
 use the current binary directory for the ``WORKING_DIRECTORY`` and where

Help/release/3.14.rst

@@ -193,7 +193,7 @@ Modules
   each one to the main build using the canonical pattern.  This
   significantly reduces the amount of boilerplate needed in a project.
 
-* The :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison``
+* The :module:`FindBISON` module's ``bison_target()`` command now runs ``bison``
   with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
   See policy :policy:`CMP0088`.
 

Help/release/3.4.rst

@@ -117,7 +117,7 @@ Modules
   useful with the :generator:`Ninja` generator to monitor CMake
   superbuild progress and prevent CPU oversubscription.
 
-* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a
+* The :module:`FindBISON` module ``bison_target()`` command learned a
   new ``DEFINES_FILE`` option to specify a custom output header
   to be generated.
 

Help/release/3.6.rst

@@ -283,7 +283,7 @@ Other Changes
   files in different directories use ``#include <moc_foo.cpp>`` with the
   same name (because the generated ``moc_foo.cpp`` files would collide).
 
-* The :module:`FindBISON` module ``BISON_TARGET`` macro now supports
+* The :module:`FindBISON` module ``bison_target()`` command now supports
   special characters by passing the ``VERBATIM`` option to internal
   :command:`add_custom_command` calls.  This may break clients that
   added escaping manually to work around the bug.

Help/release/3.7.rst

@@ -168,7 +168,7 @@ Modules
 * The :module:`ExternalProject` module gained a ``HTTP_HEADER``
   option to add http download headers.
 
-* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new
+* The :module:`FindBISON` module ``bison_target()`` command learned a new
   ``REPORT_FILE`` option to specify the bison ``--report-file=`` option.
 
 * The :module:`FindBZip2` module now provides imported targets.

Modules/FindBISON.cmake

@@ -5,120 +5,198 @@
 FindBISON
 ---------
 
-Find ``bison`` executable and provide a macro to generate custom build rules.
+Finds the Bison command-line parser generator and provides a CMake command to
+generate custom build rules for using Bison:
 
-The module defines the following variables:
+.. code-block:: cmake
 
-``BISON_FOUND``
-  True if the program was found.
+  find_package(BISON [<version>] ...)
 
-``BISON_EXECUTABLE``
-  The path to the ``bison`` program.
+Bison is a parser generator that replaced earlier Yacc (Yet Another
+Compiler-Compiler).  On Unix-like systems, most common implementation is
+GNU Bison.  On Windows, this module looks for Windows-compatible Bison, if
+installed.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``BISON_FOUND``
+  Boolean indicating whether (the requested version of) Bison is found.
 
 ``BISON_VERSION``
-  The version of ``bison``.
+  The version of Bison found.
+
+Cache Variables
+^^^^^^^^^^^^^^^
 
-The minimum required version of ``bison`` can be specified using the
-standard CMake syntax, e.g. :command:`find_package(BISON 2.1.3)`.
+The following cache variables may also be set:
 
-If ``bison`` is found, the module defines the macro:
+``BISON_EXECUTABLE``
+  The path to the ``bison`` command-line program.
+
+Commands
+^^^^^^^^
+
+This module provides the following command if ``bison`` is found:
 
 .. command:: bison_target
 
+  Creates a custom build rule to generate a parser file from a Yacc file using
+  Bison:
+
   .. code-block:: cmake
 
-    bison_target(<Name> <YaccInput> <CodeOutput>
-                 [OPTIONS <options>...]
-                 [COMPILE_FLAGS <string>]
-                 [DEFINES_FILE <file>]
-                 [VERBOSE [<file>]]
-                 [REPORT_FILE <file>]
-                 )
+    bison_target(
+      <name>
+      <input-yacc-file>
+      <output-parser-file>
+      [DEFINES_FILE <header>]
+      [VERBOSE [<file>]]       # The [<file>] argument is deprecated
+      [REPORT_FILE <file>]
+      [OPTIONS <options>...]
+      [COMPILE_FLAGS <string>] # Deprecated
+    )
+
+  .. versionchanged:: 3.14
+    When policy :policy:`CMP0088` is set to ``NEW``, ``bison`` runs in the
+    :variable:`CMAKE_CURRENT_BINARY_DIR` directory.
+
+  ``<name>``
+    String used as an identifier for this command invocation.
 
-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 can also be generated, and contains
-the token list.
+  ``<input-yacc-file>``
+    The path to an input Yacc source file (``.y``).  If given as a relative
+    path, it will be interpreted relative to the current source directory
+    (:variable:`CMAKE_CURRENT_SOURCE_DIR`).
 
-.. versionchanged:: 3.14
-  When :policy:`CMP0088` is set to ``NEW``, ``bison`` runs in the
-  :variable:`CMAKE_CURRENT_BINARY_DIR` directory.
+  ``<output-parser-file>``
+    The path of the output parser file to be generated by Bison.  If given as a
+    relative path, it will be interpreted relative to the current Bison working
+    directory.
 
-The options are:
+  ``DEFINES_FILE <header>``
+    .. versionadded:: 3.4
 
-``OPTIONS <options>...``
-  .. versionadded:: 4.0
+    By default, Bison can generate a header file containing the list of tokens.
+    This option allows specifying a custom ``<header>`` file to be generated by
+    Bison.  If given as a relative path, it will be interpreted relative to the
+    current Bison working directory.
 
-  A :ref:`semicolon-separated list <CMake Language Lists>` of options added to
-  the ``bison`` command line.
+  ``VERBOSE [<file>]``
+    Enables generation of a verbose grammar and parser report.  By default, the
+    report file is created in the current Bison working directory and named
+    ``<output-parser-filename>.output``.
 
-``COMPILE_FLAGS <string>``
-  .. deprecated:: 4.0
+    ``<file>``
+      .. deprecated:: 3.7
+        Use ``VERBOSE REPORT_FILE <file>``.
 
-  Space-separated bison options added to the ``bison`` command line.
-  A :ref:`;-list <CMake Language Lists>` will not work.
-  This option is deprecated in favor of ``OPTIONS <options>...``.
+      Specifies the path to which the report file should be copied.  This
+      argument is retained for backward compatibility and only works when the
+      ``<output-parser-file>`` is specified as an absolute path.
 
-``DEFINES_FILE <file>``
-  .. versionadded:: 3.4
+  ``REPORT_FILE <file>``
+    .. versionadded:: 3.7
 
-  Specify a non-default header ``<file>`` to be generated by ``bison``.
+    Used in combination with ``VERBOSE`` to specify a custom path for the report
+    output ``<file>``, overriding the default location.  If given as a relative
+    path, it will be interpreted relative to the current Bison working
+    directory.
 
-``VERBOSE [<file>]``
-  Tell ``bison`` to write a report file of the grammar and parser.
+  ``OPTIONS <options>...``
+    .. versionadded:: 4.0
 
-  .. deprecated:: 3.7
-    If ``<file>`` is given, it specifies path the report file is copied to.
-    ``[<file>]`` is left for backward compatibility of this module.
-    Use ``VERBOSE REPORT_FILE <file>``.
+    A :ref:`semicolon-separated list <CMake Language Lists>` of extra options
+    added to the ``bison`` command line.
 
-``REPORT_FILE <file>``
-  .. versionadded:: 3.7
+  ``COMPILE_FLAGS <string>``
+    .. deprecated:: 4.0
+      Superseded by ``OPTIONS <options>...``.
 
-  Specify a non-default report ``<file>``, if generated.
+    A string of space-separated extra options added to the ``bison`` command
+    line.  A :ref:`semicolon-separated list <CMake Language Lists>` will not
+    work.
 
-The macro defines the following variables:
+  ---------------------------------------------------------------------
 
-``BISON_<Name>_DEFINED``
-  True if the macro ran successfully.
+  This command also defines the following variables:
 
-``BISON_<Name>_INPUT``
-  The input source file, an alias for ``<YaccInput>``.
+  ``BISON_<name>_DEFINED``
+    Boolean indicating whether this command was successfully invoked.
 
-``BISON_<Name>_OUTPUT_SOURCE``
-  The source file generated by ``bison``.
+  ``BISON_<name>_INPUT``
+    The input source file, an alias for ``<input-yacc-file>``.
 
-``BISON_<Name>_OUTPUT_HEADER``
-  The header file generated by ``bison``.
+  ``BISON_<name>_OUTPUT_SOURCE``
+    The output parser file generated by ``bison``.
 
-``BISON_<Name>_OUTPUTS``
-  All files generated by ``bison`` including the source, the header and the
-  report.
+  ``BISON_<name>_OUTPUT_HEADER``
+    The header file generated by ``bison``, if any.
 
-``BISON_<Name>_OPTIONS``
-  .. versionadded:: 4.0
+  ``BISON_<name>_OUTPUTS``
+    A list of files generated by ``bison``, including the output parser file,
+    header file, and report file.
 
-  Options used in the ``bison`` command line.
+  ``BISON_<name>_OPTIONS``
+    .. versionadded:: 4.0
 
-``BISON_<Name>_COMPILE_FLAGS``
-  .. deprecated:: 4.0
+    A list of command-line options used for the ``bison`` command.
 
-  Options used in the ``bison`` command line. This variable is deprecated in
-  favor of ``BISON_<Name>_OPTIONS`` variable.
+  ``BISON_<name>_COMPILE_FLAGS``
+    .. deprecated:: 4.0
+      Superseded by ``BISON_<name>_OPTIONS`` variable with the same value.
+
+    A list of command-line options used for the ``bison`` command.
 
 Examples
 ^^^^^^^^
 
+Examples: Finding Bison
+"""""""""""""""""""""""
+
+Finding Bison:
+
 .. code-block:: cmake
 
   find_package(BISON)
-  bison_target(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
-               DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
+
+Finding Bison with a minimum required version:
+
+.. code-block:: cmake
+
+  find_package(BISON 2.1.3)
+
+Finding Bison and making it required (if Bison is not found, processing stops
+with an error message):
+
+.. code-block:: cmake
+
+  find_package(BISON 2.1.3 REQUIRED)
+
+Example: Generating Parser
+""""""""""""""""""""""""""
+
+Finding Bison and adding input Yacc source file ``parser.y`` to be processed by
+Bison into ``parser.cpp`` source file with header ``parser.h`` at build phase:
+
+.. code-block:: cmake
+
+  find_package(BISON)
+
+  if(BISON_FOUND)
+    bison_target(MyParser parser.y parser.cpp DEFINES_FILE parser.h)
+  endif()
+
   add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
 
+Examples: Command-line Options
+""""""""""""""""""""""""""""""
+
 Adding additional command-line options to the ``bison`` executable can be passed
-as a list. For example, adding the ``-Wall`` option to report all warnings, and
-``--no-lines`` (``-l``) to not generate ``#line`` directives.
+as a list.  For example, adding the ``-Wall`` option to report all warnings, and
+``--no-lines`` (``-l``) to not generate ``#line`` directives:
 
 .. code-block:: cmake
 
@@ -128,8 +206,9 @@ as a list. For example, adding the ``-Wall`` option to report all warnings, and
     bison_target(MyParser parser.y parser.cpp OPTIONS -Wall --no-lines)
   endif()
 
-Generator expressions can be used in ``OPTIONS <options...``. For example, to
-add the ``--debug`` (``-t``) option only for the ``Debug`` build type:
+:manual:`Generator expressions <cmake-generator-expressions(7)>` can be used in
+the ``OPTIONS <options>...`` argument.  For example, to add the ``--debug``
+(``-t``) option only for the ``Debug`` build type:
 
 .. code-block:: cmake
 
@@ -138,6 +217,11 @@ add the ``--debug`` (``-t``) option only for the ``Debug`` build type:
   if(BISON_FOUND)
     bison_target(MyParser parser.y parser.cpp OPTIONS $<$<CONFIG:Debug>:-t>)
   endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`FindFLEX` module to find Flex scanner generator.
 #]=======================================================================]
 
 find_program(BISON_EXECUTABLE NAMES bison win-bison win_bison DOC "path to the bison executable")
@@ -261,7 +345,7 @@ if(BISON_EXECUTABLE)
   endmacro()
 
   #============================================================
-  # BISON_TARGET (public macro)
+  # bison_target() public macro
   #============================================================
   #
   macro(BISON_TARGET Name BisonInput BisonOutput)