Up:
  1. Index of TkScript » Script library/tool documentation » DOG
DOG

The TkScript DOcument Generator

- (c) 2005-2008 by Bastian Spiegel


 
Last modified: Wed, 31/Dec/2008
 
Table of Contents:

 
1. Introduction

Welcome to DOG, the TkScript document generator !
1.1. Goals
DOG was created with the following design aspects in mind:
  • Full cross-referencability: Make it possible to e.g. cross reference API documentation from supplementary documents
  • Automatically generate a table of contents for each supplementary document
  • Be as output format independent as possible
  • Be extensible by user defined functions
1.2. License
DOG is distributed under terms of the GNU General Public License. Please see COPYING for details.
1.3. Status
DOG is WORK IN PROGRESS.
2. Usage
2.1. Extracting API documentation
Before any HTML documents can be generated, the API documentation first has to be extracted from a TkScript respectively C++ project.
 
When the API documentation is extracted, raw documentation data will be dumped to the stdout stream.
 
This documentation data is then usually piped into the dog.tkx application in order to generate a set of HTML output files.
 
In the following examples, the documentation data is captured into .ee files. These files will later be linked together so that they can cross reference each other resp. be referenced in the supplementary documentation files.
 
2.1.1. Extracting documentation data from a TkScript project
To extract documentation from a TkScript project, use the following command: 
$ tks -ee myproject.tkp >myscriptproject.ee

 
Make sure to set the project name in the project file, e.g. 
[project] 
name="tkui" 
[chapter]
2.1.2. Extracting documentation data from a C++ project
To extract documentation from a C++ project, use the following command: 
$ tks app:dog++ -mn mynativeproject -pn mynativeproject *.h >mynativeproject.ee

 
Note: the -mn and -pn command line options are used to set the module resp. project name.
2.2. Generating supplementary documents
DOG supports an output-format independent document description language that is used to write hierarchical text documents like e.g. user guides or tutorials.
 
To transform these text documents into HTML files use the following command: 
$ tks app:dog myuserguide.dog

 
This will generate a file myuserguide.html in the current directory.
 
2.3. Linking API documentation and supplementary documents

Example: 
$ tks app:dog myscriptproject.ee mynativeproject.ee myuserguide.dog
3. API documentation
3.1. Inline TkScript API documentation
The explain keyword is used to embed inline documentation in TkScript source files.
Example: 
module Main; 
 
explain "The first line contains the short description (synopsis) for the current context."; 
 
function Test() { 
  explain "Synopsis for function @this."; 
} 
 
class CTest { 
  explain "Synopsis for class @this."; 
 
  test() { 
    explain "Synopsis for method @this"; 
  } 
 
  static Test() { 
    explain "Synopsis for function @this"; 
  } 
}

 
Please notice that the explain statement documents the last module, class, define, function or method.
3.2. Inline C++ API documentation
C++ API documentation has to be embedded in /* .. */ comments. Example: 
/* @class StdErrStream,Stream 
 
Represents the stderr output stream. 
 
@see StdInStream 
@see StdOutStream 
 
*/ 
YC class _StdErrStream : public YAC_StdErrStream {  
public:  
   YAC_POOLED(_StdErrStream, YAC_POOL_PRIORITY_LOW);  
    
/* @method isOpen:boolean 
 
Check whether the stream is open (always true). 
 
@return 1(true) 
*/ 
   YM //sSI  isOpen    (void);  
 
/* @method flush 
 
Write pending/cached output buffers into the stream. 
*/ 
      YM //void flush     (void);  
};

 
Please notice that the documentation parser does not parse the actual C resp. C++ code, it basically looks only at the comments !
3.3. Keywords
The following keywords (or "tags") can be used in TkScript or C++ inline documentation.
3.3.1. @arg
Syntax: 
@arg argName desc
- Used to describe an argument if the current context object is a function or method. The tag may occur at most one time for each argument.
3.3.2. @author
Syntax: 
@author string
- Used to specify the author of the given object. The tag may occur 0..1 times.
3.3.3. @date
@date string
- Used to describe the history of the given object. The tag may occur 0..n times.
3.3.4. @deprecated
@deprecated reason
- Used to mark the current context object as outdated (i.e. not to be used anylonger in new code). Currently only allowed for functions and methods. The tag may occur 0..1 times.
3.3.5. @return
@return desc
- Used to describe the return type if the current context object is a function or method. The tag may occur 0..1 times.
3.3.6. @since
@since version
- Used to specify since when the current context object has been available. Currently only allowed for functions and methods. The tag may occur 0..1 times.
3.3.7. @this
The special string @this will be replaced by the name of the current context object.
3.4. Including files
External files can be included by using backticks.
 
