Group subcommands into sections in usage. Closes: #703797

Types/Command.hs

@@ -53,9 +53,9 @@ instance Eq CommandCheck where
 instance Eq Command where
 	a == b = cmdname a == cmdname b
 
-{- Order commands by name -}
+{- Order commands by section and then by name -}
 instance Ord Command where
-	compare = comparing cmdname
+	compare = comparing (\c -> (cmdsection c, cmdname c))
 
 {- The same sections are listed in doc/git-annex.mdwn -}
 data CommandSection 
@@ -66,3 +66,11 @@ data CommandSection
 	| SectionUtility
 	| SectionPlumbing
 	deriving (Eq, Ord, Enum, Bounded)
+
+descSection :: CommandSection -> String
+descSection SectionCommon = "Commonly used commands"
+descSection SectionSetup = "Repository setup commands"
+descSection SectionMaintenance = "Repository maintenance commands"
+descSection SectionQuery = "Query commands"
+descSection SectionUtility = "Utility commands"
+descSection SectionPlumbing = "Plumbing commands"

Usage.hs

@@ -18,11 +18,7 @@ usage header cmds commonoptions = unlines $
 	[ header
 	, ""
 	, "Options:"
-	] ++ optlines ++
-	[ ""
-	, "Commands:"
-	, ""
-	] ++ cmdlines
+	] ++ optlines ++ cmdlines
   where
 	-- To get consistent indentation of options, generate the
 	-- usage for all options at once. A command's options will
@@ -30,12 +26,17 @@ usage header cmds commonoptions = unlines $
 	alloptlines = filter (not . null) $
 		lines $ usageInfo "" $
 			concatMap cmdoptions scmds ++ commonoptions
-	(cmdlines, optlines) = go scmds alloptlines []
-	go [] os ls = (ls, os)
-	go (c:cs) os ls = go cs os' (ls++(l:o))
+	(cmdlines, optlines) = go Nothing scmds alloptlines []
+	go _ [] os ls = (ls, os)
+	go section (c:cs) os ls = go section' cs os' ls'
 	  where
+		ls' = ls++sectionheader++(l:o)
+		sectionheader
+			| section == section' = []
+			| otherwise = ["", descSection (cmdsection c) ++ ":", ""]
+		section' = Just (cmdsection c)
 		(o, os') = splitAt (length $ cmdoptions c) os
-		l = concat 
+		l = concat
 			[ cmdname c
 			, namepad (cmdname c)
 			, cmdparamdesc c

debian/changelog

@@ -1,3 +1,9 @@
+git-annex (4.20130324) UNRELEASED; urgency=low
+
+  * Group subcommands into sections in usage. Closes: #703797
+
+ -- Joey Hess <joeyh@debian.org>  Mon, 25 Mar 2013 10:21:46 -0400
+
 git-annex (4.20130323) unstable; urgency=low
 
   * webapp: Repository list is now included in the dashboard, and other