docs: fix linting issues due to incorrect relative section order

Re-order the sections of a few manual pages to be consistent with the
entirety of the rest of our documentation. This allows us to remove
the just-added whitelist of "bad" order from
lint-man-section-order.perl.

I'm doing that this way around so that code will be easy to dig up if
we'll need it in the future. I've intentionally not added some other
sections such as EXAMPLES to the list of known sections.

If we were to add that we'd find some out of order. Perhaps we'll want
to order those consistently as well in the future, at which point
whitelisting some of them might become handy again.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index 1b1c71ad9d26812da7253e2305bce296ffbbd10e..f2e4a47ebe84c321d765aac7bdfd660bf8befc37 100644 (file)
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -24,6 +24,18 @@ Usage:
 [verse]
 'git-cvsserver' [<options>] [pserver|server] [<directory> ...]
 
+DESCRIPTION
+-----------
+
+This application is a CVS emulation layer for Git.
+
+It is highly functional. However, not all methods are implemented,
+and for those methods that are implemented,
+not all switches are implemented.
+
+Testing has been done using both the CLI CVS client, and the Eclipse CVS
+plugin. Most functionality works fine with both of these clients.
+
 OPTIONS
 -------
 
@@ -57,18 +69,6 @@ access still needs to be enabled by the `gitcvs.enabled` config option
 unless `--export-all` was given, too.
 
 
-DESCRIPTION
------------
-
-This application is a CVS emulation layer for Git.
-
-It is highly functional. However, not all methods are implemented,
-and for those methods that are implemented,
-not all switches are implemented.
-
-Testing has been done using both the CLI CVS client, and the Eclipse CVS
-plugin. Most functionality works fine with both of these clients.
-
 LIMITATIONS
 -----------
 

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 4e0ba8234a0a8c2999c4a790cf0125438794d53d..3d393fbac1bb3323c41ea2b74f6bba8f8ca39c00 100644 (file)
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -38,38 +38,6 @@ are lists of one or more search expressions separated by newline
 characters.  An empty string as search expression matches all lines.
 
 
-CONFIGURATION
--------------
-
-grep.lineNumber::
-       If set to true, enable `-n` option by default.
-
-grep.column::
-       If set to true, enable the `--column` option by default.
-
-grep.patternType::
-       Set the default matching behavior. Using a value of 'basic', 'extended',
-       'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
-       `--fixed-strings`, or `--perl-regexp` option accordingly, while the
-       value 'default' will return to the default matching behavior.
-
-grep.extendedRegexp::
-       If set to true, enable `--extended-regexp` option by default. This
-       option is ignored when the `grep.patternType` option is set to a value
-       other than 'default'.
-
-grep.threads::
-       Number of grep worker threads to use. If unset (or set to 0), Git will
-       use as many threads as the number of logical cores available.
-
-grep.fullName::
-       If set to true, enable `--full-name` option by default.
-
-grep.fallbackToNoIndex::
-       If set to true, fall back to git grep --no-index if git grep
-       is executed outside of a git repository.  Defaults to false.
-
-
 OPTIONS
 -------
 --cached::
@@ -363,6 +331,38 @@ with multiple threads might perform slower than single threaded if `--textconv`
 is given and there're too many text conversions. So if you experience low
 performance in this case, it might be desirable to use `--threads=1`.
 
+CONFIGURATION
+-------------
+
+grep.lineNumber::
+       If set to true, enable `-n` option by default.
+
+grep.column::
+       If set to true, enable the `--column` option by default.
+
+grep.patternType::
+       Set the default matching behavior. Using a value of 'basic', 'extended',
+       'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
+       `--fixed-strings`, or `--perl-regexp` option accordingly, while the
+       value 'default' will return to the default matching behavior.
+
+grep.extendedRegexp::
+       If set to true, enable `--extended-regexp` option by default. This
+       option is ignored when the `grep.patternType` option is set to a value
+       other than 'default'.
+
+grep.threads::
+       Number of grep worker threads to use. If unset (or set to 0), Git will
+       use as many threads as the number of logical cores available.
+
+grep.fullName::
+       If set to true, enable `--full-name` option by default.
+
+grep.fallbackToNoIndex::
+       If set to true, fall back to git grep --no-index if git grep
+       is executed outside of a git repository.  Defaults to false.
+
+
 GIT
 ---
 Part of the linkgit:git[1] suite

diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
index 17a2603a6006b2045e4e1506bab4e9167af9944e..466a69751910e4d7d031725f8d52d41d1e7f98a3 100644 (file)
--- a/Documentation/git-mktag.txt
+++ b/Documentation/git-mktag.txt
@@ -11,14 +11,6 @@ SYNOPSIS
 [verse]
 'git mktag'
 
-OPTIONS
--------
-
---strict::
-       By default mktag turns on the equivalent of
-       linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to
-       disable it.
-
 DESCRIPTION
 -----------
 
@@ -45,6 +37,14 @@ the appropriate `fsck.<msg-id>` varible:
 
     git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers
 
