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. To download latest development tools please see Pichat downloads.

This document is part of 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.

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-author	set document author and contact information (text)
mkdoc-copyright	set document copyright 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 filename = name of input file, C++ source or header file configfile = name of file containing 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

Example documentation: PichatCore and SharkEngine libraries in the Pichat SDK

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 filename = name of input file, executable or plugin configfile = name of file containing 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 filename = name of input file configfile = name of file containing 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 padupdate program updates version information in a PAD file, which contains application description in XML format. You can specify application and PAD file at the command line, plus an optional configuration file (with the -c flag).

The following fields are updated:

Program_Version	version information from application or configuration file
Program_Release_Day	file modification time
Program_Release_Month	(")
Program_Release_Year	(")
File_Size_Bytes	file size (bytes)
File_Size_K	file size (kB)
File_Size_MB	file size (MB)
File_Checksum_SHA256	file SHA256 checksum
Primary_Download_URL	has to match name of application file (field is NOT modified)

Syntax:	padupdate appfile filename
	padupdate appfile filename -c configfile
Arguments:	appfile = name of application file, executable or plugin filename = name of PAD file configfile = name of file containing a list of input files
Examples:	padupdate application.exe application.xml
	padupdate application.exe application.xml -c example.conf

Example PAD file: http://www.pichat.net/xml/pichat_win32.xml

Notes: The PAD updater 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 pngupdate program updates or adds a comment to a PNG image, for example author or copyright information. You can either specify files at the command line or use a configuration file (with the -c flag). All comments are stored as meta data and not visible in the image.

Syntax:	pngupdate key text filename1 [...]
	pngupdate key text -c configfile
Arguments:	key = name of comment text = text of comment, multiple words have to be quoted filename = name of PNG image configfile = name of file containing a list of PNG images
	Here is a list of standard keys:
	Title title of image Author image creator and contact information Copyright copyright information Description description of image Software software used to create the image Disclaimer legal disclaimer Source device used to create the image Comment miscellaneous comment
Examples:	pngupdate Author "Mark Seuffert" screenshot.png
	pngupdate Copyright "Piratson Technologies" screenshot.png
	pngupdate Copyright "Piratson Technologies" -c example.conf

Notes: Files with unknown format are ignored. An empty text removes the key.

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
padupdate	PAD version updater for Linux/BSD
padupdate.exe	PAD version updater for Windows
pngupdate	PNG comment updater for Linux/BSD
pngupdate.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.