You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
323 lines
13 KiB
323 lines
13 KiB
<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>tdeaddons</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 <email address></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; --> |