DiaSCE, The C/C++ Code Editor
----------------------

In this file, you'll find the instalation instructions for DiaSCE (section 
1.4), as well as the usage manual (if you want to see an example of how to use 
DiasCE, jump to the 2.5 section of the user manual).

USAGE MANUAL
-------------

This section is intended to be a brief introduction to the usage of DiaSCE. The 
section will be completed for the 1.0 release of DiaSCE.

1.- Introduction
	1.1.- What's DiaSCE
	1.2.- Basic features of DiaSCE
	1.3.- Needed and suggested programs to work with DiaSCE
	1.4.- Installation instructions
2.- Basic functionality of DiaSCE
	2.1.- Executing DiaSCE
	2.2.- Menu bar options
		2.2.1.- File menu
		2.2.2.- Edit menu
		2.2.3.- View menu
		2.2.4.- Project menu
		2.2.5.- Settings menu
		2.2.6.- Tools menu
		2.2.7.- Help menu
	2.3.- Toolbars
	2.4.- Other elements
		2.4.1.- The CEFV Tree
		2.4.2.- The File Tree
		2.4.3.- The Code Editor Window
		2.4.4.- The Message Window
	2.5.- Session example
3.- Advanced functionality of DiaSCE
	3.1.- Preferences
	3.2.- Project settings
	3.3.- Recently oppened projects
	3.4.- Using multiple Tabs
	3.5.- Using the Functions Tab
	3.6.- The Search / Replace
	3.7.- Using external programs
	3.8.- Compilation and execution options
4.- Files used by DiaSCE

1.- Introduction
------------------

This section will give a description of DiaSCE, explaining the basic features 
and giving a list of programs that are required by DiaSCE to work properly, and 
a list of suggested programs that are useful for a better use of DiaSCE.

1.1.- What's DiaSCE
--------------------

DiaSCE is a C/C++ code editor for Gnome. The idea is to be a light code editor 
that doesn't need too many resources, and makes use of external applications 
for tasks like compiling, debugging,... It pretends to be a conplement for 
Glade, so it uses Glade for GUI development.

It is written in C, using the gnome libraries, and using XML for the files it 
generates.The GUI is developed using Glade.

The program is distributed under the terms of the GNU General Public License 
version 2 or later.

1.2.- Basic features of DiaSCE
------------------------------

DiaSCE offers some features to help developing an aplication. Here you have a 
list of the most important:

- Management of project files
- Creation of files used by automake and autoconf
- Compilation, linking and running
- Integrated with Glade for GUI development
- Code edition using multiple tabs
- Syntax highlighting
- Fast access to functions, variables, structures...
- Search functions
- And much more... ;-)

1.3.- Needed and suggested programs to work with DiaSCE
-------------------------------------------------------

Here is a list of programs that are REQUIRED by DiaSCE to work properly:

- Automake
- Autoconf
- Find
- Exhuberant-ctags

And here you have a list of suggested programs, which will let you use all the 
features offered by DiaSCE:

- Glade : For GUI development
- gcc 
- GNU Make
- gdb, DDD : For debugging
- which : For a faster detection of programs by DiaSCE
- grep : To search in multiple files
- Memprof : For memory leak detection
- Electrif fence : For malloc() debugging
- lpr : To print

1.4.-Installation instructions
-----------------------

To build DiaSCE from the source code, you'll need the following development 
libraries and headers instaled in your system:

- Gnome 
- XML 
- glibc 
- Xfree86
- gtk

The package names are diferent between distributions. As a tip, I've instaled 
these:

Debian:  
	libxml-dev
	libgnome-dev
	... and let apt solve the dependencies ;-)

Mandrake7:  (dependencies given by rpmdrake)
	gnome-libs-devel
                audiofile-devel
	gtk+-devel
	libjpeg-devel
	libpng-devel
	zlib-devel
	glib-devel
	libxml-devel
	esound-devel
	libungif-devel
	libtiff-devel
	XFree86-devel
	libgr-devel
	kernel-headers
	imlib-devel
	Orbit-devel
	indent
	glibc-devel

