[kaffeine] doc: doc: improve Kaffeine's handbook manual
Mauro Carvalho Chehab
null at kde.org
Mon Nov 13 11:00:16 UTC 2017
Git commit 5031844c6cecbf793f47a369a1c3970e0598ba0e by Mauro Carvalho Chehab.
Committed on 13/11/2017 at 10:58.
Pushed by mauroc into branch 'master'.
doc: improve Kaffeine's handbook manual
Add explanations about the generic TV settings and improve
descriptions for the EPG and recording schedule windows.
Signed-off-by: Mauro Carvalho Chehab <mchehab at osg.samsung.com>
M +230 -28 doc/index.docbook
A +- -- doc/kaffeine_configure_tv_general_opts.png
M +- -- doc/kaffeine_program_guide.png
https://commits.kde.org/kaffeine/5031844c6cecbf793f47a369a1c3970e0598ba0e
diff --git a/doc/index.docbook b/doc/index.docbook
index 6ce5f13..da6c144 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -32,7 +32,7 @@
<othername>Carvalho</othername>
<surname>Chehab</surname>
<affiliation>
-<address><email>mchehab at infradead.org</email></address>
+<address><email>mchehab+kde at kernel.org</email></address>
</affiliation>
</author>
</authorgroup>
@@ -42,12 +42,13 @@
<copyright>
<year>2004</year>
<year>2016</year>
+<year>2017</year>
<holder>The &kaffeine; Authors</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
-<date>2016-06-26</date>
-<releaseinfo>&kaffeine; 2.0.4</releaseinfo>
+<date>2017-11-11</date>
+<releaseinfo>&kaffeine; 2.0.14</releaseinfo>
<!-- Abstract about this handbook -->
@@ -64,6 +65,7 @@
<keyword>audio</keyword>
<keyword>mp3</keyword>
<keyword>dvd</keyword>
+<keyword>atsc</keyword>
<keyword>dvb-t</keyword>
<keyword>dvb-c</keyword>
<keyword>dvb-s</keyword>
@@ -153,23 +155,154 @@ on the player window to create a new playlist. To change a playlist name edit it
<!-- https://blogs.s-osg.org/watching-digital-tv-via-kaffeine/-->
<sect1 id="digital-tv">
-<title>Graphical User Interface for Digital TV</title>
+<title>Digital TV configuration</title>
<para>While the basic functionality is useful enough for someone who wants a simple, yet powerful
media player, the best feature in &kaffeine; is to use it as a &GUI; frontend to watch and record digital TV.
</para>
-<para>In &kaffeine; version 2.0, the digital TV support was extended to support DVB-T2 and ISDB-T.
-Since it now uses libdvbv5, extending support for other digital TV standards is simple.
-Also, since it uses the &Linux; DVB version 5 API, it supports frontends capable of implementing multiple TVs at once.
+<para>Since &kaffeine; version 2.0, the digital TV support uses libdvbv5 and
+was extended to support new standards like DVB-T2 and ISDB-T. Extending its
+support for newer digital TV standards is now simpler.
+Also, since it uses the &Linux; DVB version 5 API, it supports frontends
+capable of implementing multiple digital TV standards.
</para>
-<para>Setting the TV configuration on &kaffeine; is as simple as clicking on the <guimenu>Television</guimenu> pop up menu,
-and selecting the <guimenuitem>Configure Television</guimenuitem> option. A pop up window will open that requests the parameters to be used:
+<para>Setting the TV configuration on &kaffeine; is as simple as clicking on
+the <guimenu>Television</guimenu> pop up menu, and selecting the
+<guimenuitem>Configure Television</guimenuitem> option. A pop up window
+will open, allowing setting the parameters to be used:
</para>
<screenshot>
-<screeninfo>TV Configuration</screeninfo>
+<screeninfo>TV Configuration - General Options</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="kaffeine_configure_tv_general_opts.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>TV Configuration - General Options</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<sect2 id="dtv-general-opts">
+<title>General digital TV settings</title>
+
+<para>
+The <guimenu>General Options</guimenu> menu allows setting the
+device-independent settings.
+</para>
+
+<para>
+The <guilabel>Recording folder</guilabel> sets the location where all TV
+program records will be stored.
+</para>
+
+<para>
+The <guilabel>Time shift folder</guilabel> is used in conjunction with the
+pause button
+(<inlinemediaobject><imageobject><imagedata fileref="media-playback-pause.png" format="PNG"/></imageobject></inlinemediaobject>) of the media player screen. When the button
+is pressed, a time shift file will be stored at the location pointed by this
+menu option.
+</para>
+
+<para>
+The <guilabel>Begin margin</guilabel> and <guilabel>End margin</guilabel>
+options are used to setup a sort of <quote>security margin</quote> in order
+to avoid losing the beginning and the end of a program, as the time stamps at
+the program guide may not be precise. So, it actually starts recording a few
+minutes before the <guilabel>Start</guilabel> time defined at the
+<guimenu>Program Guide</guimenu>. The exact amount of time before is
+defined via <guilabel>Begin margin</guilabel>. It extends the
+record by the amount of time defined by <guilabel>End margin</guilabel>.
+after the end of the program.
+</para>
+
+<para>
+The <guilabel>Naming style for recordings</guilabel> is used to setup how
+&kaffeine; will name a program. Several macros can be used to dynamically
+change the name of the record:
+</para>
+<itemizedlist mark='opencircle'>
+<listitem>
+<para>
+<parameter>%title</parameter> - Title of the program, as seen at the
+<guimenu>Program Guide</guimenu> and <guimenu>Recording Schedule</guimenu>
+menus;
+</para>
+</listitem>
+<listitem>
+<para>
+<parameter>%day, %month, %year, %hour, %min, %sec</parameter> - Fields from the
+time stamp with represents the time when &kaffeine; starts recording a program;
+</para>
+</listitem>
+<listitem>
+<para>
+<parameter>%channel</parameter> - Name of the channel that streamed the program.
+</para>
+</listitem>
+</itemizedlist>
+
+<para>
+The <guilabel>Action after recording finishes</guilabel> option is used to
+setup an optional command to be executed when &kaffeine; stops recording a
+program.
+</para>
+
+<para>
+Cliking at the <guilabel>Update Scan Data over Internet</guilabel> option
+makes &kaffeine; to check if a new channel scanning definition file is
+present at <ulink url="https://autoconfig.kde.org/kaffeine/">
+KDE's site</ulink>.
+</para>
+<para>
+&kaffeine; uses a file called scanfile.dvb with stores a list of known
+digital TV channels per Country and City. This file is kept in sync with
+the contents of <ulink url="https://git.linuxtv.org/dtv-scan-tables.git">the
+dtv-scan-tables tree</ulink>, maintained
+by <ulink url="https://linuxtv.org">LinuxTV</ulink> community. For more details,
+please see <ulink url="https://linuxtv.org/wiki/index.php/Dtv-scan-tables">the
+dtv-scan-tables wiki page</ulink>.
+</para>
+<para>
+When the button is clicked, &kaffeine; will download the latest version of the
+channel definitions and store on a user-specific local data file, overriding
+any contents of a previous one.
+</para>
+<para>Please notice that, in order to use the newest definitions, it is
+required to close the TV configuration dialog and reopen.</para>
+
+<para>
+The <guilabel>Edit scanfile</guilabel> option allows
+editing the file, with can be useful to add a new set of channels, while
+the upstream file is not updated. If you need to use it, please consider
+sending an update to
+<ulink url="https://git.linuxtv.org/dtv-scan-tables.git/">dtv-scan-tables
+</ulink> for others to also benefit for the new channel definitions.
+</para>
+
+<para>
+The <guilabel>Use ISO 8859-1 charset instead of ISO 6937</guilabel>
+option allows to select the default to be used on MPEG-TS messages
+that don't explicitly set a charset. If not set, it defaults to using
+ISO-6937 encoding. If set, the default changes to ISO 8859-1.
+</para>
+
+<para>
+The <guilabel>Create info files to accompany EPG recordings</guilabel>
+option enables the creation of an ancillary files for scheduled records
+with the contents of the program guide for records made via the
+<guimenu>Program guide</guimenu>.
+</para>
+
+</sect2>
+<sect2 id="dtv-source-settings">
+<title>Configuring digital TV sources</title>
+
+<screenshot>
+<screeninfo>TV Device Configuration</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kaffeine_configure_tv_isdb_device.png" format="PNG"/>
@@ -186,6 +319,10 @@ combo box (or using one of the Autoscan sources) is enough for non-satellite con
The same happens for devices that support multiple TV standards:
</para>
+</sect2>
+<sect2 id="dtv-channel-setup">
+<title>Digital TV channel setup</title>
+
<screenshot>
<screeninfo>Channel Configuration</screeninfo>
<mediaobject>
@@ -203,6 +340,7 @@ After clicking on the <guibutton>Ok</guibutton> button, the next step is to scan
the Television pop up menu, option <guimenuitem>Channels</guimenuitem>:
</para>
+
<screenshot>
<screeninfo>Scanning Channels</screeninfo>
<mediaobject>
@@ -216,9 +354,28 @@ the Television pop up menu, option <guimenuitem>Channels</guimenuitem>:
</screenshot>
<para>
-If more then one standard is supported, the <guilabel>Source</guilabel> combo box will allow you to select the
-one that will be used to scan. Don’t forget to connect the device’s antenna cable to match
-the standard that will be used. Then, click <guibutton>Start Scan</guibutton> to start scanning for channels.
+If more then one standard is supported, the <guilabel>Source</guilabel>
+combo box will allow you to select the one that will be used to scan. Don't
+forget to connect the device's antenna cable to match the standard that
+will be used.
+</para>
+
+<para>
+When &kaffeine; identifies a channel, it reads a <acronym>MPEG-TS</acronym>
+table called Network Information Table (<acronym>NIT</acronym>), with contains
+information about channels using different tuning parameters transmitted by
+the same broadcaster. On certain networks, it is possible that some tuning
+parameters to be stored on several <acronym>NIT</acronym> tables
+(called <quote>other NITs</quote>). This is more common on some cable and
+satellite systems. By selecting <guilabel>Search transponders for other
+Networks</guilabel>, &kaffeine; is instructed to wait and parse all other
+<acronym>NITs</acronym>, with may make it to find more channels, at the cost
+of taking a lot more time to complete the channel scan operation.
+</para>
+
+<para>
+The channel scan operation is started by clicking at
+<guibutton>Start Scan</guibutton>.
Once finished, the discovered channels will appear on the right. These channels can be copied
to the left side by clicking <guibutton>Add Filtered</guibutton>. It is possible to check the tuning parameters
for the channel in the left side by clicking on the <guibutton>Edit</guibutton> button.
@@ -241,6 +398,11 @@ Some parameters are adjustable in the window that pops up.
Once the channels are saved, watching TV is as simple as clicking on the <guibutton>Digital TV</guibutton> button in the main window:
</para>
+</sect2>
+</sect1>
+<sect1 id="dtv-watching">
+<title>Watching TV</title>
+
<screenshot>
<screeninfo>Watching TV</screeninfo>
<mediaobject>
@@ -265,16 +427,15 @@ that allows you to quick record and save the program to disk.
</para>
</sect1>
+<sect1 id="program-guide">
+<title>Program Guide</title>
-<sect1 id="recording-programs">
-<title>Recording Programs</title>
-
-<para>Besides clicking on the record button
-<inlinemediaobject><imageobject><imagedata fileref="document-save.png" format="PNG"/></imageobject></inlinemediaobject>
-when the live view is opened, &kaffeine; has other ways to record a program.
-One method is to select the program to be recorded using the <guimenu>Television</guimenu> pop up menu
-and selecting the <guimenuitem>Program Guide</guimenuitem> option.
-It will present a list of programs that were identified on a previously played program:
+<para>
+Digital TV channels usually transmit a list of the current and future
+attractions. This is called Electronic Program Guide - <acronym>EPG</acronym>.
+The EPG data is captured when a channel's content is played.
+To see the <acronym>EPG</acronym>, open the <guimenu>Television</guimenu>
+pop up menu and select the <guimenuitem>Program Guide</guimenuitem> option:
</para>
<screenshot>
@@ -290,10 +451,37 @@ It will present a list of programs that were identified on a previously played p
</screenshot>
<para>
-Clicking on the
+On some Countries, the EPG may be availabe on multiple languages. By
+default, &kaffeine; shows any languages on EPG. If multiple languages
+are available for a given EPG entry, and no explicit language content is
+select, it will prefix the title, subtitle and description data with a 3
+code language code, as defined by ISO 639-2 specification.
+</para>
+
+<para>
+The <guilabel>EPG Language</guilabel> option allows to filter just one
+language. If enabled, the filter will also be applied to the On
+Screen Display - <acronym>OSD</acronym> and to any new scheduled
+recordings. It won't affect pre-existing scheduled recordings.
+</para>
+
+<para>Besides clicking on the record button
+<inlinemediaobject><imageobject><imagedata fileref="document-save.png" format="PNG"/></imageobject></inlinemediaobject>
+when the live view is opened, &kaffeine; also allows to record a program
+via the program guide, by clicking on the
<inlinemediaobject><imageobject><imagedata fileref="media-record.png" format="PNG"/></imageobject></inlinemediaobject>
-<guibutton>Record Show</guibutton> button will mark the program to be recorded. The record needs to be enabled
-via the <guilabel>Recording Schedule</guilabel> option, also located in the <guimenu>Television</guimenu> menu:
+<guibutton>Record Show</guibutton> at the
+<guimenuitem>Program Guide</guimenuitem> window.
+</para>
+
+</sect1>
+<sect1 id="recording-schedule">
+<title>Recording Schedule</title>
+
+<para>
+To see the programs that are scheduled to be recorded, open the
+<guimenu>Television</guimenu> pop up menu and select the
+<guimenuitem>Recording Schedule</guimenuitem> option:
</para>
<screenshot>
@@ -309,8 +497,22 @@ via the <guilabel>Recording Schedule</guilabel> option, also located in the <gui
</screenshot>
<para>
-By clicking one the <guibutton>New</guibutton> button, it is also possible to directly define a time and duration for a program to be recorded.
+By clicking one the <guibutton>New</guibutton> button, it is possible
+to directly define a time and duration for a program to be recorded.
+In this case, it won't use the EPG definitions.
</para>
+<para>
+By selecting an existing program and clicking at the
+<guibutton>Edit</guibutton> button, you may change the start time
+and the record duration. You may also program it to be recorded
+weekly or daily.
+</para>
+<para>
+By selecting an existing program and clicking at the
+<guibutton>Remove</guibutton> button, it will remove the program from
+the recording schedule.
+</para>
+
</sect1>
</chapter>
@@ -319,12 +521,12 @@ By clicking one the <guibutton>New</guibutton> button, it is also possible to di
<title>Copyright and License</title>
<para>
-Program copyright 2007-2016, The &kaffeine; Authors
+Program copyright 2007-2017, The &kaffeine; Authors
</para>
<para>
Documentation copyright 2003-2005, Jürgen Kofler <email>kaffeine at gmx.net</email>,
-Christophe Thommeret <email>hftom at free.fr</email>, Mauro Carvalho Chehab <email>mchehab at infradead.org</email>
+Christophe Thommeret <email>hftom at free.fr</email>, Mauro Carvalho Chehab <email>mchehab+kde at kernel.org</email>
</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
diff --git a/doc/kaffeine_configure_tv_general_opts.png b/doc/kaffeine_configure_tv_general_opts.png
new file mode 100644
index 0000000..069a3bd
Binary files /dev/null and b/doc/kaffeine_configure_tv_general_opts.png differ
diff --git a/doc/kaffeine_program_guide.png b/doc/kaffeine_program_guide.png
index 6d416f6..8e2eec2 100644
Binary files a/doc/kaffeine_program_guide.png and b/doc/kaffeine_program_guide.png differ
More information about the kde-doc-english
mailing list