--------------------------------------------------------------------------------
What is SkelGen?
--------------------------------------------------------------------------------

SkelGen is the programmer's tool for quickly creating empty (skeleton) source
files that follow a common standard. For example, your source files may all
require a standard header and footer, with a standard class "shell" which allows
your source files to follow a set of standard formatting rules.

For contact information and where to find new versions, see the about box
(Windows version) or use the -help parameter (for Linux version.)

This is other linux-specific information at the bottom of this file.

--------------------------------------------------------------------------------
Overview
--------------------------------------------------------------------------------

Source files are generated from templates which you customize. Each template may
use a series of macro replacements (performed by SkelGen) to generate the data
you want automatically.

There are two types of macros: Built-in (dynamic) macros & user-defined (static)
macros. The built-in (dynamic) macros are used to generate dynamic data within
the output (the current date, source file, etc.) The user-defined (static) macros
are read from a series of macro files that you create.

The purpose of multiple macro files is to allow you to generate different kinds
of skeleton source files.  For example, you may wish to use a set of skeleton
files for your GPL work, and one for your personal projects and yet another for
your business related work. Or, you may have a different way of segregating your
needs. For example, you may have a template for new classes as you add them to
the project. You have complete control over the template files, so go to town.

Each macro (as it appears within a template file) is a word within square
brackets. For example:

	// This file created on: [asctime]

...will produce the following output:

	// This file created on: Sat Oct 21 13:41:55 2000

In the previous example, the macro [asctime] is one of the built-in macros. When
a macro is referenced from one of the macro files (i.e. a user-defined static
macro) it is referenced with the macro filename as part of the macro itself.
Here's an example of the macro "company" as referenced from the macro file
"work.macro":

	// This file belongs to: [work.company]

...which, depending on how the user defined this macro, might produce something
similar to:

	// This file belongs to: ACME Software

--------------------------------------------------------------------------------
Built-in macros
--------------------------------------------------------------------------------

[description]	-- File description
[class]		-- Class name
[user1]		-- User definable macro #1
[user2]		-- User definable macro #2
[user3]		-- User definable macro #3
[user4]		-- User definable macro #4
[user5]		-- User definable macro #5
[asctime]	-- Time as reported from asctime()
[dayname]	-- Name of the current day of the week ('mon', 'tue', etc.)
[monthname]	-- Name of the current month ('Jan', 'Feb', etc.)
[month]		-- Two digit month
[day]		-- Two-digit day of the month
[year]		-- Four digit year
[hour]		-- Two digit hour
[minute]	-- Two digit minutes
[second]	-- Two digit seconds
[filepath]	-- File path (i.e. "g:\proj" from "g:\proj\myprog.cpp")
[filebase]	-- Base filename (i.e. "myprog" from "g:\proj\myprog.cpp")
[fileext]	-- File extension (i.e. "cpp" from "g:\proj\myprog.cpp")

Note that the [class] macro (and its associated user input edit box) can be used
for creating C++ class skeletons on a per-file basis.

--------------------------------------------------------------------------------
Static macros via *.macro files
--------------------------------------------------------------------------------

A macro file is very simple. It is just a list of macro names (no spaces),
followed by an '=' sign, followed by the macro replacement (which may include
spaces) and is terminated by a carriage return. Spaces on either side of the
equal sign are ignored.

It's important to note what you call your macro files since, as mentioned
earlier, the filename is part of the macro reference within the template files.
Each macro file must be named with an extension of ".macro". For example, the
file "work.macro" might contain the following (rather boring) information:

	company = ACME Software
	author = John Doe, esq. III
	project = FAD - Financial Accounting Database

These macros would then be referenced within the template files in the form of:

	[work.company]
	[work.author]
	[work.project]

Note that any template file can access a macro from any macro file. So if you
have a set of macros that are common too all your projects and source files, you
may wish to create a "common.macro" file so that you can access this information
within each of your template files.

--------------------------------------------------------------------------------
Notes about macros
--------------------------------------------------------------------------------

