man: Update manual for desktop-file-install/desktop-file-edit changes

2 files changed, 76 insertions, 20 deletions

diff --git a/man/desktop-file-install.1 b/man/desktop-file-install.1
index 1e4de02..8bd6a7e 100644
--- a/man/desktop-file-install.1
+++ b/man/desktop-file-install.1
@@ -4,20 +4,27 @@
 .\"
 .TH DESKTOP-FILE-INSTALL 1 FREEDESKTOP.ORG
 .SH NAME
-desktop-file-install \- Install desktop files
+desktop-file-install, desktop-file-edit \- Installation and edition of desktop files
 .SH SYNOPSIS
-.B desktop-file-install [\-\-delete-original] [\-\-dir=DIR]
-.B [\-m MODE|\-\-mode=MODE] [\-\-vendor=VENDOR] [\-\-rebuild-mime-info-cache]
+.B desktop-file-install [\-\-dir=DIR] [\-m MODE|\-\-mode=MODE]
+.B [\-\-vendor=VENDOR] [\-\-delete-original]
+.B [\-\-rebuild-mime-info-cache]
 .B [EDITOPTION]... FILE...
+.PP
+.B desktop-file-edit [EDITOPTION]... FILE
 .SH DESCRIPTION
-The \fIdesktop-file-install\fP program is a tool to install desktop
-files. It is mostly useful for developers and packagers. Various
-operations to edit the files can be realized thanks to the available
-options.
+The \fIdesktop-file-install\fP program is a tool to install, and
+optionally edit, desktop files. The \fIdesktop-file-edit\fP program is a
+tool to edit a desktop file. They are mostly useful for developers and
+packagers.
+.PP
+Various options are available to edit the desktop files. The edit
+options can be specified more than once and will be processed in the
+same order as the options passed to the program.
 .PP
-\fIdesktop-file-install\fP will always try to validate the resulting
-desktop file, and if it fails to do so, the installation will be
-aborted.
+\fIdesktop-file-install\fP and \fIdesktop-file-edit\fP will always try
+to validate the resulting desktop file. A failure to validate might lead
+to the abortion of the installation of the desktop files.
 .PP
 The list of registered categories and desktop environments is defined in
 the Menu specification:
@@ -25,10 +32,6 @@ the Menu specification:
 .SH OPTIONS
 The following options are supported:
 .TP
-.I --delete-original
-Delete the source desktop files, leaving only the target files.
-Effectively "renames" the desktop files.
-.TP
 .I --dir=DIR
 Install desktop files to the \fIDIR\fP directory.
 .TP
@@ -42,25 +45,52 @@ prefix, nothing happens; else, the file will be named
 \fBfreedesktop.org\fP and \fIFILE\fP is \fBspecification.desktop\fP, the
 result file will be \fBfreedesktop.org-specification.desktop\fP.
 .TP
+.I --delete-original
+Delete the source desktop files, leaving only the target files.
+Effectively "renames" the desktop files.
+.TP
 .I --rebuild-mime-info-cache
 Rebuild the MIME types application database after installing the desktop
 files. See \fIupdate-desktop-database(1)\fP for information about this
 database.
 .PP
-Various options are available to edit the desktop files. All of them can
-be specified more than once:
+.SH EDIT OPTIONS
+The following edit options are supported:
+.TP
+.I --set-key=KEY
+Set the KEY key to the value passed to the next \fI--set-value\fP
+option. A matching \fI--set-value\fP option is mandatory.
+.TP
+.I --set-value=VALUE
+Set the key specified with the previous \fI--set-key\fP option to VALUE.
+A matching \fI--set-key\fP option is mandatory.
+.TP
+.I --set-name=NAME
+Set the name (key \fBName\fP) to NAME. If a name was already set, it
+will be overridden. Localizations of the old name will be removed.
 .TP
 .I --copy-name-to-generic-name
 Copy the value of the \fBName\fP key to the \fBGenericName\fP key. Note
 that a desktop file requires a \fBName\fP key to be valid, so this
 option will always have an effect.
 .TP
