Gen
README
CONTENTS OF THIS FILE
---------------------
01| HOW TO USE THIS DOCUMENT
02| INTRO
03| GETTING STARTED
04| BUILDING
05| INSTALLATION
06| CONFIGURATION
07| MANUAL
08| FAQ
19| PLATFORM NOTES
10| TROUBLESHOOTING
11| KNOWN ISSUES
12| BUG REPORTING
13| FEEDBACK
14| TESTING
15| CONTRIBUTING
16| UPDATING
17| RECENT CHANGES
18| LICENSE
19| LEGAL
20| CREDITS
---01| HOW TO USE THIS DOCUMENT
Prefer to use the website for better and more up-to-date info instead. Otherwise, prefer to use HTML versions as they are hyperlinked.
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.
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 ~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
You are coding and you need to do something simple. Like what? Maybe you need to read a file into a string. Perhaps you need to check whether your input is a datetime. Is there a library for this?
It is better if you have a good library to use. Why? Because it is better to stay focused on the main problem you are trying to solve and keep your flow going. Suppose you have to write the contents to a string variable to a file. This is not difficult, but then again you already have work you are doing. It is better to look up one command that does it all that it is to look up the five or so commands you would otherwise need. Further, there is a chance you may do something like neglect to do a flush or use the file pointer in the puts, etc. There is always plenty of opportunity for making mistakes in the coding game.
So it is better to have a library that makes things nice and convenient for you. That is what this project aims to produce. Please take a look. We have put together documentation that is like what you are used to with TCL. We have also made a screencast that shows you how to get things up-and-running within minutes. Give it a try!
---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.0
% set Number 1
1
% AddTo Number 2
3
%
You should be all set!
---04| BUILDING
This is provided as a simple TCL package and does not need to be built.
---05| INSTALLATION
If you are reading this you most likely have already successfully installed.
To install, unzip gen.zip in the directory of your choice. 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.
.git
Source git repo.
/src
Source files
pkgIndex.tcl
Used by the TCL package mechanism.
gen.tcl
Main script file.
/doc
Any other documents (like the manual).
/tests
Test suite
You will probably want to add the following to your init.tcl so that Tcl can find the gen package:
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 your version number you can find it in the same spot.
C:\Tcl\lib\tcl8.5
/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.
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? It is posted up on GitHub at https://github.com/rbrogan/Gen for you.
---06| CONFIGURATION
No configuration necessary to get started or for basic usage.
For options / settings, see MANUAL.txt.
---07| MANUAL
See doc/MANUAL.txt or http://www.robertbrogan.com/gen/manual.html.
---08| FAQ
No questions yet.
Please send questions you have to
gen.questions@robertbrogan.com or visit http://www.robertbrogan.com/gen/feedback.html.
Also note, you may possibly find the answer to your question in ~MANUAL~, ~PLATFORM NOTES~, ~TROUBLESHOOTING~, or ~KNOWN ISSUES~.
---09| PLATFORM NOTES
The project was developed on Windows Vista using ActiveState ActiveTcl. No platform-specific features are used and it is expected it should run with any TCL interpreter.
---10| TROUBLESHOOTING
No tips at this time.
Also note, you may possibly find help in ~MANUAL~, ~PLATFORM NOTES~, ~FAQ~, or ~KNOWN ISSUES~.
---11| KNOWN ISSUES
None at this time.
For a more up-to-date list, you can visit http://www.robertbrogan.com/gen/knownissues.html.
---12| BUG REPORTING
Visit http://www.robertbrogan.com/gen/feedback.html.
Alternatively, 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.
---13| FEEDBACK
Visit http://www.robertbrogan.com/gen/feedback.html.
Alternatively, 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.
---14| TESTING
Currently, there are no tests.
If and when there are tests, they will be added to a directory called 'test'.
---15| CONTRIBUTING
Nothing formal has been set up for governing this project, yet.
If you like, you may change the code yourself and submit a patch to:
gen.bugreport@robertbrogan.com (for bug fixes)
-or-
gen.wishlist@robertbrogan.com (for features you implemented)
A roadmap (planned changes) and wishlist (unplanned) are available at:
http://www.robertbrogan.com/gen/roadmap.html
http://www.robertbrogan.com/gen/wishlist.html
You may want to get involved by submitting wishlist items and/or offering to do work listed in the above two sites.
---16| UPDATING
The latest version can be found at http://www.robertbrogan.com/gen/download.html.
No announcements mechanism has been set up yet. When it is, information for how to subscribe will be put on the above page.
---17| RECENT CHANGES
Initial revision. No changes yet.
---18| LICENSE
See LICENSE.txt
---19| LEGAL
No legal notice at this time (i.e. no use of crypto). See LICENSE.txt for information about the license.
---20| CREDITS
Information posted at wiki.tcl.tk has been helpful throughout work on TCL projects.