I think that the package names for Redhat are similar to the ones for Mandrake.

Once you have all the development libraries and headers installed, you can 
build DiaSCE by doing:

	- tar xvzf DiaSCE-xxxxxx.tar.gz
	- cd DiaSCE-xxxxx
	- ./configure
	- make
	- (as root) make install

This will hopefully build DiaSCE correctly. 

If you have problems, you can try generating a new "configure" script by 
executing "autoconf" and running the configure again.   

If you still have problems, check if you have installed all the needed 
libraries and headers, as shown above.

If you still have problems, send us a mail and we'll help you as soon as we 
can. You can use the form of our web page (http://DiaSCE.es.gnome.org).

2.- Basic functionality of DiaSCE
---------------------------------

In this section you'll find a description of basic functionalities of DiaSCE, 
and a sample session of DiaSCE, to help you take first contact with the 
aplication.

2.1.- Executing DiaSCE
----------------------

Once instaled, you just have to type "diasce" in the command shell. It will 
launch DiaSCE and create a configuration file called .david in your home 
directory. It will then perform some detections of programs and libraries, and 
at 
last you'll be presented the main window. This windows has some elements that 
will be described in the next sections.

2.2.- Menu bar options
-----------------------

This section will describe the options you'll see in the menu bar.

2.2.1.- File menu
------------------

This menu has the following options:

- New Project: This option to starts a new project
- New File: This option creates a new file and adds it to the project
- Open project: Use this option to open an existing project
- Save: This option saves the changes of the current file
- Save all: This option saves the changes of all the files of the project
- Print: This option will print the current file
- Exit: To exit DiaSCE

In this menu you'll also find shortcuts to recently openned projects.

2.2.2.- Edit Menu
------------------

This menu has the following options (self explanatory):

- Cut
- Copy
- Paste
- Delete
- Search

2.2.3.- View Menu
------------------

This menu has the following options:

- Show message box: To toggle the status (visible/hidden) of the message window
- Show file box: To toggle the status of the file/CEFV windows

2.2.4.- Project Menu
---------------------

This menu has the following options:

- Compile: To compile the project files
- Make: To compile and link the project files
- Run: To compile, link and run the project in a terminal
- Add existing file: To add an external file to the project
- Properties: To change the project properties (information, directories, 
compilation and debugging options...)

2.2.5.- Settings Menu
----------------------

This menu has the following options:

- Preferences: To change configuration options of DiaSCE

2.2.6.- Tools Menu
-------------------

This menu has the following options:

- Glade: To launch Glade when you want to develop the GUI of your program.
- DDD: To launch DDD to debug your project
- Memprof: To launch Memprof, to help you detecting memory leaks.

2.2.7.- Help Menu
------------------

This menu has shortcuts to the API description files of different libraries. 
The path to these files must be configured in the Settings Menu.

2.3.- Toolbars
--------------- 

DiaSCE has 2 toolbars. 

The first of them has shortcuts to some menu options. 

In the second one you can find the Function List. From this combo box, you can 
select a function that will be displayed in the editor tabs. The functions are 
alphabetically sorted. In this toolbar you'll also find two buttons to 
display/hide the message and file windows.

2.4.- Other elements
---------------------

In this section you'll find the description of other elements of the main 
screen of DiaSCE:

2.4.1.- The CEFV tree
----------------------

This tree has entries for every function, class, variable, structure... of the 
loaded project. When you select one of the entries of this tree, it'll be 
displayed on one of the code editor's tabs.

2.4.2.- The File tree
----------------------

This tree lists files that are inside of the loaded project. You can load the 
files in the code editor's tabs by selecting them in this tree. If the file 
was not loaded before, it'll be loaded in the first tab.

2.4.3.- The Code Editor window
-------------------------------

This window is where the files are shown. It has different tabs:

- 1st tab: This is the "master" tab. Every file that is loaded for the first 
time will be shown in this tab. You can then move the file to another tab by 
selecting "Move to new tab" from the right-mouse-button menu.

- 2nd tab: This is the "functions" tab. This tab is used to display the 
function definitions you want. When you want to see one function's definition, 
you just have to put the cursor over the function call, and from the 
right-mouse-button menu, select "Show Function". The definition of the 
function will be show in this tab.

- next tabs: This tabs are used when you select "Move to new tab" when you're 
viewing one file in the 1st tab.

2.4.4.- The Message Window
---------------------------

This window is where DiaSCE displays the messages. When you compile the 
project, or when you perform a search in multiple files, the results will be 
displayed in this window (warnings, errors and search results). You can click 
on those messages to go to the line number they refer to.

2.5.- Sample session
---------------------

Here you'll find an example of the usage of DiaSCE.

Start DiaSCE by executing "diasce" from the command line.
 
When the main screen comes up, you can start a new project by selecting "New 
Project" from the file menu. The project window will come up, where you must 
enter some information for the project: 

- "General" Tab: General information, name, email, languaje, version...
- "Files" Tab: Here you have to enter the directories where project files will 
be stored. If your project is going to have a GUI, you must select the name of 
the glade file.
- "Libraries" Tab: Here you select the libraries your project will use.
- "Warnigs" Tab: Here you select the warnings you wan't to see while compiling 
your project
- "Compiler" Tab: Here you can select the optimization level, the debug level..

Once filed this project windows, select Accept and the project files will be 
created. 

Before you can start coding, you must create a new file or add an existing 
file to the project. Once the file is added to the project, you can select it 
in the File Tree, and the fille will be openned for editing in the Code Editor 
Window. Now you can start coding. :-)

