<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" [
]>

<chapter id="features">
<title>Features</title>

<para>
<application>Screem</application> has a very wide range of useful features, and probably some not so useful ones :-)
</para>
<para>
The following section of this manual describes in depth each of those features, along with any currently know bugs so
you know how to avoid them while they are being fixed
</para>


<sect1 id="mutipages">
<title>Multiple pages open at once</title>
<para>
As can be expected in any reasonable editor multiple pages can be edited at once.  Notebook tabs for each page are present below the editor window, and can be switched between by clicking with the left mouse button.  Clicking on them with the right mouse button will present a popup menu allowing you to do the following:
<itemizedlist>
<listitem>
<para>
Save the page
</para>
</listitem>
<listitem>
<para>
Save the page as a different filename
</para>
</listitem>
<listitem>
<para>
Close the page
</para>
</listitem>
<listitem>
<para>
Rename the page
</para>
</listitem>
</itemizedlist>
</para>
</sect1>


<sect1 id="multiprojects">
<title>Multiple projects (or Sites) open at once</title>
<para>
As well as multiple pages open at once you can also have multiple projects, or Sites, open at once.  These can be switched between from the box at the top of the site view.  There is a special project call &quot;Single Pages&quot; which is used as a fake project for when you want to edit individual files which are not associated with any specific project.
</para>
</sect1>

<sect1 id="highlighting">
<title>Syntax Highlighting</title>
<para>
As already mentioned in the Getting Started Section <application>Screem</application> supports syntax highlighting.  There are a couple of ways to edit the highlighting colours.
<itemizedlist>
<listitem>
<para>
via the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice> menu item.
</para>
</listitem>
<listitem>
<para>
editing the syntax highlighting files
</para>
</listitem>
</itemizedlist>
</para>
<para>
Obviously the first option is the simplest to do.  Select the <menuchoice><guimenuitem>Colours</guimenuitem></menuchoice> option in the preferences dialog.  This will present you with a selection of frames, allowing you to change the colours for the different syntax groups.
</para>
<para>
The latter is more compicated.  The syntax files themselves utilise XML.  The files are stored in <filename Class="Directory">~/.screem/syntax</filename>.   A simple syntax file is as follows:
<screen>
&lt;?xml version="1.0"?&gt;
&lt;screem_syntax&gt;
	&lt;type&gt;mime type goes here&lt;/type&gt;

	&lt;group name=&quot;group name&quot;&gt;
		&lt;fore use=&quot;1&quot; red=&quot;65535&quot; green=&quot;0&quot; blue=&quot;0&quot;&gt;
		&lt;back use=&quot;0&quot; red=&quot;0&quot; green=&quot;0&quot; blue=&quot;0&quot;&gt;
		&lt;pattern&gt;regexp to match goes here&lt;/pattern&gt;
	&lt;/group&gt;
&lt;/screem_syntax&gt;
</screen>

You can have multiple &lt;type&gt; tags for each mime-type that the highlighting is for.  There is no limit on the number of &lt;group&gt; section there can be.  The &lt;fore&gt; and&lt;back&gt; elements control the foreground and background colour highlighting.  The use attribute determines if highlighting is in use, and the red, green, and blue attributes control the colour.
</para>
<sect2 id="highlightBugs">
<title>Known problems</title>
<para>
<itemizedlist>
<listitem>
<para>
The syntax highlighting causes horrible flickering in the editor on slower machines.
</para>
</listitem>
<listitem>
<para>
Doesn't like some expressions in syntax files.
</para>
</listitem>
<listitem>
<para>
May cause a crash due to the GtkText widget being so buggy.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>

<sect1 id="previewWindow">
<title>Previewing Pages</title>
<para>
An internal preview view is provided by <application>Screem</application> should you wish to check your work quickly without having to resort to an external browser / viewer.  The preview currently only handles plain HTML, ie no javascript, PHP etc.  Later versions will support these and also other document formats such as Docbook, and also possibly the use of <application>Mozilla</application> as the preview widget.
</para>
<para>
Any links in the preview view which link to pages in the site being edited can be clicked on, and the page will be opened up in the editor, ready to be modified.  External links will not work.
</para>
<sect2 id="previewBugs">
<title>Known Problems</title>
<para>
There are two different preview widgets that can be used, the default is GtkXmHTML and does a very poor job.  The second which screem will use if it was available when compiled is GtkHTML.   Problems from the GtkXmHTML preview will <emphasis>not be supported</emphasis>.  To tell if which one you are using type the following in a terminal window:
<command>
ldd `which screem` | grep html
</command>

