<chapter id="katefiletemplates">
<chapterinfo>

<title>File Templates</title>

<authorgroup>
<author>
<firstname>Anders</firstname>
<surname>Lund</surname>
<affiliation>
<address><email>anders@alweb.dk</email></address>
</affiliation>
</author>
</authorgroup>
<date>Mon Feb 16 2004</date>
<releaseinfo>0.1</releaseinfo>

<abstract>
<para></para>
</abstract>

<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 plugin 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 environment variables, and position the cursor at a
convenient position in the new file.</para>
<para>Furthermore, templates located in the template directories will
be presented in the menu item
<menuchoice><guimenu>File</guimenu><guimenuitem>From
Template..</guimenuitem></menuchoice>.</para>
<para>The plugin also provides a method to easily create a new template
from an open document.</para>
<para>The template directories 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 K
DEDIRS enviroment 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) directory 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-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 l
aunch 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, macros and cursor
position marker, 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 sta
rting with <constant>katetemplate:</constant> will be taken as the start of
 the template contents. VALUE may contain any character but euqal 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>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>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 plugin 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>Highlight</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>%STRING
</userinput> are expanded. The following macros are supported:
<variablelist>
<varlistentry><term>%time</term>
<listitem><para>Expands to the current time in your locale format, as returned
by <userinput>QTime::currentTime().toString()</userinput>.</para></listitem>
</varlistentry>
<varlistentry>
<term>%date</term>
<listitem><para>Expands to the current date in long format, as returned by
<userinput>QDate::currentDate().toString()</userinput>.</para></listitem>
</varlistentry>
<varlistentry>
<term>%datetime</term>
<listitem><para>Expands to the current date and time,
formatted as a string according to your locale by
<userinput>QDateTime::currentDateTime().toString()</userinput>.</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>%{date(FORMATSTRING)}</term>
<listitem><para>This will expand to a date/time string as
defined by <userinput>FORMATSTRING</userinput>. FORMATSTRING
is a text string, within which the following substitutions
will be performed:</para>
<table><title>Date formatting entities</title><tgroup cols="2"><tbody>
<row><entry><para>h</para></entry><entry><para>the hour without a leading zero
(0..23 or 1..12 if AM/PM display)</para></entry></row>
<row><entry>hh<para></para></entry><entry><para>the hour with a leading zero
(00..23 or 01..12 if AM/PM display) </para></entry></row>
<row><entry><para>m</para></entry><entry><para>the minute without a leading zero
(0..59) </para></entry></row>
<row><entry><para>mm</para></entry><entry><para>the minute with a leading zero
(00..59) </para></entry></row>
<row><entry><para>s</para></entry><entry><para>the second whithout a leading
zero (0..59)</para></entry></row>
<row><entry><para>ss</para></entry><entry><para>the second whith a leading zero
(00..59) </para></entry></row>
<row><entry><para>z</para></entry><entry><para>the milliseconds without leading
zeroes (0..999) </para></entry></row>
<row><entry><para>zzz</para></entry><entry><para>the milliseconds with leading
zeroes (000..999) </para></entry></row>
<row><entry><para>AP</para></entry><entry><para>use AM/PM display. AP will be
replaced by either "AM" or "PM". </para></entry></row>
<row><entry><para>ap</para></entry><entry><para>use am/pm display. ap will be
replaced by either "am" or "pm". </para></entry></row>

<row><entry><para>d</para></entry><entry><para>the day as number without a
leading zero (1-31) </para></entry></row>
<row><entry><para>dd</para></entry><entry><para>the day as number with a leading
zero (01-31) </para></entry></row>
<row><entry><para>ddd</para></entry><entry><para>the abbreviated localized day
name (e.g. 'Mon'..'Sun').</para></entry></row>
<row><entry><para>dddd</para></entry><entry><para>the long localized day name
(e.g. 'Monday'..'Sunday').</para></entry></row>
<row><entry><para>M</para></entry><entry><para>the month as number without a
leading zero (1-12)</para></entry></row>
<row><entry><para>MM</para></entry><entry><para>the month as number with a
leading zero (01-12) </para></entry></row>
<row><entry><para>MMM</para></entry><entry><para>the abbreviated localized month
name (e.g. 'Jan'..'Dec').</para></entry></row>
<row><entry><para>MMMM</para></entry><entry><para>the long localized month name
(e.g. 'January'..'December').</para></entry></row>
<row><entry><para>YY</para></entry><entry><para>The year
as a two digit number (00-99).</para></entry></row>
<row><entry><para>YYYY</para></entry><entry><para>The year
as a four digit number (1752-8000).</para></entry></row>
</tbody></tgroup></table>
<para>This allows you to control the displayed date very detailled, using common
separators between the items, for example: <userinput>h:m:s ap</userinput>.
</para></listitem>
</varlistentry>
<varlistentry><term>%realname</term>
<listitem><para>Expands to Your full name, if it can be found. The parser
will first try the KDE Email settings from the KDE control center, then the user
account information. If a full name can not be found, your user name is filled
in.</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, if it can be found. The
parer will look for it in the KDE Email settings from the KDE control
center, and if not found it will use
<userinput>$USER@$HOST</userinput> instead.</para></listitem>
</varlistentry>
<varlistentry>
<term>%organisation</term>
<listitem><para>This is your organisation, if present in the KDE Email settings
from the KDE control
center. If not found, an empty string is returned.</para></listitem>
</varlistentry>
<!-- LAST ENTRY: %ENV -->
<varlistentry>
<term>%VARIABLE</term>
<listitem><para>Any other string will be interpreted as an
environment variable, and expands to the value of that
variable. If the If no variable by that name is set, it expands to
&quot;WARNING &lt;VARIBALE&gt; is not set&quot;.</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2 id="katefiletemplates-cursor">
<title>Setting the cursor position</title>
<para>The parser looks for a caret character (^) that is not
preceeded by a backslash (\) to decide where to position the cursor. If
found, it is removed and the cursor is positioned where is was. If more
unescaped carets are found, all will be removed, and the position of the
last one will be used.</para>
<para>If any escaped caret characters (preceeded by a backslash character) are
found, the backslash will be removed.</para>
</sect2>

</sect1>

<sect1 id="katefiletemplates-thanks-and-acknowledgements">
<title>Thanks and Acknowledgments</title>

<para>
&kate; Plugin <quote>File Templates</quote> copyright 2004 Anders Lund
<email>anders@alweb.dk</email>.
</para>

<para>
Documentation copyright 2004 Anders Lund
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

<!-- &underFDL; -->
&underGPL;

</sect1>
</chapter>

<!-- kate: word-wrap on; -->