Merge topic 'patch-flex-bison-docs-2'

559a8d088a FindFLEX: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10128

Modules/FindFLEX.cmake

@@ -5,46 +5,55 @@
 FindFLEX
 --------
 
-Find Fast Lexical Analyzer (Flex) executable and provides a macro
-to generate custom build rules
+Find Fast Lexical Analyzer (Flex) executable and provide a macro
+to generate custom build rules.
 
+The module defines the following variables:
 
+``FLEX_FOUND``
+  True if ``flex`` executable is found.
 
-The module defines the following variables:
+``FLEX_EXECUTABLE``
+  The path to the ``flex`` executable.
 
-::
+``FLEX_VERSION``
+  The version of ``flex``.
 
-  FLEX_FOUND - True is flex executable is found
-  FLEX_EXECUTABLE - the path to the flex executable
-  FLEX_VERSION - the version of flex
-  FLEX_LIBRARIES - The flex libraries
-  FLEX_INCLUDE_DIRS - The path to the flex headers
+``FLEX_LIBRARIES``
+  The ``flex`` libraries.
 
+``FLEX_INCLUDE_DIRS``
+  The path to the ``flex`` headers.
 
+The minimum required version of ``flex`` can be specified using the
+standard CMake syntax, e.g. :command:`find_package(FLEX 2.5.13)`.
 
-The minimum required version of flex can be specified using the
-standard syntax, e.g.  :command:`find_package(FLEX 2.5.13)`
+If ``flex`` is found on the system, the module defines the macro:
 
+.. command:: flex_target
 
+  .. code-block:: cmake
 
-If flex is found on the system, the module provides the macro:
+    flex_target(<Name> <FlexInput> <FlexOutput>
+                [COMPILE_FLAGS <string>]
+                [DEFINES_FILE <string>]
+                )
 
-::
+which creates a custom command to generate the ``<FlexOutput>`` file from
+the ``<FlexInput>`` file.  ``<Name>`` is an alias used to get details of this
+custom command.
 
-  FLEX_TARGET(Name FlexInput FlexOutput
-              [COMPILE_FLAGS <string>]
-              [DEFINES_FILE <string>]
-              )
+The options are:
 
-which creates a custom command to generate the ``FlexOutput`` file from
-the ``FlexInput`` file.  Name is an alias used to get details of this custom
-command.  If ``COMPILE_FLAGS`` option is specified, the next
-parameter is added to the flex command line.
+``COMPILE_FLAGS <string>``
+  Space-separated flex options added to the ``flex`` command line.
+  A :ref:`;-list <CMake Language Lists>` will not work.
 
-.. versionadded:: 3.5
-  If flex is configured to
-  output a header file, the ``DEFINES_FILE`` option may be used to specify its
-  name.
+``DEFINES_FILE <string>``
+  .. versionadded:: 3.5
+
+  If flex is configured to output a header file, this option may be used to
+  specify its name.
 
 .. versionchanged:: 3.17
   When :policy:`CMP0098` is set to ``NEW``, ``flex`` runs in the
@@ -52,60 +61,51 @@ parameter is added to the flex command line.
 
 The macro defines the following variables:
 
-::
+``FLEX_<Name>_DEFINED``
+  True if the macro ran successfully.
 
-  FLEX_${Name}_DEFINED - true is the macro ran successfully
-  FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
-  alias for FlexOutput
-  FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
-  FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
+``FLEX_<Name>_OUTPUTS``
+  The source file generated by the custom rule, an alias for ``<FlexOutput>``.
 
+``FLEX_<Name>_INPUT``
+  The flex source file, an alias for ``<FlexInput>``.
 
+``FLEX_<Name>_OUTPUT_HEADER``
+  The header flex output, if any.
 
 Flex scanners often use tokens defined by Bison: the code generated
 by Flex depends of the header generated by Bison.  This module also
 defines a macro:
 
-::
-
-  ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
-
-which adds the required dependency between a scanner and a parser
-where ``FlexTarget`` and ``BisonTarget`` are the first parameters of
-respectively ``FLEX_TARGET`` and ``BISON_TARGET`` macros.
-
-::
+.. command:: add_flex_bison_dependency
 
-  ====================================================================
-  Example:
+  .. code-block:: cmake
 
+    add_flex_bison_dependency(<FlexTarget> <BisonTarget>)
 
+which adds the required dependency between a scanner and a parser
+where ``<FlexTarget>`` and ``<BisonTarget>`` are the first parameters of
+respectively ``flex_target`` and ``bison_target`` macros.
 
-::
-
-   find_package(BISON)
-   find_package(FLEX)
-
-
-
-::
-
-   BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
-   FLEX_TARGET(MyScanner lexer.l  ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
-   ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
+Examples
+^^^^^^^^
 
+.. code-block:: cmake
 
+  find_package(BISON)
+  find_package(FLEX)
 
-::
+  bison_target(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
+  flex_target(MyScanner lexer.l  ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
+  add_flex_bison_dependency(MyScanner MyParser)
 
-   include_directories(${CMAKE_CURRENT_BINARY_DIR})
-   add_executable(Foo
-      Foo.cc
-      ${BISON_MyParser_OUTPUTS}
-      ${FLEX_MyScanner_OUTPUTS}
-   )
-   target_link_libraries(Foo ${FLEX_LIBRARIES})
-  ====================================================================
+  include_directories(${CMAKE_CURRENT_BINARY_DIR})
+  add_executable(Foo
+    Foo.cc
+    ${BISON_MyParser_OUTPUTS}
+    ${FLEX_MyScanner_OUTPUTS}
+  )
+  target_link_libraries(Foo ${FLEX_LIBRARIES})
 #]=======================================================================]
 
 find_program(FLEX_EXECUTABLE NAMES flex win-flex win_flex DOC "path to the flex executable")