If you wish the '[' character to be used in the actual output, and not as part 
of a macro, you can escape the first '['. For example, "\[filebase]" will result 
in the string "[filebase]" being output into the file without expanding the 
macro. Any occurance of the '[' character that is not part of an actual macro 
must be escaped, or an error will result.

--------------------------------------------------------------------------------
Prefixes
--------------------------------------------------------------------------------

You may force a macro to be upper-cased or lower-cased with the following
prefixes:

	[upper:basename]
	[lower:filepath]

The 'comment' prefix allows you to leave yourself comments that will not be
placed in the output source file. For example:

	[comment: This is a comment block. Note that comments may not span]
	[comment: multiple lines so a new comment block must be used for  ]
	[comment: each successive line of text.                           ]

You may include other template files (recursively). For example:

	[include:foo.template]

Be careful with file inclusion, no checks for cyclic inclusions are made.

--------------------------------------------------------------------------------
Large "Bubble" text
--------------------------------------------------------------------------------

You may also use 8-character tall bubble-text. For example:

	// [bubble1:filebase] <--
	// [bubble2:filebase] <--
	// [bubble3:filebase] <--
	// [bubble4:filebase] <-- 'filebase' from
	// [bubble5:filebase] <-- "c:\foo\testfile.cpp"
	// [bubble6:filebase] <--
	// [bubble7:filebase] <--
	// [bubble8:filebase] <--

...will generate the following ouput

	//  _            _    __ _ _       <--
	// | |          | |  / _(_) |      <--
	// | |_  ___ ___| |_| |_ _| | ___  <--
	// | __|/ _ \ __| __|  _| | |/ _ \ <-- 'filebase' from
	// | |_|  __/__ \ |_| | | | |  __/ <-- "c:\foo\testfile.cpp"
	//  \__|\___|___/\__|_| |_|_|\___| <--
	//                                 <--
	//                                 <--

Note that you must specify each of the eight lines within your template file.
This allows you to format your bubble-text any way you like. The 'kerning'
option in the UI allows you to control the spacing of the characters. A kerning
value of -1 will cause the characters to sligtly overlap (as shown above),
positive values will increase the spacing between characters. 

--------------------------------------------------------------------------------
Additional notes about prefixes
--------------------------------------------------------------------------------

If you use a macro that is not found, you will get the text of the macro. For 
example, the macro [foo] does not exist, so it will expand to "foo" (the body of 
the macro, minus the square brackets.) This applies to all macros, all the time. 
This allows you to generate bubble-text from something other than a macro 
replacement (i.e. if you want the bubble-text of the string "foo".) 


You can mix the upper-case with bubble-text. If you do so, be sure to place the 
'upper' prefix _in_front_ of the 'bubble' prefix, such as: 

	[upper:bubble1:filebase]
		.
		.
		.
	[upper:bubble8:filebase]

The same goes for the 'lower' prefix: 

	[lower:bubble1:filebase]
		.
		.
		.
	[lower:bubble8:filebase]

--------------------------------------------------------------------------------
Linux-specific
--------------------------------------------------------------------------------

Though this documentation was written based on the Windows (original) version,
it still applies to the linux version, so if you haven't read it, read it.

The primary difference with the Linux version (aside from the command-line
interface) is the location of the macros & templates. In both versions, these
files are stored in directories called "macros" and "templates". However, under
Linux, the location of these directories is configurable. The default location
is the current directory ("."). This allows you to have different templates &
macros for each project.

However, you may still want to use a different prefix. You do this with the -p
option, like this:

	skelgen somefile -p/usr/local/skelgen

This will use macros & templatges located in the following directory:

	/usr/local/skelgen/macros
	/usr/local/skelgen/templates

You may also put this into an environment variable, like so:

	set skelgen_prefix=/usr/local/skelgen

--------------------------------------------------------------------------------
TODO
--------------------------------------------------------------------------------

	* Add functionality for plug-in to MSVC (under windows)
	* Develop a GUI interface under X
	* Add the ability to create a batch of files at once
	* Add the ability to update existing files with skeleton headers

--------------------------------------------------------------------------------
END OF HELP
--------------------------------------------------------------------------------
