man/desktop-file-install.1

   1 .\"
   2 .\" desktop-file-install manual page.
   3 .\" (C) 2010 Vincent Untz (vuntz@gnome.org)
   4 .\"
   5 .TH DESKTOP-FILE-INSTALL 1 FREEDESKTOP.ORG
   6 .SH NAME
   7 desktop-file-install, desktop-file-edit \- Installation and edition of desktop files
   8 .SH SYNOPSIS
   9 .B desktop-file-install [\-\-dir=DIR] [\-m MODE|\-\-mode=MODE]
  10 .B [\-\-vendor=VENDOR] [\-\-delete-original]
  11 .B [\-\-rebuild-mime-info-cache]
  12 .B [EDITOPTION]... FILE...
  13 .PP
  14 .B desktop-file-edit [EDITOPTION]... FILE
  15 .SH DESCRIPTION
  16 The \fIdesktop-file-install\fP program is a tool to install, and
  17 optionally edit, desktop files. The \fIdesktop-file-edit\fP program is a
  18 tool to edit a desktop file. They are mostly useful for developers and
  19 packagers.
  20 .PP
  21 Various options are available to edit the desktop files. The edit
  22 options can be specified more than once and will be processed in the
  23 same order as the options passed to the program.
  24 .PP
  25 \fIdesktop-file-install\fP and \fIdesktop-file-edit\fP will always try
  26 to validate the resulting desktop file. A failure to validate might lead
  27 to the abortion of the installation of the desktop files.
  28 .PP
  29 The list of registered categories and desktop environments is defined in
  30 the Menu specification:
  31 \fIhttp://freedesktop.org/wiki/Specifications/menu-spec\fP.
  32 .SH OPTIONS
  33 The following options are supported:
  34 .TP
  35 .I --dir=DIR
  36 Install desktop files to the \fIDIR\fP directory.
  37 .TP
  38 .I -m, --mode=MODE
  39 Set the permissions of the destination files to \fIMODE\fP.
  40 .TP
  41 .I --vendor=VENDOR
  42 Add a vendor prefix to the desktop files. If a file already has this
  43 prefix, nothing happens; else, the file will be named
  44 \fIVENDOR\fP-\fIFILE\fP. For example: if \fIVENDOR\fP is
  45 \fBfreedesktop.org\fP and \fIFILE\fP is \fBspecification.desktop\fP, the
  46 result file will be \fBfreedesktop.org-specification.desktop\fP.
  47 .TP
  48 .I --delete-original
  49 Delete the source desktop files, leaving only the target files.
  50 Effectively "renames" the desktop files.
  51 .TP
  52 .I --rebuild-mime-info-cache
  53 Rebuild the MIME types application database after installing the desktop
  54 files. See \fIupdate-desktop-database(1)\fP for information about this
  55 database.
  56 .PP
  57 .SH EDIT OPTIONS
  58 The following edit options are supported:
  59 .TP
  60 .I --set-key=KEY
  61 Set the KEY key to the value passed to the next \fI--set-value\fP
  62 option. A matching \fI--set-value\fP option is mandatory.
  63 .TP
  64 .I --set-value=VALUE
  65 Set the key specified with the previous \fI--set-key\fP option to VALUE.
  66 A matching \fI--set-key\fP option is mandatory.
  67 .TP
  68 .I --set-name=NAME
  69 Set the name (key \fBName\fP) to NAME. If a name was already set, it
  70 will be overridden. Localizations of the old name will be removed.
  71 .TP
  72 .I --copy-name-to-generic-name
  73 Copy the value of the \fBName\fP key to the \fBGenericName\fP key. Note
  74 that a desktop file requires a \fBName\fP key to be valid, so this
  75 option will always have an effect.
  76 .TP
  77 .I --set-generic-name=GENERIC-NAME
  78 Set the generic name (key \fBGenericName\fP) to GENERIC-NAME. If a
  79 generic name was already set, it will be overridden. Localizations of
  80 the old generic name will be removed.
  81 .TP
  82 .I --copy-generic-name-to-name
  83 Copy the value of the \fBGenericName\fP key to the \fBName\fP key, if
  84 the \fBGenericName\fP key is present.
  85 .TP
  86 .I --set-comment=COMMENT
  87 Set the comment (key \fBComment\fP) to COMMENT. If a comment was already
  88 set, it will be overridden. Localizations of the old comment will be
  89 removed.
  90 .TP
  91 .I --set-icon=ICON
  92 Set the icon (key \fBIcon\fP) to ICON. If an icon was already set, it
  93 will be overridden. Localizations of the old icon will be removed.
  94 .TP
  95 .I --add-category=CATEGORY
  96 Add \fICATEGORY\fP to the list of categories (key \fBCategories\fP). If
  97 \fICATEGORY\fP was already present in the list, this operation is a
  98 no-op. A non-registered category should be prefixed with \fBX-\fP.
  99 .TP
 100 .I --remove-category=CATEGORY
 101 Remove \fICATEGORY\fP from the list of categories (key
 102 \fBCategories\fP). If \fICATEGORY\fP was not present in the list, this
 103 operation is a no-op.
 104 .TP
 105 .I --add-mime-type=MIME-TYPE
 106 Add \fIMIME-TYPE\fP to the list of MIME types (key \fBMimeType\fP). If
 107 \fIMIME-TYPE\fP was already present in the list, this operation is a
 108 no-op.
 109 .TP
 110 .I --remove-mime-type=MIME-TYPE
 111 Remove \fIMIME-TYPE\fP from the list of MIME types (key \fBMimeType\fP).
 112 If \fIMIME-TYPE\fP was not present in the list, this operation is a
 113 no-op.
 114 .TP
 115 .I --add-only-show-in=ENVIRONMENT
 116 Add \fIENVIRONMENT\fP to the list of desktop environments where the
 117 desktop files should be displayed (key \fBOnlyShowIn\fP). If
 118 \fIENVIRONMENT\fP was already present in the list, this operation is a
 119 no-op. A non-registered desktop environment should be prefixed with
 120 \fBX-\fP. Note that an empty \fBOnlyShowIn\fP key in a desktop file
 121 means that the desktop file will be displayed in all environments.
 122 .TP
 123 .I --remove-only-show-in=ENVIRONMENT
 124 Remove \fIENVIRONMENT\fP from the list of desktop environments where the
 125 desktop files should be displayed (key \fBOnlyShowIn\fP). If
 126 \fIENVIRONMENT\fP was not present in the list, this operation is a
 127 no-op.
 128 .TP
 129 .I --add-not-show-in=ENVIRONMENT
 130 Add \fIENVIRONMENT\fP to the list of desktop environments where the
 131 desktop files should not be displayed (key \fBNotShowIn\fP). If
 132 \fIENVIRONMENT\fP was already present in the list, this operation is a
 133 no-op. A non-registered desktop environment should be prefixed with
 134 \fBX-\fP. Note that an empty \fBNotShowIn\fP key in a desktop file
 135 means that the desktop file will be displayed in all environments.
 136 .TP
 137 .I --remove-not-show-in=ENVIRONMENT
 138 Remove \fIENVIRONMENT\fP from the list of desktop environments where the
 139 desktop files should not be displayed (key \fBNotShowIn\fP). If
 140 \fIENVIRONMENT\fP was not present in the list, this operation is a
 141 no-op.
 142 .TP
 143 .I --remove-key=KEY
 144 Remove the \fIKEY\fP key from the desktop files, if present.
 145 .SH ENVIRONMENT
 146 Some environment variables change the behavior of
 147 \fIdesktop-file-install\fP:
 148 .PP
 149 .B DESKTOP_FILE_VENDOR
 150 .IP
 151 This variable can be used as an alternative to the \fI--vendor\fP
 152 option. If the \fI--vendor\fP option is used, this environment variable
 153 will be ignored.
 154 .PP
 155 .B DESKTOP_FILE_INSTALL_DIR
 156 .IP
 157 This variable can be used as an alternative to the \fI--dir\fP
 158 option. If the \fI--dir\fP option is used, this environment variable
 159 will be ignored.
 160 .PP
 161 .B RPM_BUILD_ROOT
 162 .IP
 163 This variable is set when building RPM packages. If the \fI--dir\fP
 164 option and the \fBDESKTOP_FILE_INSTALL_DIR\fP environment variable are
 165 not used, it will automatically be prepended to the default install
 166 directory to install the desktop files appropriately when building
 167 packages.
 168 .SH BUGS
 169 If you find bugs in the \fIdesktop-file-install\fP program, please report
 170 these on https://bugs.freedesktop.org.
 171 .SH SEE ALSO
 172 .BR desktop-file-validate(1)
 173 .BR update-desktop-database(1)