fix bullet points from restic man (#398)

restic/commands.go

@@ -149,7 +149,9 @@ var (
 
 	manSectionStart   = regexp.MustCompile(`^\.SH ([A-Z 0-9]+)$`)
 	manParagraphStart = regexp.MustCompile(`^\.PP$`)
-	manEscapeSequence = regexp.MustCompile(`(\\f[A-Z]|\\)`)
+	manBulletPoint    = regexp.MustCompile(`^\.IP \\\(bu \d+$`)
+	manEscapeSequence = regexp.MustCompile(`(\\f[A-Z]|\\&|\\)`)
+	diffCode          = regexp.MustCompile(`^([+-UMT?])  `)
 	lineCleanup       = regexp.MustCompile("([`]{2,})")
 )
 
@@ -159,6 +161,8 @@ func parseStream(input io.Reader, commandName string) (cmd *command, err error)
 		commandName = DefaultCommand
 	}
 
+	bulletPoint := false
+
 	cmd = &command{Name: commandName}
 
 	var option *Option
@@ -180,6 +184,10 @@ func parseStream(input io.Reader, commandName string) (cmd *command, err error)
 				section = m[1]
 			} else if manParagraphStart.MatchString(line) {
 				addOption()
+			} else if manBulletPoint.MatchString(line) {
+				bulletPoint = true
+			} else {
+				bulletPoint = false
 			}
 		} else {
 			line = manEscapeSequence.ReplaceAllString(line, "")
@@ -190,6 +198,11 @@ func parseStream(input io.Reader, commandName string) (cmd *command, err error)
 				if len(cmd.Description) > 0 {
 					cmd.Description += "\n"
 				}
+				if bulletPoint {
+					cmd.Description += "* "
+					bulletPoint = false
+					line = diffCode.ReplaceAllString(line, "`$1` ")
+				}
 				cmd.Description += line
 			case "OPTIONS":
 				if option == nil {

restic/commands.json

@@ -518,7 +518,7 @@
   },
   {
     "Name": "diff",
-    "Description": "The \"diff\" command shows differences from the first to the second snapshot. The\nfirst characters in each line display what has happened to a particular file or\ndirectory:\n\n+  The item was added\n-  The item was removed\nU  The metadata (access mode, timestamps, ...) for the item was updated\nM  The file's content was modified\nT  The type was changed, e.g. a file was made a symlink\n?  Bitrot detected: The file's content has changed but all metadata is the same\n\n\nMetadata comparison will likely not work if a backup was created using the\n\u0026'--ignore-inode' or '--ignore-ctime' option.\n\nTo only compare files in specific subfolders, you can use the\n\"snapshotID:subfolder\" syntax, where \"subfolder\" is a path within the\nsnapshot.",
+    "Description": "The \"diff\" command shows differences from the first to the second snapshot. The\nfirst characters in each line display what has happened to a particular file or\ndirectory:\n\n* `+` The item was added\n* `-` The item was removed\n* `U` The metadata (access mode, timestamps, ...) for the item was updated\n* `M` The file's content was modified\n* `T` The type was changed, e.g. a file was made a symlink\n* `?` Bitrot detected: The file's content has changed but all metadata is the same\n\n\nMetadata comparison will likely not work if a backup was created using the\n'--ignore-inode' or '--ignore-ctime' option.\n\nTo only compare files in specific subfolders, you can use the\n\"snapshotID:subfolder\" syntax, where \"subfolder\" is a path within the\nsnapshot.",
     "FromVersion": "",
     "RemovedInVersion": "",
     "Options": [
@@ -2238,7 +2238,7 @@
   },
   {
     "Name": "stats",
-    "Description": "The \"stats\" command walks one or multiple snapshots in a repository\nand accumulates statistics about the data stored therein. It reports\non the number of unique files and their sizes, according to one of\nthe counting modes as given by the --mode flag.\n\nIt operates on all snapshots matching the selection criteria or all\nsnapshots if nothing is specified. The special snapshot ID \"latest\"\nis also supported. Some modes make more sense over\njust a single snapshot, while others are useful across all snapshots,\ndepending on what you are trying to calculate.\n\nThe modes are:\n\nrestore-size: (default) Counts the size of the restored files.\nfiles-by-contents: Counts total size of unique files, where a file is\nconsidered unique if it has unique contents.\nraw-data: Counts the size of blobs in the repository, regardless of\nhow many files reference them.\nblobs-per-file: A combination of files-by-contents and raw-data.\n\n\nRefer to the online manual for more details about each mode.",
+    "Description": "The \"stats\" command walks one or multiple snapshots in a repository\nand accumulates statistics about the data stored therein. It reports\non the number of unique files and their sizes, according to one of\nthe counting modes as given by the --mode flag.\n\nIt operates on all snapshots matching the selection criteria or all\nsnapshots if nothing is specified. The special snapshot ID \"latest\"\nis also supported. Some modes make more sense over\njust a single snapshot, while others are useful across all snapshots,\ndepending on what you are trying to calculate.\n\nThe modes are:\n\n* restore-size: (default) Counts the size of the restored files.\n* files-by-contents: Counts total size of unique files, where a file is\nconsidered unique if it has unique contents.\n* raw-data: Counts the size of blobs in the repository, regardless of\nhow many files reference them.\n* blobs-per-file: A combination of files-by-contents and raw-data.\n\n\nRefer to the online manual for more details about each mode.",
     "FromVersion": "",
     "RemovedInVersion": "",
     "Options": [
@@ -2422,7 +2422,7 @@
         "Name": "cache-dir",
         "Alias": "",
         "Default": "\"\"",
-        "Description": "set the cache directory\u0026. (default: use system default cache directory)",
+        "Description": "set the cache directory. (default: use system default cache directory)",
         "Once": true,
         "FromVersion": "",
         "RemovedInVersion": ""

restic/commands_test.go

@@ -102,6 +102,16 @@ Next paragraph
 			validation: descriptionIs("First Line\n\tSecond Line"),
 		},
 
+		{
+			name: "parse description with dummy escape sequence",
+			source: `
+.SH DESCRIPTION
+.PP
+Metadata comparison will likely not work if a backup was created using the
+\&'--ignore-inode' or '--ignore-ctime' option.`,
+			validation: descriptionIs("Metadata comparison will likely not work if a backup was created using the\n'--ignore-inode' or '--ignore-ctime' option."),
+		},
+
 		{
 			name: "merge description sections",
 			source: `
@@ -127,6 +137,28 @@ Second Line`,
 			validation: descriptionIs("First Line\n\nSecond Line"),
 		},
 
+		{
+			name: "parse a list of flags for the diff command",
+			source: `
+.SH DESCRIPTION
+.RS
+.IP \(bu 2
++  added
+.IP \(bu 2
+-  removed
+.IP \(bu 2
+U  updated
+.IP \(bu 2
+M  modified
+.IP \(bu 2
+T  type changed
+.IP \(bu 2
+?  bitrot
+
+.RE`,
+			validation: descriptionIs("* `+` added\n* `-` removed\n* `U` updated\n* `M` modified\n* `T` type changed\n* `?` bitrot"),
+		},
+
 		{
 			name: "parse option",
 			source: `
@@ -154,6 +186,30 @@ Desc 2
 			),
 		},
 
+		{
+			name: "parse option with double backticks bug",
+			source: `
+.SH DESCRIPTION
+.PP
+Desc
+
+.SH OPTIONS
+.PP
+\fB-v\fP, \fB--verbose\fP[=0]
+	be verbose (specify multiple times or a level using --verbose=n` + "``" + `, max level/times is 2)
+
+`,
+			validation: all(
+				descriptionIs("Desc"),
+				optionIs(
+					"verbose",
+					"be verbose (specify multiple times or a level using --verbose=n, max level/times is 2)",
+					"0",
+					true,
+				),
+			),
+		},
+
 		{
 			name: "parse multiline option",
 			source: `