Help: Document HEADER_FILE_ONLY use case

Describe how to get sources into IDE project files.

Help/command/add_executable.rst

@@ -40,6 +40,9 @@ the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
+See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
+pre-processed, and you want to have the original sources reachable from
+within IDE.
 
 --------------------------------------------------------------------------
 

Help/command/add_library.rst

@@ -59,6 +59,10 @@ the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
+See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
+pre-processed, and you want to have the original sources reachable from
+within IDE.
+
 Imported Libraries
 ^^^^^^^^^^^^^^^^^^
 

Help/prop_sf/HEADER_FILE_ONLY.rst

@@ -7,3 +7,18 @@ A property on a source file that indicates if the source file is a
 header file with no associated implementation.  This is set
 automatically based on the file extension and is used by CMake to
 determine if certain dependency information should be computed.
+
+By setting this property to ``ON``, you can disable compilation of
+the given source file, even if it should be compiled because it is
+part of the library's/executable's sources.
+
+This is useful if you have some source files which you somehow
+pre-process, and then add these pre-processed sources via
+:command:`add_library` or :command:`add_executable`. Normally, in IDE,
+there would be no reference of the original sources, only of these
+pre-processed sources. So by setting this property for all the original
+source files to ``ON``, and then either calling :command:`add_library`
+or :command:`add_executable` while passing both the pre-processed
+sources and the original sources, or by using :command:`target_sources`
+to add original source files will do exactly what would one expect, i.e.
+the original source files would be visible in IDE, and will not be built.