Migrate to latest project structure

man/man1/tagger.1

@@ -0,0 +1,116 @@
+.Dd July 24, 2024
+.Dt tagger 1
+.Os
+.Sh NAME
+.Nm tagger
+.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
+.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
+tool allows you to list and/or edit tags in bulk, with a convenient command line
+interface.
+.Pp
+If you add, change, and delete tags from files and/or directories in a single
+command,
+.Nm
+will first delete tags, then apply changes, and finally add tags, in that order.
+.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
+.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.
+.Pp
+If you don't specify any
+.Sx Editing Options
+the
+.Fl l
+option is implied, and can be omitted.
+.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 or 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, if defined and non-empty.
+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
+.Nm
+exits 0 on success, and 1 if an error occurs.
+.Sh EXAMPLES
+To change `Biografie' into `Biography' in all files in the current directory,
+but only if present:
+.Pp
+.Dl tagger -c Biografie -i Biography *
+.Pp
+List the tags in a file named `MyMovie.mp4':
+.Pp
+.Dl tagger -l MyMovie.mp4
+.Pp
+or, simply:
+.Pp
+.Dl tagger MyMovie.mp4
+.Pp
+To delete all `foo' and `bar' tags from files, if present:
+.Pp
+.Dl tagger -d foo -d bar *
+.Pp
+.\" .Sh DIAGNOSTICS
+.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
+.Sh SEE ALSO
+.Xr xattr 7
+.Sh AUTHORS
+Bob Polis