/'* \file Tutorial.bi
\brief Source for Tutorial pages

This file contains the context of the Tutorial pages of this 
documentation. There's no executable source code in this file and it 
isn't used in the fb-doc source code tree.

It's context gets included in to the documentation when Doxygen 
scans the *. \em bi files in the \em src folder.

'/

/'* \page introduction Introduction
\tableofcontents

\section intro Introduction

In software projects it's state-of-the-art to write and edit the 
documentation context inside the source code. This way the 
programmer can adapt the documentation on each bug fix or 
improvement at one place (in comments placed in the source file). 
Beside the compiler, which extracts information for the CPU, an 
additional tool-chain is used to extract the information from the 
source code comments to build the documentation.

Powerful tool-chains (back-ends) exist for several programming 
languages like C to generate output in different formats, ie like 
\em html, \em pdf, \em man-pages and others. But privious to fb-doc
there is nothing for FreeBasic source code yet.

Since it's a lot of work to design and test such a tool-chain for 
several output formats, fb-doc isn't designed as a complete tool 
chain. Instead it works as a bridge that closes the gap between 
FreeBasic and C syntax to make existing, well developed and tested C 
documenting back-ends usable with FreeBasic syntax. fb-doc has been 
tested with

 - gtk-doc (see: http://developer.gnome.org/gtk-doc-manual/stable/index.html)

 - Doxygen (see: http://www.doxygen.org/)

The first is a good choise if you like to document a libraries API 
in the GNOME documentation style. In all other cases, especially 
when you have to document a program or application, the later is the 
better choise. Doxygen is a more modern tool, it's easier to handle, 
comes with a GUI front-end and has more features than gtk-doc.

The steps to generate a well documented project are

 -# generate source code, compile and test it

 -# add documentation comments and up-date them on each change 
    inside the source code

 -# run fb-doc on the FreeBasic source code to build a C-like 
    intermediate format

 -# run the C-back-end on the intemediate format to build the 
    documentation output in one or more output formats (ie \em html, 
    \em pdf, \em manpage, ...)

This intermediate format doesn't contain complete C source and 
cannot get compiled by a C compiler. Instead it just includes all 
information the lexical scanners of the back-ends need to build the 
documentation output. And fb-doc itself doesn't parse the complete 
FreeBasic source code. Instead it also acts as a lexical scanner to 
extract just the necessary information. Therefor fb-doc shouldn't be 
executed on buggy source (, be prepared to face fancy output in that 
case).


\section prinzip The Prinzip 

First fb-doc has to copy the documenting comments from the FreeBasic 
source code to the intermediate format and adapt the characters 
starting and ending the comment from one language to the other. But 
since some comments may only be useful in the FB source and others 
should go to the documentation, fb-doc uses magic characters at the 
beginning of a comment to specify how to act. FreeBasic syntax 
allows two kinds of comments

 -# line end comments starting by a ' character and ending at the 
    line end

 -# comment blocks enclosed by /' and  &apos;/

fb-doc supports both types. To get the comment emitted to the 
intermediate format, its first character has to be a *. In that case 
the context of the comment gets emitted as a similar C construct (as 
a line end comment starting by // or as a comment block enclosed by 
\f$/*\f$ and \f$*/\f$).

\note There's also the additional magic character '&' that makes 
       fb-doc emit the comment context as pure C-source.

See \ref exacomments for an example.

Second the lexical scanner of the back-end needs to know the target 
of the documentation context. This can be a declaration of

 - a variable (VAR / DIM / CONST / COMMON / EXTERN / STATIC),

 - a memory block (ENUN / UNION / TYPE / CLASS),

 - a forward declaration (TYPE alias),

 - a function (SUB / FUNCTION / PORPERTY / CONSTRUCTOR / DESTRUCTOR) or

 - a macro (\#DEFINE / \#MACRO).

fb-doc scans for this keywords and analyses the context. Depending 
on the choosen emitter it generates output in a specific way. In the 
default configuration (when acting as the start of a documentation 
tool-chain) fb-doc translates the context to C (or C-like) source.

See \ref exadim for an example.


\section introadd Additional Features

In addition to this basic feature fb-doc offers further 
functionality by adapting the operation mode and emitter:

 -# It can extract a list of all function names from the source code 
    tree. The list is necessary to generate caller / callee graphs 
    with Doxygen back-end (as in this documentation), see \ref 
    backdoxy for details.

 -# It can generate templates inside the FB source when acting as a 
    Geany custom command. We can mark a block of source code in 
    Geany and send it to fb-doc. fb-doc generates a matching 
    documentation comment block and prepends it to the source, see 
    \ref usagetemplates for details.

Depending on the operation mode it can input either from StdIn or 
files and output to StdOut or files. Piping context in and from 
fb-doc offers a lot more fields of application. In case of file 
input / output, *.\em bas files get translated to *.\em c files and 
*.\em bi files translate to *.\em h.

Last but not least fb-doc comes with a plugin-interface. It can load 
and use external emitters, compiled as a dynamic loadable library (*.
\em dll or *.\em so). By such an external emitter modul any output 
can get generated, using the informations comming from the fb-doc 
scanner.

An example source code for an external emitter is in the package, 
just customize it by your functionality. External emitter plugins 
may add features like

 - an emitter filling a data base as input for source code analysing 
   tools like <a 
   href="http://sourcenav.sourceforge.net/">sourcenavigator</a> 

 - an emitter to generate direct output, ie html pages

 - an ...


\section introself About this Text

And finally some words about this documentation (the text you're 
currently reading). It is generated from FB source in the above 
mentioned way by using Doxygen as back-end. If you need examples for 
any topic just study the fb-doc source code. Beside this you may 
want to check the file \em Doxyfile in the \em src folder. It 
contains the configuration for Doxygen to extract this pages. A 
good start may be to use these files and create your customized 
fb-doc documentation and play around with the parameters.

To be honest: in some cases this documentation may be a bit 
overloaded and serve more information than necessary. But one of the 
reasons for creating it is to demonstrate the features of fb-doc and 
Doxygen. Therefor not all possibilities are used to reduce the 
output to the essentials (see the Doxygen manual for details).

\note It's not under the scope of this documentation to describe the 
       usage of any (or all possible) tool-chain(s). Please refer to 
       the respective manual(s) for further information.

'/


/'* \page installation Compiling and Installing
\tableofcontents

fb-doc gets shipped as a FreeBasic source tree. Find the code in the 
\em src folder of your \em fb-doc.zip archive. To create your 
binary for your operating system just extract the folder to any 
place on your hard disk and compile the main file 
<em>fb-doc.bas</em>. Ie load the file in to Geany IDE and choose 
<em>Build -> Compile</em> menu. Or call the Freebasic compiler at the 
command line (in the extracted \em src folder)

\code fbc -w all fb-doc.bas \endcode

This creates an executable binary named

 - <em>fb-doc</em> (on LINUX) or
 - <em>fb-doc.exe</em> (on DOS / windows).

That's all you need to get started. Now you can use fb-doc and check 
its features, translate FB code to C (ie the fb-doc source) and 
generate templates. But &mdash; as mentioned in the prvious section 
&mdash; fb-doc is not a complete tool-chain. To generate some 
documentational output you additionally need a back-end for C 
source, like

 - <a href="http://developer.gnome.org/gtk-doc-manual/stable/index.html">gtk-doc</a> 

 - <a href="http://www.doxygen.org/">Doxygen</a> 

Download one of these packages for your operating system and follow 
the installation instruction.

There's no need to install fb-doc when you just want to find out if 
it's helpful. For a short test just place the compiled binary in any 
of your source folders and execute it there (see \ref usage for 
details). Depending on the used options it may create the folder 
<em>../doc/c_src</em> (beside your source folder) and write some 
files in it. And it may create the file <em>fb-doc.lfn</em> in your 
source folder (see \ref externfiles for details).

If you find out that fb-doc is useful, you may want to use it in 
different folders and for different projects. In that case it's best 
to install fb-doc in your system.

\section installlin LINUX Installation

It's recommended to install a batch file that calls fb-doc, because:

 -# when using it as Doxygen-filter you can send additional options 
    via the batch file (Doxygen doesn't allow sending options to a 
    filter directly)

 -# the batch file can call the latest fb-doc version in the source 
    folder and you're up-to-date right after compiling any up-date

This batch file should be named \em fbdoc and may look like (example 
for bash shell, replace \em _YOUR_PATH_TO_ by a proper path)

\code
#! /bin/bash
# Start fb-doc in src folder

/home/_YOUR_PATH_TO_/fb-doc/src/fb-doc $@
\endcode

For a single user installation place this file in your folder

\code ~/bin \endcode

or for a system wide installation (all users, admin privileges 
needed) place the file in any folder included in your PATH, ie in

\code /usr/bin \endcode

To execute fb-doc just type (in a shell in any folder)

\code fbdoc \endcode

and append the options you need.

\note You can test your installation by executing the above 
       command. It should output the help text.


\section installwoe DOS / windows Installation

Sorry, not done yet. Feel free to support the fb-doc project by 
sending a description of your working environment.


\section installgeany Geany IDE Installation

fb-doc can act as a filter (= custom command) for Geany IDE. In this 
IDE we can define several custom commands and send the currently 
selected text to one of these commands using the menu 
<em>Edit->Format->Send Selection to</em> (or we use the matching 
keybinding &mdash; \em Crtl-[1, 2, 3, ...] is default). The output 
from the custom command will be used to replace the current 
selection. See <a 
href="http://www.geany.org/manual/current/index.html#sending-text-through-custom-commands">Geany documentation</a> for details.

If there is no selection, Geany sends the current line. The current 
line may be empty, so that the reciever gets just the line end 
character.

To use fb-doc as a custom command in Geany the option \em --geany 
has to be given in the command line. In that case fb-doc reads its 
input from StdIn and write its output to StdOut. Depending on the 
input two different actions are possible

 - an empty input causes fb-doc to send either the context of the \em
   empty.txt file (if exists in the current directory) or send the 
   output specified in the empty-function of the choosen emitter.

 - a block containing FB source causes fb-doc to analyse the 
   context. The results for each known construct gets send to the 
   choosen emitter. Depending on the emitter, the output may be a 
   template to document this part of the source (gtk-doc and Doxygen 
   emitters are included). In case of a template emitter, the 
   original source code gets emitted unchanged right behind the 
   template block.

\note When the input doesn't contain a known construct, fb-doc 
       sends a help text.

To desribe this in a more practical way: We select some FB source in 
Geany and send it to the fb-doc custom command. fb-doc adds 
customized documentation comments to this block. The documentation 
block is formated for a specific back-end and includes all symbol 
names needed for the documentation. Next, we just need to fill the 
entries of the auto-created block. An efficient way to document our 
source code, see sections \ref exagtkdoc and \ref exadoxy for 
examples.

To add fb-doc as a custom command in Geany, we use the <em>Send 
Selection to->Set Custom Commands</em> menu item. We click on \em Add
to get a new item and type this command (after installing the batch 
file, see \ref installlin)

\code fbdoc --geany \endcode

(When the batch isn't installed, we have to repalce \em fbdoc by the 
full path and \em fb-doc.)

The \em GtkDocTemplates emitter is the default emitter in Geany 
mode. To use another emitter we just append its name (or just parts 
of it) behind the option \em --geany (separated by a space 
character). fb-doc checks this text against the emitter names and 
switches to the other emitter in case of a (non-case-sensitive) 
match. Ie to generate templates for Doxygen we add the emitter name

\code fb-doc --geany DoxygenTemplates \endcode

and instead of the long option and name we can use short forms like

\code fb-doc -g doxy \endcode

See section \ref sectionoptions and \ref tabemitters for details.

'/

/'* \page usage How To Use
\tableofcontents

As mentioned before a auto-generated documentation consists of 
information extracted from source code and from special comments. 
While the source code is well defined by the FB syntax, the comments 
need to match the syntax of the back-end in use.

So to test fb-doc and to learn about its usage and features you need 
both, an installation of a C tool-chain and some source code with 
documentation comments in the tool-chain's syntax.

The easiest way to get started is to use Doxygen and the fb-doc 
sourc code. In that case you can skip the next section.


\section usagetemplates Generating Templates

For Doxygen back-end there's no need for generating templates. It's 
best practise to write the documenting comment right in front of or 
just behind the relevant construct. The only exeption is a 
documenting comment for a function. It contains the names of the 
variables in the parameter list.

Its different when using gtk-doc tool-chain. Here the documentation 
context is collected in blocks. Such a block contains the name of 
the relevant construct (ie a ENUM block) and the names of all its 
members, followed by its decription. (Doxygen can handle such blocks 
as well, but it isn't well supported.)

Generating such a comment block is a reasonable amount of word. Each 
name has to get copied from the source in to the block. fb-doc can 
do this for us.

When we use Geany IDE, we can use a convenient method by installing 
fb-doc as Geany custom command (see \ref installgeany) and choose 
the emitter for the tool-chain in use (\em GtkDocTemplates or \em 
DoxygenTemplates). After loading the source, we select a block of 
code, send it to fb-doc and we receive the original block, prepended 
by a customized documentation block. We just need to edit the 
entries (marked by the text \em FIXME). See \ref exagtkdoc and 
\ref exadoxy for examples.

We can select a single construct and generate the comment blocks 
one-by-one. Or we select a bunch of statements and fb-doc inserts 
the templates inbetween the constructs. In case of a block 
construct (ENUM / UNION / TYPE) it's advantageous to select the 
complete block up to the END ... statement, to get all members 
listed in the documentation block. In case of a function 
decalaration the selection need not include the function body, but 
should contain the complete decalaration.

It's a bit less convenient to auto-generate templates when an other 
IDE is in use. In that case the documentation blocks can get 
generated for a complete file, by piping its context to fb-doc. See 
\ref usagepipe for details.


\section backgtk Gtk-doc

When using gtk-doc as back-end the documentation comment blocks are
placed before a structure, union, function ... and the names of the
members or parameters are listed in the comment block, prepended by
a \@ character and appended by a colon. See the manual
http://developer.gnome.org/gtk-doc-manual/stable/index.html for
details. Find an example for a gtk-doc documentation comment in \ref
exagtkdoc.

fb-doc helps us by creating such documentation comment blocks (=
template). We select a piece of code in Geany and send it to the
fb-doc filter. fb-doc creates a template, evaluates the names from
our source code and includes them in the template, followed by the
text \em FIXME. We just replace this text by the proper description.
To use this feature we have to install fb-doc as Geany filter, see
\ref installgeany for details.

When our documentation texts are done, we create a pseudo C source
tree in a separate folder and use the gtk-doc tool chain on this C
files. Therefor we start a command line interpreter (shell) and
switch to the folder where our FB source is placed. Then, we execute

\code fb-doc --asterix --fileoutput \endcode

This makes fb-doc creating a new folder <em>../doc/c_src</em> (if 
not present) and write pseudo C files similar to our FB source 
(overriding existing files). *.\em bas files get translated to *.\em
c and *.\em bi files get translated to *.\em h. Our documentation 
comments get transfered to this files and some of our FB code gets 
translated to C syntax. Then we start the gtk-doc tool-chain in the 
<em>../doc/c_src</em> folder as descibed in the above mentioned 
manual (\em gtkdoc-scan, ...).

gtk-doc works well to document a library API. Especially when it's 
related to GLib, GTK+ or gnome software. One of the unique features 
is auto-extracting the properties from the source code (I'll publish 
an FB tool soon). But it's not the best choise when we want to 
document a program like fb-doc. In that case we better use Doxygen.


\section backdoxy Doxygen Back-End

For Doxygen we can either use separate comment blocks, similar to
the gtk-doc blocks. Doxygen blocks use a different syntax and they
don't need to be placed in front of the related construct. fb-doc
also supports Doxygen templates, but this way of documenting isn't
very common and not well supported yet.

The other case is &mdash; a more commen way &mdash; to place the 
documentation directly in front of (or behind the) related construct.
Rather than documenting a complete block at once, just the class 
name or just one member gets documented in one comment. This way is 
more convenient, we need not extract the names from our source code. 
We just place the documentation beside the construct and Doxygen 
picks the names from the source. For that way of documenting there's 
no need to generate templates. The only execption is a parameter 
list, where the parameter names have to be listed in the 
documentation block. See

 - the manual 
   http://www.stack.nl/~dimitri/doxygen/manual.html for details.
 - \ref exadoxy for an example for a function comment block
 - all fb-doc source code as further examples.

For Doxygen we can also create the pseudo C files in the 
<em>../doc/c_src</em> folder, as described in the previous section. 
But it's more convenient to send the pseudo C code directly to 
Doxygen without creating intermediate files. This can be done by 
using fb-doc as a Doxygen filter. (We use Doxygen as if we were 
working on C source code, fb-doc translates on-the-fly when Doxygen 
reads the input.)

Doxygen gets controlled by a configuration file. This file contains 
all options. Here we can specify the fb-doc filter by adapting the 
following:

First we have to tell Doxygen that it should load FB source files:

\code
FILE_PATTERNS          = *.bi \
                         *.bas
\endcode

and second we need to set fb-doc as the filter for these files

\code
FILTER_PATTERNS        = *.bas=fbdoc \
                         *.bi=fbdoc
\endcode

\note Doxygen doesn't allow to send additional options directly to 
       a filter. So if we need further options we can set the name 
       of a batch file here and call fb-doc from the batch file 
       passing further options.

That's it. When we now start doxygen with proper settings for the 
paths and output format, we get our first auto-created 
documentation. (Try it with the fb-doc source code.)

To get caller and callees graphs (as in this document) it gets a 
little tricky. Doxygen needs the function calls inside the function 
bodies (in the C source). But when fb-doc acts as a Doxygen filter 
it gets restarted on each file. So it doesn't know a function 
declaration in file B when working on file A. The names of all the 
functions must be known to evaluate their calls in a function body 
and to generate proper pseudo C source. That's why fb-doc reads the 
names from a file called <em>fb-doc.lfn</em> in the current folder.

We needn't generate this file manually, fb-doc can do this for 
us by executing the command

\code fb-doc --list \endcode

in our source folder. This writes a new (or overrides an existing) file 
<em>fb-doc.lfn</em> in the current folder. When we don't start Doxygen 
in our source folder, we have to move the file to the folder where 
we execute the \em doxygen command. When we use Doxywizzard (the GUI 
frontend for Doxygen) this is the folder specified under

\verbatim
Step1: Specify the working directory from which doxygen will run
\endverbatim

And we have to specify fb-doc as filter for source files and enable 
source file filtering

\code
FILTER_SOURCE_FILES    = YES

FILTER_SOURCE_PATTERNS = *.bas=fbdoc \
                         *.bi=fbdoc
\endcode

In the next run Doxygen should be able to generate caller and callee 
graphs in the documentation (if the settings are correct and all 
tools are available).

But this has a downside: when we want the source files in the 
documentation (as in this document) the C-like code is used. To get 
the FB code we have to run Doxygen twice:

 -# without source filtering to get the \em html files with FB source

 -# with source filtering to get the graphs

Before the second run we save the \em html source files in a 
separate folder by executing in the Doxygen html output folder 
something like (example for LINUX OS)

\code
mkdir bas
mv *bas_source.html bas
mv *bi_source.html bas
\endcode

and after the second run we restore the FB source files

\code
rm *bas_source.html
rm *bi_source.html
cd bas
mv * ..
cd ..
rmdir bas
\endcode


\section libapi C Headers

Since fb-doc needs to generate C-like code for the back-end parsers, 
it can also be useful to create a set of C headers for a library 
written in FreeBasic. By default the FB types get mangled in to one 
word (for documentation purposes). Ie a FB parameter <em>byref Nam 
as const short</em> gets the pseudo C code <em>byref_as_const_short 
Nam</em>. This mangling can get suppressed by option \em --cstyle 
and fb-doc emitts real C types. In that case the example gets 
<em>const short* Nam</em> and this code can be used by a C compiler.

So when we need C headers for our FB library we just execute

\code fb-doc --csource --fileoutput "*.bi" \endcode

in our source folder and get a set of C translations in *.\em h 
files in the target folder (<em>../doc/c_src</em> by default).

\note fb-doc doesn't handle initializers. You have to check them 
       maunally.


\section usagepipe Piping

By default fb-doc reads its input for (one or more) files and sends 
its output to StdOut. We can switch to StdIn input by option \em 
--geany and then use the operating system commands to control the 
data flow in and from fb-doc.

Ie this is useful when we don't use Geany IDE or when we want to get 
templates for a complete file or a bunch of files at once. We can 
pipe the files context to the fb-doc StdIn channel and the fb-doc 
output to a file.

To get templates for all constructs in an existing file, first we 
create a copy the file (example for LINUX OS)

\code cp filename.bas filename.txt \endcode

Then we pipe the copy to fb-doc in geany mode (using emitter \em 
DoxygenTemplates here). The output gets piped to the original file 
(omit <em>>filename.bas</em> to see the output in the console)

\code fbdoc --geany doxy < filename.txt > filename.bas \endcode

Finally we may want to delete the intermediate file

\code rm filename.txt \endcode

To insert templates in all files of an existing project we write a 
batch file (or FB program) that does these three steps for all our 
source files.

'/

/'* \page pagetables Tables
\tableofcontents

This page contains some information on fb-doc in table format.

\section sectionoptions Options

Table of all fb-doc options. An option starts by a minus character 
followed by a single character (short form) or by two minus 
characters followed by a word (long form). Both forms have the same 
meaning.

Each word in the command line without the leading '-' character gets 
interpreted as a file name or pattern (ie a string in single or 
double quotes). The only exeptions are the (may be qouted) strings 
right behind the \em --emitter or \em --path options, which gets 
interpreted as a path or emitter name.

<TABLE>

<TR><TH> Option </TH>
<TH> Parameter </TH>
<TH> Description </TH></TR>

<TR><TD> \em -a or \em --asterix </TD>
<TD> none </TD>
<TD> emit lines in a multi line comment block with leading '* '
characters (gtk-doc style)</TD> </TR>

<TR><TD> \em -c or \em --cstyle </TD>
<TD> none </TD>
<TD> emit types in real C syntax (instead of FB styled pseudo C
syntax) </TD> </TR>

<TR><TD> \em -e or \em --emitter </TD>
<TD> Emitter name </TD>
<TD> Use the specified emitter. Standard emitters are named \em 
C_Source, \em ListOfFunction, \em GtkDocTemplates and \em 
DoxygenTemplates. fb-doc will compare the specified name with each 
emitter name and apply this emitter if there is a match. Comparison 
is done non-case-sensitve and just the given characters are 
compared, so ie \em dox matches \em DoxygenTemplates. If no match is 
found, fb-doc tries to load and use an external emitter module as a 
dynamic linked library from its EXEPATH. If there is no such modul, 
the standard emitter is used (each run mode has its own standard 
emitter). </TD></TR>

<TR><TD> \em -f or \em --fileoutput </TD>
<TD> none </TD>
<TD> scan the current folder for file(s) or pattern(s) and 
create similar C source including comments in the folder 
<em>../doc/c_src</em></TD>. When no filename or pattern is 
specified, all *.\em bas and *.\em bi files gets translated. </TR>

<TR><TD> \em -g or \em --geany </TD>
<TD> Emitter name </TD>
<TD> read input from StdIn (normaly send in Geany to receive the 
selected text block, default emitter is GtkDocTemplates) </TD> </TR>

<TR><TD> \em -h or \em --help </TD>
<TD> none </TD>
<TD> print the help text and stop </TD> </TR>

<TR><TD> \em -l or \em --list </TD>
<TD> filename or pattern </TD>
<TD> scan the current folder for one file, a file pattern or all 
FbreeBasic source files *.\em bas and *.\em bi and collect the names 
of all functions. Write them in to the file \em fb-doc.lfn (override 
existing or create new if not exist). This file is used to create 
caller and callee graphs with Doxygen back-end. </TD> </TR>

<TR><TD> \em -p or \em --path </TD>
<TD> path name </TD>
<TD> specify the folder to start scanning </TD> </TR>

<TR><TD> \em -r or \em --recursiv </TD>
<TD> none </TD>
<TD> scan input files in the current folder and all subfolders </TD> </TR>

<TR><TD> \em -t or \em --tree </TD>
<TD> none </TD>
<TD> scan the source tree and follow all \#INCLUDE statements </TD> </TR>

<TR><TD> \em -v or \em --version </TD>
<TD> none </TD>
<TD> print the version information and stop </TD> </TR>

</TABLE>

\note An empty command line makes fb-doc to output the help text 
       (as if option \em --help was given).

\note In case of interaction between multiple options the latest is 
       the dominant (see \ref tabrunmodi for details).


\section tabemitters Inbuild Emitters

fb-doc comes with four inbuild emitters to target different goals. 
Option \em --emitter (\em -e) is used to choose the one in use. 
(There cannot be more than one emitter in use.)

Inbuild emitters can be specified by the complete name or just a 
part of it. fb-doc compares all characters of the (non-quoted) word 
behind the \em --emitter option against the names of the inbuild 
emitters (non-case-sensitive), as listed in the following table.

Beside inbuild emitters also external emitters can be used by 
specifying the library name after the \em --emitter option (full 
name including suffix, case sensitive on LINUX). A quoted string 
gets allways interpreted as a library name. See \ref extend and 
\ref Options::chooseEmitter() for further information.

<TABLE>

<TR><TH> Name </TH>
<TH> Prefered Mode </TH>
<TH> Function </TH></TR>

<TR><TD> C_Source </TD> <TD> gtk-doc or Doxy-Filter </TD> <TD> Emit 
translated FB source in (pseudo) C syntax (default) or real C syntax 
(option \em --cstyle) </TD></TR>

<TR><TD> GtkDocTemplates </TD>
<TD> Geany </TD>
<TD> Generate templates for gtk-doc (default in \em --geany mode). 
This emitter doesn't support the option \em --tree. </TD></TR>

<TR><TD> DoxygenTemplates </TD> <TD> Geany </TD> <TD> Generate 
templates for Doxygen. This emitter doesn't support the option \em 
--tree.  </TD></TR>

<TR><TD> Callees </TD>
<TD> create \em fb-doc.lfn </TD>
<TD> Emit all function names to be used in a further run in 
Doxy-Filter mode (default in \em --list mode) </TD></TR>

</TABLE>

\note It's recommended to specify an internal emitter by its 
       (non-quoted) name and external emitter moduls by a quoted 
       string.


\section tabrunmodi Input / Output

Some options control the execution of fb-doc and the streams of 
input and output data. The following table shows the relations 
between working mode and input / output targets:

<TABLE>

<TR><TH> Run-Mode </TH>
<TH> Option </TH>
<TH> Input </TH>
<TH> Output </TH>
<TH> Default Emitter </TH></TR>

<TR><TD> Doxy-Filter </TD>
<TD> none </TD>
<TD> one file </TD>
<TD> standard out (StdOut) </TD>
<TD> C_Source </TD></TR>

<TR><TD> gtk-doc </TD>
<TD> \em -f or \em --fileoutput </TD>
<TD> one file, files matching a pattern or all source files </TD>
<TD> *.\em c and *.\em h files </TD>
<TD> C_Source </TD></TR>

<TR><TD> Geany templates </TD>
<TD> \em -g or \em --geany </TD>
<TD> standard in (StdIn) </TD>
<TD> standard out (StdOut) </TD>
<TD> GtkDocTemplates </TD></TR>

<TR><TD> List-Generation </TD>
<TD> \em -l or \em --list </TD>
<TD> files matching a pattern or all source files </TD>
<TD> file \em fb-doc.lfn </TD>
<TD> Callees </TD></TR>

<TR><TD> Help </TD>
<TD> \em -h or \em --help </TD>
<TD> none </TD>
<TD> standard out (StdOut) </TD>
<TD> none </TD></TR>

<TR><TD> Info </TD>
<TD> \em -v or \em --version </TD>
<TD> none </TD>
<TD> standard out (StdOut) </TD>
<TD> none </TD></TR>

</TABLE>

\note the default mode is the Doxygen filter mode, since Doxygen 
       doesn't allow to send further options (directly).

\note Input and output channels are fixed to the listed options. 
       But you can apply changes, ie by specifying an other the emitter 
       with \em --emitter option or input more than one file by walking 
       through the source tree with \em --tree option, ...

\note The modi \em --help (\em -h) and \em --version (\em -v) 
       are not related to any FB source. Instead of using an emitter 
       they create fixed output on standard output channel (StdOut).

\note When more then one run mode is specified in the command line, 
       the latest is the dominant.


\section tabfilenames File Names

Any text in the command line not matching an option or its parameter 
gets interpreted as a file name or file pattern. They get added to a 
queue and fb-doc executes this queue in the given order. Depending on 
the file name and the run mode fb-doc operates in different ways:

<table>

<TR><TH> Option (run-mode) </TH>
<TH> no name </TH>
<TH> exact name </TH>
<TH> pattern </TH></TR>

<TR><TD> default </TD>
<TD> print help text </TD>
<TD> load file, emit output to StdOut </TD>
<TD> load all files matching the pattern, emit output to StdOut </TD></TR>

<TR><TD> -f or --fileoutput </TD> <TD> load all *.\em bas and *.\em 
     bi files, emit output for each file to a *.\em c or *.\em h file 
     </TD>
<TD> load this one file, scan the source tree and load each 
     \#INCLUDE file, emit output for each file to a *.\em c or *.\em
     h file </TD>
<TD> load all files matching the pattern, emit output for each file 
     to a *.\em c or *.\em h file </TD></TR>

<TR><TD> \em -g or \em --geany </TD>
<TD> ignored </TD>
<TD> ignored </TD>
<TD> ignored </TD></TR>

<TR><TD> \em -l or \em --list </TD> <TD> load all *.\em bas and *.
     \em bi files, emit output to one file named \em fb-doc.lfn </TD> 
<TD> load this one file, scan the source tree and load each 
     \#INCLUDE file, emit output to one file named \em fb-doc.lfn</TD>
<TD> load all files matching the pattern, emit output to one file 
     named \em fb-doc.lfn</TD></TR>

</table>

\note A file name may be prepended by a relative or an absolute path.

\note File names or paths including a space character have to be 
       enclosed by single or double qoutes.

\note Multiple file names get separated by a space character or by a 
       ; character.

\note A file name cannot start with a minus character and cannot 
       include single or double quote characters.


\section tabmangling Type Mangling

fb-doc mangles the keywords of a FB type declaration in to a single 
word, separated by an underscore character. The following table 
contains some examples. This mangling can get suppressed by option 
\em --cstyle, to get real C types emitted.

<table>

<TR><TH> FB source </TH>
<TH> default </TH>
<TH> \em --cstyle </TH></TR>

<TR><TD> DIM AS INTEGER Nam</TD>
<TD> INTEGER Nam </TD>
<TD> int Nam </TD></TR>

<TR><TD> DIM Nam AS INTEGER</TD>
<TD> INTEGER Nam </TD>
<TD> int Nam </TD></TR>

<TR><TD> CONST Nam AS INTEGER</TD>
<TD> CONST_INTEGER Nam </TD>
<TD> const int Nam </TD></TR>

<TR><TD> Extern Nam AS INTEGER</TD>
<TD> Extern_INTEGER Nam </TD>
<TD> extern int Nam </TD></TR>

<TR><TD> DECLARE PROPERTY CurTok() AS INTEGER PTR </TD>
<TD> PROPERTY_AS_INTEGER_PTR CurTok() </TD>
<TD> int *CurTok(void) </TD></TR>

<TR><TD> BYVAL Export_ AS EmitFunc </TD>
<TD> BYVAL_AS_EmitFunc Export_ </TD>
<TD> EmitFunc *Export_ </TD></TR>

<TR><TD> byref Z as byte </TD>
<TD> byref_as_byte Z </TD>
<TD> char *Z </TD></TR>

<TR><TD> byval Z as byte </TD>
<TD> byval_as_byte Z </TD>
<TD> char Z </TD></TR>

</table>


\section tabundocfiles Undocumented files

The \em src folder in the fb-doc archive contains two more files, 
which are not included in the files list in this ducumentation. 
These are files used by Doxygen, check its manual for details:

<table>

<TR><TH> Name </TH>
<TH> Function </TH></TR>

<TR><TD> Doxyfile </TD>
<TD> A configuration file, controlling the Doxygen operation. </TD></TR>

<TR><TD> DoxygenLayout.xml </TD>
<TD> A configuration file, controlling the index context of these \em html pages. </TD></TR>

</table>

'/

/'* \page externfiles Files used
\tableofcontents

fb-doc currently uses two external files. It tries to load the 
context when needed and continues without the context when the files 
aren't present. fb-doc searches for the files in the EXEPATH (the 
folder of the fb-doc binary).

\section filecsrc ../doc/c_src

This folder gets created by fb-doc to write the file output. It's 
used to collect the translations from the \em C_source emitter. The 
back-end read its input from here.

\section filecallees fb-doc.lfn

The suffix lfn means list of function names. This file is used in 
the C_SOURCE emitter to create pseudo function calls in a function 
body. It gets created by the ListOfFunction emitter when using 
(option \em --list) and it isn't used in Geany mode (option \em 
--geany, emitters GtkDocTemplates and DoxygenTemplates).

Allthough it's usually created by fb-doc, it also can get 
manipulated by any text editor.

The file contains the names of all functions in the source code. 
Member functions of a UDT are listed as they are named in the 
function body (ie TypeName.FunctionName). The first line is empty. 
Further lines contain the names, one in each line, including the dot 
in case of a member function. The lines \b must be separated by a 
single line feed character (LINUX line end = 'CHR(10)'). So be 
careful when we edit on DOS / windows (ie use Geany and switch to 
LF line ends).

This file is needed when running as a filter for Doxygen to create 
the caller and callees graphs. Therefor the bodys of the function 
have to include the function calls. fb-doc checks all words in a 
function body against the known function names. Any match gets 
emitted as a pseudo function call (with empty parameter list).

Since in this mode Doxygen serves the file names in any order and 
fb-doc gets started new for each file, it doesn't know about a 
function declaration from file A when working on file B. Therefor the
function names have to be served from an external source. They get 
red from this file at each program start.

The file offers an additional way to control the context of the caller 
and callees graphs. Only functions listed in this file gets included 
in the C source (and in the graphs).

When this file isn't present fb-doc continues execution without any 
message and the function bodys of the pseudo C code are empty. This 
means no caller or callees graphs will be created.


\section fileempty empty.txt

This file is used in Geany mode (option \em --geany). When we send an 
empty block to fb-doc (place the cursor in an emppty line and call 
fb-doc) then a standard text gets emitted to our source file. This 
is a documentation block

 - for a section, when in gtk-doc mode or
 - for a file, when in Doxygen mode.

We can replace these standard blocks by the context of this file. 
When fb-doc finds this file in the EXEPATH it emits its context 
instead of the standard text to fill an empty line. The file gets 
red each time when passing an empty block, so we can edit the file 
and use the new context without restarting Geany or fb-doc.

Usually this file contains a comment block with any kind of 
documentation. When the file isn't present the standard text of the 
emitter gets emited.


\section externemitters External Moduls (*.so / *.dll)

fb-doc can use external emitter modules. These are executable 
binaries, compiled and linked as a library for dynamic linkage, 
either by using the FreeBasic compiler or any other compiler / linker
combination. These files may have any name and get the system 
specific file name extension (= suffix) \em .so on LINUX or \em .dll 
on windows.

Such files aren't necessary for basic usage of fb-doc. They are used 
for external emitters to extend the fb-doc features and get loaded on 
demand (option \em --emitter) at run-time, see \ref extend for 
details. So you may have one or more files with one of these 
suffixes in your working directory.

'/


/'* \page examples Examples
\tableofcontents

Here're some examples for the features of fb-doc (using gtk-doc or
Doxygen back-end).


\section exacomments Comments (in general)

\note In these examples the ends of the FreeBasic multi line 
comments are fakes, because the straight single quote mark cannot be 
used in the source. Instead an acute accent is used. Correct them 
when you intend to copy / paste the code.

A line end comment in the FB source like
\code '* a line end comment \endcode

gets emitted as
\code //! a line end comment \endcode

Direct export comments in FB source (each are line end comments) like
\code
'&// a line end comment in C syntax

'&/*
'&Some
'&lines of
'&C comment
'&*/
\endcode

get emitted as
\code
// a line end comment in C syntax

/*
Some
lines of
C comment
*/
\endcode

And a multi line comment in FB source like
\code
/'*
Some
lines of
comment `/
\endcode

gets emitted as
\code
/**
Some
lines of
comment */
\endcode

or &mdash; when option \em --asterix is set &mdash; as
\verbatim
/**
* Some
* lines of
* comment */
\endverbatim

Normal FreeBasic comments (without magic character) wont be emitted. 
(They're only visible in the FB source, The intermediate format 
contains empty line in that case.)
\code
' a line end comment

/'
A block
of
comment
`/
\endcode


\section exadim Variable Declaration

A varible declaration in a FreeBasic source code line like
\code
DIM VarName AS ZSTRING PTR
\endcode

gets in the intermediate (C-like) format
\code
ZSTRING_PTR VarName;
\endcode

The FB type <em>ZSTRING PTR</em> consists of two words. The C 
scanner can not handle it directly. That's why fb-doc mangels the 
words in to one word, separeted by an underscore. Now the lexical 
scanner of the C tool-chain interprets the single word \em 
ZSTRING_PTR as a user defined type (or macro) and generates 
documentation like \verbatim ZSTRING_PTR VarName \endverbatim See 
\ref tabmangling for more examples.

In this syntax the FB user can identify the type as an FB 
declaration and easily understand the documentation. The only 
difference is that in the documentation context the type is allways 
in front of the name (C style) while FB allows to swap the order 
(and in FB parameter lists the name must be in front of the type),

fb-doc can also generate real C types. In this case the above 
example gets
\code
char* VarName;
\endcode

and this syntax can be used direrctly by a C compiler (this can be 
useful to auto-generate C headers with fb-doc, ie for a library 
written in FB that should be used in a C project).


\section exagtkdoc Gtk-doc

\note This example is based on a system wide installation of fb-doc
and a setting as Geany custom command with option \em --geany. (See
\ref installgeany for details.))