</para>
</sect2>
</sect1>

<sect1 id="externalBrowsers">
<title>External Browsers</title>
<para>
Should you wish to see what your web documents look like in specific browsers <application>Screem</application> has support for 4 different ones.  The first is the default GNOME viewer for HTML documents which can be set from <command>gnomecc</command>.  The other three are user definable.  If one is not set then left clicking on the toolbar button will display a dialog where you can set the icon to display, and the application to use.  If already set the left clicking will display the page, whereas right clicking will display the configuration dialog allowing you to change the application and/or the icon.
</para>
</sect1>

<sect1 id="SiteWideTemplates">
<title>Site Wide Templates</title>
<para>
There are two different types of template that are supported.
<itemizedlist>
<listitem>
<para>
Page Templates
</para>
</listitem>
<listitem>
<para>
Site Templates
</para>
</listitem>
</itemizedlist>
</para>
<sect2 id="pageTemplates">
<title>Page Templates</title>
<para>
Page templates are as can be expected for individual pages.  You can use these to create standard page styles/ layouts
to quickly create large numbers of pages which share the same basic features.  When working on a site you can set a template
which will be used by default for all new pages created for that project.
</para>
</sect2>
<sect2 id="siteTemplates">
<title>Site Templates</title>
<para>
Site Templates describe a layout of an entire sites directory structure and files.  You can use this feature to have a standard
directory layout for sites and hence quickly build a basic site with a few clicks.  A very nice feature of site templates is that
they can include page templates as well, so not only do you get the directory heirarchy but you also get the basic page layouts as well.
</para>
</sect2>
<sect2 id="templateProbs">
<title>Known problems</title>
<para>
The site template feature needs a lot of work, especially on the interface used to create them.
</para>
</sect2>
</sect1>


<sect1 id="CVS">
<title>CVS</title>
<para>
CVS is a version control system that allows multiple developers to work on a project and handle merging the different changes made by individuals.  <application>Screem</application> supports CVS so multiple developers can work on a website without stepping on each others toes.  It is recommended that only 1 developer handles uploading the site at the moment if the upload wizard is used.
</para>
</sect1>


<sect1 id="DND">
<title>Drag and Drop</title>
<para>
Extensive Drag and Drop support is available in <application>Screem</application>  The main area which supports this the text editor itself.  The following areas support drag and drop:
<itemizedlist>
<listitem>
<para>
The editor
</para>
</listitem>
<listitem>
<para>
The Site file list
</para>
</listitem>
<listitem>
<para>
The document structure view
</para>
</listitem>
<listitem>
<para>
All the standard Gnome widgets that feature DnD, such as entry widgets.
</para>
</listitem>
</itemizedlist>
</para>
<sect2 id="editorDnd">
<title>Editor DnD</title>
<para>
The action taken when dropping items onto the editor depends on whether the draw was performed with the left mouse
button, or the middle mouse button.  Left button drops will insert text into the editor, the text itself will depend on what the
drop was.
<sect3 id="editorFileDrop">
<title>File Drop</title>
<para>
Dropping a file onto the editor with a left button drag/drop will insert that filename at the position it is dropped at.  The filename will be converted to a relative path if it is within the site being edited.
</para>
<para>
Dropping a file onto the editor with a middle button drag/drop will present a menu allowing you to select the action to be taken.
</para>
</sect3>
<sect3 id="urlDrop">
<title>URI Drop</title>
<para>
Dropping a URI onto the editor will insert that URI into the editor as text, drops from <application>Netscape</application> are supported, however drops from <application>Mozilla</application> are not currently supported.
</para>
</sect3>
<sect3 id="colourDrop">
<title>Colour Drop</title>
<para>
Dropping a colour onto the editor with a left button drag/drop will insert that colour code in quotes, eg:
<screen>
&quot;#ffa500&quot;
</screen>
</para>
<para>
Although there are no applications that currently support middle button drag/drop of colours, if one does occur on the editor you will be presented with a popup menu of what action to take.
</para>
</sect3>
</para>
</sect2>
<sect2 id="siteFilelistDnd">
<title>Site File List DnD (and Browse File List)</title>
<para>
The site file list will behave in the expected manner, drag/drops copy/move files/directories around.  A normal left button drag/drop will attempt to move the dragged/dropped item.  A middle button drop will give you the option.
</para>
</sect2>
<sect2 id="documentDnd">
<title>Document Structure DnD</title>
<para>
The document structure view drag/drop support allows you to move sections of SGML/XML documents around by dragging the elements.  As always a middle button drop presents a menu inquiring what action should be performed with the drop.
</para>
</sect2>
</sect1>