If you want to add external files to the project, you can do it by selecting 
"Add existing file.." from the "Project Menu".

If you want to add a new file, you can do it by selecting "New File" from the 
"File Menu" or using the toolbar button.

Then, you can select a file from the File Tree. The file will be loaded in the 
first tab of the Code Editor Window, where you'll be able to edit it. If you 
want, you can move the file to a new tab, as new files allways open in the 
first tab. 

If your project is going to have a GUI, you can build it by selecting "Glade" 
from the toolbar or the "Tools Menu". Glade will be launched, and when you 
finish editing your GUI, you save it and select "Write Source Code" from 
Glade. This will generate the interface files and the callbacks file, that 
will be added to your proyect.

If you want to see the definition of a function, you can select it in the 
Function List of the toolbar, or you can place the cursor over the function 
call in the code, right click and select "Show Function". The function 
definition will be shown in the Functios Tab.

Once finishing with the code, you can save it selecting "Save" (current file) 
or "Save All" (all project files).

You can the compile the code, by selecting:
- Compile: Compile the project
- Make: Compile and link the project
- Run: Compile, link and run the project 

You'll see the results in the message window. If there is any warning or 
error, it'll be shown in this window, and you can go to the line of the 
warning or the error just by clicking over it in the message window.

To exit DiaSCE, you just have to select "Exit" from the "File Menu".

3.- Advanced Functionality of DiaSCE
------------------------------------

In this section, you'll find the description of the advanced functions of 
DiaSCE. 

3.1.- Preferences
------------------

In this menu you have the options for the configuration of DiaSCE. The 
Preferences Windows contains the following items:

- "General" Tab

In this tab you have the following options:
	* Personal information (name, e-mail): 
	* Working directory: Directory where new projects will be stored.
	* Show text in toolbar buttons: This option let's you select whether toolbar 
buttons will have the name shown in the toolbar or not.

- "Editor" Tab

In this tab you have the following options:
	* Auto Indent: Select this option if you want DiaSCE to automaticaly indent 
lines like the previous line.
	* Super Indent: Select this options if you want DiaSCE to automatically add an 
indentation after openning braces.
	* Close braces: Select this option if you want DiaSCE to automatically put the 
closing braces when you open them.
	* Tab size: This options let's you select the size in chars of the tabulation.

- "Documentation" Tab

