[kate] doc/kate: Update kate docbooks to 18.04

Mon Mar 26 05:05:14 UTC 2018

Git commit 0f06e1172f7d24096971557ac9a05df48d21f395 by Burkhard Lück.
Committed on 26/03/2018 at 05:04.
Pushed by lueck into branch 'master'.

Update kate docbooks to 18.04

proofread
bump date + releaseinfo
add info how to use a non default tmp folder
expand explanation/usecase for option --desktopfile
add document preview plugin, infos from https://frinring.wordpress.com/

Differential Revision: https://phabricator.kde.org/D11592

M  +16   -2    doc/kate/fundamentals.docbook
M  +3    -3    doc/kate/index.docbook
M  +91   -0    doc/kate/plugins.docbook

https://commits.kde.org/kate/0f06e1172f7d24096971557ac9a05df48d21f395

diff --git a/doc/kate/fundamentals.docbook b/doc/kate/fundamentals.docbook
index 28616efdf..c4878e92e 100644
--- a/doc/kate/fundamentals.docbook
+++ b/doc/kate/fundamentals.docbook
@@ -61,6 +61,15 @@ of &kde;'s network transparency to open files on the internet.
 </screen>
 </informalexample>
 
+<para>To change the directory for temporary files, which defaults to <filename class="directory">/tmp</filename>
+set the <envar>TMPDIR</envar> environment variable before starting &kate;, ⪚
+<informalexample>
+<screen>
+<prompt>%</prompt><userinput><command>mkdir</command> /tmp/kate -p && export TMPDIR=/tmp/kate && kate</userinput>
+</screen>
+</informalexample>
+</para>
+
 <sect3 id="command-line-options">
 <title>Command Line Options</title>
 <para>&kate; accepts following command line options:</para>
@@ -168,11 +177,15 @@ downloaded to a temporary) and should be reuploaded, after you saved it.
 deleted (if they are local files and you have sufficient permissions) when
 closed, unless they were modified since they were opened.</para></listitem>
 </varlistentry>
-<!--FIXME usecase? -->
+
 <varlistentry>
 <term><userinput><command>kate</command>
 <option>--desktopfile</option> <parameter>filename</parameter></userinput></term>
-<listitem><para>The base file name of the desktop entry for this application.</para></listitem>
+<listitem><para>The base file name of the desktop entry for this application.</para>
+<para>This is in particular useful for wrapper applications and
+applications having in general multiple desktop files. Thus each desktop
+file can have its own command line for the <option>Exec</option> entry.
+</para></listitem>
 </varlistentry>
 
 <varlistentry>
@@ -205,6 +218,7 @@ Shows license information.
 </listitem>
 </varlistentry>
 </variablelist>
+
 </sect3>
 </sect2>
 
diff --git a/doc/kate/index.docbook b/doc/kate/index.docbook
index 19a1b4087..7596c1c79 100644
--- a/doc/kate/index.docbook
+++ b/doc/kate/index.docbook
@@ -42,13 +42,13 @@
 </copyright>
 <legalnotice>&FDLNotice;</legalnotice>
 
-<date>2016-08-27</date>
-<releaseinfo>Applications 16.08</releaseinfo>
+<date>2018-03-23</date>
+<releaseinfo>Applications 18.04</releaseinfo>
 
 <abstract>
 <para>&kate; is a programmer's text editor by &kde;.</para>
 
-<para>This handbook documents &kate; Version 16.08</para>
+<para>This handbook documents &kate; Version 18.04</para>
 </abstract>
 
 <keywordset>
diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook
index 8c822be18..e243cc1f7 100644
--- a/doc/kate/plugins.docbook
+++ b/doc/kate/plugins.docbook
@@ -52,6 +52,10 @@ The available application plugins are:
 Look up definitions/declarations with CTags</para>
 </listitem>
 <listitem>
+<para><link linkend="kate-application-plugin-preview">Document preview</link> -
+Preview the document in the target format.</para>
+</listitem>
+<listitem>
 <para><link linkend="kate-application-plugin-documentswitcher">Document switcher</link> -
 Quick document switching with <keycombo action="simul">&Alt;	</keycombo> behavior</para>
 </listitem>
@@ -603,6 +607,93 @@ place the cursor at the start of the definition.</para>
 
 </sect2>
 
+</sect1>
+<!--https://frinring.wordpress.com/2017/11/07/ktexteditorpreviewplugin-0-2-1-last-stand-alone/-->
+<!-- https://frinring.wordpress.com/2017/08/21/look-what-you-have-donewwdo/-->
+<sect1 id="kate-application-plugin-preview">
+<title>Document Preview Plugin</title>
+
+<sect2 id="preview-introduction">
+<title>Introduction</title>
+<para>
+The plugin enables a live preview of the currently edited text document in the
+final format in the sidebar. So when editing ⪚ a Markdown text or an SVG image,
+the result is instantly visible next to the source text.
+</para>
+
+<para>For the display the plugin uses that KParts plugin which is currently selected
+as the preferred one for the &MIME; type of the document.
+If there is no KParts plugin for that type, no preview is possible.
+</para>
+
+<para>To change the preferred plugin open the <guilabel>File Associations</guilabel>
+module in the &systemsettings; and edit the <guilabel>Services Preference Order</guilabel>
+on the <guilabel>Embedding</guilabel> tab.
+</para>
+
+<table>
+<title>Some available KParts plugins</title>
+<tgroup cols="2">
+<tbody>
+<row>
+<entry>&MIME; type</entry><entry>KParts plugin</entry>
+</row>
+<row>
+<entry>Markdown text</entry><entry>KMarkdownWebViewPart or OkularPart</entry>
+</row>
+<row>
+<entry>SVG image</entry><entry>SVGPart</entry>
+</row>
+<row>
+<entry>&Qt; UI files</entry><entry>KUIViewerPart</entry>
+</row>
+<row>
+<entry>Dot graph files</entry><entry>KGraphviewerPart</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+</sect2>
+
+<sect2 id="preview-menu">
+<title>Menu Structure</title>
+<variablelist>
+
+<varlistentry id="view-toolviews-show-preview">
+<term><menuchoice>
+<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show Preview</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Toggle the display of &kate;'s Document preview in a sidebar.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="preview-interface">
+<title>Interface</title>
+<para>The buttons at the top of the preview window provide these actions:
+</para>
+<itemizedlist>
+<listitem>
+<para>Lock the preview to a given document. Selecting this option ensures
+that if switching the focus to the view of another document in the same &kate;
+window, the preview will not follow to that document, but keep previewing
+this document.</para>
+</listitem>
+<listitem>
+<para>Enable or disable updates of the preview of the current document content</para>
+</listitem>
+<listitem>
+<para>Manually update the preview of the current document content</para>
+</listitem>
+<listitem>
+<para>A dropdown menu with actions from the KParts plugin</para>
+</listitem>
+</itemizedlist>
+</sect2>
+
 </sect1>
 
 <sect1 id="kate-application-plugin-documentswitcher">