<sect1 id="tagList">
<title>User definable tag list</title>
<para>
The tag list provides a convinient way to access data that you commonly want to insert in the editor.  By default the tag list is populated with HTML 4.0 data.  You will also find the contents of your resources folders there as well.  One other group of items which may appear there is the function information from <application>Bluefish</application>, which will be available if Bluefish is installed on your system.
</para>
<para>
The tag list has a tree like organisation, where nodes with no children will insert data when clicked.  Now although it is nice having all the preset items available you may also add your own items here for quick access.  There is currently no graphical interface for this, but it is very easy to do as it is built up from XML files.  Here's a quick example:
<screen>

&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;TagTree&gt;
&lt;node name=&quot;group name&quot;&gt;
&lt;node name=&quot;example&quot; open=&quot;&amp;lt;opentag&amp;gt;&quot; close=&quot;&amp;lt;/opentag&amp;gt;&quot;/&gt;
&lt;/node&gt;
&lt;/TagTree&gt;

</screen>
This will create a group called &quot;group name&quot; with a single node in it which will insert &lt;opentag&gt;&lt;/opentag&gt; when clicked on.  You do not need to provide both open and close, an open attribute is required though, although it may be any string you wish.  For a larger example see <filename>$prefix/share/screem/screem.tagtree</filename> or the development manual.
</para>
</sect1>


<sect1 id="keyMacros">
<title>User definable key macros</title>
<para>
As well as the tag list for insertion of commonly used text you may also assigned key combinations to do the same task.
You can edit them via <menuchoice><guimenu>Settings</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice> and selecting the <menuchoice><guimenuitem>Keys</guimenuitem></menuchoice> item.
</para>
<para>
To add a new key combo type the combo you want, or click the <guibutton>Grab Key</guibutton> button which will wait for you to press the combo and insert the text in the <guilabel>New key combo</guilabel> entry.  The <guilabel>Action/Text</guilabel> entry is where you either enter the text that will be inserted upon pressing the key combo in the editor, or you can select a specific action to be performed from one of the preset options.  When you are happy with the combo clicked the <guibutton>Add</guibutton> button.
</para>
<para>
To update a key combination click on it in the list, then edit the information as per adding a new key combo.  When you are happy with it click <guibutton>Update</guibutton>, or if you decide you want it to be a new combo you can also click <guibutton>Add</guibutton>
</para>
<para>
Should you decide that you no longer want a specific combo select it in the list, then click on the <guibutton>Remove</guibutton> button.
</para>
</sect1>


<sect1 id="guileScripting">
<title>Guile Scripting</title>
<para>
Although <application>Screem</application> has many features you may find that you want more.  To help with this you can create a script written in Guile that can perform the task you want.  For more information on scripting read the development manual for Screem
</para>
</sect1>


<sect1 id="todoList">
<title>Project Todo list</title>
<para>
Managing a website may involve many tasks, and it can be difficult to keep track of them all.  Therefore <application>Screem</application> provides a project todo list when editing any site.  To access it simply click on the toolbar button.
</para>
<para>
The todo dialog shows all the current tasks for the project, along with their status.  To add a new item to the list click the <guibutton>Add</guibutton> button.  This will popup a dialog allowing you to enter the task details.
</para>
<para>
Obviously you will want to manipulate tasks once they have been added.  When a task has been completed select it in the list, then click the <guibutton>Complete</guibutton> button and it will be removed.  To modify the details of the task select it in the list and click the <guibutton>Edit</guibutton> button.
</para>
</sect1>


<sect1 id="tagHelp">
<title>HTML tag help</title>
<para>
Whether you are new to HTML, or an expert there are times when you will need to lookup some information, such as the allowed values of an attribute.  <application>Screem</application> provides help for HTML 4.0 tags.  You can view this help either by selecting the tag name in the toolbar combo and clicked in the help button, or the more powerful and useful way is via the editor popup menu, which will provide a help item if available.
</para>
<sect2 id="tagHelpProbs">
<title>Known Problems</title>
<para>
Without using GtkHTML the help doesn't work, this is due to the GtkXmHTML widget which isn't very good.
</para>
</sect2>
</sect1>