+OPTIONS
+-------
+
+--strict::
+       By default mktag turns on the equivalent of
+       linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to
+       disable it.
+
 Tag Format
 ----------
 A tag signature file, to be fed to this command's standard input,

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index f08ae27e2aefc0a2ff81b1ca8fa310f8006a42d7..8423d463724ab89a5c0b8153def58b59c409913e 100644 (file)
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -200,12 +200,6 @@ Alternatively, you can undo the 'git rebase' with
 
     git rebase --abort
 
-CONFIGURATION
--------------
-
-include::config/rebase.txt[]
-include::config/sequencer.txt[]
-
 OPTIONS
 -------
 --onto <newbase>::
@@ -1266,6 +1260,12 @@ merge tlsv1.3
 merge cmake
 ------------
 
+CONFIGURATION
+-------------
+
+include::config/rebase.txt[]
+include::config/sequencer.txt[]
+
 BUGS
 ----
 The todo list presented by the deprecated `--preserve-merges --interactive`

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 67b143cc81ea9534722a082fdfbc016081621411..d5776ffcfd5149d1d204973af7239db94d4a38c8 100644 (file)
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -1061,25 +1061,6 @@ with different name spaces.  For example:
        branches = stable/*:refs/remotes/svn/stable/*
        branches = debug/*:refs/remotes/svn/debug/*
 
-BUGS
-----
-
-We ignore all SVN properties except svn:executable.  Any unhandled
-properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
-
-Renamed and copied directories are not detected by Git and hence not
-tracked when committing to SVN.  I do not plan on adding support for
-this as it's quite difficult and time-consuming to get working for all
-the possible corner cases (Git doesn't do it, either).  Committing
-renamed and copied files is fully supported if they're similar enough
-for Git to detect them.
-
-In SVN, it is possible (though discouraged) to commit changes to a tag
-(because a tag is just a directory copy, thus technically the same as a
-branch). When cloning an SVN repository, 'git svn' cannot know if such a
-commit to a tag will happen in the future. Thus it acts conservatively
-and imports all SVN tags as branches, prefixing the tag name with 'tags/'.
-
 CONFIGURATION
 -------------
 
@@ -1166,6 +1147,25 @@ $GIT_DIR/svn/\**/.rev_map.*::
 if it is missing or not up to date.  'git svn reset' automatically
 rewinds it.
 
+BUGS
+----
+
+We ignore all SVN properties except svn:executable.  Any unhandled
+properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
+
+Renamed and copied directories are not detected by Git and hence not
+tracked when committing to SVN.  I do not plan on adding support for
+this as it's quite difficult and time-consuming to get working for all
+the possible corner cases (Git doesn't do it, either).  Committing
+renamed and copied files is fully supported if they're similar enough
+for Git to detect them.
+
+In SVN, it is possible (though discouraged) to commit changes to a tag
+(because a tag is just a directory copy, thus technically the same as a
+branch). When cloning an SVN repository, 'git svn' cannot know if such a
+commit to a tag will happen in the future. Thus it acts conservatively
+and imports all SVN tags as branches, prefixing the tag name with 'tags/'.
+
 SEE ALSO
 --------
 linkgit:git-rebase[1]

diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 5767e7e4567b93eee531dad4f4f5cc619ac61a05..b05f9156dd9800466d79d3178f388b7fc26a9397 100755 (executable)
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -18,24 +18,13 @@ my %SECTIONS;
                'DESCRIPTION' => {
                        required => 1,
                        order => $order++,
-                       bad => {
-                               'git-mktag.txt' => 'OPTIONS',
-                               'git-cvsserver.txt' => 'OPTIONS',
-                       },
                },
                'OPTIONS' => {
                        order => $order++,
                        required => 0,
-                       bad => {
-                               'git-grep.txt' => 'CONFIGURATION',
-                               'git-rebase.txt' => 'CONFIGURATION',
-                       },
                },
                'CONFIGURATION' => {
                        order => $order++,
-                       bad => {
-                               'git-svn.txt' => 'BUGS',
-                       },
                },
                'BUGS' => {
                        order => $order++,
@@ -77,16 +66,7 @@ while (my $line = <>) {
 
                my $expected_last = $expected_order[-2];
                my $actual_last = $actual_order[-2];
-               my $except_last = $SECTIONS{$line}->{bad}->{$ARGV} || '';
-               if (($SECTIONS{$line}->{bad}->{$ARGV} || '') eq $actual_last) {
-                       # Either we're whitelisted, or ...
-                       next
-               } elsif (exists $SECTIONS{$actual_last}->{bad}->{$ARGV}) {
-                       # ... we're complaing about the next section
-                       # which is out of order because this one is,
-                       # don't complain about that one.
-                       next;
-               } elsif ($actual_last ne $expected_last) {
+               if ($actual_last ne $expected_last) {
                        report("section '$line' incorrectly ordered, comes after '$actual_last'");
                }
                next;