+.I --set-generic-name=GENERIC-NAME
+Set the generic name (key \fBGenericName\fP) to GENERIC-NAME. If a
+generic name was already set, it will be overridden. Localizations of
+the old generic name will be removed.
+.TP
 .I --copy-generic-name-to-name
 Copy the value of the \fBGenericName\fP key to the \fBName\fP key, if
 the \fBGenericName\fP key is present.
 .TP
-.I --remove-key=KEY
-Remove the \fIKEY\fP key from the desktop files, if present.
+.I --set-comment=COMMENT
+Set the comment (key \fBComment\fP) to COMMENT. If a comment was already
+set, it will be overridden. Localizations of the old comment will be
+removed.
+.TP
+.I --set-icon=ICON
+Set the icon (key \fBIcon\fP) to ICON. If an icon was already set, it
+will be overridden. Localizations of the old icon will be removed.
 .TP
 .I --add-category=CATEGORY
 Add \fICATEGORY\fP to the list of categories (key \fBCategories\fP). If
@@ -83,7 +113,7 @@ If \fIMIME-TYPE\fP was not present in the list, this operation is a
 no-op.
 .TP
 .I --add-only-show-in=ENVIRONMENT
-Add \fIENVIRONMENT\fP to the list of desktop environment where the
+Add \fIENVIRONMENT\fP to the list of desktop environments where the
 desktop files should be displayed (key \fBOnlyShowIn\fP). If
 \fIENVIRONMENT\fP was already present in the list, this operation is a
 no-op. A non-registered desktop environment should be prefixed with
@@ -91,10 +121,27 @@ no-op. A non-registered desktop environment should be prefixed with
 means that the desktop file will be displayed in all environments.
 .TP
 .I --remove-only-show-in=ENVIRONMENT
-Remove \fIENVIRONMENT\fP from the list of desktop environment where the
+Remove \fIENVIRONMENT\fP from the list of desktop environments where the
 desktop files should be displayed (key \fBOnlyShowIn\fP). If
 \fIENVIRONMENT\fP was not present in the list, this operation is a
 no-op.
+.TP
+.I --add-not-show-in=ENVIRONMENT
+Add \fIENVIRONMENT\fP to the list of desktop environments where the
+desktop files should not be displayed (key \fBNotShowIn\fP). If
+\fIENVIRONMENT\fP was already present in the list, this operation is a
+no-op. A non-registered desktop environment should be prefixed with
+\fBX-\fP. Note that an empty \fBNotShowIn\fP key in a desktop file
+means that the desktop file will be displayed in all environments.
+.TP
+.I --remove-not-show-in=ENVIRONMENT
+Remove \fIENVIRONMENT\fP from the list of desktop environments where the
+desktop files should not be displayed (key \fBNotShowIn\fP). If
+\fIENVIRONMENT\fP was not present in the list, this operation is a
+no-op.
+.TP
+.I --remove-key=KEY
+Remove the \fIKEY\fP key from the desktop files, if present.
 .SH ENVIRONMENT
 Some environment variables change the behavior of
 \fIdesktop-file-install\fP:
@@ -110,6 +157,14 @@ will be ignored.
 This variable can be used as an alternative to the \fI--dir\fP
 option. If the \fI--dir\fP option is used, this environment variable
 will be ignored.
+.PP
+.B RPM_BUILD_ROOT
+.IP
+This variable is set when building RPM packages. If the \fI--dir\fP
+option and the \fBDESKTOP_FILE_INSTALL_DIR\fP environment variable are
+not used, it will automatically be prepended to the default install
+directory to install the desktop files appropriately when building
+packages.
 .SH BUGS
 If you find bugs in the \fIdesktop-file-install\fP program, please report
 these on https://bugs.freedesktop.org.
diff --git a/man/desktop-file-validate.1 b/man/desktop-file-validate.1
index 09ca564..9697c27 100644
--- a/man/desktop-file-validate.1
+++ b/man/desktop-file-validate.1
@@ -37,4 +37,5 @@ or of the \fBService\fP, \fBServiceType\fP and \fBFSDevice\fP types.
 If you find bugs in the \fIdesktop-file-validate\fP program, please
 report these on https://bugs.freedesktop.org.
 .SH SEE ALSO
+.BR desktop-file-edit(1)
 .BR desktop-file-install(1)