This example is about documenting a function and its parameter list. 
We load our source code in to Geany IDE, select the function 
declaration (the code in the following bix) and send it to the 
fb-doc custom command:

\code
FUNCTION goo_axis_new CDECL( _
  BYVAL Parent AS GooCanvasItem PTR, _
  BYVAL Back AS GooCanvasItem PTR, _
  BYVAL Text AS gchar PTR, _
  BYVAL Modus AS GooAxisType, _
  ...) AS GooAxis PTR
\endcode

fb-doc extracts the names of the function and its parameters, 
generates a matching template and returns the customized template 
and the original code. The entries for the individual documentation 
text are marked with then text \em FIXME:

\code
/'*
goo_axis_new:
@Parent: FIXME
@Back: FIXME
@Text: FIXME
@Modus: FIXME
@...: FIXME

FIXME

Returns: FIXME
`/
FUNCTION goo_axis_new CDECL( _
  BYVAL Parent AS GooCanvasItem PTR, _
  BYVAL Back AS GooCanvasItem PTR, _
  BYVAL Text AS gchar PTR, _
  BYVAL Modus AS GooAxisType, _
  ...) AS GooAxis PTR
\endcode

Now we complete the documentation comment by filling the entries
marked by the text \em FIXME, and we end-up with something like:

\code
/'*
goo_axis_new:
@Parent: the parent item, or %NULL. If a parent is specified, it 
         will assume ownership of the item, and the item will 
         automatically be freed when it is removed from the 
         parent. Otherwise call g_object_unref() to free it.
  @Back: the background box to connect the axis to (a 
         #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...). 
         Note: to set the axis position and size, the properties 
         #GooCanvasItemSimple:x, #GooCanvasItemSimple:y, 
         #GooCanvasItemSimple:width and 
         #GooCanvasItemSimple:height will be red (and therefore 
         must be set in the background box item).
  @Text: the label text for the axis
 @Modus: the position and type (like %GOO_AXIS_SOUTH or 
         %GOO_GRIDAXIS_SOUTH, ...)
   @...: optional pairs of property names and values, and a 
         terminating %NULL.

Creates a new axis item.

Returns: (transfer full): a new axis item.
`/
FUNCTION goo_axis_new CDECL( _
  BYVAL Parent AS GooCanvasItem PTR, _
  BYVAL Back AS GooCanvasItem PTR, _
  BYVAL Text AS gchar PTR, _
  BYVAL Modus AS GooAxisType, _
  ...) AS GooAxis PTR
