Automatic links and automatic insertions
There is a lot of way in Cod2Doc to have a link automatically created:
- links for variables, types and functions
- crossed links
- links to an html page (with or without an anchor specified)
- links to a Blitz Basic file (.bb)
- e-mail address
For every links, you can specify an alternate text between brackets []. These brackets could be placed before or after the link at your convenience. If these brackets are empty, then the name of variable/type/function/file will be used instead.
Sometimes it can be useful to not turn a word into a link. In this case, a ! should be put in front of the word (the ! will disappear after the treatment). This is of course not needed when the option "No automatic links" is set.
If you don't want to add automatic links, the following option has to be set in the main window:
Option "No automatic links at all": with this option set, no automatic link are generated.
Cod2Doc inserts also automatically some objects in your documentation:
Links for variables, types and functions:
| Structure: ; For variables (constant, global, field), these links are all valid: ; myVariable, myVariable%, [some text]myVariable, myVariable%[some text], etc. ; For types (to make a link explicit, add a ~ to the type): ; myType, myType~, [some text]myType, [some text]myType~, etc. ; For functions: ; myFunction, myFunction$, myFunction$(), myFunction() ; myFunction[some text], myFunction$()[some text], [some text]myFunction(), etc. ; These examples won't turn into links: ; !variableExample, !functionExample |
In Cod2Doc, every variables (constant, global, array, field of type), every types and every functions creates automatically a reference (anchor) in the html file. To access it from the documentation, you just have to write the name of the variable or of the function, and it will turn automatically into a link to this variable or function (depending on the options you choose in the main window). The automatic link generation is available from any comments which will appear in the documentation.
You can also specify a text to replace the normal text of the link: this optional text should be located between brackets [] appended just before or after the link (maybe more aesthetic before the link for the continuity of the text).
If you don't wish that the word turn into a link (in particular if the word is a homonym of the variable/function name), then put simply a ! in front of the word.
Different options are available to modify the automatic links. These options can be set from the main window.
Option "Explicit links only": if this option is set, then only variables, types and functions which have their type specified are turned into link. For function, specifying the parenthesis will turn also the function into link. Also, it the brackets are specified, it will be considered as a link (if there is no text specified between the brackets, then the name of the variable is taken instead).
To make a Type explicit, you can either add brackets or the "~" character to it.
For example, thisVariable%, thisString$, thisString[some text], thisType~, thisType[some text], thisFunction(), thisFunction%, thisFunction%() will turn into links, whereas thisVariable, thisString, thisType and thisFunction won't turn into a link as no type is specified.
This option is useful when you don't want that normal words (homonym of a variable for example) become links.
Notice that the name of anchor is case sensitive in some browser (like Netscape).
|
Example: | ||||||||
This gives the result:
|
Crossed links:
| structure: ; fileName#NameOfVariableOrFunction ; fileName.bb#NameOfVariableOrFunction ; [some text]fileName#NameOfVariableOrFunction ; fileName#NameOfVariableOrFunction[some text] |
Crossed links are links to an other file which are retrieved automatically by Cod2Doc. However, to retrieve this link, Cod2Doc needs that all the files concerned by the crossed links are treated in the same session (by treating a whole directory and all its subdirectories for example).
The advantage of crossed links is that you don't have to specify a path if this one is different from the current path: Cod2Doc will find the good path for you!
To specify a cross link, you put the name of the file without extension (or with the .bb or .c2d extension) and without path, the # character and the name of the variable or function that you want to reference (you can optionally add the type of the variable - %, $, # - or the parenthesis of the function). You can also specify a text to replace the normal text of the link: this optional text should be located between brackets [] appended just before or after the link. Notice also that the capitalization of the variable/function name should match exactly the one in the .bb source file.
See also: the options which forbid such links or ask them to be explicit (containing brackets []).
|
Example: | |
This gives the result: aFunction() in SimpleExample or click here |
Links to an html page:
| structure: ; - fileName.html ; [some text]fileName.html ; fileName.html[some text] ; - path/fileName.html ; [some text]path/fileName.html ; path/fileName.html[some text] ; - fileName.html#NameOfAnchor ; [some text]fileName.html#NameOfAnchor ; fileName.html#NameOfAnchor[some text] ; - [some text]http://www.blitzbasic.com |
To add a link to an html page, you just have to write the name of the html file in a comment which will be documented. You can specify a path in the file name. The current directory is always considered as the directory where were created the documentation file (usually Cod2Doc\).
You can also reference a external web page (starting with http:// or www).
If you want also to provide an anchor to go to on the html page, then you just append #NameOfTheAnchor to the file name (the anchor are case sensitive!).
You can also specify a text to replace the normal text of the link: this optional text should be located between brackets [] appended just before or after the link. Add a ! in front of the html file name if you don't want to turn this file into a link.
See also: the options which forbid such links or ask them to be explicit (containing brackets []).
|
Example: | |
This gives the result: CommentYourCode.html or click on this link |
Links to a Blitz Basic file:
| structure: ; - fileName.bb ; [some text]fileName.bb ; fileName.bb[some text] ; - path/fileName.bb ; [some text]path/fileName.bb ; path/fileName.bb[some text] |
The principles are strictly identical to that of html links (see previous paragraph). A click on the .bb link will open the Blitz Basic editor (if you associated .bb files with the Blitz IDE in your browser).
Adding a name of variable or function as an anchor to the file source name is treated above.
See also: the options which forbid such links or ask them to be explicit (containing brackets []).
|
Example: | |
This gives the result: files/FunctionExampleCode.bb or click on this link |
E-mail address:
| structure: ; name@address.ext ; [some text]name@address.ext ; name@address.ext[some text] |
A e-mail address is automatically turns into a link when inserted into a description.
See also: the options which forbid such links or ask them to be explicit (containing brackets []).
|
Example: | |
This gives the result: repeatuntil@free.fr or click to contact me |
Insertion of images:
| structure: ; path/image.jpg ; path/image.jpg[width,height] ; [width,height]path/image.jpg |
To insert an image in the documentation, write simply the name of the image file (possibly with the path). File format could be ".jpg", ".jpeg", ".gif", ".bmp" and ".png" (".bmp" format does not seem to be supported by Netscape!). The current directory is always considered as the directory where were created the documentation file (usually Cod2Doc\). The path may be relative or absolute, or even a path on the web. For clarity in your directory where are stored your documentation, you may wish to place your images in the subdirectory files\ (usually Cod2Doc\files): in this case just write files/image.jpg for example.
Optionally, you can specify between brackets [] the width and the height of the image.
You may place a ! in front of the image name to not include it (the text of the image will be displayed instead).
See also: the options which forbid such links or ask them to be explicit (containing brackets []).
|
Result: | |
|
and Insertion of lists:
| structure: ; Normal list: ; - first point ; - second point, ; more second point ; - third point ;/list ; End of the list ; Numbered list: ; * first point ; * second point, ;; more second point on the same line ; * third point ; ; End of the list |
Use the " - " character for normal list, and the " * " character for numbered list (they should be the first character of the comment to turn into a list). A list is considered closed either when Cod2Doc meets the ;/list special tag or when Cod2Doc meets an empty line or empty comment (like ";", ";;" or an empty line for inline documentation).
To change the type of bullets, you will have to modify the style file with cascading style sheets (css).
If you don't want that your list turns to an html list, then you have to add the ;nolist tags on the same line. You can also set the No automatic list option of the graphical interface.
Notice that nested list are not supported. For such list, you should directly type in the code the html tags (<ul>...</ul>)
|
Result: | |
|
