Pichat SDK, tools documentation

This document describes a set of tools for Pichat software developers. These tools help with writing and maintaining software, they run on Linux, BSD and Windows.

All tools are complimentary to the Pichat SDK, available at http://www.pichat.net

The mkdocument program creates a simple documentation from C++ source and header files. You can either specify files at the command line or use a configuration file (with the -c flag). The basic idea of this tool is to extract documentation directly from the existing code base with easy setup and maintenance. All information are collected from class definitions, source code and comments.

For example documentation please see PichatCore and SharkEngine libraries in the Pichat SDK.

When your source code contains comments a decent documentation will be automatically generated, e.g. one-line comments in front of methods are used as descriptions. Optionally, the generated output can be adjusted and extended by inline configuration. Any comment in the form '//(mkdoc-option argument)' will be interpreted as inline configuration.

The following configuration options are available, sorted by relevance:
(Some options expect arguments, text in brackets lists them)

mkdoc-title	set document title (text)
mkdoc-copyright	set document copyright information (text)
mkdoc-author	set document author and contact information (text)
mkdoc-footer	set document footer (text)
mkdoc-show	show class/namespace/method/element
mkdoc-hide	hide class/namespace/method/element
mkdoc-description	add description for class or method (name)
mkdoc-comments	add comments for class or namespace (name)
mkdoc-comments-block-begin	begin of comments block for class or namespace (name)
mkdoc-comments-block-end	end of comments block
mkdoc-notes	add notes for method (name)
mkdoc-construction	add constructor or factory method to class (name)
mkdoc-group	combine multiple methods into one group (number)
mkdoc-group-force	force multiple methods into one group (name number)
mkdoc-section-new	start a new section number with class or namespace (name)
mkdoc-section-block-begin	begin of block with new text section (name)
mkdoc-section-block-end	end of block with new text section
mkdoc-ignore	ignore comment line, do nothing

Syntax:	mkdocument outfile namespace exportfilter filename1 [...]
	mkdocument outfile namespace exportfilter -c configfile
Arguments:	outfile = name of output file, the file suffix defines the format: txt = plaintext (default) wiki = text format with formatting information html = HTML format with meta information xml = XML format with meta information namespace = namespace to be documented exportfilter = export filter for classes: 0 = document any class in given namespace, no filter 1 = document only classes marked with an "EXPORT" macro configfile = name of file containg a list of input files
Examples:	mkdocument sdklibrary.txt SdkLibrary 0 SdkLibraryClasses.h
	mkdocument sdklibrary.txt SdkLibrary::Component 0 -c SdkLibrary.conf
	mkdocument sdklibrary.xml SdkLibrary::Component 0 -c SdkLibrary.conf

Notes: The documentation tool requires C++ code inside a namespace. Per default all public methods, variables and enums are included in the generated documentation, you can overwrite this per inline configuration in your code. Unkown or missing information are marked with 'n/a' (not available) in generated documentation. Source files should have a suffix starting with 'c' and header files starting with 'h' (e.g. *.cpp and *.h), other file extensions are ignored. Comments have to be in C++ syntax. Style sheets for HTML/XML output are included.

The mkrepository program creates file repositories with version information and SHA256 checksum. You can either specify files at the command line or use a configuration file (with the -c flag).

Syntax:	mkrepository outfile name filename1 [...]
	mkrepository outfile name -c configfile
Arguments:	outfile = name of output file name = name for created repository configfile = name of file containg a list of input files
Examples:	mkrepository updates.ini Plugins plugin.dll
	mkrepository updates.ini Plugins -c example.conf

Notes: The repository tool tries to detect version information from executables and plugins. For unknown file formats you have to specify the version manually, in a config file you can use comma separated arguments with file name and version. The '^' character may be used as place holder in the config file, to use same version number as the previous line.

The mkresource program creates resources from files in order to include them in a C++ application, plugin or library. You can either specify files at the command line or use a configuration file (with the -c flag, alternatively the -z flag to generate 'gzip' compressed data).

Syntax:	mkresource outfile namespace exportversion filename1 [...]
	mkresource outfile namespace exportversion -c configfile
	mkresource outfile namespace exportversion -z configfile
Arguments:	outfile = base name for output files namespace = namespace for created data exportversion = line number of text string (in first file), adds an "EXPORT" macro to generated files, 0 to disable configfile = name of file containg a list of input files
Examples:	mkresource PluginResourceModule Plugin 0 plugin.txt plugin.png
	mkresource PluginResourceModule Plugin::Uncompressed 0 -c example.conf
	mkresource PluginResourceModule Plugin::Compressed 0 -z example.conf

Notes: Generated resources can be statically linked to your application, e.g. to create a single executable file. The SharkEngine library offers the class CResourceHandler to access resources and the class CDataCompression to decompress data. Each resource has meta data with file name, size and modification time.

The pngcomment program adds copyright information to a PNG image. You can either specify files at the command line or use a configuration file (with the -c flag). Files which already have copyright information or files with unknown format are ignored.

Syntax:	pngcomment copyright filename1 [...]
	pngcomment copyright -c configfile
Arguments:	copyright = text string with copyright information configfile = name of file containg a list of input files
Examples:	pngcomment www.piratson.se screenshot.png
	pngcomment www.piratson.se -c example.conf

mkdocument	Documentation tool for Linux/BSD
mkdocument.exe	Documentation tool for Windows
mkdocument_default.css	Documentation tool, style sheet (part 1)
mkdocument_default.xsl	Documentation tool, style sheet (part 2)
mkrepository	Repository tool for Linux/BSD
mkrepository.exe	Repository tool for Windows
mkresource	Resource tool for Linux/BSD
mkresource.exe	Resource tool for Windows
pichat_sdk_tools.txt	This friendly help file
pngcomment	PNG comment updater for Linux/BSD
pngcomment.exe	PNG comment updater for Windows

Linux/BSD software is compiled with gcc4 and libc6, i586 compatible CPU.
Windows software is compiled with VC6, i386 compatible CPU.

These files may be used and distributed under the terms of the Piratson public license as published in Pichat readme.