\endcode

Finally we translate all FB sources (*.\em bas and *.\em bi) to C 
source using
\code fbdoc --asterix --fileoutput \endcode

The files gets written to the path <em>../doc/c_src</em> and the 
output in the corresponding .\em c file looks like

\verbatim
/**
* goo_axis_new:
* @Parent: the parent item, or %NULL. If a parent is specified, it 
*          will assume ownership of the item, and the item will 
*          automatically be freed when it is removed from the 
*          parent. Otherwise call g_object_unref() to free it.
*   @Back: the background box to connect the axis to (a 
*          #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...). 
*          Note: to set the axis position and size, the properties 
*          #GooCanvasItemSimple:x, #GooCanvasItemSimple:y, 
*          #GooCanvasItemSimple:width and 
*          #GooCanvasItemSimple:height will be red (and therefore 
*          must be set in the background box item).
*   @Text: the label text for the axis
*  @Modus: the position and type (like %GOO_AXIS_SOUTH or 
*          %GOO_GRIDAXIS_SOUTH, ...)
*    @...: optional pairs of property names and values, and a 
*          terminating %NULL.
* 
* Creates a new axis item.
* 
* Returns: (transfer full): a new axis item.
* */
FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (
BYVAL_AS_GooCanvasItem_PTR Parent, 
BYVAL_AS_GooCanvasItem_PTR Back, 
BYVAL_AS_gchar_PTR Text, 
BYVAL_AS_GooAxisType Modus, 
...) {

};
\endverbatim

