diff options
Diffstat (limited to 'doc/kate-plugins/filetemplates.docbook')
| -rw-r--r-- | doc/kate-plugins/filetemplates.docbook | 323 |
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 <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; -->
\ No newline at end of file |