docs: explain the purpose of -! / --magic / 'set magic'

Also, colorize 'set magic' as valid option in a nanorc file.

doc/nano.1

@@ -95,6 +95,10 @@ The default key bindings can be changed via a \fInanorc\fR file -- see
 
 .SH OPTIONS
 .TP
+.BR \-! ", " \-\-magic
+When neither the file's name nor its first line give a clue,
+try using libmagic to determine the applicable syntax.
+.TP
 .BR \-% ", " \-\-stateflags
 Use the top-right corner of the screen for showing some state flags:
 \fBI\fR when auto-indenting, \fBM\fR when the mark is on, \fBL\fR when

doc/nano.texi

@@ -165,6 +165,11 @@ a command straight into a buffer, and then edit it.
 
 @table @option
 
+@item -!
+@itemx --magic
+When neither the file's name nor its first line give a clue,
+try using libmagic to determine the applicable syntax.
+
 @item -%
 @itemx --stateflags
 Use the top-right corner of the screen for showing some state flags:
@@ -888,6 +893,12 @@ Display line numbers to the left of the text area.
 @item set locking
 Enable vim-style lock-files for when editing files.
 
+@item set magic
+When neither the file's name nor its first line give a clue,
+try using libmagic to determine the applicable syntax.
+(Calling libmagic can be relatively time consuming.
+It is therefore not done by default.)
+
 @anchor{@code{set matchbrackets}}
 @item set matchbrackets "@var{characters}"
 Specify the opening and closing brackets that can be found by bracket

doc/nanorc.5

@@ -170,6 +170,12 @@ Display line numbers to the left of the text area.
 .B set locking
 Enable vim-style lock-files for when editing files.
 .TP
+.B set magic
+When neither the file's name nor its first line give a clue,
+try using libmagic to determine the applicable syntax.
+(Calling libmagic can be relatively time consuming.
+It is therefore not done by default.)
+.TP
 .BI "set matchbrackets """ characters """
 Specify the opening and closing brackets that can be found by bracket
 searches.  This may not include blank characters.  The opening set must

doc/sample.nanorc.in

@@ -76,6 +76,9 @@
 ## no plans to implement vim-style undo state in these files.
 # set locking
 
+## Fall back to slow libmagic to try and determine an applicable syntax.
+# set magic
+
 ## The opening and closing brackets that can be found by bracket
 ## searches.  They cannot contain blank characters.  The former set must
 ## come before the latter set, and both must be in the same order.

syntax/nanorc.nanorc

@@ -7,7 +7,7 @@ comment "#"
 color brightred ".*"
 
 # Keywords
-color brightgreen "^[[:space:]]*(set|unset)[[:space:]]+(afterends|allow_insecure_backup|atblanks|autoindent|backup|boldtext|breaklonglines|casesensitive|constantshow|cutfromcursor|emptyline|historylog|indicator|jumpyscrolling|linenumbers|locking|mouse|multibuffer|noconvert|nohelp|nonewlines|positionlog|preserve|quickblank|rawsequences|rebinddelete|regexp|saveonexit|showcursor|smarthome|softwrap|stateflags|suspendable|tabstospaces|trimblanks|unix|view|wordbounds|zap)\>"
+color brightgreen "^[[:space:]]*(set|unset)[[:space:]]+(afterends|allow_insecure_backup|atblanks|autoindent|backup|boldtext|breaklonglines|casesensitive|constantshow|cutfromcursor|emptyline|historylog|indicator|jumpyscrolling|linenumbers|locking|magic|mouse|multibuffer|noconvert|nohelp|nonewlines|positionlog|preserve|quickblank|rawsequences|rebinddelete|regexp|saveonexit|showcursor|smarthome|softwrap|stateflags|suspendable|tabstospaces|trimblanks|unix|view|wordbounds|zap)\>"
 color yellow "^[[:space:]]*set[[:space:]]+((error|function|key|number|scroller|selected|status|stripe|title)color)[[:space:]]+(bold,)?(italic,)?(bright|light)?(white|black|red|blue|green|yellow|magenta|cyan|normal|pink|purple|mauve|lagoon|mint|lime|peach|orange|latte)?(,(light)?(white|black|red|blue|green|yellow|magenta|cyan|normal|pink|purple|mauve|lagoon|mint|lime|peach|orange|latte))?\>"
 color brightgreen "^[[:space:]]*set[[:space:]]+(backupdir|brackets|errorcolor|functioncolor|keycolor|matchbrackets|numbercolor|operatingdir|punct|quotestr|scrollercolor|selectedcolor|speller|statuscolor|stripecolor|titlecolor|whitespace|wordchars)[[:space:]]+"
 color brightgreen "^[[:space:]]*set[[:space:]]+(fill[[:space:]]+-?[[:digit:]]+|(guidestripe|tabsize)[[:space:]]+[1-9][0-9]*)\>"