| fb-doc 0.2 documentation tool for FreeBasic

- Main Page
- Tutorial
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Compiling and Installing

fb-doc gets shipped as a FreeBasic source tree. Find the code in the src folder of your 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 fb-doc.bas. Ie load the file in to Geany IDE and choose Build -> Compile menu. Or call the Freebasic compiler at the command line (in the extracted src folder)

fbc -w all fb-doc.bas

This creates an executable binary named

- fb-doc (on LINUX) or
- fb-doc.exe (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 — as mentioned in the prvious section — fb-doc is not a complete tool-chain. To generate some documentational output you additionally need a back-end for C source, like

- gtk-doc
- Doxygen

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 How To Use for details). Depending on the used options it may create the folder ../doc/c_src (beside your source folder) and write some files in it. And it may create the file fb-doc.lfn in your source folder (see Files used 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.

# LINUX Installation

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

1. 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)
2. 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 fbdoc and may look like (example for bash shell, replace _YOUR_PATH_TO_ by a proper path)

#! /bin/bash
# Start fb-doc in src folder
/home/_YOUR_PATH_TO_/fb-doc/src/fb-doc $@

For a single user installation place this file in your folder

~/bin

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

/usr/bin

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

fbdoc

and append the options you need.

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

# DOS / windows Installation

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

# 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 Edit->Format->Send Selection to (or we use the matching keybinding — Crtl-[1, 2, 3, ...] is default). The output from the custom command will be used to replace the current selection. See Geany documentation 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 –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 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 Gtk-doc and Doxygen for examples.

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

fbdoc --geany

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

The 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 –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

fb-doc --geany DoxygenTemplates

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

fb-doc -g doxy

See section Options and Inbuild Emitters for details.