This fb-doc C-like output can be used as input for the gtk-doc 
tool-chain to generate the desired documentation output. The tools 
operate on the files in the <em>../doc/c_src</em> folder.


\section exadoxy Doxygen

\note This example is based on a system wide installation of fb-doc
and a setting as Geany custom command with option <em>--geany
doxy</em>. (See \ref installation for details.))

We load our code in to Geany IDE, select some source like the
following code and send it to the fb-doc custom command:

\verbatim
FUNCTION goo_axis_new CDECL( _
  BYVAL Parent AS GooCanvasItem PTR, _
  BYVAL Back AS GooCanvasItem PTR, _
  BYVAL Text AS gchar PTR, _
  BYVAL Modus AS GooAxisType, _
  ...) AS GooAxis PTR
\endverbatim

fb-doc extracts the names and returns the customized template,
followed by the original code:

\verbatim
/'* \fn FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (BYVAL_AS_GooCanvasItem_PTR Parent, BYVAL_AS_GooCanvasItem_PTR Back, BYVAL_AS_gchar_PTR Text, BYVAL_AS_GooAxisType Modus, ...)
\param Parent FIXME
\param Back FIXME
\param Text FIXME
\param Modus FIXME
\param ... FIXME

\brief FIXME

\returns: FIXME

FIXME

