diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index afaccc6ed..6557686ef 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -519,8 +519,16 @@ containing just the line:: The ``cmake-module`` directive will scan the module file to extract reStructuredText markup from comment blocks that start in ``.rst:``. -Add to the top of ``Modules/.cmake`` a -:ref:`Line Comment` block of the form: +At the top of ``Modules/.cmake``, begin with the following +license notice: + +.. code-block:: cmake + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + +After this notice, add a *BLANK* line. Then, add documentation using +a :ref:`Line Comment` block of the form: .. code-block:: cmake @@ -552,6 +560,9 @@ For example, a ``Modules/Findxxx.cmake`` module may contain: .. code-block:: cmake + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + #.rst: # FindXxx # ------- @@ -579,25 +590,6 @@ For example, a ``Modules/Findxxx.cmake`` module may contain: endmacro() -After the top documentation block, leave a *BLANK* line, and then add a -copyright and licence notice block like this one (change only the year -range and name) - -.. code-block:: cmake - - #============================================================================= - # Copyright 2009-2011 Your Name - # - # Distributed under the OSI-approved BSD License (the "License"); - # see accompanying file Copyright.txt for details. - # - # This software is distributed WITHOUT ANY WARRANTY; without even the - # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - # See the License for more information. - #============================================================================= - # (To distribute this file outside of CMake, substitute the full - # License text for the above reference.) - Test the documentation formatting by running ``cmake --help-module ``, and also by enabling the ``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. @@ -791,10 +783,17 @@ A Sample Find Module We will describe how to create a simple find module for a library ``Foo``. -The first thing that is needed is documentation. CMake's documentation -system requires you to start the file with a documentation marker and -the name of the module. You should follow this with a simple statement -of what the module does. +The first thing that is needed is a license notice. + +.. code-block:: cmake + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + +Next we need module documentation. CMake's documentation system requires you +to follow the license notice with a blank line and then with a documentation +marker and the name of the module. You should follow this with a simple +statement of what the module does. .. code-block:: cmake @@ -825,24 +824,6 @@ If the package provides any macros, they should be listed here, but can be documented where they are defined. See the `Module Documentation`_ section above for more details. -After the documentation, leave a blank line, and then add a copyright and -licence notice block - -.. code-block:: cmake - - #============================================================================= - # Copyright 2009-2011 Your Name - # - # Distributed under the OSI-approved BSD License (the "License"); - # see accompanying file Copyright.txt for details. - # - # This software is distributed WITHOUT ANY WARRANTY; without even the - # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - # See the License for more information. - #============================================================================= - # (To distribute this file outside of CMake, substitute the full - # License text for the above reference.) - Now the actual libraries and so on have to be found. The code here will obviously vary from module to module (dealing with that, after all, is the point of find modules), but there tends to be a common pattern for libraries.