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/kdewebdev@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 792 insertions, 0 deletions

diff --git a/doc/quanta/quanta-projects.docbook b/doc/quanta/quanta-projects.docbook
new file mode 100644
index 00000000..06814ebb
--- /dev/null
+++ b/doc/quanta/quanta-projects.docbook
@@ -0,0 +1,792 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<sect1 id="quanta-projects-3-2">
+<sect1info>
+<title>Projects</title>
+<authorgroup>
+<author>
+<firstname>Robert</firstname>
+<surname>Nickel</surname>
+<affiliation>
+<address><email>robert@artnickel.com</email></address>
+</affiliation>
+</author>
+<author>
+  <firstname>Andr&#225;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>
+</sect1info>
+
+<title>Projects</title>
+
+<sect2 id="create-new-project-3-2">
+<title>New Projects</title>
+
+<para>
+The &quantaplus; project wizard
+(<menuchoice>
+<guimenu>Project</guimenu>
+<guimenuitem>New Project...</guimenuitem>
+</menuchoice>) makes project creation an easy task.
+</para>
+
+<mediaobject>
+<imageobject>
+<imagedata format="PNG" fileref="project-1.png" />
+</imageobject>
+<caption><para>The Project Wizard.</para></caption>
+</mediaobject>
+
+<para>
+The fields are pretty straight forward. It is best to fill them in from
+top to bottom. Filling in a project name will autocomplete all the
+folder structure for the rest of the project. All of the paths and
+author information fields can be configured later on clicking
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Shift;<keycap>F7</keycap></keycombo>
+</shortcut>
+<guimenu>Project</guimenu>
+<guimenuitem>Project Properties</guimenuitem>
+</menuchoice>.
+</para>
+
+<variablelist>
+<title>General Project Settings</title>
+<varlistentry>
+<term><guilabel>Name</guilabel></term>
+<listitem>
+<para>
+Here you fill in the name for your project. For example, we will call ours
+<quote><literal>foo</literal>.</quote> When you fill in
+<guilabel>Name</guilabel>, <guilabel>File</guilabel> is filled out for
+you automatically.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>File</guilabel></term>
+<listitem>
+<para>
+This is the name of the &quantaplus; project file. By default, it is the
+name of your project, but in lowercase letters and without spaces. It
+uses the extension <literal role="extension">webprj</literal> (&eg;
+<filename>foo.webprj</filename>). This file is stored in the root of the
+project's Main Folder.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<variablelist>
+<varlistentry>
+<term>Server Settings</term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Protocol</guilabel></term>
+<listitem>
+<para>
+Here you select the protocol you will be using to access you project. If
+your project is on the same machine that you are using Quanta Plus on,
+then leave the value at Local. The list of protocols shown here is
+dependant of your system setup. Available protocols include SSH, FTP, NFS,
+SMB, WebDAV, and others. The protocol list is powered by &kde;'s
+powerful KIOSlave architecture. This framework allows every &kde;
+application to easily access remote information as if it is local to the
+machine.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Host</guilabel></term>
+<listitem>
+<para>
+Here you fill in the server address of the machine you want to access,
+unless you are working through the Local protocol. Either a hostname
+(hostname.example.com) or an IP address (127.0.0.1) can go here.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>User</guilabel></term>
+<listitem>
+<para>
+User name for logging onto the remote machine. This is case-sensitive.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Password</guilabel></term>
+<listitem>
+<para>
+Password for logging onto the remote machine. This is case-sensitive.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Port</guilabel></term>
+<listitem>
+<para>
+Leave this field blank to use the default port for the protocol you are
+using. You may need to change this depending on your server's
+configuration.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+
+
+<variablelist>
+<varlistentry>
+<term>Directory Settings</term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Main directory</guilabel></term>
+<listitem>
+<para>
+This is the root folder where all of the project files and folders
+will be stored.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Templates directory</guilabel></term>
+<listitem>
+<para>
+This is where the templates for this project will be stored. It is a relative path to the project and by default,
+it points to 
+<filename class="directory">templates</filename>.
+If you have a common set of files that you use for several
+projects, then it may be useful to point this field to it, instead of to
+the default.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Toolbars directory</guilabel></term>
+<listitem>
+<para>
+  This is where the toolbars for this project will be stored.  It is a relative path to the project and by default,
+it points to <filename>toolbars</filename>.
+If you have a common set of toolbars
+that you use for several projects, it may be useful to point this there
+instead of the default.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+
+
+<variablelist>
+<varlistentry>
+<term>Project Sources</term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Add local or remote files</guilabel></term>
+<listitem>
+<para>
+This allows you to get files from the local file system. You can choose
+multiple files or entire folders.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Use wget to download files from site</guilabel></term>
+<listitem>
+<para>
+This option is great if you have static web content that you wish to
+download and modify. For server side scripting (&eg; &PHP;, Python,
+&etc;.) you will have to get the files another way.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<variablelist>
+<title>Insert Files in Project</title>
+<varlistentry>
+<term><guilabel>Insert file from</guilabel></term>
+<listitem>
+<para>
+Check this if you wish to include files found in the path of the Main
+Folder. Leave unchecked when starting a project from scratch.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Filters</term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Insert only markup, script and image files</guilabel></term>
+<listitem>
+<para>
+Choosing this option will only insert markup, script, and image files into
+your project.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Insert files with the following mask</guilabel></term>
+<listitem>
+<para>
+Choosing this option will display all files and folders within the
+Main Folder and allow you to be more specific with your choices.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Included files</guilabel></term>
+<listitem>
+<para>
+This displays a list of the files in the Main Folder. You can choose
+the desired files for inclusion, by checking, or exclusion, by unchecking,
+in your project.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<variablelist>
+<title>More Project Settings</title>
+<varlistentry>
+<term><guilabel>Author</guilabel></term>
+<listitem>
+<para>
+Insert your name (or alias) here.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Email</guilabel></term>
+<listitem>
+<para>
+The address where you would like email regarding this project to go.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Project Defaults</term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Default DTD</guilabel></term>
+<listitem>
+<para>
+Choose the markup language you will be working with the most within this
+project.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Default encoding</guilabel></term>
+<listitem>
+<para>
+Choose the character encoding you wish the files in your project to be
+opened and saved with.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Use preview prefix</guilabel></term>
+<listitem>
+<para>
+Check this to use a prefix for your previews. This allows you to set the
+path prefix to something other than your local file system. This is most
+useful for pages that contain dynamic content and are dependent on server
+processing (like &PHP;, <acronym>JSS</acronym>, Python, &etc;). Simply
+type in the first portion of the address as it exists on that server and
+the filepath at the end will be complete by &quantaplus;. For example, if
+you have the domain <literal>bar.com</literal> and you are editing the
+<filename>index.html</filename> page, you could edit it on your remote
+machine (<systemitem>foo.bar.com</systemitem>), upload it to the server
+and press <keycap>F6</keycap> to see the results from
+<systemitem>www.bar.com</systemitem> instead of your local file system.
+</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Prefix</guilabel></term>
+<listitem>
+<para>
+Enter the prefix you wish to use here.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Insert global templates</guilabel></term>
+<listitem>
+<para>
+This makes a copy of the global templates in your projects folder tree.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Insert local templates</guilabel></term>
+<listitem>
+<para>
+This makes a copy of the local templates in your projects folder tree.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>
+The last screen of the new project wizard has 3 settings that can make
+your life easier. These settings are available for change from the
+<menuchoice>
+<guimenu>Project</guimenu>
+<guimenuitem>Project Properties</guimenuitem>
+</menuchoice>
+menu tree on the Upload Profiles Tab or with the keyboard shortcut
+<keycombo action="simul">&Shift;<keycap>F7</keycap></keycombo>.
+</para>
+
+</sect2>
+
+<sect2 id="configuring-projects-3-2">
+<title>Configuring Projects</title>
+<para>
+  The project properties dialog looks like:  
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="project-properties.png" format="PNG" />    
+  </imageobject>    
+  <caption><para>The general options page</para></caption>
+  </mediaobject>
+</para>
+
+<para>
+  Some of the items are the same as in the project wizard and are described in <xref linkend="create-new-project-3-2" />. The extra items are described below.
+<variablelist>
+<title>General Project Settings</title>
+<varlistentry>
+<term><guilabel>Exclude from project</guilabel></term>
+<listitem>
+<para>
+  A list of file names (wildcards can be used) that will be ignored when you do project related operations like <guimenuitem>Rescan Project Folder</guimenuitem>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+  <term><guilabel>Exclude files listed in .cvsignore</guilabel></term>
+  <listitem>
+    <para>
+      A complementary option to the above one, also files listed in the .cvsignore file will be excluded from the project.
+    </para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term><guilabel>Default view</guilabel></term>
+  <listitem>
+    <para>
+      The project view that will be loaded when the project is opened.
+      You can read more about project views in <xref linkend="project-views-3-2" />.
+    </para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term><guilabel>Debugger</guilabel></term>
+  <listitem>
+    <para>
+      Select the debugger you want to use. Currently only Gubed is support. You can find more information about Gubed at <ulink url="http://gubed.sourceforge.net"></ulink>.The debugger plugin can be configured with the <guilabel>Options</guilabel> button.
+      read <xref linkend="debugging-3-2" /> to learn more about debugging.
+    </para>
+  </listitem>
+</varlistentry>
+<varlistentry>
+  <term><guilabel>Default view</guilabel></term>
+  <listitem>
+    <para>
+      The project view that will be loaded when the project is opened.
+      You can read more about project views in <xref linkend="project-views-3-2" />.
+    </para>
+  </listitem>
+</varlistentry>
+</variablelist>
+</para>
+<para>On the <guilabel>Upload Profiles</guilabel> page you can configure the upload profiles (see <xref linkend="upload-profiles" />), as well as enable the showing of a treeview with the content of the server for each profile by checking the <guilabel>Show a treeview for each profile</guilabel> checkbox.
+</para>
+<para>
+  On the <guilabel>Team Configuration</guilabel> page you can add, edit and remove members of the project as well as define a mailing list. Read <xref linkend="team-members" /> for details.
+</para>
+<para>
+  On the <guilabel>Event Configuration</guilabel> page you can <guilabel>Enable the event actions</guilabel>, add, modify and remove these actions. Event actions are executed when some predefined event occurs, like saving a file. See <xref linkend="event-actions" /> for details.
+</para>
+</sect2>
+
+<sect2 id="using-projects-3-2">
+<title>Using Projects</title>
+
+<sect3 id="project-files-3-2">
+<title>Project Files</title>
+
+<para>
+By default &quantaplus; will open the last project accessed when launched.
+This behavior is not currently configurable.
+</para>
+
+<para>
+To open another project, select <guimenuitem>Open Project...</guimenuitem> from the
+<guimenu>Project</guimenu> menu or the <guiicon>Open Project</guiicon>
+icon on the toolbar. The open project dialog will pop up and allow you to
+choose the project you wish. Projects have a <literal
+role="extension">webprj</literal> extension.
+</para>
+
+<para>
+When closing &quantaplus;, your project file will be saved automatically.
+You will be asked to save any changes before exiting if &quantaplus;
+detects any changed files. This same behavior occurs if you load a new
+project.
+</para>
+
+</sect3>
+
+<sect3 id="project-tree-view-3-2">
+<title>The Project Tree View</title>
+
+<para>
+The project tree view gives you uncluttered access to the files in your
+project. This is where you manage the files in the current project.
+</para>
+
+<para>For files, a &RMB; click brings up the following menu:</para>
+
+<mediaobject>
+<imageobject>
+<imagedata fileref="project-tree-view-file-rmb-menu.png" format="PNG" />
+</imageobject>
+</mediaobject>
+
+<para>
+These items are fairly self-explanatory and will be left to  the reader
+for exploration.
+</para>
+
+<para>
+Folders are similar but do not contain the <guimenuitem>Open</guimenuitem>
+and <guimenuitem>Open With...</guimenuitem> &RMB; menu items:
+</para>
+
+<mediaobject>
+<imageobject>
+<imagedata fileref="project-tree-view-dir-rmb-menu.png" format="PNG" />
+</imageobject>
+</mediaobject>
+
+<para>
+These items are left to the reader for exploration as well.
+</para>
+
+</sect3>
+
+<sect3 id="upload-project-3-2">
+<title>Uploading Projects</title>
+
+<para>
+The Upload Project dialog:
+</para>
+
+<mediaobject>
+<imageobject>
+<imagedata fileref="project-upload-dialog.png" format="PNG" />
+</imageobject>
+<caption><para>The Upload Project dialog.</para></caption>
+</mediaobject>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Profile name</guilabel></term>
+<listitem>
+<para>
+This is where different <link linkend="upload-profiles">profiles</link> can be chosen. The profile contains
+information on where the uploaded files are to be placed. Read <xref linkend="upload-profiles" />.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>New</guibutton></term>
+<listitem>
+<para>
+This button allows you to create new upload profiles.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Edit</guibutton></term>
+<listitem>
+<para>
+This allows you to edit the currently selected upload profile.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Remove</guibutton></term>
+<listitem>
+<para>
+This allows you to remove the current profile. If only
+one profile is available the button is grayed out to prevent its
+removal.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Keep passwords in memory</guilabel></term>
+<listitem>
+<para>
+The password is stored in memory and is lost as soon as the program is closed.
+This option is useful if frequent uploading of files is necessary and you do
+not want to use the more insecure <quote>Store password on disc</quote> option.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>All</guibutton></term>
+<listitem>
+<para>
+Select all files in your project for upload.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Modified</guibutton></term>
+<listitem>
+<para>
+Select all modified files for upload.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>None</guibutton></term>
+<listitem>
+<para>
+Unselects all files in the list.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Invert</guibutton></term>
+<listitem>
+<para>
+Selects/Unselects all files in the list.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Expand All</guibutton></term>
+<listitem>
+<para>
+Expands all folders.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Collapse All</guibutton></term>
+<listitem>
+<para>
+Collaspes all folders.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Update All</guibutton></term>
+<listitem>
+<para>
+Refreshes list.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Proceed</guibutton></term>
+<listitem>
+<para>
+Start the upload
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Cancel</guibutton></term>
+<listitem>
+<para>
+This will abort your transfer in progress or just exit out of the dialog
+if you change your mind before starting the upload.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect3>
+
+<sect3 id="upload-profiles">
+<title>Upload profiles</title>
+<para>
+With &quantaplus; you can define multiple upload profiles and, in this
+way, upload your project (or parts of your project) to different servers.
+When you edit or create a profile you will face the following dialog:
+<mediaobject>
+<imageobject>
+<imagedata fileref="edit-upload-profile.png" format="PNG" />
+</imageobject>
+</mediaobject>
+</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Profile name</guilabel></term>
+<listitem>
+<para>Enter the name you wish to give your profile here.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Host</guilabel></term>
+<listitem>
+<para>
+This is the hostname of the server you are copying the files to. Either a
+fully qualified domain name, or an IP address is needed.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Protocol</guilabel></term>
+<listitem>
+<para>
+Transfer protocol to use for this upload. Depending on your version of
+&kde; this list will vary. At the very least you should be able to choose
+from &FTP;, file (&ie; local) and <acronym>NFS</acronym>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Port</guilabel></term>
+<listitem>
+<para>
+Port for the transfer. Usually this will not need to be changed unless your
+network administrator is hosting a service on a port other than its well
+known port.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>User</guilabel></term>
+<listitem>
+<para>
+Username to use for authentication.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Password</guilabel></term>
+<listitem>
+<para>
+Password to use for authentication.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Store password on disc</guilabel></term>
+<listitem>
+<para>
+Depending on your level of paranoia, this is a time saving feature, or a
+danger. Use it at your discretion. The password is kept on disk as text in an obscured form, so it's not simple to read it, but anyone with programming knowledge can easily un-obscure it.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Path</guilabel></term>
+<listitem>
+<para>
+This is the base path on the remote host that you will be copying files
+to.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Use as default profile</guilabel></term>
+<listitem>
+<para>
+Allows you to mark the profile currently being viewed as the default.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect3>
+</sect2>
+
+<sect2 id="project-views-3-2">
+ <title>Project Views</title> 
+ <para>
+ A project view is just a set of files and toolbars. You can have multiple views in a project, meaning that by simply changing the view you can load several files and toolbars which will replace the currently opened files and toolbars.
+ </para>
+ <para>
+   Views can be saved, opened, deleted using the <guimenu>Project</guimenu> menu or the <guilabel>Project Toolbar</guilabel>, accessible via <menuchoice><guimenu>Settings</guimenu><guisubmenu>Toolbars</guisubmenu><guimenuitem>Project Toolbar</guimenuitem></menuchoice>.
+ </para>
+ <para>
+   You can have a default view (loaded when the project is opened). See <xref linkend="configuring-projects-3-2" />.
+ </para>
+</sect2>
+</sect1>