Pichat SDK, Tools Documentation

This document describes a set of tools for software developers and advanced Pichat users. 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 mkdoc program creates 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 emphasis on easy setup and maintenance. All information is collected from class definitions, source code and comments.

For an example documentation please see PichatCore library in the Pichat SDK.

When your 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-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-title	set document title (text)
mkdoc-copyright	set copyright information (text)
mkdoc-author	set author and contact information (text)
mkdoc-footer	set document footer (text)
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:	mkdoc outfile namespace exportfilter filename1 [...]
	mkdoc 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 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:	mkdoc sdklibrary.txt SdkLibrary 0 SdkLibraryClasses.h
	mkdoc sdklibrary.txt SdkLibrary::Component 0 -c SdkLibrary.conf
	mkdoc sdklibrary.xml SdkLibrary::Component 0 -c SdkLibrary.conf

Notes: Mkdoc 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. Comments have to be in C++ syntax. 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. XML output is shown as HTML in a standard web browser, style sheets are included.

The mkres 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:	mkres outfile namespace exportversion filename1 [...]
	mkres outfile namespace exportversion -c configfile
	mkres 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:	mkres PluginResourceModule Plugin 0 plugin.txt plugin.png
	mkres PluginResourceModule Plugin::Uncompressed 0 -c example.conf
	mkres 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 pipasswd program can create or update your Pichat user permissions which are used by chat and web server. You can either specify arguments at the command line or use an interactive mode (with the -i flag). With the -r flag you can remove an user permission.

Syntax:	pipasswd inifile usertype username password address [description]
	pipasswd inifile usertype -i username
	pipasswd inifile usertype -r username
Arguments:	inifile = name of user permissions file usertype = type of user, one of the following: USER_NORMAL = registered user, for chat and web server USER_ADMIN = chat admin, for chat server only username = name of user, not case sensitive password = password of user, case sensitive address = address of user description = text with optional user description
Examples:	pipasswd pichat_user_permissions.ini USER_NORMAL -i flicka
	pipasswd pichat_user_permissions.ini USER_NORMAL flicka puss12 10.10.1.2
	pipasswd pichat_user_permissions.ini USER_ADMIN admin pass1234 10.10.1.2

Notes: As address you can choose any IP address or IP range, e.g. 10.10.1.2 or 10.10.1.0/8 (IP range from 10.10.1.0 - 10.10.1.255). The '*' character may be used as wildcard to match every address, but it is not recommended to make use of wildcards when you have sensitive data on your server. Chat admins can also use a hostname like 'pichat.no-ip.com'.

The pipository 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:	pipository outfile name filename1 [...]
	pipository 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:	pipository updates.ini Plugins plugin.dll
	pipository 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 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 a copyright comment 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

mkdoc	SharkEngine documentation tool for Linux/BSD
mkdoc.exe	SharkEngine documentation tool for Windows
mkdoc_default.css	SharkEngine documentation tool, style sheet (part 2)
mkdoc_default.xsl	SharkEngine documentation tool, style sheet (part 1)
mkres	SharkEngine resource tool for Linux/BSD
mkres.exe	SharkEngine resource tool for Windows
pichat_sdk_tools.txt	This friendly help file
pipasswd	Pichat user permissions update for Linux/BSD
pipasswd.exe	Pichat user permissions update for Windows
pipository	Pichat repository tool for Linux/BSD
pipository.exe	Pichat repository tool for Windows
pngcomment	SharkEngine PNG comment update for Linux/BSD
pngcomment.exe	SharkEngine PNG comment update 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.