file(): restored the legacy file() source options page and added a warning of its 'deprecation' at multiple places

Signed-off-by: Hofi <hofione@gmail.com>

Author: HofiOne

_data/link_aliases.yml

@@ -165,6 +165,9 @@ adm-src-hypr:
 adm-src-macOS:
   aliases: [ "darwin-oslog()", "darwin-oslog-stream()" ]
 
+adm-src-file-note:
+  aliases: [ "read kernel messages" ]
+
 adm-dest-google-bq:
   aliases: [ "bigquery()" ]
 

_data/navigation.yml

@@ -138,20 +138,20 @@ admin-guide-nav:
       subnav:
       - title: "internal() source options"
         url: /admin-guide/060_Sources/010_Internal/000_Internal_options
-    - title: "file (DEPRECATED)"
+    - title: "file"
       url: /admin-guide/060_Sources/020_File/README
       subnav:
       - title: "file() source options"
         url: /admin-guide/060_Sources/020_File/000_File_source_options
-      - title: "How file sources are followed"
-        url: /admin-guide/060_Sources/020_File/001_File_following
       - title: "Notes on reading kernel messages"
-        url: /admin-guide/060_Sources/020_File/002_Notes_on_reading_kernel_messages
+        url: /admin-guide/060_Sources/020_File/001_Notes_on_reading_kernel_messages
     - title: "wildcard-file"
       url: /admin-guide/060_Sources/021_Wildcard-file/README
       subnav:
       - title: "wildcard-file() source options"
         url: /admin-guide/060_Sources/021_Wildcard-file/000_Wildcard-file_options
+      - title: "How file sources are followed"
+        url: /admin-guide/060_Sources/021_Wildcard-file/001_File_following
     - title: "freebsd-audit"
       url: /admin-guide/060_Sources/030_Freebsd-audit/README
       subnav:
@@ -403,7 +403,7 @@ admin-guide-nav:
         url: /admin-guide/070_Destinations/100_Kafka-c/001_Shifting_from_Java_to_C
       - title: "Flow control in {{ site.product.short_name }} and the Kafka client"
         url: /admin-guide/070_Destinations/100_Kafka-c/002_Flow_control
-      - title: "Options of the kafka() destination's C implementation"
+      - title: "Options of the kafka() destination"
         url: /admin-guide/070_Destinations/100_Kafka-c/003_Kafka-c_options
     - title: "Loggly"
       url: /admin-guide/070_Destinations/110_Loggly/README
@@ -689,6 +689,8 @@ admin-guide-nav:
           url: /admin-guide/080_Log/030_Filters/005_Filter_functions/011_source
         - title: "tags()"
           url: /admin-guide/080_Log/030_Filters/005_Filter_functions/012_tags
+        - title: "blank()"
+          url: /admin-guide/080_Log/030_Filters/005_Filter_functions/013_blank
     - title: "Dropping messages"
       url: /admin-guide/080_Log/040_Dropping_messages
   - title: "Global options of {{ site.product.short_name }}"

_includes/doc/admin-guide/options/follow-method.md

@@ -7,7 +7,7 @@
 The default `legacy` mode preserves the pre-4.9 version file follow-mode behavior of {{ site.product.short_name }}, which is based on the value of follow-freq().\
 The `poll` value forces {{ site.product.short_name }} to poll for file changes at the interval specified by the monitor-freq() option, even if a more efficient method (such as `inotify` or `kqueue`) is available.\
 If `inotify` is selected and supported by the platform, {{ site.product.short_name }} uses it to detect changes in source files. This is the most efficient and least resource-consuming option available on Linux for regular files.\
-The `system` value will use system poll methods (via ivykis) like `port-timer` `port` `dev_poll` `epoll-timerfd` `epoll` `kqueue` `ppoll` `poll` and `uring`. For more information about how to control the system polling methods used, see How content changes are followed in file() and wildcard-file() sources.
+The `system` value will use system poll methods (via ivykis) like `port-timer` `port` `dev_poll` `epoll-timerfd` `epoll` `kqueue` `ppoll` `poll` and `uring`.
 
 **NOTE:** Using `inotify` also requires setting monitor-method() to `inotify`.
 {: .notice--info}

_includes/doc/admin-guide/warnings/file-source-deprecation-warning.md

