From fb5368fefeb66e1496a707e81701e8ed0e5224f0 Mon Sep 17 00:00:00 2001
From: Mingye Wang <arthur2e5@aosc.io>
Date: Sat, 7 Nov 2020 23:04:51 +0800
Subject: [PATCH] plutil: Some documentation

---
 Tools/plutil.1 | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++
 Tools/plutil.m | 18 +++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 Tools/plutil.1

diff --git a/Tools/plutil.1 b/Tools/plutil.1
new file mode 100644
index 000000000..e1e5cdee1
--- /dev/null
+++ b/Tools/plutil.1
@@ -0,0 +1,83 @@
+.\"Copyright (C) 2020 Free Software Foundation, Inc.
+.\"Copying and distribution of this file, with or without modification,
+.\"are permitted in any medium without royalty provided the copyright
+.\"notice and this notice are preserved.
+.Dd September 23, 2020
+.Dt plutil 1
+.Os
+.Sh NAME
+.Nm plutil
+.Nd Property list utility
+.Sh SYNOPSIS
+.Nm progname
+.Op Fl command
+.Op Fl options
+.Ar file
+.Sh DESCRIPTION
+The
+.Nm
+utility can be used to edit property lists, to verify the syntax, or
+to convert from one format to another. If
+.Ql -
+is given as the file path, stdin and stdout are used.
+.Pp
+The first part is the action to perform, one of:
+.Bl -tag
+.It -p
+Print the whole plist to stdout, in the human-readable GNUStep format.
+.It -lint
+Verifies the plist can be parsed.
+.It -convert Ar FMT
+Converts the plist to another format.
+.Ql FMT
+can be one of:
+.Bl -tag
+.It xml1
+Apple XML.
+.It binary1
+Apple binary.
+.It openstep
+OpenStep (untyped human-readable).
+.It gnustep
+GNUStep (typed human-readable).
+.It json
+JSON (lossy human-readable).
+.El
+The NSPropertyListFormat names are accepted too.
+.It -insert Ar PATH Ar KEY Ar Value
+.El
+The default action is
+.Ql -lint.
+.Pp
+The general options are:
+.Bl -tag
+.El
+
+.Pp
+The plutil "keypath" is a dot-separated chain of keys for traversing
+a plist object. An empty keypath refers to the object itself. The
+format of keys conform to that of GNUStep plist string literals.
+
+.Sh IMPLEMENTATION NOTES
+.Bl
+.It
+Quoted strings in the keypath is a GNUStep extension.
+.It
+The Objective-C and Swift literal output formats are not yet implemented.
+.El
+.Sh EXIT STATUS
+.Pp 0 on success.
+.Sh EXAMPLES
+.Sh DIAGNOSTICS
+.Sh SEE ALSO
+.Xr pl 1
+.Xr pldes 1
+.Sh AUTHORS
+.An -nosplit
+This version of
+.Nm
+was written by
+.An Mingye Wang Aq Mt arthur2e5@aosc.io .
+.Nm
+first appeared in Mac OS X 10.2. It received path-related capabilities
+around Mac OS X 10.13.
diff --git a/Tools/plutil.m b/Tools/plutil.m
index 223d5201f..ace064d74 100644
--- a/Tools/plutil.m
+++ b/Tools/plutil.m
@@ -411,7 +411,25 @@ print_help(FILE *f)
   GSPrintf(f, @"Accepted commands:\n");
   GSPrintf(
     f, @"  -p\tPrints the plists in a human-readable form (GNUstep ASCII).\n");
+    GSPrintf(
+    f, @"  -lint\tVerifies the plist can be parsed.\n");
+    GSPrintf(
+    f, @"  -convert FMT\tConverts the plist to another format.\n");
+    GSPrintf(
+    f, @"  -insert PATH KEY VALUE\tInsert KEY=VALUE to the object at PATH.\n");
+    GSPrintf(
+    f, @"  -replace PATH KEY VALUE\tReplace KEY=VALUE for the object at PATH.\n");
+    GSPrintf(
+    f, @"  -remove PATH KEY\tRemove KEY from the object at PATH.\n");
+    GSPrintf(
+    f, @"  -extract PATH KEY\tExtract the KEY from the object at PATH.\n");
   GSPrintf(f, @"Accepted options:\n");
+  GSPrintf(
+    f, @"  -s\t(No effect.)\n");
+  GSPrintf(
+    f, @"  -o OUTFILE\tOutput to the file given.\n");
+  GSPrintf(
+    f, @"  -e OUTEXT\tOutput to a file with the given extension.\n")
 }
 
 typedef enum _Action