diff options
Diffstat (limited to 'doc/quanta/working-with-quanta.docbook')
| -rw-r--r-- | doc/quanta/working-with-quanta.docbook | 650 |
1 files changed, 650 insertions, 0 deletions
diff --git a/doc/quanta/working-with-quanta.docbook b/doc/quanta/working-with-quanta.docbook new file mode 100644 index 00000000..4a0ca0b1 --- /dev/null +++ b/doc/quanta/working-with-quanta.docbook @@ -0,0 +1,650 @@ +<?xml version="1.0" encoding="UTF-8" ?> + +<chapter id="using-quanta-3-2"> +<chapterinfo> +<title>Working With...</title> +<authorgroup> +<author> +<firstname>Robert</firstname> +<surname>Nickel</surname> +<affiliation> +<address><email>robert@artnickel.com</email></address> +</affiliation> +</author> +<author> + <firstname>András</firstname> + <surname>Mantia</surname> + <affiliation> + <address><email>amantia@kde.org</email></address> + </affiliation> +</author> + +<othercredit role="reviewer"> +<firstname>Christopher</firstname> +<surname>Hornbaker</surname> +<affiliation> +<address><email>chrishornbaker@earthlink.net</email></address> +</affiliation> +<contrib>Reviewer</contrib> +</othercredit> + +<othercredit role="reviewer"> +<firstname>Fabrice</firstname> +<surname>Mous</surname> +<affiliation> +<address><email>fabrice@kde.nl</email></address> +</affiliation> +<contrib>Reviewer</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> +</chapterinfo> + +<title>Working With...</title> + +<para> +This chapter describes the parts of &quantaplus; that you will be +interacting with mostly. These not only make your more productive, but +they also allow you to customize &quantaplus; to your work-flow. +</para> + +<sect1 id="toolbars-howto-3-2"> +<title>Toolbars</title> + +<para> +As previously mentioned, toolbars in &quantaplus; are primarily managed +through the <guimenu>Toolbars</guimenu> menu. Usage and creation are +somewhat different. The creation of toolbars is discussed in a later +section entitled <quote><link linkend="creating-toolbars-3-2">Creating +Toolbars</link>.</quote> +</para> + +<para> +Using toolbars is quite simple. When you click on an icon for a desired +element or action, one of three possibilities occur: the element is +inserted (optionally with a closing element); an element dialog is +activated, allowing you to fill in the attributes in a dialog box; or, +lastly, an action is activated and does something nifty for your current +file or project. If you find yourself doing tedious and redundant typing +for a particular element, that is not in &quantaplus;, then you can add it. +See <xref linkend="dtep-intro-3-2" /> for more information. +</para> + +<para> +Configuring the toolbars and the elements on it can be done either by +using the context menu (right click on a toolbar), where you can +create a <guilabel>New Action</guilabel>, a <guilabel>New Toolbar</guilabel>, you can perform other actions like <guilabel>Remove Toolbar</guilabel>, <guilabel>Rename Toolbar</guilabel> or <guilabel>Configure Toolbars</guilabel>, which will get you the dialog where you can specify which actions should be visible on this or other toolbars. +</para> +<para> + By invoking the context menu on an action (icon) placed to a toolbar, aside of the above actions you will see the <guilabel>Remove Action</guilabel> and <guilabel>Edit Action</guilabel> entries, which speak for themselves. +</para> +<para> + The toolbars and the actions on them can be configured by using the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem></menuchoice> and <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Actions..</guimenuitem></menuchoice> menu entries. +</para> +<para> + About the user definable actions you can read in <xref linkend="user-actions" />. +</para> + +<para> +A tag dialog looks just like the following: + +<mediaobject> +<imageobject> +<imagedata fileref="taginputex.png" format="PNG" /> +</imageobject> +<caption><para>An example of a tag dialog.</para></caption> +</mediaobject> +</para> + +<para> +The above image is the dialog for the anchor tag. If you know &HTML;/&XHTML;, +then you should have noticed that all the attributes that you can use, in +an anchor element, are available. Notice the tabs above for +<guilabel>Main</guilabel>, <guilabel>Core and i18n</guilabel>, +<guilabel>Events</guilabel>, and <guilabel>Focus</guilabel>, they hold +all of the other attributes, according to their purpose, available to the +anchor element. All you need do is: fill in the blanks for the attributes +you want in your anchor, omit the attributes you do not want, and click OK. +You now have a well formed anchor set down at the current cursor position. +</para> +</sect1> + +&quanta-projects; + +<sect1 id="templates-3-2"> +<title>Templates</title> + +<para> +Templates are basically skeleton documents, code snippets and files to +link to. &quantaplus; uses templates fundamentally as a standard file +system with enhanced organization and interfacing. You can copy, move or +link any repository currently on your system into the templates tree. +Think of &quantaplus; templates as having roughly the limitations to your +imagination that your file system has. +</para> + +<para> +Templates exist in nested folders. There is no limit to how deep you +can nest them, however, within any given folder &quantaplus; expects a +consistent action for the base template type described below. Additionally +templates allow for pre and post text to be concatenated to non document +type templates. This facilitates tag creation. The next update after the +introduction is scheduled to add the ability to pass variables to the text +such as image size information to assist in tag creation. +</para> + +<para> +Our goal with templates is to extend them to include multi file +<quote>concept</quote> templates useful for things like placing an order or +creating an about section. Ideally this will be a tool for making your +work more productive and dynamic. An eventual goal is to have a structural +template design mode to deal with site layout and structure which you +could use to design and interactively update your sites. If you would like +to be involved, check out our +<ulink url="http://quanta.sourceforge.net/main1.php?contfile=needs">help +wanted</ulink> page. +</para> + +<important> +<para> +Some of the templates that ship with &quantaplus; have conditions for +their usage. Please read carefully the usage statement of conditions at +the top of each template before you use it. +</para> +</important> + +<sect2 id="template-types-3-2"> +<title>Template Types</title> + +<para> +There are various template types supported by &quantaplus;. +These are: +</para> +<para> +<simplelist> +<member>Binary templates</member> +<member>Document templates</member> +<member>Text snippets</member> +<member>Site templates</member> +</simplelist> + +Examples for these types are provided with &quantaplus;. +</para> +<variablelist> +<varlistentry> +<term>Binary templates</term> +<listitem> +<para> +Binaries are anything not identified purely in text. They can be any file, +except text, including images, &PDF;s, flash files, etc. Binary templates +are usually included in your document via links (&ie; images as +an <sgmltag class="starttag">img src=/src/url</sgmltag>). +Some examples can be found in the Templates tree under Global Templates. +Please see <xref linkend="qit-3-2" /> for more information on the +<guilabel>Templates</guilabel> tree. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Document templates</term> +<listitem> +<para> +Documents can be any type of text document. You can create new documents +based on these templates. Generally you would want to nest +more specific or diverse documents in subfolders. Here you can make a +basic framework for what you do and deliver it to your work in an +organized fashion and realize much better efficiency. Some examples +can be found in the Templates tree under Global Templates. +Please see <xref linkend="qit-3-2" /> for more information on the +<guilabel>Templates</guilabel> tree. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Text snippets</term> +<listitem> +<para> +This type of template is useful when you don't want to create a new +document based on a template, but want to insert the same text area +over and over in your documents. They can contain anything, starting +with a comment and ending with a complete menu handling JavaScript +method or perl script. Some examples can be found in the Templates +tree under Global Templates. +Please see <xref linkend="qit-3-2" /> for more information on the +<guilabel>Templates</guilabel> tree. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Site templates</term> +<listitem> +<para> +As the name says these templates are useful to build a whole site +from a template. They are a collection of various documents which +can be organized in a directory structure, everything gathered in +a compressed tar archive. As of writing there are no example site +templates in &quantaplus;. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="template-scope-3-2"> +<title>Template Scopes</title> + +<para> +Templates are accessible based upon their established +<link linkend="quanta-workspaces-3-2">workspace</link> in &quantaplus; +</para> + +</sect2> + +<sect2 id="creating-templates-3-2"> +<title>Creating Templates</title> + +<sect3 id="creating-document-templates"> +<title>Creating document templates</title> +<para> +Create a document structure that you love (&XML;, &HTML;, DocBook, &etc;.) +and click on +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save as Template</guimenuitem> +<guimenuitem>Save as Local/Project Template</guimenuitem> +</menuchoice>. +</para> + +<para> +Once this is done, you will notice that (even if it is saved as a Project +template) the template does <emphasis>not</emphasis> show in the project +tab view. Look into the templates view to find your template under the +Project templates tab. +</para> +</sect3> +<sect3 id="creating-text-templayes"> +<title>Creating text snippets</title> +<para>Select some text in your document and click on +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save as Template</guimenuitem> +<guimenuitem>Save Selection to Local/Project Template file</guimenuitem> +</menuchoice>. +Alternatively you can just use drag and drop to drag the selection to the <guilabel>Templates</guilabel> treeview. +</para> +</sect3> +<sect3 id="creating-binary-templates"> +<title>Creating binary templates</title> +<para>Creation of a binary template is simple: just copy the file +into a template folder. You can use standard file management +functions to do it, like drag and drop or copy and paste from +Konqueror or the <guilabel>Files Tree</guilabel>. +</para> +</sect3> +<sect3 id="creating-site-templates"> +<title>Creating site templates</title> +<para> +In the <guilabel>Files Tree</guilabel> or the <guilabel>Project Files</guilabel> +treeviews right click on a folder and select <guilabel>Create Site Template</guilabel>, +pick up a name for the template and save it. By default it will try +to save to the project template folder, but of course you can choose +to save it as a local or global template as well. +</para> +</sect3> +</sect2> + +<sect2 id="using-templates-with-projects-3-2"> +<title>Using Templates With Projects</title> + +<para> +Project templates allow you to be more tightly focused. You can create +headers, footers or go dynamic with &PHP; include files and link them. +Additionally there are some very cool things we took into consideration +when using templates in projects. +</para> + +<para> +When creating a project you can opt to copy to your local project, all the +existing global and user templates. Legacy project get default templating +abilities so nothing is lost You can choose where to locate your template +files so they can be in your server root and easy to upload or you can +make them secure to link to below server root which is a very cool trick. +When linking to a file not in the project templates you will be prompted +to copy the file to the project templates prior to linking. This will prevent +broken links on upload. You always have control where you place your +templates so you can choose to move them. However &quantaplus; does not +track this so you will need to change links. +</para> + +</sect2> + +<sect2 id="managing-templates-3-2"> +<title>Managing Templates</title> + +<para> +Template structure on the template tab is based on the files found in +<filename class="directory"> +$<envar>KDEDIR</envar>/share/apps/quanta/templates</filename> and +<filename class="directory"> +$<envar>HOME</envar>/.kde/share/apps/quanta/templates</filename>. Each of +these folders is specified as one of four types of container as explained <link linkend="template-types-3-2">above</link>. +</para> + +<para> +To set the behavior of each folder, &RMB; click in the template view on +the folder and choose <guimenuitem>Properties</guimenuitem>. The +following dialog will come up: + +<mediaobject> +<imageobject> +<imagedata fileref="template-rmb.png" format="PNG" /> +</imageobject> +<caption><para>Properties dialog.</para></caption> +</mediaobject> +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Type</guilabel></term> + +<listitem> +<para> +Drop down box with the three types discussed previously; files, text, +template. This box will be grayed out if you have the <guilabel>Inherit +parent attribute box</guilabel> checked. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Inherit parent attribute</guilabel> (<sgmltag +class="starttag">foo</sgmltag>)</term> +<listitem> +<para> +This is checked by default and is fine for all but the top level +folders in your templates tree. If the top level folder has this +checked, it will basically deactivate templates for that folder and all +that aren't explicitly set below it. If this is not a top level folder, +then the <sgmltag class="starttag">blah</sgmltag> will say something like +<literal>Text snippet</literal>. If it says nothing, then chances are that +you are on a top level folder. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Use pre/post text</guilabel></term> +<listitem> +<para> +Enables pre and post text for templates in this folder. This could be a +common header/footer for all of your templates for a given project and +then you copy content templates into that folder and have a complete +page with the custom header/footer as a starting point. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Pre-text</guilabel></term> +<listitem> +<para> +The actual text to insert before your templates content. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Post-text</guilabel></term> +<listitem> +<para> +The actual text to insert after your templates content. +</para> +</listitem> +</varlistentry> +</variablelist> +<!--<para> +The properties for a template file looks a bit different: +<mediaobject> +<imageobject> +<imagedata fileref="template-file-rmb.png" format="PNG" /> +</imageobject> +<caption><para>Properties dialog.</para></caption> +</mediaobject> + +</para>--> +<para> +Additionally if you look at your options with the &RMB; you will see +complete file management tools for creating folders or copying and +pasting templates from one location to another. +</para> +</sect2> +</sect1> + +<sect1 id="vpl-3-2"> +<sect1info> +<title><application>Visual Page Layout</application></title> +<authorgroup> +<author> +<firstname>Nicolas</firstname> +<surname>Deschildre</surname> +<affiliation> +<address><email>nicolasdchd@ifrance.com</email></address> +</affiliation> +</author> + +<othercredit role="reviewer"> +<firstname>Christopher</firstname> +<surname>Hornbaker</surname> +<affiliation> +<address><email>chrishornbaker@earthlink.net</email></address> +</affiliation> +<contrib>Reviewer</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> +</sect1info> + +<title><application>Visual Page Layout</application></title> + +<sect2 id="vpl-views-3-2"> +<title>&VPL; Modes</title> + +<para> +The <application>Visual Page Layout</application> (&VPL;) editor (also known +as <acronym>WYSIWYG</acronym> (What You See Is What You Get)) allows you +to edit a &HTML; or &XHTML; document while seeing the changes on-the-fly. +Just like your favorite wordprocessor, you can click on your document and +a cursor will appear, thus enabling you to enter text, insert images, +apply text decorations, &etc;. &VPL;'s aim is to allow you to create great, +valid web pages without any knowledge of Internet markup languages. +</para> + +<para> +&quantaplus; offers two modes: <guilabel>&VPL; Editor</guilabel> and +<guilabel>&VPL; & Source Editors</guilabel>, which are accessible from +the <guimenu>View</guimenu> menu. The first replaces the <guilabel>Source +Editor</guilabel> with the <guilabel>&VPL; Editor</guilabel>, and the +second splits the editor window into two parts: the <guilabel>Source +Editor</guilabel> and the <guilabel>&VPL; Editor</guilabel>. +</para> + +<para> +The <guilabel>&VPL; Editor</guilabel> works like so: It loads a document +like a normal &HTML; or &XHTML; page and a cursor appears. Then you can +edit it, and switching back to <guilabel>Source Editor</guilabel>, you see +that the changes you made on the <guilabel>&VPL; Editor</guilabel> have +been merged in the <guilabel>Source Editor</guilabel>. +</para> + +<note> +<para> +When working in the <guilabel>&VPL; Editor</guilabel> with a document that +contains &PHP;, you will see a small green icon representing the &PHP; +code. You cannot directly edit it with the <guilabel>&VPL; +Editor</guilabel>. To edit &PHP;, you will still need to use the +<guilabel>Source Editor</guilabel>. There are no plans to change this +functionality. +</para> +</note> + +<para> +The second mode behaves exactly like the first, except that you instantly +see the impact that your changes have made, either in the <guilabel>Source +Editor</guilabel> or in the <guilabel>&VPL; Editor</guilabel>, and the +cursors of the source editor and of the <guilabel>&VPL; Editor</guilabel> +are synchronized. Pressing <keycap>F9</keycap> loads this mode, but, if +it is already loaded, it will move the focus from one view to the other, +while keeping you at the same location of the document. +</para> + +<para> +The refresh intervals between the <guilabel>&VPL; Editor</guilabel> and +the <guilabel>Source Editor</guilabel> are configurable. Go to +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Quanta...</guimenuitem> +</menuchoice>. Select the <guimenu>&VPL; View</guimenu> tab. You can +choose whether you want to refresh a view only when you click on it or +automatically. If you choose automatically, then you can choose a refresh +interval. The general recommendation is: A smaller number for fast +computers and a bigger number for slower ones. +</para> + +<mediaobject> +<imageobject> +<imagedata fileref="vplsourceview.png" format="PNG" /> +</imageobject> +<caption><para>The <guilabel>&VPL; & Source Editors</guilabel> mode.</para></caption> +</mediaobject> +</sect2> + +<sect2 id="vpl-editing-3-2"> +<title>&VPL; Editing</title> + +<sect3 id="doc-prop-dia-3-2"> +<title>The <guilabel>Document Properties</guilabel> Dialog</title> + +<para> +Now, let's say you want to edit the title of your web page. How do you do +it? Simply launch +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Document Properties</guimenuitem> +</menuchoice>. This tool allows editing of <quote>invisible</quote> +tags when using the <guilabel>&VPL; Editor</guilabel>. The +<guilabel>Document Properties</guilabel> dialog is also launched when you +create a new document while in the <guilabel>&VPL; Editor</guilabel>. This +is in order to lessen the amount of hand coding you need to perform. With +it, you can edit: +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Title</guilabel></term> +<listitem> +<para> +The title of the document. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Meta items</guilabel></term> +<listitem> +<para> +Meta tags allow you to store information about the document itself +⪚ keywords for the Internet search engines. You can add or remove +<guilabel>Meta items</guilabel> by pressing the two buttons below, +and edit them by clicking on the list ⪚ put <quote>keywords</quote> on +the <quote>name</quote> column and <quote>keyword1 keyword2</quote> on the +<quote>content</quote> column. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>CSS Rules</guilabel></term> +<listitem> +<para> +<guilabel>CSS Rules</guilabel> are the new way to tell your web browser +how to present the page. You can add or delete the <guilabel>CSS +Rules</guilabel> by pressing the buttons below. You can also fill the +fields like the <guilabel>Meta items</guilabel>. The editing of +<guilabel>CSS Rules</guilabel> is not yet supported. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Link CSS Stylesheet</guilabel></term> +<listitem> +<para> +You can also link an external CSS stylesheet. Simply click on the +<guilabel>Browse</guilabel> button and select your file. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3 id="vpl-editor-3-2"> +<title>The <guilabel>&VPL; Editor</guilabel></title> + +<para> +You can use your cursor like you do in a wordprocessor, moving with the +arrows. There may come a time when the cursor does not want to go where you +want it to go (a pesky bug). Selection also works as usual. You can insert +text by typing and remove text by pressing the &Backspace; or Delete key. +</para> + +<para> +Now we come to tag insertion. You can insert images, applets, text +decorations such as bold and so on by using the same toolbars you use in +the source editor. Note that the insertion of tags does not remove previous +identical tags ⪚ if you insert an anchor tag around some text, then you +must remove any other anchor tag around it. +</para> + +<note> +<para> +Some toolbar items will be disabled, such as the <guilabel>Table +Wizard</guilabel> or <guilabel>Quick List Wizard</guilabel>. They will +work later in &VPL;, but, for this release, you should use the +<guilabel>Tables</guilabel> or <guilabel>Lists</guilabel> toolbars. +</para> +</note> + +<para> +To edit a tag (be it an image, an applet, or whatever), switch to the +<guilabel>Attribute Tree</guilabel>, accessible via +<menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Tool views</guisubmenu> +</menuchoice>. Click on the tag you wish to edit, or, if you cannot access +it, click on an object contained by it. The <guilabel>Attribute +Tree</guilabel> will show the current tag name as well as a list of all its +parents and attributes. Currently &VPL; does not support, say, +&XHTML;+<acronym>MathML</acronym>, but you will see that you can edit +namespaces via this view. You can simply click on the +<guilabel>Value</guilabel> field and modify whatever you want. If you want +to access a parent of the current tag, then select it and the +<guilabel>Attribute Tree</guilabel> will load it. +</para> + +<para> +To delete a tag, we will use the <guilabel>Attribute Tree</guilabel>. Have +you noticed the two little red crosses at the top-right corner? The first one +deletes only the currently selected tag and, if the &HTML;/&XHTML; +specification does not allow some children of the deleted tag to be children of +the parent tag of the tag set to be deleted, then they are also deleted, +and so on. The second cross will delete the selected tag as well as all of +its children, so be careful! +</para> + +</sect3> +</sect2> +</sect1> +</chapter> |