`/
FUNCTION goo_axis_new CDECL( _
  BYVAL Parent AS GooCanvasItem PTR, _
  BYVAL Back AS GooCanvasItem PTR, _
  BYVAL Text AS gchar PTR, _
  BYVAL Modus AS GooAxisType, _
  ...) AS GooAxis PTR
\endverbatim

The first line is the declaration of our function in C syntax &mdash;
without the character ; at the end and prepended by the keyword \em 
\\fn . This line enables Doxygen to read the documentation comment 
anywhere in its input, so the documentations comment needs not to be 
in front of the matching function. Since we won't move the block 
(it's advantageous to place the documentation text near to the source
code) we remove this line and then we complete the documentation 
comment by filling the entries marked by the text \em FIXME. We 
end-up with something like:

\verbatim
/'* 
\param Parent the parent item, or %NULL. If a parent is specified, it 
          will assume ownership of the item, and the item will 
          automatically be freed when it is removed from the 
          parent. Otherwise call g_object_unref() to free it.
\param Back the background box to connect the axis to (a 
          #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...). 
          Note: to set the axis position and size, the properties 
          #GooCanvasItemSimple:x, #GooCanvasItemSimple:y, 
          #GooCanvasItemSimple:width and 
          #GooCanvasItemSimple:height will be red (and therefore 
          must be set in the background box item).
\param Text the label text for the axis
\param Modus the position and type (like %GOO_AXIS_SOUTH or 
          %GOO_GRIDAXIS_SOUTH, ...)
\param ... optional pairs of property names and values, and a 
          terminating %NULL.

\brief Creates a new axis item.

\returns: a new axis item.

A detailed desription of the function may follow here ...

`/
FUNCTION goo_axis_new CDECL( _
  BYVAL Parent AS GooCanvasItem PTR, _
  BYVAL Back AS GooCanvasItem PTR, _
  BYVAL Text AS gchar PTR, _
  BYVAL Modus AS GooAxisType, _
  ...) AS GooAxis PTR

