From 66a38395895f52cadbd7085817f9d35baab73a27 Mon Sep 17 00:00:00 2001
From: Dmytro Maluka <dmitrymaluka@gmail.com>
Date: Sun, 24 Mar 2024 02:07:58 +0100
Subject: [PATCH] Update and clarify documentation on filetype detection
 patterns

---
 runtime/help/colors.md   | 33 ++++++++++++++++++++++++++++++---
 runtime/syntax/README.md |  3 ++-
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/runtime/help/colors.md b/runtime/help/colors.md
index 80a877d7..4e7d874f 100644
--- a/runtime/help/colors.md
+++ b/runtime/help/colors.md
@@ -271,13 +271,40 @@ detect:
 ```
 
 Micro will match this regex against a given filename to detect the filetype.
-You may also provide an optional `signature` regex that will check a certain
-amount of lines of a file to find specific marks. For example:
+
+In addition to the `filename` regex (or even instead of it) you can provide
+a `header` regex that will check the first line of the line. For example:
 
 ```
 detect:
     filename: "\\.ya?ml$"
-    signature: "%YAML"
+    header: "%YAML"
+```
+
+This is useful in cases when the given file name is not sufficient to determine
+the filetype, e.g. with the above example, if a YAML file has no `.yaml`
+extension but may contain a `%YAML` directive in its first line.
+
+`filename` takes precedence over `header`, i.e. if there is a syntax file that
+matches the file with a filetype by the `filename` and another syntax file that
+matches the same file with another filetype by the `header`, the first filetype
+will be used.
+
+Finally, in addition to `filename` and/or `header` (but not instead of them)
+you may also provide an optional `signature` regex which is useful for resolving
+ambiguities when there are multiple syntax files matching the same file with
+different filetypes. If a `signature` regex is given, micro will match a certain
+amount of first lines in the file (this amount is determined by the `detectlimit`
+option) against this regex, and if any of the lines match, this syntax file's
+filetype will be preferred over other matching filetypes.
+
+For example, to distinguish C++ header files from C and Objective-C header files
+that have the same `.h` extension:
+
+```
+detect:
+    filename: "\\.c(c|pp|xx)$|\\.h(h|pp|xx)?$"
+    signature: "namespace|template|public|protected|private"
 ```
 
 ### Syntax rules
diff --git a/runtime/syntax/README.md b/runtime/syntax/README.md
index 4fa58647..3e2c5631 100644
--- a/runtime/syntax/README.md
+++ b/runtime/syntax/README.md
@@ -2,7 +2,8 @@
 
 Here are micro's syntax files.
 
-Each yaml file specifies how to detect the filetype based on file extension or given signature. The signature can be matched to all available lines of the file or to the value defined with the option `detectlimit` (to limit parse times) for a best "guess".
+Each yaml file specifies how to detect the filetype based on file extension or header (first line of the line).
+In addition, a signature can be provided to help resolving ambiguities when multiple matching filetypes are detected.
 Then there are patterns and regions linked to highlight groups which tell micro how to highlight that filetype.
 
 Making your own syntax files is very simple. I recommend you check the file after you are finished with the