@@ -0,0 +1,3 @@
+![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:**
+Currently, the file() source is maintained for compatibility, but for regular files — especially when using wildcards in the filename — it is recommended to use the wildcard-file() source, as it provides better long-term support and more configuration options. The only real use case for the legacy file() source is when you need to read kernel messages.
+{: .notice--warning}

_includes/doc/admin-guide/warnings/file-source-follow-warning.md

@@ -1,2 +1,3 @@
-![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:** As the follow-freq(), follow-method(), monitor-method(), and the monitor-freq() options could have performance penalty effects, it is important to understand how the file and directory monitoring operates depending on these values. For details, refer to How content changes are followed in file() and wildcard-file() sources.
+![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:**
+As the follow-freq(), follow-method(), monitor-method(), and the monitor-freq() options could have performance penalty effects, it is important to understand how the file and directory monitoring operates depending on these values. For details, refer to How content changes are followed in file() and wildcard-file() sources.
 {: .notice--warning}

doc/_admin-guide/060_Sources/020_File/000_File_source_options.md

@@ -0,0 +1,52 @@
+---
+title: file() source options
+id: adm-src-file-opt
+description: >-
+    This section describes the options of the file() source in {{ site.product.short_name }}.
+---
+
+{% include doc/admin-guide/warnings/file-source-deprecation-warning.md %}
+
+The file() driver has the following options:
+
+{% include doc/admin-guide/options/default-facility.md %}
+
+{% include doc/admin-guide/options/default-priority.md %}
+
+{% include doc/admin-guide/options/encoding.md %}
+
+{% include doc/admin-guide/options/source-flags.md %}
+
+{% include doc/admin-guide/options/follow-freq.md %}
+
+{% include doc/admin-guide/options/follow-method.md %}
+
+{% include doc/admin-guide/options/hook.md %}
+
+{% include doc/admin-guide/options/keep-timestamp.md %}
+
+{% include doc/admin-guide/options/log-fetch-limit.md %}
+
+{% include doc/admin-guide/options/log-iw-size.md %}
+
+{% include doc/admin-guide/options/log-msg-size.md %}
+
+{% include doc/admin-guide/options/log-prefix.md %}
+
+{% include doc/admin-guide/options/multi-line-garbage.md %}
+
+{% include doc/admin-guide/options/multi-line-mode.md %}
+
+{% include doc/admin-guide/options/multi-line-prefix.md %}
+
+{% include doc/admin-guide/options/multi-line-suffix.md %}
+
+{% include doc/admin-guide/options/multi-line-timeout.md %}
+
+{% include doc/admin-guide/options/pad-size.md %}
+
+{% include doc/admin-guide/options/program-override.md %}
+
+{% include doc/admin-guide/options/tags.md %}
+
+{% include doc/admin-guide/options/time-zone.md %}

doc/_admin-guide/060_Sources/020_File/000_Notes_on_reading_kernel_messages.md renamed to doc/_admin-guide/060_Sources/020_File/001_Notes_on_reading_kernel_messages.md

@@ -4,17 +4,19 @@ short_title: file
 id: adm-src-file
 description: >-
     Collects log messages from plain-text files, for example, from the logfiles of
-    an Apache webserver. If you want to use wildcards in the filename, use the [[wildcard-file() source|adm-src-wild]]. Currently, {{ site.product.short_name }} supports the file() source to maintain certain compatibilities, but it is advised to use the wildcard-file() source for longevity reasons and more configuration options.
+    an Apache webserver.
 ---
 
+{% include doc/admin-guide/warnings/file-source-deprecation-warning.md %}
+
 The {{ site.product.short_name }} application notices if a file is renamed or replaced with
 a new file, so it can correctly follow the file even if logrotation is
 used. When {{ site.product.short_name }} is restarted, it records the position of the last
 sent log message in the /var/lib/syslog-ng/syslog-ng.persist file, and
 continues to send messages from this position after the restart.
 
 The file driver has a single required parameter specifying the file to
-open. If you want to use wildcards in the filename, use the [[wildcard-file() source|adm-src-wild]].
+open. If you want to use wildcards in the filename, use the wildcard-file() source.
 For the list of available optional parameters, see file() source options.
 
 {% include doc/admin-guide/warnings/file-source-follow-warning.md %}
@@ -49,5 +51,3 @@ treats messages received from files as sent by the kern facility. Use
 the **default-facility()** and **default-priority()** options in the
 source definition to assign a different facility if needed.
 {: .notice--info}
-
-For the configuration options available in the `file()` source, see wildcard-file() source options.