' ...
END FUNCTION
\endverbatim

Using Doxygen we don't need to generate intermediate C source code 
in files. Instead this code gets directly piped by fb-doc acting as 
a filter, so we usually don't see it. Being curious we may generate 
files by using fb-doc with option \em --fileoutput and see output like

\code
/**
\param Parent the parent item, or %NULL. If a parent is specified, it 
         will assume ownership of the item, and the item will 
         automatically be freed when it is removed from the 
         parent. Otherwise call g_object_unref() to free it.
\param Back the background box to connect the axis to (a 
         #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...). 
         Note: to set the axis position and size, the properties 
         #GooCanvasItemSimple:x, #GooCanvasItemSimple:y, 
         #GooCanvasItemSimple:width and 
         #GooCanvasItemSimple:height will be red (and therefore 
         must be set in the background box item).
\param Text the label text for the axis
\param Modus the position and type (like %GOO_AXIS_SOUTH or 
         %GOO_GRIDAXIS_SOUTH, ...)
\param ... optional pairs of property names and values, and a 
         terminating %NULL.

\brief Creates a new axis item.

\returns: a new axis item.

The detailed desription of the function follows here ...

*/
FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (
BYVAL_AS_GooCanvasItem_PTR Parent, 
BYVAL_AS_GooCanvasItem_PTR Back, 
BYVAL_AS_gchar_PTR Text, 
BYVAL_AS_GooAxisType Modus, 
...) {

};
\endcode

