Tips and tricks
# Chapter 5 Fresh tips and tricks.

    There is still no full user guide for Fresh.

    I will write in this page some tips and tricks. Later, they will be used in the full user guide.

## The new help engine

Fresh IDE contains an index of the help files in a file `%FreshHelp%/index.help`.
Every row in this file, contains a relative path to a single help file that to be searched when F1
is pressed in the Fresh IDE editor.

Fresh IDE supports following help file formats:

### Windows .CHM files.

They work good only in Windows. In Linux, Wine has CHM viewer, but essential features
are not supported.

### Windows .HLP files.

The support in Linux is a little bit better, but still not very useful.

### HTML files.

Fresh IDE searches the html files, scanning for anchor tag with `ID` containing the keyword searched.
For example, searching `%FreshHelp%/FASM.html` file for `movsw` keyword, Fresh will
find the anchor `<a id="movsw21148">`.

Then Fresh IDE will start the configured web browser on URL `http://127.0.0.1:7000/FASM.html#movsw21148`

Notice, that Fresh IDE uses built in web server to handle such files.

### `.idx` files.

These files are simple text file, containing index of URLs. The format of the file is:
;begin
KEYWORD = HELP_FILE_URL
;end

Empty lines and lines starting with ";" are ignored. The file must contains a special keyword `__index_main_file`
that to point to the main file URL.

In Fresh IDE, the Linux system calls help is organized this way. See `%FreshHelp%/lscr/index.idx` for example.

### Markdown formatted files with `.md` extension.

Similar to the .html files, Fresh IDE searches for anchor tags.

In markdown format they looks like: `[#KEYWORD]` at the beginning of the line.

Once the keyword has been found, Fresh opens the web browser at URL: `http://127.0.0.1:7000/helpfile.md#KEYWORD`


## Built in web server

Fresh IDE v2.1.9 and newer contains a built-in web server in order to handle the help files of different types.

This web server binds *only* to `127.0.0.1` IP address and automatically searches for accessible port in the range of `7000..9999`.

The web server automatically renders the markdown formatted help files to .html and send them to the browser.

## Configuring the web browser.

In order to use the online help system, Fresh IDE needs to know the path to some web browser.

Usually, on the first run (or if Fresh.ini file has been deleted) Fresh will try to guess the default OS web browser.

In Windows it will check the registry. In Linux `/usr/bin/xdg-open` command will be used.

Later, the user can change this setting from `Options|IDE options|IDE options|Web browser`.

There are three more options for the help system:

* *"Try google as a last hope"* - if checked and the searched keyword has not been found in the configured help files,
Fresh IDE will try to search with *google.com* for the specified keyword. 

* If *"I'm feeling lucky"* option is checked as well, the browser will go directly to the first found web site.

* *"Ignore WinApi suffix on search"* - if checked the system tries to detect the "A" or "W" suffix on the searched keyword and removes it, in order to provide better search results, because the API functions are usually specified without this suffix.

The former two options works very good for searching Windows API functions - in most cases it navigates directly at the proper page in MSDN.


## Linux support

* How to develop Linux application from Windows?

* How to develop Windows application from Linux?

* What about Fresh IDE version for Linux?

    For now, Fresh is Windows application. The versions 2.x.x will be Windows applications.
The upcoming v3.0.0 is planed to be portable - for Windows and Linux. Of course every port
will be able to create applications for every OS.

    Despite of this situation, even the current versions can work in Linux through Wine.

    There is a separate [setup][setup manual] describing the setup of Fresh IDE for Linux development.

[setup] advanced_setup.md

## Goto address

    How to find the place in the source where application crashes?

    Press Ctrl+G in order to open "Goto address" dialog:

	[!goto][Goto address]

    Then enter the address where application crashes and press OK. Fresh will show you the
line of the source that is compiled on the given address. The format of the number is standard
FASM number format.


## Code exploration and cross reference.

There are several functions, aimed to provide easy exploration the source of the big project.

### Unroll macro

This function displays in the scratch pad window the preprocessed code, generated from some
line in the source. If the line contains macro invocation, the macro will be unrolled and 
the result code displayed in the hierarchical form in the window.

The function can be activated by pressing *Ctrl+U* shortcut when the caret is on the needed line or
by using the editor context menu - "Unroll macro".

The source must be compiled and this file to not be changed after compilation in order to use this function.


### Labels explorer

After compilation, you can browse all labels tree from the labels explorer. Open it from the
main menu: `Project|Label explorer`.
In the label explorer you can view the lables values, type and where in the source these labels
was defined and used.

### Editor cross reference

If you position the text caret on some label and press Ctrl+R, or choose from context menu
"Cross reference", a window with the cross reference information for this label will be open.

	  [!cross][Cross reference]

The first row of the table display the line of the source, label was defined.
Following rows - the lines where the label is used. Besides the pointed label, all its
children labels will be displayed.s

If you double click on some of the rows, the editor will bring you to this line of source.

The cross reference window can be closed by pressing *Esc* key.

## Goto definition

If you position the text caret on some symbol and press *Ctrl+D* or choose from the context menu
"Goto definition", the editor will bring you to the line of the source where this symbol were
defined.
The project must be compiled for this function to work.

