Readme - Gen

Gen

Readme

—01| HOW TO USE THIS DOCUMENT

(Note that this README is designed to be filled out over the course of many versions. Some sections are currently blank.)

What is the software about?
See INTRO.

Is it OK for me to use? OK for me to modify? OK to make copies?
See LICENSE for info about the software license. License page itself is here.
See LEGAL for any additional info.

How do I get it working?
See GETTING STARTED (after you have it installed and configured) to see how to use.
See DEPENDENCIES for anything external that is required or optional.
See BUILDING for how to compile from source.
See INSTALLATION for how to install it on your system (and how to uninstall).
See CONFIGURATION for how you can customize it for your own use.

I cannot make it work, what now?
See TROUBLESHOOTING for dealing with problems with the software.
See PLATFORM NOTES for ensuring it works with your platform/OS.
See MANUAL to make sure you are using it correctly.
See FAQ to see if your question has been answered.
See KNOWN ISSUES to see if your problem is already known about (and any workarounds / advice).
See BUG REPORTING if you want to make a report and get follow-up.

What is in the other sections?
FEEDBACK - Info about things like feature requests.
TESTING - How you can test changes you make to the code.
CONTRIBUTING - How you improve the product for everyone.
UPDATING - How to get the latest changes.
RECENT CHANGES - What the latest changest are.
CREDITS - Third party components used.

—02| INTRO

Say you are in the middle of solving one problem and find you need to solve another. Suppose you need to insert into a string. You could write code that will do this, but it would be nice and convenient if there were something that does it all for you with one command.

Gen is about making it a little bit easier to write Tcl programs. Gen is supposed to be code that you could well write yourself but do not want to have to.

Gen is General Utilities for Tcl.

—03| GETTING STARTED

Since this is a utilities library, you do not need to do much of anything to get started. The best thing would be to try typing in the examples from the documentation.

If you would like to confirm the library is installed and working then try the following from a Tcl shell.


% package require gen

1.18.0

% set Number 1

1

% AddTo Number 2

3

You should be all set!

—04| DEPENDENCIES

Gen CAN use the following packages, but they are not strictly necessary (see below). You likely will already have got them as part of your Tcl distribution:

sqlite3
Tclx
textutil::adjust
textutil::string
ftp
registry (Windows only)

If you do not have these, then check the documentation that came with your distro for information on how to get them.

However! Since the introduction of the Partial Loading feature, it is possible to use Gen without having these packages installed. Of course, any commands that need missing packages will not work, but you can still use any other commands that do not need the missing packages. Inside the MANUAL you can find a page with more details.

—05| BUILDING

Gen is provided as a simple Tcl package and does not need to be built.

—06| INSTALLATION

If you are reading this you most likely have already successfully installed Gen.

To install, extract the contents of the archive file (.zip or .tar.gz). That will result in the following files:

README.txt Plenty of info on how to get going.

LICENSE.txt Terms of use and whatnot.

WARNING.txt Special notices to prevent surprises.

/src

Source files

`pkgIndex.tcl`	Used by the Tcl package mechanism.
`gen.tcl`	Main script file.
`gen-config.tcl`	Configuration variables (e.g. datetime format).
`gen-error.tcl`	Error codes and messages used by Gen.
`loading-module.tcl`	Code that tries to load packages and then Gen commands.
`loading-module-data.tcl`	Data used to do the loading.
`*.tcl`	Each command has its own source file.

/doc Any other documents (like the manual).

/test Test suite

Take the path to the install directory you just made and with it add the following line at the bottom of your init.tcl file:

lappend auto_path YOUR_DIR_PATH

See DEPENDENCIES for info about what Gen may need.

See CONFIGURATION for more info about init.tcl.

What to do after you install? You can check out the Getting Started section of the README. We recommend browsing the manual (or even better, use the .chm file included in your download). Each command reference has at least one example. You can type that directly into your terminal and try out the command.

Prefer use to git and clone the repo? There is a repo posted up on GitHub for you.

How to uninstall? To uninstall you can simply delete the directory. You can also remove the lappend auto_path YOUR_DIR_PATH line from your Tcl init.

—07| CONFIGURATION

To configure Tcl so it can find Gen:

Take the path to the install directory you just made and with it add the following line at the bottom of your init.tcl file:

lappend auto_path YOUR_DIR_PATH.

How to find init.tcl? Here are some locations found for Windows and Linux. Most likely if you use the number of your version then you can find your init.tcl in a similar spot.

C:\Tcl\lib\tcl8.5\init.tcl
C:\Tcl\lib\tcl8.6\init.tcl
/usr/share/tcltk/tcl8.4/init.tcl
/usr/share/tcltk/tcl8.5/init.tcl

Alternatively, do a search for init.tcl starting from the root directory of your installation.

In order to use various commands, you will want to do configuration of certain variables. You can take a look at the following, when you need to use the commands:

Database
- doc/about-configuration-for-database-use.html
Date and Time
- doc/about-date-and-time-commands.html
FTP
- doc/about-ftp-use.html

To run the FTP tests, you will also need to do special set up. See test/README-test-ftp.txt or test/README-test-ftp.html for details.

—08| MANUAL

We have a few options. You can see the online manual (which will be the most up-to-date).

Alternatively, you can use the offline version at doc/manual-home.html or (preferrably) use the compiled HTML Help version at doc/gen.chm.

—09| FAQ

No questions yet. We will put them here as we get them.

Please send questions you have to gen.questions@robertbrogan.com or visit our feedback page.

Also note, you may possibly find the answer to your question in MANUAL, TROUBLESHOOTING, or KNOWN ISSUES.

—10| PLATFORM NOTES

If you have Tcl working for your platform, then the library should work without problem.

None of the commands themselves include platform-specifc interactions (i.e. make system calls) beyond occasionally calling another Tcl command that is platform-specific (e.g. in an upcoming release the command Reg2Dict will call the Tcl command registry, which is Windows-specific).

—11| TROUBLESHOOTING

No tips at this time. We will post them here as we get them.

Also note, you may possibly find help in MANUAL, FAQ, or KNOWN ISSUES.

—12| KNOWN ISSUES

See the local HTML Known Issues page or the online Known Issues page.

—13| BUG REPORTING

To report a bug, you can visit our feedback page and use the form there.

Alternatively, you can send an email to—

gen.bugreport@robertbrogan.com

—and we will try to get back to you ASAP.

Note that you may also want to check the Known Issues page and the Latest Fixes page to see if your issue has already been reported or perhaps already fixed.

—14| FEEDBACK

You can visit our feedback page at our feedback page.

Alternatively, you can use your own email client and send an email to one of:

gen.questions@robertbrogan.com
gen.comments@robertbrogan.com
gen.bugreport@robertbrogan.com
gen.wishlist@robertbrogan.com
gen.other@robertbrogan.com

and we will try to get back to you ASAP.

—15| TESTING

You can find tests in the /test directory.

You will find a README file there as well, with further details on things like how to run the tests yourself.

To run the FTP tests, you will also need to do special set up. See test/README-test-ftp.txt or test/README-test-ftp.html for details.

—16| CONTRIBUTING

Nothing formal has been set up for governing this project, yet.

—17| UPDATING

The latest version can be found at www.robertbrogan.com/gen/download.html.

Want to receive notifications about changes to Gen? You can subscribe to the announcements mailing list by sending an email to gen-announce-subscribe@robertbrogan.com. (No need for anything in subject or message body.) You will get an email every time we have a new release.

Note that you may want to check out the Policies page to find out how releases are done. You may also want to check out the Roadmap page to find out when the next release is coming out.