'/

/'* \page extend Extending fb-doc

Since the fb-doc Parser calls emitter functions via the emitter 
interface \ref EmitterIF, it can get extended by new emitters 
providing additional features, ie to support further tools (= 
back-ends, ie like <em>source navigator</em>). This can either be 
done by adding a new emitter to the fb-doc source or by writing an 
external emitter modul, that can be loaded at run-time. The first 
variant may have the disadvantage that the extension may need 
refactoring when fb-doc gets updated. So it's recommended to prefer 
external emitters.

The \em src folder of the \em fb-doc archive contains a file \em
Plugin.bas. In this file you find example source code for an 
external emitter modul and this further information:

\dontinclude Plugin.bas
\skipline This emitter generates
\until endverbatim

'/

/'* \page todo Further Development

In combination with Doxygen fb-doc is a powerful documentation 
system for FreeBasic source code. The Doxygen support for FreeBasic 
is much better than for any other BASIC dialect (ie like VB6). But 
there's still some room for optimization, for Doxygen support as 
well as for other features, like:

 - optimize syntax high-lighting in listings or examples
 - additional emitters to support further documentation systems or other tools
 - a hash table for callees to speed up the execution
 - ...

Feel free to post your ideas, bug reports, wishes or patches, either 
to the project page at

 - \ProjPage

or by email to

 - \Email

'/
