From e4a69f8b946690fca6b6b72f9d2146ff66a90f46 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@telfort.nl>
Date: Sat, 15 Jul 2017 12:32:57 +0200
Subject: [PATCH] docs: move the descriptions of 'header' and 'magic' next to
 'syntax'

And reword them too, so that it is clearer what the mechanism is
for determining which syntax to use for a file.
---
 doc/nano.texi | 25 +++++++++++++------------
 doc/nanorc.5  | 28 ++++++++++++++--------------
 2 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/doc/nano.texi b/doc/nano.texi
index 48e453f9..4a4a9273 100644
--- a/doc/nano.texi
+++ b/doc/nano.texi
@@ -951,6 +951,19 @@ and applies to files that don't match any syntax's @var{fileregex}.
 The @code{none} syntax is reserved; specifying it on the
 command line is the same as not having a syntax at all.
 
+@item header "@var{regex}" @dots{}
+If from all defined syntaxes no @var{fileregex} matched, then compare
+this @var{regex} (or regexes) against the first line of the current file,
+to determine whether this syntax should be used for it.
+
+@item magic "@var{regex}" @dots{}
+If no @var{fileregex} matched and no @code{header} regex matched
+either, then compare this @var{regex} (or regexes) against the
+result of querying the @code{magic} database about the current
+file, to determine whether this syntax should be used for it.
+(This functionality only works when @code{libmagic} is installed
+on the system and will be silently ignored otherwise.)
+
 @item linter @var{program} [@var{arg} @dots{}]
 Use the given @var{program} to do a syntax check on the current file.
 (This overrides the speller function.)
@@ -960,18 +973,6 @@ Use the given @var{program} to automatically reformat text ---
 useful for a programming language like Go.
 (This overrides the speller and linter functions.)
 
-@item header "@var{regex}" @dots{}
-Add one or more regexes which will
-be compared against the very first line of the file to be edited,
-to determine whether this syntax should be used for that file.
-
-@item magic "@var{regex}" @dots{}
-Add one or more regexes which will be
-compared against the result of querying the magic database about the file
-to be edited, to determine whether this syntax should be used for that
-file.  This functionality only works when libmagic is installed on the
-system and will be silently ignored otherwise.
-
 @item comment "@var{string}"
 Use the given string for commenting and uncommenting lines.
 If the string contains a vertical bar or pipe character (@t{|}),
diff --git a/doc/nanorc.5 b/doc/nanorc.5
index 14818f94..fc2e6911 100644
--- a/doc/nanorc.5
+++ b/doc/nanorc.5
@@ -315,6 +315,19 @@ and applies to files that don't match any syntax's regexes.
 The syntax "\fBnone\fP" is reserved; specifying it on the command line
 is the same as not having a syntax at all.
 .TP
+.BR header " ""\fIregex\fR"" " ...
+If from all defined syntaxes no \fIfileregex\fR matched, then compare
+this \fIregex\fR (or regexes) against the first line of the current file,
+to determine whether this syntax should be used for it.
+.TP
+.BR magic " ""\fIregex\fR"" " ...
+If no \fIfileregex\fR matched and no \fBheader\fR regex matched
+either, then compare this \fIregex\fR (or regexes) against the
+result of querying the \fBmagic\fP database about the current
+file, to determine whether this syntax should be used for it.
+(This functionality only works when \fBlibmagic\fP is installed on the
+system and will be silently ignored otherwise.)
+.TP
 .BI linter " program " \fR[ "arg " \fR...]
 Use the given \fIprogram\fR to run a syntax check on the current file.
 (This overrides the speller function.)
@@ -324,20 +337,7 @@ Use the given \fIprogram\fR to automatically reformat text --
 useful in a programming language like Go.
 (This overrides the speller and linter functions.)
 .TP
-.BR header " \fIregex\fR " ...
-Add one or more regexes which will
-be compared against the very first line of the file to be edited,
-to determine whether this syntax should be used for that file.
-.TP
-.BR magic " \fIregex\fR " ...
-Add one or more regexes which
-will be compared against the result of querying the \fBmagic\fP
-database about the file to be edited, to determine whether this
-syntax should be used for that file.  This
-functionality only works when \fBlibmagic\fP is installed on the
-system and will be silently ignored otherwise.
-.TP
-.BI comment " string"
+.BR comment " ""\fIstring\fR"""
 Use the given string for commenting and uncommenting lines.
 If the string contains a vertical bar or pipe character (\fB|\fR),
 this designates bracket-style comments; for example, "\fB/*|*/\fR" for
-- 
GitLab