[PATCH 2/2] docs: explain the purpose of --magic / 'set magic' / -!

[Benno Schulenberg]

---
 doc/nano.1           |  4 ++++
 doc/nano.texi        | 11 +++++++++++
 doc/nanorc.5         |  6 ++++++
 doc/sample.nanorc.in |  3 +++
 4 files changed, 24 insertions(+)

diff --git a/doc/nano.1 b/doc/nano.1
index 4a953dc2..bdddad0e 100644
--- a/doc/nano.1
+++ b/doc/nano.1
@@ -214,6 +214,10 @@ defined in the \fInanorc\fP files.
 Let an unmodified Backspace or Delete erase the marked region
 (instead of a single character, and without affecting the cutbuffer).
 .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 \-a ", " \-\-atblanks
 When doing soft line wrapping, wrap lines at whitespace
 instead of always at the edge of the screen.
diff --git a/doc/nano.texi b/doc/nano.texi
index 4bd079e1..f10479ae 100644
--- a/doc/nano.texi
+++ b/doc/nano.texi
@@ -310,6 +310,11 @@ Specify the syntax to be used for highlighting.
 Let an unmodified @key{Backspace} or @key{Delete} erase the marked region
 (instead of a single character, and without affecting the cutbuffer).
 
+@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 -a
 @itemx --atblanks
 When doing soft line wrapping, wrap lines at whitespace
@@ -879,6 +884,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
diff --git a/doc/nanorc.5 b/doc/nanorc.5
index 6f33a20c..60c76e01 100644
--- a/doc/nanorc.5
+++ b/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
diff --git a/doc/sample.nanorc.in b/doc/sample.nanorc.in
index 724dc6bc..92988921 100644
--- a/doc/sample.nanorc.in
+++ b/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.
-- 
2.25.4