In this tab, you can enter the paths to the documentation files of some 
libraries. When you select one of the entries of the "Help Menu", DiaSCE will 
look here for the path to the documentation.

- "Colors" Tab

In this tab you can select the colors DiaSCE will use to highlight the syntax 
of your code. You can change the colors by pressing the colored buttons. You 
can also return to the default colors by pressing the "Default" button at the 
bottom.

3.2.- Project Settings
-----------------------

In this menu, you can fill the information about your project. Whenever you 
start a new project, the Project Settings Windows will pop up and you'll have 
to enter some options, like the project directories, compilation options, ...
If you want to change this information during the development of your project, 
you can access this windows from the "Project Menu". 

You can find the following options in this window:

- "General" Tab:

	* Name: Name of the project.
	* Version: Current version. This is used for the "--version" option of the 
command line, for example.
	* Author: You ;-)
	* e-mail: Your e-mail adress.
	* Languaje: The languaje of the project.

- "Files" Tab:

In this tab you can choose the directories where the project will be stored, 
as well as some other options.
	* Executable's Name: The name of the executable of the project
	* Project's Directory: The directory where the project files will be stored.
	* Source's Directory: The directory where the source files (sources and 
headers) will be stored.
	* Pixmap's Directory: The directory where the project pixmaps will be stored.
	* Glade's project file: If your project is going to have a GUI, you must 
select this option and especify a name for the glade project file
	* Create a header for every source file: Select this option if you want DiaSCE 
to automatically create a header file for every new source file you create.
	* Add GNU header to every file: Select this option if you want the GNU header 
to be added to the beginning of every file you create.
	* Add "#ifndef _HEADER_H"...: Select this option if you want DiaSCE to 
automatically add "#ifndef _HEADER_H_", "#define _HEADER_H_" and "#endif" to 
every new header file of the project.

- "Libraries" Tab: 

In this tab you can select the libraries your project will be linked against. 
If you select one of the libraries listed in this tab, and that library 
depends on another ones, the dependencies will be selected too. You can also 
especify libraries that are not listed in this window, by using the text 
entries at the bottom:
	* Others: Other libraries to link against
	* Libraries Path: Aditional paths to libraries for linking
	* Headers Path: Aditional paths to headers for compilation
Note: You must enter the (-l, -L, -I) too, for example:
	*Others:  -lglib-2.0  -lm  -latk-1.0
	*Libraries Path:  -L/usr/lib
	*Headers Path:  -I/usr/include/gkt-2.0

- "Warnings" Tab:

In this tab, you can select the warning levels you want to use to compile your 
project. You can select individual warnings, or you can select all the 
warnings by choosing -Wall at the top.

- "Compiler" Tab:

In this tab you can select the following options:
	* Optimize: Select this option if you want optimization to be added to the 
compilation of your project
	* Level: Level of optiomization selected.
	* Add debugging information: Select this option if you want your project to 
be compiled with debugging information.
	* Level: The debugging level selected
	* Link with electric-fence: If you have electric-fence instaled, you can 
select this option to have your project linked against it for debugging 
purposes.
	* Additional options: Additional options you want to pass to the compiler.

3.3.- Recently openned projects
--------------------------------

You can access the recently openned projects by selecting them in the "File 
Menu". There's one shortcut for the last 6 openned projects. 

3.4.- Using multiple tabs
--------------------------

By default, all the new files you select in the "File Tree" are openned in the 
first tab of the Code Editor Window. If you want to have more than one file 
openned at the same time, you can move them from the first tab to a new tab, 
by clicking the right mouse button and selecting "Move to new tab". The file 
will be moved to a new tab, and the first tab will be available to open new 
files. 

If you want to close a tab of the Code Editor Window, you can do by right 
clicking in that window and selecting "Close Tab".

The first and the second tab can not be closed, as they're used to open new 
files and to show function definitions.

3.5.- Using the Functions Tab
------------------------------

When you're editing code an you want to see the definition of a function, you 
can put the cursor over the function call or over the declaration, right click 
and select "Show Function". The function definition will be openned in the 
Functions Tab. 

