man: don't document ".include" in configuration files anymore as first step to deprecate them one day

man/systemd.unit.xml

@@ -200,12 +200,6 @@
                 has the appropriate section headers before any
                 directive.</para>
 
-                <para>If a line starts with <option>.include</option>
-                followed by a filename, the specified file will be
-                parsed at this point. Make sure that the file that is
-                included has the appropriate section headers before
-                any directives.</para>
-
                 <para>Note that while systemd offers a flexible
                 dependency system between units it is recommended to
                 use this functionality only sparingly and instead rely

src/shared/conf-parser.c

@@ -225,6 +225,15 @@ static int parse_line(const char* unit,
         if (startswith(l, ".include ")) {
                 _cleanup_free_ char *fn = NULL;
 
+                /* .includes are a bad idea, we only support them here
+                 * for historical reasons. They create cyclic include
+                 * problems and make it difficult to detect
+                 * configuration file changes with an easy
+                 * stat(). Better approaches, such as .d/ drop-in
+                 * snippets exist.
+                 *
+                 * Support for them should be eventually removed. */
+
                 if (!allow_include) {
                         log_syntax(unit, LOG_ERR, filename, line, EBADMSG,
                                    ".include not allowed here. Ignoring.");