doc: include (#473)

cfg_samples/included-file.kbd

@@ -0,0 +1,3 @@
+(defalias
+  included-alias (macro i spc a m spc i n c l u d e d)
+)

cfg_samples/kanata.kbd

@@ -871,9 +871,15 @@ If you need help, you are welcome to ask.
   (  2 4 8) (multi 1 4)
   (1 2 4 8) (multi 1 5)
 )
+
 (defalias
   ch1 (chord binary 1)
   ch2 (chord binary 2)
   ch4 (chord binary 4)
   ch8 (chord binary 8)
 )
+
+;; The top-level action `include` will read a configuration from a new file.
+;; At the time of writing, includes can only be placed at the top level. The
+;; included files also cannot contain includes themselves.
+(include included-file.kbd)

docs/config.adoc

@@ -1666,6 +1666,36 @@ Only zero or one `defoverrides` is allowed in a configuration file.
 )
 ----
 
+[[include]]
+== Include other files
+<<table-of-contents,Back to ToC>>
+
+The `include` optional configuration item
+allows you to include other files into the configuration.
+This configuration accepts a single string which is a file path.
+The file path can be an absolute path or a relative path.
+The path will be relative to the defined configuration file.
+
+At the time of writing, includes can only be placed at the top level.
+The included files also cannot contain includes themselves.
+
+.Example:
+----
+;; This is in the file initially read by kanata, e.g. kanata.kbd
+(include other-file.kbd)
+
+;; This is in the other file
+(defalias
+  included-alias XX
+  ;; ...
+)
+
+;; This is in the other file
+(deflayer included-layer
+  ;; ...
+)
+----
+
 [[advanced-weird-features]]
 == Advanced/weird features