Example: 
`some_file.txt
4. Document generator
4.1. Pages
Each supplementary document should be put in a separate file. The first line of that file must look like this: 
!%<page_name> <page_title>

 
Example: 
!%dog The DOG manual
4.2. Comments
The !* keyword is used to prevent the DOG page parser from parsing anything until the end of the current line.
 
Example: 
!.mynode 
!* this is a comment that will not appear in the output file 
!/mynode
4.3. Nodes
4.3.1. Opening a new node
The !. keyword is used to begin a new (sub-) node.
 
The syntax is: 
!.mynode Title of my node
4.3.2. Closing a node (unchecked)
To close a node without validating the hierarchy level, the following syntax is used: 
!/

 
Example: 
!.mynode Title of my node    !* open a new node 
!/                           !* close the node
4.3.3. Closing a node (checked)
Once a document has reached a certain size, it becomes not so obvious which node will actually be closed by the !/ keyword.
DOG therefore provides a simple mechanism to verify that the correct node is closed.
 
Example: 
!.mynode Title of my node              !* open a new node 
!.myothernode Title of my other node   !* open another node 
!/myothernode                          !* close node and make sure that the current node is "myothernode" 
!/mynode                               !* close node and make sure that the current node is "mynode"
4.4. Links

Links to nodes within supplementary documents or to API entries (classes, functions, methods) can be inserted by using the § keyword.
4.4.1. Fully qualified links
A fully qualified link includes the complete path to the given documentation element.
 
Example: 
§dog.doc.link.fqlink

Will create the following link: Fully qualified links.
4.4.2. Best match links
When the name of a node is unique, a shortpath can be used.
 
Example: 
§bestmatch

Will create the following link: Best match links.
 
It is possible to restrict the best-match search to a specific document.
 
Example: 
§dog.bestmatch

Will create the following link: Best match links.
4.5. Macros
Macros are used to abbreviate and even parametrize recurring text blocks.
4.5.1. Defining a named macro
The !$ keyword is used to start a macro definition.
 
Example: 
!$macroname    !* start definition of "macroname" 
macrotext      !* .. 
!$$            !* end macro definition
4.5.2. Calling a named macro
The !$? keyword is used to call a macro and add its output as regular text.
The !?! keyword is used to call a macro and add its output as pre-formatted output text (e.g. HTML).
 
4.5.2.1. Without arguments
Example: 
!$x Hippopotomonstrosesquippedaliophobie !$$  !* Define macro "x" 
!$?x                                          !* call macro "x"
4.5.2.2. With arguments
Example: 
!$html_blue <font color="#0000ff">$(1)</font> !$$  !* Define macro "html_blue" 
!$!html_blue(Some text)                            !* call macro "html_blue"

 
Will have the following output: Some text
4.5.3. Anonymous macros
In order to just insert some raw HTML code, it is possible to insert anonymous macros.
 
Example: 
!$! <p style="color: red">Some paragraph!</p> !$$

 
Will have the following output:

Some paragraph

4.6. Functions
It is possible to embed TkScript function calls in documentation pages. These functions can generate either regular text or pre-formatted (HTML) text when they are called.
 
A number of functions is already included in the dog.tkx executable. More (document-specific) functions can easily be added on-the-fly.
4.6.1. Calling a function
The !: and !; keywords are used to call script functions.
4.6.1.1. Text functions
The !: function call inserts regular document text. This text will be converted to the output format, quicklinks will be replaced et cetera.
 
Example: 
!:CurrentDate()  !* Insert the current date
4.6.1.2. Raw functions
The !; function call inserts text that needs to be pre-formatted for the current output format (e.g. HTML).
 
Example: 
!$mylist         !* define a variable that holds an ASCII list/enumeration 
  - item 1 
  - item 2 
!$$              !* end of variable declaration 
!;List($mylist)  !* convert ASCII list to HTML

 
Will have the following output:
  • item 1
  • item 2
4.6.1.3. Function arguments
Functions can take an arbitrary and variable number of arguments.
4.6.1.3.1. Simple arguments
Simple arguments are - simply - strings.
 
Example: 
!:B(Some bold text)

 
Will have the following output: some bold text
4.6.1.3.2. Macro arguments
Example: 
!$mytext Some italic text.. !$$ 
!:I($mytext)

Will have the following output: Some italic text..
4.6.2. Builtin functions
The following functions are already built into the dog.tkx executable.
Please be aware that this list is just a first draft and may change without notice.
4.6.2.1. Print
Simply print the arguments. Sometimes useful to escape the keywords without using the designated escape sequence ( !\ )
4.6.2.2. Code
Preformatted text without linebreaks
4.6.2.3. Pre
Preformatted text including linebreaks
4.6.2.4. B
Bold text
4.6.2.5. I
Italic text
4.6.2.6. U
Underlined text
4.6.2.7. WIP
Used to mark text sections that are WORK IN PROGRESS. This is mainly for the people editing a document.
4.6.2.8. A

The A function is used to insert external links. 
!:A(www.tkscript.de)

 
Will have the following output: www.tkscript.de
!:A(www.tkscript.de,tkscript home)

 
Will have the following output: tkscript home
4.6.2.9. TitlePage
Generate a title page for the document.
The first argument is the document title, the second and third (optional) arguments are the sub-titles.
4.6.2.10. List
Convert an ASCII list to the current output format (HTML). If a line starts with one of the *+-o characters, a new list item is created. The whitespace indent level determines the nesting depth of the item.
 
Example: 
!$t 
  * Level0, Item0 
    - Level1, Item0 
    - Level1, Item1 
    - Level1, Item2 
  * Level0, Item1 
    - Level1, Item0 
      - Level2, Item0 
        - Level3, Item0 
  * Level0, Item2 
    - Level1, Item0 
      - Level2, Item0 
        - Level3, Item0 
      - Level2, Item1 
    - Level1, Item1 
  * Level0, Item3 
  * Level0, Item4 
!$$ 
!:List($t)

 
Will have the following output:
  • Level0, Item0
    • Level1, Item0
    • Level1, Item1
    • Level1, Item2
  • Level0, Item1
    • Level1, Item0
      • Level2, Item0
        • Level3, Item0
  • Level0, Item2
    • Level1, Item0
      • Level2, Item0
        • Level3, Item0
      • Level2, Item1
    • Level1, Item1
  • Level0, Item3
  • Level0, Item4
4.6.2.11. CurrentDate
Inserts the current date (Weekday, DayOfMonth/Month/Year format).
 
Example: Wed, 31/Dec/2008
4.6.2.12. CurrentTime
Inserts the current time (HourOfDay:Minute:Second format)
 
Example: 15:53:35
4.6.3. User defined functions
Any function that shall be callable from within a documentation page needs to be registered first.
 
Example: 

function DSA_Test(StringArray _args, String r) { 
   r.append("hello, DSA :-)"); 
} 
DSA.RegisterFunction("Test", DSA_Test);
4.6.3.1. Adding extra script files
Since DOG itself is a TkScript application, users would normally need to extend the dog.tkx executable to include additional script files.
Since TKS v0.9.10.18, a new commandline option -ef, --extrafile has been added that can be used to load extra script sources in addition to a TkScript executable.
 
Example: 
$ tks -ef myscript.tks app:dog mydocument.dog
4.7. Escaping the DOG keywords
In order to prevent DOG from falsely intepreting a char sequence as one of its keywords, the following escape sequences can be used:
  • "!\," escapes the ',' character (e.g. in function or macro argument lists)
  • "!\)" escapes the ')' character (also useful in argument lists)
  • "!\§" escapes the '§' character
  • "!\!" escapes the '!' character
  • "!\\" escapes the '\' character

auto-generated by "DOG", the TkScript document generator. Wed, 31/Dec/2008 15:53:35