The code shown in the Functions Tab is non-editable. This tab has a history of 
10 functions, which you can access by selecting the combo-box of the Functions 
Tab.

3.6.- The Search / Replace
-----------------

To perform a search / replace of character strings in DiaSCE, you must first 
open a file in the Code Editor Window. Then, you right-click on the Code 
Editor Window and select "Search..." or select it in the menu bar or the 
toolbar. The search window will pop up, where you can enter the search string, 
and select the search options. If you have selected text in the Code Editor 
Window, the text will appear in the search window. 

You have the following options in the search window:

- Search: Use this button to perform a search of the string entered in the 
Search string entry.
- Replace: Use this button to replace the searched string with the string 
entered in the Replace string entry.
- Replace All: Use this button to replace all the found strings with the text 
in the Replace string entry

You can configure the scope of the search, with the following options:

- Search in current file:  Select this if you want the search to be performed 
in the file that is currently active in the Code Editor Window. When a 
coincidence is found, it will be highlighted in the Code Editor Window. You 
can look for the next coincidence by pressing Search again in the Search 
Window. You can especify 2 options for this kind of search:
	* All file: Select this if you want to perform the search from the beginning 
of the file.
	* From cursor: Select this if you want to perform the search from the current 
cursor position to the end of the file.

- Search in multiple files: Select this if you want the search to be performed 
in multiple files. The results will be shown in the Message Window, and if you 
click in one of the results the file will be opened in the Code Editor Window, 
and the searched text will be highlighted. You can especify 3 options for this 
kind of search:
	* All Sources: Select this if you want to perform the search in all the files 
in the Sources Tree
	* All Headers: Select this if you want to perform the search in all the files 
in the Headers Tree
	* All Others: Select this if you want to perform the search in all the files 
in the Others Tree

- Case sensitive search: Select this option if you want the search to be 
case-sensitive.

The default search is a case-insensitive search performed in the current file, 
from the beginning of the file.

3.7.- Using external programs
------------------------------

DiaSCE gives you the option to use external programs for some tasks. You can 
launch these programs by selecting them in the Tools Menu or using the 
launchers in the toolbar. You can use the following programs:

- Glade: You can use Glade to design the GUI for your project. To use Glade, 
you must have selected the option "Glade File" in the Project Properties. Once 
you launch Glade, DiaSCE won't be available until you return from Glade. If you 
generate code from Glade, it will be added to your project by DiaSCE when you 
return.

- DDD: If you want to Debug your project, you can use DDD for it. You must 
have a binary of your project to use DDD. Once your project is compiled and 
linked, you can launch DDD by selecting it in the Tools Menu or in the Toolbar.

- Memprof: You can look for memory leaks by using the tool Memprof. You must 
have a binary of your project to use Memprof. Once your project is compiled 
and linked, you can launch Memprof by selecting it in the Tools Menu or in the 
Toolbar.

- Electric-fence: You can use this malloc debugger by selecting it in the 
Project Properties window, in the Compiler Tab. Once selected, your project 
will be configured to link against electric-fence. (Note: Electric-fence is a 
great tool for malloc debugging, but it uses a lot of RAM, so remember this 
when you use it)

3.8.- Compilation and execution options
----------------------------------------

You can run the "configure" script with the --prefix option to install DiaSCE 
in the location you want. If you want to know about more options you can give 
to the "configure" script, you can use the --help option.

DiaSCE accepts the execution options provided by Gnome. You can read a list of 
them by executing DiaSCE with the --help option.

4.- Files used by DiaSCE
------------------------

DiaSCE uses some files for the configuration and the project. It uses a file in 
the user's home directory called ".david" to store the configuration options 
of DiaSCE. This file should not be edited manually. You can edit the 
preferences from the Options Menu->Preferences.

The project files of DiaSCE are stored in the project's directory, and their 
name is finished with ".davidprj". This files should not be edited manually. 
You can edit the options from the Project Menu->Properties.








