Add man pages

6 files changed, 240 insertions, 2 deletions

diff --git a/Makefile.am b/Makefile.am
index 2894c9f..734c480 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,4 +1,4 @@
-SUBDIRS = src misc
+SUBDIRS = man misc src
 
 ACLOCAL_AMFLAGS = -I m4
 
diff --git a/configure.ac b/configure.ac
index 948666f..0d94a65 100644
--- a/configure.ac
+++ b/configure.ac
@@ -102,8 +102,9 @@ AM_PATH_LISPDIR
 
 AC_CONFIG_FILES([
 Makefile
-src/Makefile
+man/Makefile
 misc/Makefile
+src/Makefile
 ])
 
 AC_OUTPUT
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..ac56bb7
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,8 @@
+man_MANS =					\
+	desktop-file-validate.1			\
+	desktop-file-install.1			\
+	update-desktop-database.1
+
+EXTRA_DIST = $(man_MANS)
+
+-include $(top_srcdir)/git.mk
diff --git a/man/desktop-file-install.1 b/man/desktop-file-install.1
new file mode 100644
index 0000000..1e4de02
--- /dev/null
+++ b/man/desktop-file-install.1
@@ -0,0 +1,118 @@
+.\"
+.\" desktop-file-install manual page.
+.\" (C) 2010 Vincent Untz (vuntz@gnome.org)
+.\"
+.TH DESKTOP-FILE-INSTALL 1 FREEDESKTOP.ORG
+.SH NAME
+desktop-file-install \- Install desktop files
+.SH SYNOPSIS
+.B desktop-file-install [\-\-delete-original] [\-\-dir=DIR]
+.B [\-m MODE|\-\-mode=MODE] [\-\-vendor=VENDOR] [\-\-rebuild-mime-info-cache]
+.B [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.
+.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.
+.PP
+The list of registered categories and desktop environments is defined in
+the Menu specification:
+\fIhttp://freedesktop.org/wiki/Specifications/menu-spec\fP.
+.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
+.I -m, --mode=MODE
+Set the permissions of the destination files to \fIMODE\fP.
+.TP
+.I --vendor=VENDOR
+Add a vendor prefix to the desktop files. If a file already has this
+prefix, nothing happens; else, the file will be named
+\fIVENDOR\fP-\fIFILE\fP. For example: if \fIVENDOR\fP is
+\fBfreedesktop.org\fP and \fIFILE\fP is \fBspecification.desktop\fP, the
+result file will be \fBfreedesktop.org-specification.desktop\fP.
+.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:
+.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 --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.
+.TP
+.I --add-category=CATEGORY
+Add \fICATEGORY\fP to the list of categories (key \fBCategories\fP). If
+\fICATEGORY\fP was already present in the list, this operation is a
+no-op. A non-registered category should be prefixed with \fBX-\fP.
+.TP
+.I --remove-category=CATEGORY
+Remove \fICATEGORY\fP from the list of categories (key
+\fBCategories\fP). If \fICATEGORY\fP was not present in the list, this
+operation is a no-op.
+.TP
+.I --add-mime-type=MIME-TYPE
+Add \fIMIME-TYPE\fP to the list of MIME types (key \fBMimeType\fP). If
+\fIMIME-TYPE\fP was already present in the list, this operation is a
+no-op.
+.TP
+.I --remove-mime-type=MIME-TYPE
+Remove \fIMIME-TYPE\fP from the list of MIME types (key \fBMimeType\fP).
+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
+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
+\fBX-\fP. Note that an empty \fBOnlyShowIn\fP key in a desktop file
+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
+desktop files should be displayed (key \fBOnlyShowIn\fP). If
+\fIENVIRONMENT\fP was not present in the list, this operation is a
+no-op.
+.SH ENVIRONMENT
+Some environment variables change the behavior of
+\fIdesktop-file-install\fP:
+.PP
+.B DESKTOP_FILE_VENDOR
+.IP
+This variable can be used as an alternative to the \fI--vendor\fP
+option. If the \fI--vendor\fP option is used, this environment variable
+will be ignored.
+.PP
+.B DESKTOP_FILE_INSTALL_DIR
+.IP
+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.
+.SH BUGS
+If you find bugs in the \fIdesktop-file-install\fP program, please report
+these on https://bugs.freedesktop.org.
+.SH SEE ALSO
+.BR desktop-file-validate(1)
+.BR update-desktop-database(1)
diff --git a/man/desktop-file-validate.1 b/man/desktop-file-validate.1
new file mode 100644
index 0000000..09ca564
--- /dev/null
+++ b/man/desktop-file-validate.1
@@ -0,0 +1,40 @@
+.\"
+.\" desktop-file-validate manual page.
+.\" (C) 2010 Vincent Untz (vuntz@gnome.org)
+.\"
+.TH DESKTOP-FILE-VALIDATE 1 FREEDESKTOP.ORG
+.SH NAME
+desktop-file-validate \- Validate desktop entry files
+.SH SYNOPSIS
+.B desktop-file-validate [\-\-no-warn-deprecated] [\-\-warn-kde] FILE...
+.SH DESCRIPTION
+The \fIdesktop-file-validate\fP program is a tool to validate desktop
+entry files according to the Desktop Entry specification 1.0.
+.PP
+The specification describes a file format to provide information such as
+name, icon and description for an application. Such a file can then be
+used as an application launcher and to display the application in the
+applications menu.
+.PP
+For information about the Desktop Entry specification, see
+\fIhttp://freedesktop.org/wiki/Specifications/desktop-entry-spec\fP.
+.PP
+The desktop entry files are commonly called \fBdesktop files\fP.
+.SH OPTIONS
+The following options are supported:
+.TP
+.I --no-warn-deprecated
+Do not warn about usage of deprecated items that were defined in
+previous versions of the specification.
+.TP
+.I --warn-kde
+Warn about usage of KDE extensions to the specification. This includes
+the use of the \fBKDE Desktop Entry\fP group, of the \fBServiceTypes\fP,
+\fBDocPath\fP, \fBKeywords\fP, \fBInitialPreference\fP, \fBDev\fP,
+\fBFSType\fP, \fBMountPoint\fP, \fBReadOnly\fP, \fBUnmountIcon\fP keys,
+or of the \fBService\fP, \fBServiceType\fP and \fBFSDevice\fP types.
+.SH BUGS
+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-install(1)
diff --git a/man/update-desktop-database.1 b/man/update-desktop-database.1
new file mode 100644
index 0000000..5a177c3
--- /dev/null
+++ b/man/update-desktop-database.1
@@ -0,0 +1,71 @@
+.\"
+.\" update-desktop-database manual page.
+.\" (C) 2010 Vincent Untz (vuntz@gnome.org)
+.\"
+.TH DESKTOP-FILE-VALIDATE 1 FREEDESKTOP.ORG
+.SH NAME
+update-desktop-database \- Build cache database of MIME types handled by
+desktop files
+.SH SYNOPSIS
+.B update-desktop-database [\-q|\-\-quiet] [\-v|\-\-verbose] [DIRECTORY...]
+.SH DESCRIPTION
+The \fIupdate-desktop-database\fP program is a tool to build a cache
+database of the MIME types handled by desktop files.
+.PP
+The cache database contains the list of MIME types that can be handled
+by desktop files, as well as, for each MIME type, a list of desktop
+files that can handle this MIME type. This cache database ease the work
+of applications that need to find an application that can open a
+document of a specific MIME type: those applications will not have to
+parse all the desktop files existing on the system, and can instead
+parse this cache database.
+.PP
+If no \fIDIRECTORY\fP is specified as argument, the desktop files that
+will be processed are the ones installed in
+\fB$XDG_DATA_DIRS/applications\fP.
+.PP
+If both the \fI--quiet\fP and \fI--verbose\fP options are used, then
+\fI--verbose\fP will be ignored.
+.SH OPTIONS
+The following options are supported:
+.TP
+.I -q, --quiet
+Do not display any information about processing and updating progress.
+.TP
+.I -v, --verbose
+Display more information about processing and updating progress.
+.SH NOTES
+.PP
+If an invalid MIME type is met, it will be ignored and the creation of
+the cache database will continue.
+.PP
+The format of the cache database is a simple desktop entry format, with
+a \fBMIME Cache\fP group, containing one key per MIME type. The key
+name is the MIME type, and the key value is the list of desktop file
+that can handle this MIME type.
+.PP
+The order of the desktop files found for a MIME type is not significant.
+Therefore, an external mechanism must be used to determine what is the
+preferred desktop file for a MIME type.
+.SH EXAMPLE
+Here is a simple example of a cache database:
+.IP
+ [MIME Cache]
+ application/x-shellscript=gedit.desktop;
+ text/plain=gedit.desktop;gvim.desktop;
+ video/webm=totem.desktop;
+.PP
+This cache database is created with three desktop files, each containing
+a \fBMimeType\fP key:
+.IP
+ \fBgedit.desktop\fP: MimeType=text/plain;application/x-shellscript;
+ \fBgvim.desktop\fP: MimeType=text/plain;
+ \fBtotem.desktop\fP: MimeType=video/webm;
+.SH FILES
+.PP
+.B $XDG_DATA_DIRS/applications/mimeinfo.cache
+.IP
+This file is the cache database created by \fIupdate-desktop-database\fP.
+.SH BUGS
+If you find bugs in the \fIupdate-desktop-database\fP program, please
+report these on https://bugs.freedesktop.org.