<sect1 id="inlineTaggingInfo">
<title>Inline tagging</title>
<para>
Inline tagging is a very powerful feature which comes in useful more often than not.  When the cursor is inside a tag, and you press <keycombo action="press"><keysym>space</keysym></keycombo> a popup menu will appear containing the valid attributes.  Where possible those attributes will have a submenu which will contain the legal values for that attribute.  Should you actually want the space character to be inserted into the editor just continue your typing and it will be inserted.  However if you only wish to insert a single space character you will need to press it twice.
</para>
<para>
The inline tagging works from the DTD for the current page, as such if it isn't available then the inline tagging will not work.  The menu is also accessable via the editor popup menu when clicking on a tag.
</para>
<sect2 id="inlineTaggingProbs">
<title>Known Problems</title>
<para>
Due to utilising the DTD support the inline tagging will only work if the DTD could be parsed.
</para>
</sect2>
</sect1>


<sect1 id="searchReplace">
<title>Search/Replace</title>
<para>
As can be expected there are search/replace features available, either from the toolbar, or the menu.  By default the find/replace just performs a straight forward comparison on the strings.  Once ready to start search/replacing click the <guibutton>Find Next</guibutton> button, this will jump to the next occurance of the string.  If you are replacing then you can click the <guibutton>Replace</guibutton> button to perform the action, or the <guibutton>Replace All</guibutton> button to replace every occurance without prompting.
</para>
<para>
Sometimes matching against a string isn't enough, therefore <application>Screem</application> supports the use of regular expressions in the find string.  This can be enabled by clicking on the checkbutton.
</para>
<para>
Project wide search/replace is also provided.  A list of all files where a match is found is shown in the find/replace dialog.  Clicking on a file in that list will view that file and allow you to perform the find/replace as usual.
</para>
</sect1>


<sect1 id="printing">
<title>Printing</title>
<para>
Printing support is included for both the editor, so you can print the text, and the HTML preview (GtkHTML preview required).
Along with the ability to print a print preview can also be viewed for both the editor and the preview.   Printing can be to a normal printer, or to a file.  gnome-print support is required when the binary is built.
</para>
</sect1>


<sect1 id="tooltips">
<title>PHP function tooltips</title>
<para>
PHP has a wide range of functions, as such you may not be able to remember the parameters a function requires.  To aid in solving this problem you can point the mouse over the name of a PHP function and the function prototype will be displayed in the status bar of the main application window.
</para>
<sect2 id="tooltipProbs">
<title>Known Problems</title>
<para>
Not all PHP functions are supported.
</para>
</sect2>
</sect1>

<sect1 id="linkView">
<title>Site Navigation View</title>
<para>
Large sites can have many pages, images, script files etc, therefore it can be useful to see how everything links together and see an overview of your site.  The Site Navigation View is centred around the current file being edited.  It allows you to control the depth of links that will be displayed, scroll around the view, and even zoom in / out so that more / less of your site is displayed.
</para>
<para>
Just viewing the linkage is useful, but you may also decide you want to edit one of the pages in the view, this can be done by simply double clicking on the file in the view.  A popup menu, identical to that available in the Site file list is also available by right clicking on the file in the view.
</para>
<sect2 id="linkViewProbs">
<title>Known Problems</title>
<para>
<itemizedlist>
<listitem>
<para>
Processor usage will go to 100% sometimes, just quit <application>Screem</application> and restart it.
</para>
</listitem>
<listitem>
<para>
Sometimes links will stay in the &quot;Checking&quot; state, this is a problem with gnome-vfs
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>


<sect1 id="documentStructure">
<title>Document structure view</title>
<para>
The document structure view provides the tree structure of the current document.  Clicking on a item in the tree will take you to the line in the editor that contains that tag.  This can be useful for naviating around a large document.  You can also reorganise your document by dragging parts of the tree around and placing them elsewhere.
</para>
</sect1>


<sect1 id="TagProperties">
<title>Tag Properties View</title>
<para>
The tag properties view is an alternative method for setting the attributes in a tag.  Its shows every legal attribute for a tag, based on the DTD in use, and allows you to enter/select the value for those attributes.  Pressing enter/return in each text area will insert that attribute.  Using this view you can easily enter all the attributes for a tag that you want without having to type them all in the editor.
</para>
<sect2 id="tagPropertiesProbs">
<title>Known Problems</title>
<para>
Requires that the DTD in use is parsed correctly.
</para>
</sect2>
</sect1>


