Add man page

tagger.1

@@ -1,59 +1,88 @@
-.Dd $Mdocdate$
+.Dd July 21, 2024
 .Dt tagger 1
 .Os
 .Sh NAME
 .Nm tagger
-.Nd one line about what it does
-.\" .Sh LIBRARY
-.\" For sections 2, 3, and 9	only.
-.\" Not used in OpenBSD.
+.Nd Show and edit file system tags, stored as extended attribute
 .Sh SYNOPSIS
 .Nm
 .Fl h
 .Nm
 .Fl \-version
 .Nm
+.Op Fl a Ar tag
+.Op Fl d Ar tag
+.Op Fl c Ar tag Fl i Ar tag
+.Op Fl l
+.Op Fl s
 .Op Ar
 .Sh DESCRIPTION
+On Linux file systems that support extended attributes, the XDG desktop uses the
+attribute `user.xdg.tags' to store a comma-separated list of user-defined tags.
+File browsers such as Dolphin on KDE have user interface to manipulate them.
+Unfortunately, it is inconvenient if one wishes to change tags for many files or
+directories at once.
 The
 .Nm
-utility processes files ...
-When no file arguments are given,
-.Nm
-will read from the standard input.
+tool allows you to list and/or edit tags in bulk, with a convenient command line
+interface.
 .Pp
 The options are as follows:
+.Ss General Options
 .Bl -tag -width Ds
 .It Fl h, \-help
 Print help text and exit.
 .It Fl \-version
 Print version info and exit.
 .El
-.\" .Sh CONTEXT
-.\" For section 9 functions only.
-.\" .Sh IMPLEMENTATION NOTES
-.\" Not used in OpenBSD.
-.\" .Sh RETURN VALUES
-.\" For sections 2, 3, and 9 function return values only.
-.\" .Sh ENVIRONMENT
-.\" For sections 1, 6, 7, and 8 only.
-.\" .Sh FILES
+.Ss Listing tags
+.Bl -tag -width Ds
+.It Fl l, \-list
+List tags.
+If you also specify any
+.Sx Editing Options
+(see below),
+.Nm
+reports tags before and after applying any changes.
+.El
+.Ss Editing Options
+.Bl -tag -width Ds
+.It Fl a, \-add Ar tag
+Add the specified tag.
+This option can be used multiple times.
+.It Fl c, \-change Ar tag
+Change the given tag, into a new value supplied as an argument for the
+.Fl i
+option (see below).
+.It Fl i, \-into Ar tag
+Change the value given with the last
+.Fl c
+option into the new value given here.
+These pairs of
+.Fl c
+and
+.Fl i
+options can be used multiple times.
+.It Fl d, \-delete Ar tag
+Delete the given tag, if it exists.
+This option can be used multiple times.
+.It Fl s, \-sort
+With this flag, changes will be written back for the file of directory in
+alphabetically sorted order.
+.El
+.Sh ENVIRONMENT
+.Nm
+uses libscterm for its color output support, and as such honors the NO_COLOR
+environment variable.
+Color output is also automatically suppressed when it is not written to a tty,
+such as when writing to a pipe, or when using output redirection.
 .Sh EXIT STATUS
-.\" For sections 1, 6, and 8 only.
 .Nm
 exits 0 on success, and 1 if an error occurs.
 .\" .Sh EXAMPLES
 .\" .Sh DIAGNOSTICS
 .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
-.\" .Sh ERRORS
-.\" For sections 2, 3, 4, and 9 errno settings only.
-.\" .Sh SEE ALSO
-.\" .Xr foobar 1
-.\" .Sh STANDARDS
-.\" .Sh HISTORY
+.Sh SEE ALSO
+.Xr xattr 7
 .Sh AUTHORS
 Bob Polis
-.\" .Sh CAVEATS
-.\" .Sh BUGS
-.\" .Sh SECURITY CONSIDERATIONS
-.\" Not used in OpenBSD.