## Embeded help

Similar to "Goto definition" is the next function "Embeded help".

If the definition of some symbol is preceded by comments block, describing this symbol, Fresh can
show this description everywhere in the source, when you position the text caret on the symbol and
press *Ctrl+W* shortcut.

The hint window looks like on the screenshot:

		    [!_images/EmbededHelp.png][Embeded help system]

The hint window can be closed by pressing *Esc* key.

## Arguments hint

    How to use "Procedure arguments hint"?

	[!procarg][Procedure argument hints]

    This function works with call macros: *stdcall, ccall, invoke and cinvoke*;

    When you type such line and the function is known (the source have to be compiled prior to
that moment) Fresh shows a hint window that helps you to enter the arguments. This happens
automatically when you type "," somewhere in the line.

    When you want to open the hint window without typing (just for check up) you can press
Ctrl+Q when the caret is at the line. You can close the hint window, pressing *Esc* key.

    "Procedure argumens hint" works for the procedures defined in the compiled source and if
the program uses import definitions from FreshLib, for imported functions as well.

## Code completion

    How to type less and to code more?

	[!code][Code completion]

    Code completion is very powerful function, that can save you thousands of keystrokes.
In order to use it, the source have to be compiled (at least partially - some errors are
acceptable) because Fresh have to build the tree of labels, defined in you program.

    Fresh does not use fixed pre-defined lists. It uses the labels you defined in the source.

    This is the only possible solution, because Fresh is not committed to any particular OS or
platform. If you write Win32 program, you need Windows API and constants in the auto completion box.
If you write Linux program, you need all Linux constants and API functions.

    To open code completion, press *Ctrl+Space* shortcut. Then when you type, the content of the box
will be refreshed in order to correspond with the word you type.

    You can select suitable element from the list with *Up, Down, PgUp and PgDn* keys
and press *Enter* to insert it in the line.

    Auto competion list will open automatically when you type some existing in the list label
and then press *"."* in order to select local label.

    You can close the auto completion window with *ESC* key.

## Project categories

    How to move a file from one category to another in the project?

    Open the file in the editor. Select the category where you want it to be moved.
Click the right mouse button on the tab of the file in order to display the context menu.
Select "Add to project" function. It will remove the file from the old category and will
move it to the current selected category.

## Fast open files

    How to open the file specified in "include" or "file" directive?

    Place the caret on the line that contains file name and press Ctrl+Enter.
    Opening files this way, Fresh replace the directory aliases and/or environment
variables in the filename.

    Files like `%lib%/%TargetOS%/MyFile.asm` will be opened correctly.

## Directory aliases

    How to set promptly the values of the environment variables?

    Fresh have very flexible system of environment variables handling. Actually I prefer to call them
"Aliase", because they are aliases of the directories or other text.

    You can define such aliases in three ways:

* As OS environment variable.

* As IDE-wide aliases in the Fresh IDE options dialog ("Options|IDE options|Aliases" menu).

* As Project-wide aliases in the project options (Project|Project options" menu or Ctrl+F12 shortcut)

    When exists alias defined several times, then the project aliases have higher priority, then
the IDE aliases and with lowest priority are the OS environment variables.

    Now on the topic: The project aliases allows rapid value change. In order to use this
feature, you have to define the alias with several values, delimited with "|" symbol.
The count of different values is not limited.

    One typical example is the alias %TargetOS% used in the FreshLib test project.
This alias may have as values the names of the OS, the project will be compiled for.
So, in order to switch quick from Win32 to Linux we can define TargetOS as "Win32|Linux".

    In this case, at the top of the project window appears popup menu, where you can select what of these
values to be used. Additionally, the panel "Settings:" will display currently selected values.

       [!alias][Alias fast change]

## Portable applications

    How to write portable assembly applications with Fresh IDE?

    Most people think that assembly language can't be portable. It is not the case. There are many
examples that assembly can be portable. It is only matter of the project design, not the language.

    In order to allow creating of portable applications, FreshLib was created. It is work-in-progress,
but even now it allows creating of small applications that can be compiled for Win32 and Linux platforms
without change of the source.

    Read the unfinished [FreshLibRef][FreshLib reference manual]
and check the sources of FreshLib in "Fresh/freshlib" directory of your Fresh IDE installation.
There is a working test project called TestFreshLib.fpr that I use to test different FreshLib features.

Also, you can create FreshLib projects from template engine. Choose "File|New Application" from the
main menu or press *Shift+Ctrl+N* shortcut.

In the dialog window, select the target directory and application template -
"FreshLib portble console application" or "FreshLib portable GUI application",
then click *"OK"* and new project will be created.

Press *Shift+Ctrl+S* to save all new created files (you can change the filenames to whatever you like).

Then you can compile your application to Linux or Windows executable file.

The latest development version of FreshLib can be downloaded from the [rep][repository] - *FreshLibDev* branch.

[FreshLibRef] FreshLibRef.md

[rep] http://chiselapp.com/user/johnfound/repository/FreshIDE/

[!goto] _images/goto.png

[!procarg] _images/ProcArgumentsHint.png

[!code] _images/CodeCompletion.png

[!alias] _images/AliasFastChange.png

[!cross] _images/CrossReference.png