<sect1 id="spellChecking">
<title>Spell Checking</title>
<para>
Intelligent spell checking is available from the toolbar.  It is intelligent in so much as it will not try and correct and markup, namely tags and attributes.  Attribute values are not currently spell checked although this is on the list of things to be implemented.
</para>
<sect2 id="spellCheckinProbs">
<title>Known Problems</title>
<para>
Lots
</para>
</sect2>
</sect1>


<sect1 id="intelliClose">
<title>Intelligent tag closing</title>
<para>
Ever get sick of having to type all those closing tags?  Well now you don't have to!  <application>Screem</application> will automatically fill in the correct closing tag name when you enter the / character part of the close tag.  This is based on the currently loaded DTD.  If the tag shouldn't be closed you will receive a message on the status bar of the main application window.  If the tag is already closed you will also receive a message in the status bar.
</para>
</sect1>


<sect1 id="intelliEntity">
<title>Intelligent entity insertion</title>
<para>
Can't remember the SGML entity name for a character you want to insert?  It doesn't matter with <application>Screem</application> as the correct entity can be inserted when you press the character.  There are some special exceptions to this, such as for &amp;, &lt;, and &gt; which requires you to enter the &amp; then press the character.
</para>
<para>
If you aren't using the ISO-8859-1 character set then you may not actually want the entity insertion.  In that case you can turn the feature off, or have it enabled on a character set basis.
</para>
</sect1>


<sect1 id="internationalisation">
<title>Internationalisation</title>
<para>
English not your native language?  Well <application>Screem</application> supports GNU gettext style internationalisation, and currently has support for 13 non English languages.  These are:
<itemizedlist>
<listitem><para>Danish</para></listitem>
<listitem><para>German</para></listitem>
<listitem><para>Spanish</para></listitem>
<listitem><para>French</para></listitem>
<listitem><para>Italian</para></listitem>
<listitem><para>Japanese</para></listitem>
<listitem><para>Norwegian</para></listitem>
<listitem><para>Polish</para></listitem>
<listitem><para>Brazilian Portuguese</para></listitem>
<listitem><para>Russian</para></listitem>
<listitem><para>Swedish</para></listitem>
<listitem><para>Turkish </para></listitem>
<listitem><para>Ukrainian</para></listitem>
</itemizedlist>
Some of the internationalisation may not be up to date with the current release version.
</para>
</sect1>


<sect1 id="linkFix">
<title>Automatic link updating</title>
<para>
Don't feel like going through every file in your web site whenever you change the name or move a file?  Well you don't have to!
<application>Screem</application> will automatically update links to files which you move/rename within Screem itself.  If you perform the move or rename outside of Screem then you will still have to do it all by hand.
</para>
<para>
Relative links will be kept relative, and absolute links will stay as absolute links.
</para>
</sect1>


<sect1 id="plugins">
<title>Plugin Support</title>
<para>
In order for <application>Screem</application> to be more extensible plugin support has been present from day one.  The plugin support allows separate features to be released and/or distributed separetly from the main Screem pacakge, and also allows you to lessen the memory usage by not loading the plugins you don't want.
</para>
<para>
Currently the only plugins available are those that come with the main package.  For information on creating plugins see the development manual.
</para>
<!-- add info on all current plugins -->
</sect1>


<sect1 id="DTD">
<title>DTD Support</title>
<para>
<application>Screem</application> has support for looking at the &lt;!DOCTYPE&gt; tag and reading the DTD file, if present on the system, or downloading the DTD if not.  Other features, such as inline tagging for example will then use the DTD to decide what to present to you.
</para>
<para>
The following features utilise DTD support
<itemizedlist>
<listitem>
<para>
inline tagging
</para>
</listitem>
<listitem>
<para>
auto closing tag completion
</para>
</listitem>
<listitem>
<para>
invalid element warning
</para>
</listitem>
<listitem>
<para>
element properties view
</para>
</listitem>
</itemizedlist>
</para>
<sect2 id="DTDProbs">
<title>Known problems</title>
<para>
Currently there are problems parsing some DTDs and so only simple ones, such as HTML will probably parse correctly, others such as Docbook are known to have some problems.
</para>
</sect2>
</sect1>
</chapter>