Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeaddons@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 323 insertions, 0 deletions

diff --git a/doc/kate-plugins/filetemplates.docbook b/doc/kate-plugins/filetemplates.docbook
new file mode 100644
index 0000000..74ee3cb
--- /dev/null
+++ b/doc/kate-plugins/filetemplates.docbook
@@ -0,0 +1,323 @@
+<chapter id="filetemplates">
+  <chapterinfo>
+
+    <title>File Templates</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Anders</firstname>
+        <surname>Lund</surname>
+        <affiliation>
+          <address>&Anders.Lund.mail;</address>
+        </affiliation>
+      </author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+    </authorgroup>
+    <date>2006-01-10</date>
+    <releaseinfo>0.1</releaseinfo>
+
+    <keywordset>
+      <keyword>KDE</keyword>
+      <keyword>kate</keyword>
+      <keyword>kdeaddons</keyword>
+      <keyword>template</keyword>
+      <keyword>macro</keyword>
+    </keywordset>
+  </chapterinfo>
+
+  <title>Introduction</title>
+
+  <para>The File Templates plug-in allows you to create files based on other
+    files. You can use any file as a template, which will create a copy of the
+    file with an empty &URL;, or use a special template file which may contain
+    macros to fill in information like your name and email address, the
+    current date and so on, and position the cursor at a
+    convenient position in the new file.</para>
+  <para>Furthermore, templates located in the template folder will
+    be presented in the menu item
+    <menuchoice><guimenu>File</guimenu><guimenuitem>New from
+        Template</guimenuitem></menuchoice>.</para> <para>The plug-in also
+    provides a method to easily create a new template
+    from an open document.</para>
+  <para>The template folder is part of the &kde; file system, and
+    consists of at least
+    KDEDIR/share/applications/kate/plugins/katefiletemplates/templates and
+    KDEHOME/share/applications/kate/plugins/katefiletemplates/templates. If your
+    KDEDIRS environment variable contains additional directories, those are
+    searched for a similar subdirectory as well. If equally named templates are
+    found, the one in the local (KDEHOME) folder is chosen.</para>
+  <sect1 id="katefiletemplates-menu">
+    <title>Menu Structure</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>
+          <menuchoice>
+            <guimenu>File</guimenu>
+            <guimenu>New From Template</guimenu>
+            <guimenuitem>Any File...</guimenuitem>
+          </menuchoice>
+        </term>
+        <listitem><para>Presents you with Open File dialog that allows
+            you to use any file as a template. If the chosen file has the
+            extension <filename>katetemplate</filename> it will be parsed
+            for template information and macros.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <menuchoice>
+            <guimenu>File</guimenu>
+            <guimenu>New From Template</guimenu>
+            <guimenuitem>Use Recent</guimenuitem>
+          </menuchoice>
+        </term>
+        <listitem><para>Presents a list of files recently used as
+            templates, represented by their &URL;.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <menuchoice>
+            <guimenu>File</guimenu>
+            <guimenuitem>New From Template</guimenuitem>
+          </menuchoice>
+        </term>
+        <listitem><para>The remainder of submenus contains links to
+            templates. Click a menuitem to create a file as described by
+            the menu item text.</para></listitem>
+      </varlistentry>
+
+      <!-- Settings menu -->
+
+      <varlistentry>
+        <term>
+          <menuchoice><guimenu>Settings</guimenu><guimenuitem>Manage
+              Templates...</guimenuitem></menuchoice></term>
+        <listitem><para>This will launch a dialog with a list of all templates
+            found within the template directories, along with options to add,
+            edit or remove templates.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </sect1>
+
+  <sect1 id="katefiletemplates-use">
+    <title>Using a &kate; Template</title>
+    <para>When creating a file from a template that contain template
+      macros, some macros appears as editable variables in the text. Such
+      variables appears as underlined words in the text.</para>
+    <para>The first variable will be selected, so you just have to type to edit
+      it.If the document text contains more instances of the same variable,
+      they are changed as you edit. To move to the next editable variable,
+      press the TAB key. When the last variable is edited, the list is
+      dropped, and your TAB key works as normal.</para>
+  </sect1>
+
+  <sect1 id="katefiletemplates-create">
+    <title>Creating your own templates</title>
+    <para>To create a new template, use the
+      <menuchoice><guimenu>Settings</guimenu>
+        <guimenuitem>Manage Templates</guimenuitem></menuchoice> Item to launch
+      the template management dialog. In that, click
+      <guibutton>New...</guibutton> to launch the File Template Wizard. You
+      will be asked for an optional file to turn into a template and prompted
+      for template information settings, and a template file will be created for
+      you.</para> <para>Alternatively, you can create a template manually by
+      adding template information to the top of any file, add text and macros,
+      and save it with the <filename>katetemplate</filename> extension.</para>
+    <para>The template menu gets automatically updated if you chose to store
+      your template in the template directory.</para>
+  </sect1>
+
+  <sect1 id="katefiletemplates-edit">
+    <title>Editing templates</title>
+    <para>To edit a template, use the
+      <menuchoice><guimenu>Settings</guimenu>
+        <guimenuitem>Manage Templates...</guimenuitem></menuchoice>. Select the
+      template you want to work on and click <guibutton>Edit...</guibutton>,
+      and the template file will be opened. Close the dialog, edit the template
+      file as desired, save it and close it. Changes to templates takes
+      immediate effect, you can activate the template to test your changes after
+      saving it.</para>
+  </sect1>
+
+  <sect1 id="katefiletemplates-format">
+    <title>The &kate; Template Format</title>
+    <para>If you use files with the extension
+      <filename>katetemplate</filename>, they will be parsed for template
+      information, macros and a cursor position.</para>
+
+    <sect2 id="katefiletemplates-template-info">
+      <title>Template information</title>
+      <para>While reading in the file, the parser keeps
+        lines beginning with the phrase
+        <constant>katetemplate:</constant> and searches them for
+        template information in the form VARIABLENAME=VALUE. The first line not
+        starting with <constant>katetemplate:</constant> will be taken as the
+        start of the template contents. VALUE may contain any character but
+        equal sign (=). Legal variable names are:
+        <variablelist>
+          <varlistentry>
+            <term><varname>Template</varname></term>
+            <listitem><para>This is the template name, displayed in the
+                <menuchoice><guimenu>File</guimenu><guimenuitem>New from
+                Template</guimenuitem></menuchoice> menu.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><varname>Group</varname></term>
+            <listitem><para>The group places the template in a submenu of
+                the <menuchoice><guimenu>File</guimenu><guimenuitem>New from
+                    Template</guimenuitem></menuchoice> menu.</para></listitem>
+          </varlistentry>
+          <varlistentry><term><varname>Name</varname></term>
+            <listitem><para>This is the name that will be set for the
+                document, and displayed in the file list and title bar. If the
+                name contains <userinput>%N</userinput> that will be replaced
+                with a number, increasing if more documents has the same
+                name.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><varname>Highlight</varname></term>
+            <listitem><para>The plug-in will try to set the Highlight for
+                the new document to the value of this variable. The value
+                should be the name, as found in the
+                <menuchoice><guimenu>Tools</guimenu>
+                  <guimenuitem>Highlighting</guimenuitem>
+                </menuchoice>.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><varname>Description</varname></term>
+            <listitem><para>A short informative description of the
+                template. This is currently used to set a Whatsthis string for
+                the menu item, but may be used for more purposes in the
+                future.</para></listitem>
+          </varlistentry>
+          <varlistentry><term>Author</term>
+            <listitem><para>A string identifying the author, for example
+                in the form <userinput>Name &lt;email address&gt;</userinput>.
+                This is currently used to set a Whatsthis string for the menu
+                item, but may be used for more purposes in the
+                future.</para></listitem>
+          </varlistentry>
+        </variablelist>
+      </para>
+
+    </sect2>
+
+    <sect2 id="katetemplates-macros">
+      <title>Template Macros</title>
+
+      <para>While parsing the template contents, macros in the form
+        <userinput>%{NAME}</userinput> or <userinput>${NAME}</userinput> are
+        expanded. If you use the <userinput>$</userinput> prefix, the
+        expanded macro will be treated as a editable variable when a document
+        is created from the template, whereas if you use
+        <userinput>%</userinput> it is not, unless expanding failed.</para>
+      <para>The following macros are expanded:
+        <variablelist>
+          <varlistentry><term>time</term>
+            <listitem><para>Expands to the current time in your locale
+                format.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>date</term>
+            <listitem><para>Expands to the current date in short
+                format.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>datetime</term>
+            <listitem><para>Expands to the current date and time,
+                formatted as a string according to your
+                locale.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>year</term>
+            <listitem><para>The current year as a four digit
+                number.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>month</term>
+            <listitem><para>The full name of the current month, according
+                to your locale.</para></listitem>
+          </varlistentry>
+          <varlistentry><term>day</term>
+            <listitem><para>Expands to the current day of the month.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term>hostname</term>
+            <listitem><para>Expands to the 'hostname' of your computer.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term>index</term>
+            <listitem><para>Expands to 'i'.</para></listitem>
+          </varlistentry>
+          <varlistentry><term>fullname</term>
+            <listitem><para>Expands to your full name, as defined by the
+                owner addressee in your standard &kde;
+                addressbook.</para></listitem>
+          </varlistentry>
+          <varlistentry><term>firstname</term>
+            <listitem><para>Expands to your first name, as defined in the owner
+                addressee in your standard &kde; addressbook.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry><term>lastname</term>
+            <listitem><para>Expands to your last name, as defined in the owner
+                addressee in your standard &kde; addressbook.</para>
+            </listitem>
+          </varlistentry>
+          <!-- <varlistentry>
+            <term>username</term>
+            <listitem><para>Expands to your username.</para></listitem>
+          </varlistentry> -->
+          <varlistentry>
+            <term>email</term>
+            <listitem><para>Expands to your email address, as defined by
+                the owner address in your standard &kde;
+                addressbook.</para></listitem>
+          </varlistentry>
+          <!--<varlistentry>
+            <term>organisation</term>
+            <listitem><para>This is your organisation, as defined by
+                the owner address in your standard KDE
+                addressbook.</para></listitem>
+          </varlistentry>-->
+        </variablelist>
+      </para>
+      <para>Any macro not in the above list is treated as a editable variable
+        no matter the prefix.
+        If the same variable occurs multiple times in the template, they can be
+        edited at once after creating a document from the template.</para>
+    </sect2>
+
+    <sect2 id="katefiletemplates-cursor">
+      <title>Setting the cursor position</title>
+      <para>The special macro <userinput>${cursor}</userinput> will be replaced
+        with a vertical bar and added to the end of the list of editable variables,
+        independent on its location in the text.</para>
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="katefiletemplates-thanks-and-acknowledgements">
+    <title>Thanks and Acknowledgments</title>
+
+    <para>
+      &kate; Plug-in <quote>File Templates</quote> copyright 2004 &Anders.Lund;
+      &Anders.Lund.mail;.
+    </para>
+
+    <para>
+      Documentation copyright 2004 &Anders.Lund;
+    </para>
+
+    <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+    <!-- &underFDL; -->
+    &underGPL;
+
+  </sect1>
+</chapter>
+
+<!-- kate: word-wrap on; space-indent on; indent-width 2; -->
\ No newline at end of file