[kde-doc-english] [kaffeine] doc: add man page for kaffeine

[Burkhard Lück]

Git commit aa15d5e3773040c07045ba1c6a8e3e8d5f93ba1b by Burkhard Lück.
Committed on 08/06/2016 at 04:30.
Pushed by lueck into branch 'master'.

add man page for kaffeine

add new man page
debian policy requires it anyway
this should replace the outdated sect in the handbook
add a Files sect with infos about scanfile.dvb and how to add new channels
add  dvbv5-scan + w-scan
kf5options is still commented, cause we ship a horrible outdated version fron Qt 3.2 of that file
REVIEW:128096

M  +1    -0    doc/CMakeLists.txt
A  +163  -0    doc/man-kaffeine.1.docbook

http://commits.kde.org/kaffeine/aa15d5e3773040c07045ba1c6a8e3e8d5f93ba1b

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 06f05fb..c6445e9 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -1 +1,2 @@
 kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kaffeine)
+kdoctools_create_manpage (man-kaffeine.1.docbook 1 INSTALL_DESTINATION ${MAN_INSTALL_DIR})
diff --git a/doc/man-kaffeine.1.docbook b/doc/man-kaffeine.1.docbook
new file mode 100644
index 0000000..f231269
--- /dev/null
+++ b/doc/man-kaffeine.1.docbook
@@ -0,0 +1,163 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+<title>Kaffeine User's Manual</title>
+<author><personname>
+<firstname>Burkhard</firstname>
+<surname>Lück</surname>
+</personname>
+<email>lueck at hube-lueck.de</email></author>
+
+<date>2016-06-07</date>
+<releaseinfo>Kaffeine 2.0.3</releaseinfo>
+
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>Kaffeine</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>kaffeine</command></refname>
+<refpurpose>A media player by KDE with digital TV support</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>kaffeine</command>
+<arg choice="opt"><option>--tempfile</option></arg>
+<arg choice="opt"><option>-f, --fullscreen</option></arg>
+<arg choice="opt"><option>--audiocd</option></arg>
+<arg choice="opt"><option>--videocd</option></arg>
+<arg choice="opt"><option>--dvd</option></arg>
+<arg choice="opt"><option>--dumpdvb</option></arg>
+<arg choice="opt"><option>--channel <replaceable>name</replaceable> / <replaceable>number</replaceable></option></arg>
+<arg choice="opt"><option>--tv <replaceable>channel</replaceable></option></arg>
+<arg choice="opt"><option>--lastchannel</option></arg>
+<arg choice="opt"><option><replaceable>file</replaceable></option></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1>
+<title>Description</title>
+<para>Kaffeine is a media player. What makes it different from the others is
+its excellent support of digital TV (DVB). Kaffeine has user-friendly interface,
+so that even first time users can start immediately playing their movies:
+from DVD (including DVD menus, titles, chapters, etc.), VCD, or a file.</para>
+
+<para>Kaffeine uses libVLC as video/audio play backend.</para>
+
+</refsect1>
+
+<refsect1>
+<title>Options</title>
+
+<variablelist>
+<varlistentry>
+<term><option>--tempfile</option></term>
+<listitem><para>The files/URLs opened by the application will be deleted after use</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-f</option> <option>--fullscreen</option></term>
+<listitem><para>Start in full screen mode</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--audiocd</option></term>
+<listitem><para>Play Audio CD</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--videocd</option></term>
+<listitem><para>Play Video CD</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--dvd</option></term>
+<listitem><para>Play DVD</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--dumpdvb</option></term>
+<listitem><para>Dump dvb data (debug option)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--channel</option> <replaceable>name</replaceable> / <replaceable>number</replaceable></term>
+<listitem><para>Play TV channel</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--tv</option> <replaceable>channel</replaceable></term>
+<listitem><para>(deprecated option)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--lastchannel</option> </term>
+<listitem><para>Play last tuned TV channel</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option><replaceable>file</replaceable></option></term>
+<listitem><para>Files or URLs to play</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>Files</title>
+<para>
+Kaffeine uses the file <filename>scanfile.dvb</filename> with a list of known channels
+per locality and per Satellite (for DVB-S).</para>
+<para>
+When either new channels are added on some City, or when new Satellite beams are added,
+which are not available in Kaffeine, either use dvbv5-scan or w_scan to generate a new file
+(in the latter case, converted to the proper format using dvb-format-convert),
+and submit it to <email>linux-media at vger.kernel.org</email>, with the subject
+<quote>[PATCH] dtv-scan-tables: <replaceable>some description</replaceable></quote>.
+The new patch will be added to <filename>scanfile.dvb</filename> and the updated
+file will be available to be updated from the Internet in the Kaffeine application.
+</para>
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+<simplelist>
+<member>More detailed user documentation is available from <ulink
+url="help:/kaffeine ">help:/kaffeine</ulink>
+(either enter this &URL; into &konqueror;, or run
+<userinput><command>khelpcenter</command>
+<parameter>help:/kaffeine</parameter></userinput>).</member>
+<member>kf5options(1)</member>
+<!--<member>qt5options(1)</member>  only for application with a GUI FIXME use if we have an updated man page qt5options-->
+<member>dvbv5-scan(1)</member>
+<member>w-scan(1)</member>
+<member>There is also further information available at the
+<ulink url="https://www.kde.org/applications/multimedia/kaffeine/">Kaffeine Page</ulink></member>
+</simplelist>
+</refsect1>
+
+<refsect1>
+<title>Authors</title>
+<para>To list the authors of Kaffeine use <userinput><command>kaffeine</command> <option>--author</option></userinput> in a terminal.</para>
+</refsect1>
+
+</refentry>