 |
fb-doc
0.4.0
FreeBASIC documentation tool
|
|
|
fb-doc
0.4.0
FreeBASIC documentation tool
|
|
fb-doc operates on input and generates output, that is either pipe streams (STDIN and STDOUT) or to files. The run mode determines which kind of input to get, where to get it from and where to write the output at, see first table in section Executable for an overview.
This chapter contains detailed informations on the different file types used by fc-doc for input or output. Here's a grafical overview
Input files get read in all run modes except --geany-mode (-g). At least one file of the first catagory (*.bas / *.bi) is used in any case. The other files are used by specific emitters and run modi.
The standard input of fb-doc is FreeBASIC source code, stored in files with the suffix *.bas or *.bi. The Parser is designed to operate on this files. It doesn't evaluate all the code, just documentation related constructs get sent to the related emitter functions.
fb-doc is designed to operate on error-free source code. Usually the documentation gets done after the code has been checked. So fb-doc contains just a minimal set of syntax checks, it relys on input previously validated by the FB compiler.
The suffix means List of File Names. This file is optional. It's used by emitter C_Source in order to generate caller / callee graphs and it's located in the Doxygen folder near the configuration file Doxyfile.
The file usually gets generated by fb-doc in run mode --list-mode (-l) with its default emitter FunctionNames, but it can get manipulated manualy by any text editor. The file contains a comment in the first line, followed by list of function names, one name per line. Entries for member functions contain the class name and the function name, separated by a dot. The lines are separated by new line characters. (Only !"\\n", but no !"\\c" is allowed, so be careful when editing the file on non-LINUX systems.)
Those names are used to generate calls in function bodies in the pseudo C intermediate syntax for Doxygen back end.
Background: When fb-doc runs as a Doxygen filter (default mode), it gets called for a single input file and pipes output to STDOUT. At this moment, fb-doc doesn't know about function declarations in the other source files.
In order to generate caller / callee graphs by Doxygen, the output must contain the function calls in the function bodies. To generate those function calls in the intermediate format, fb-doc checks the words before brackets in a function body. If such a word is a symbol (no keyword), it can either be an array or a function call. fb-doc needs further information to determine the correct type and to make the decision if to function call should generated in the output stream for that word.
Since the symbol may be defined in an other file in the source tree and fb-doc operates on a single file only, the names of the functions in all source files get read from an external file. When a symbol found in a function body matches an entry in this file, a function call gets generated in the output stream. (This is a pseudo call with empty parameter list, fb-doc doesn't support OVERLOADed functions yet.)
This is an external file format, designed and used as configuration file for Doxygen. The file is located in the Doxygen directory. fb-doc evaluates it in order to operate on the same input and output as Doxygen. It's used for run modi --list-mode (-l) and --syntax-mode (-s).
Find details in the description of function Highlighter.doDoxy().
INPUT only the first source path get parsed. So make sure that your path to the FB source code is at first place when you've more than one path in the list.In run mode --syntax-mode (-s) fb-doc reads special html files generated by Doxygen (tags GENERATE_HTML = YES and SOURCE_BROWSER = YES), containing the source code listings. Doxygen generates them in the path specified by the tags OUTPUT_DIRECTORY = and HTML_OUTPUT =. The contents is based on the intermediate pseudo C format (= the filtered output of fb-doc) and therefor not useful for the documentation. fb-doc can update those files, using the real Fb source code and applying Doxygen links and style information.
The emitter SyntaxHighlighting skips the file header and parses the middle part (the listing) for hyper links. Those get collected in a list to transfer them when the file update gets created.
In run mode --syntax-mode (-s) fb-doc reads special tex files generated by Doxygen (tags GENERATE_LATEX = YES and SOURCE_BROWSER = YES), containing the source code listings. Doxygen generates them in the path specified by the tags OUTPUT_DIRECTORY = and LATEX_OUTPUT =. The contents is based on the intermediate format (= the filtered output of fb-doc) and therefor not useful for the documentation. fb-doc can update those files, using Doxygen like style information on the real Fb source code.
The emitter SyntaxHighlighting skips the file header and parses the middle part (the listing) for hyper links. Those get collected in a list to transfer them when the file update gets created.
In run mode --syntax-mode (-s) fb-doc reads special xml files generated by Doxygen (tags GENERATE_XML = YES and SOURCE_BROWSER = YES), containing the source code listings. Doxygen generates them in the path specified by the tags OUTPUT_DIRECTORY = and XML_OUTPUT =. The contents is based on the intermediate format (= the filtered output of fb-doc) and therefor not useful for the documentation. fb-doc can update those files, using Doxygen like style information on the real Fb source code.
The emitter SyntaxHighlighting skips the file header and parses the middle part (the listing) for hyper links. Those get collected in a list to transfer them when the file update gets created.
Those files are optional, used in order to extend the fb-doc features. fb-doc has an interface for external emitter modules (= plugins). 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 able to create shared libraries. Those files may have any name and get the system specific file name extension (suffix .so on LINUX or .dll on other systems). See External Emitters for details.
An external emitter can get used in any run mode. It gets specified by option --emitter (-e). The binary gets loaded at run-time.
Output files get generated by fb-doc depending on the run mode. The context of the output files depend on the emitter in use. In case of a customized emitter setting (option --emitter (-e)) make sure that the emitter generates reasonable context for the output files specified by the given run mode (find an overview in the first table in Executable).
Those files get generated in run mode --file-mode (-f) (ie. by default emitter C_Source). They contain the C-like intermediate format, transformed from the FB source input. The base file name stays unchanged, and the suffix depends on the input file name: files with suffix .bas get suffix to .c, all other input files get suffix .h.
By default those files get written to the path ../c_src, overriding existend files. Customize the default output folder setting by option --outpath (-o).
This file gets generated in run mode --list-mode (-l) by emitter FunctionNames. It contains the list of function names, used by the emitter C_Source. Place (and generate) this file in the Doxygen folder near the Doxygen configuration file, since fb-doc searches for that file in the current directory when running as a Doxygen filter.
Those files get generated in run mode --syntax-mode (-s) by emitter SyntaxHighlighting when in the Doxygen configuration file Doxyfile the tags GENERATE_HTML and SOURCE_BROWSER are both set to YES. They are located in the folder specified by the tags OUTPUT_DIRECTORY = and HTML_OUTPUT =. In the original state (after being generated by Doxygen) the files contain source code listings generated by Doxygen based on the intermediate pseudo C syntax.
fb-doc updates the files by copying the original header and footer unchanged, but replacing the middle part with source listings based on the original FB contents. FB keywords get highlighted and hyper links from symbols to the text description get transfered to the new context. During this process, a temporary file with suffix *.html_ gets generated and removed after successful operation.
Those files get generated in run mode --syntax-mode (-s) by emitter SyntaxHighlighting when in the Doxygen configuration file Doxyfile the tags GENERATE_LATEX and LATEX_SOURCE_CODE are both set to YES. They are located in the folder specified by the tags OUTPUT_DIRECTORY = and LATEX_OUTPUT =. In the original state (after being generated by Doxygen) the files contain source code listings generated by Doxygen based on the intermediate pseudo C syntax.
fb-doc updates the files by copying the original header and footer unchanged, but replacing the middle part with source listings based on the original FB contents. FB keywords get highlighted and hyper links from symbols to the text description get transfered to the new context. During this process, a temporary file with suffix *.tex_ gets generated and removed after successful operation.
Those files get generated in run mode --syntax-mode (-s) by emitter SyntaxHighlighting when in the Doxygen configuration file Doxyfile the tags GENERATE_XML and XML_PROGRAMLISTING are both set to YES. They are located in the folder specified by the tags OUTPUT_DIRECTORY = and XML_OUTPUT =. In the original state (after being generated by Doxygen) the files contain source code listings generated by Doxygen based on the intermediate pseudo C syntax.
fb-doc updates the files by copying the original header and footer unchanged, but replacing the middle part with source listings based on the original FB contents. FB keywords get highlighted and hyper links from symbols to the text description get transfered to the new context. During this process, a temporary file with suffix *.tex_ gets generated and removed after successful operation.
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).
This folder gets created by fb-doc to write the file output. It's used to collect the translations from the C_Source emitter. The back-end read its input from here.
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 ยด–list-mode) and it isn't used in Geany mode (option–geany-mode`, 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 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 read 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.
1.8.11