sfgen Files

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.