Update documentation.

Added required/optional development package info in README.betatester
and added info on ldconfig and its configuration.

git-svn-id: https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk@3034 7ae35d74-ebe9-4afe-98af-79ac388436b8

INSTALL

@@ -3,11 +3,11 @@ Basic Installation
 
 For more information specific to Hamlib, please read the README as well as
 README.betatester and the first part of README.developer to see which
-additional development packages are needed. This source code distribution  
+additional development packages are needed. This source code distribution is
-is autoconfiguring and you should be able to compile it and install it 
+autoconfiguring and you should be able to compile it and install it without
-without manual interventions such as editing Makefiles, configuration files, 
+manual interventions such as editing Makefiles, configuration files, and so
-and so on. These are generic instructions for people who are not familiar 
+on. These are generic instructions for people who are not familiar with
-with installing autoconfiguring software (along with some Hamlib-specific 
+installing autoconfiguring software (along with some Hamlib-specific
 information).
 
 The simplest way to compile this package is to enter the source code
@@ -196,9 +196,11 @@ diffs or instructions to the address given in the `README' so they can
 be considered for the next release.  If at some point `config.cache'
 contains results you don't want to keep, you may remove or edit it.
 
-   The file `configure.in' is used to create `configure' by a program
+   The file `configure.ac' is used to create `configure' by a program
-called `autoconf'.  You only need `configure.in' if you want to change
+called `autoconf'.  You only need `configure.ac' if you want to change
-it or regenerate `configure' using a newer version of `autoconf'.
+it or regenerate `configure' using a newer version of `autoconf'.  This
+project uses a custom `autoconf.sh' for running autoconf in a developer's
+checkout of Hamlib from a source repository.
 
 Advanced installation options.
 ==============================
@@ -259,7 +261,8 @@ to the configure script (may happen under MacOSX).
 
    Any problem encountered with the perl, tcl, python or swig tool can be
 disabled by passing `--without-tcl-binding', `--without-perl-binding',
-and/or '--without-python-binding'.
+and/or '--without-python-binding'.  Note that these bindings are disabled
+by default.
 
    Some platfroms may have trouble compiling the RPC support (e.g. Mac OS X).
 in such a case, the rpcrig and rpcrot backends may be disabled

README

@@ -8,8 +8,9 @@ Applications.
 
 Many Amateur Radio Transceivers come with serial interfaces that allows
 software to control the radio. This project will endeavour to provide shared
-libraries that greatly simplify the application programmer's interaction with
+libraries that greatly simplify the application programmer's interaction
-radio equipment and other controllable devices such as rotators, switches, etc.
+with radio equipment and other controllable devices such as rotators,
+switches, etc.
 
 Supported Radios
 ----------------
@@ -74,24 +75,25 @@ at least the following tools:
     * svn and ssh to connect to http://sourceforge.net/
 
 There are also the README.betatester and README.developer files in this
-directory if you feel like testing or hacking Hamlib.  Otherwise, contributions
+directory if you feel like testing or hacking Hamlib.  Otherwise,
-of rig specifications and protocol documentation are highly encouraged.  Do
+contributions of rig specifications and protocol documentation are highly
-keep in mind that in some cases the manufacturer may not provide complete
+encouraged.  Do keep in mind that in some cases the manufacturer may not
-control information or it is only available under a Non-Disclosure Agreement
+provide complete control information or it is only available under a
-(NDA).  Any documentation *must* be publicly available so we can legally write
+Non-Disclosure Agreement (NDA).  Any documentation *must* be publicly
-and distribute Free Software supporting a given device.
+available so we can legally write and distribute Free Software supporting a
+given device.
 
-However, if you just want to recompile the library, please refer to the INSTALL
+However, if you just want to recompile the library, please refer to the
-and README.betatester files.
+INSTALL and README.betatester files.
 
 IMPORTANT: If autoconf or automake are installed on your system, make sure
 they are matching *at least* the version shown above.  The Hamlib team is
-very interrested to hear from you, how Hamlib builds and works on your system,
+very interested to hear from you, how Hamlib builds and works on your
-especially on non-Linux system or non-PC systems. We try to make Hamlib as
+system, especially on non-Linux system or non-PC systems. We try to make
-portable as possible.
+Hamlib as portable as possible.
 
 Please report in case of problems at hamlib-developer@lists.sourceforge.net
-Patches are welcome too!
+Patches in unified diff format are welcome too!
 
 Most distributions have the latest Hamlib release in their testing or alpha
 versions of their distribution.  Check your package manager for the Hamlib
@@ -100,9 +102,9 @@ version included in your distribution.
 Take a look at tests/README for more info on simple programming examples and
 test programs.
 
-Also, take a look at http://sourceforge.net/projects/hamlib/
+Also, take a look at http://sourceforge.net/projects/hamlib/ Here you will
-Here you will find a mail list, and the latest releases.  Feedback, questions,
+find a mail list, and the latest releases.  Feedback, questions, etc. about
-etc. about Hamlib are very welcome at the mail list:
+Hamlib are very welcome at the mail list:
 <hamlib-developer@lists.sourceforge.net>
 
 Have Fun / Frank S / Stephane F / The Hamlib Group

README.betatester

@@ -4,13 +4,13 @@ Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
 
 * Why does Hamlib need beta-testers?
 
-Hamlib is developed by a team of radio enthusiasts around the world, for fun,
+Hamlib is developed by a team of radio enthusiasts around the world, for
-much in the spirit of ham radio. (Note that it is not restricted for ham
+fun, much in the spirit of ham radio. (Note that it is not restricted for
-usage only). There are a great deal of protocols and rigs around the world
+ham usage only). There are a great deal of protocols and rigs around the
-developers may not own. However, protocols may be available, so backends
+world developers may not own. However, protocols may be available, so
-can be implemented, but cannot always be tested by developers. That's where
+backends can be implemented, but cannot always be tested by developers.
-beta-testers are so precious. On top of that, I've been told that there's
+That's where beta-testers are so precious. On top of that, I've been told
-no such sure thing like bug free code.
+that there's no such sure thing like bug free code.
 
 Feedback and improvement requests are also valuable.
 
@@ -18,15 +18,15 @@ Feedback and improvement requests are also valuable.
 * Okay, you volunteer as beta-tester, how to proceed?
 
 First of all, you can start testing official releases. They are easier to
-test because they come in precompiled and packaged (.rpm, .deb, etc.) but they
+test because they come in precompiled and packaged (.rpm, .deb, etc.) but
-have the drawback of being older than the SVN repository. Reports from these
+they have the drawback of being older than the SVN repository. Reports from
-versions are still very appreciated.  Please send them to the
+these versions are still very appreciated.  Please send them to the
 hamlib-developer@lists.sourceforge.net mailing list.
 
 However, the development of Hamlib is still very active, so it's better to
-test from the latest SVN version of the code.  And, depending on feedback you
+test from the latest SVN version of the code.  And, depending on feedback
-make, developers can commit a fix, so you can try out the change soon after,
+you make, developers can commit a fix, so you can try out the change soon
-without waiting for the next official version.
+after, without waiting for the next official version.
 
 To proceed, you will have first to obtain either a daily snapshot or a check
 out of the latest sources from the SVN repository, then rebuild the Hamlib
@@ -55,10 +55,45 @@ uploaded and the prior day's version is removed.
 
 The advantage of the SVN snapshot is that you won't need as many tools
 installed to build Hamlib as the work of Autoconf, Automake, and Libtool
-have already been done.  Most of the other packages listed in README.developer
+have already been done.  Most of the other packages listed below will be
-will be needed unless you tell the `configure' script to not build certain
+needed.  If you tell the `configure' script to build certain parts of Hamlib
-parts of Hamlib like documentation or scripting language bindings.
+like documentation or scripting language bindings the relavent optional
-See `configure --help' for more information.
+packages will be needed.  See `configure --help' for more information.
+
+Here is a list of development packages needed for a complete build of the
+library:
+
+* Gnu C or any C99 compliant compiler       # gcc --version
+* Gnu make  (or any modern one, BSD okay)   # make --version
+* libtool       2.2.6b                      # libtool --version
+* svn for connection to hamlib.svn.sourceforge.net
+
+N.B. The Debian and derivatives (Ubuntu and friends) 'build-essentials'
+package will install a number of tools and minimize the number of packages
+that need to be installed manually.
+
+N.B. Hamlib no longer supports versions of libtool earlier than 2.2.6b in
+compliance with CVE-2009-3736.  If an older version is found, Hamlib will
+use the bundled libtool 2.2.6b instead.
+
+Optional, but highly recommended for a complete build:
+* GNU C++                           # g++ --version
+* swig (for bindings)   1.3.14      # swig -version
+* perl devel                        # h2xs
+* tcl devel                         # tcltk-depends
+* python devel                      # python-config
+* libxml2 devel                     # xml2-config --version
+* libgd2 devel                      # gdlib-config --version
+* libusb devel                      # libusb-config --version (not 1.0.0!)
+* RPC devel (libc-dev)              # rpcgen --version
+
+N.B  The libusb package is required for building most of the 'kit' backend.
+The older version is needed, not 1.0.0 or higher.  Debian and derivatives
+package libusb 0.1.12 which is what is needed.
+
+Documentation:
+* Doxygen
+* DocBook                           # Deprecated in favor of Doxygen
 
 
 * SVN checkout:
@@ -99,6 +134,20 @@ following in the same parent directory of hamlib:
 
 This will keep the binary output files seperate from the source tree.
 
+NOTE!  If Hamlib has not been previously installed as a locally built
+package you will need to make sure that `ldconfig' is configured correctly
+and run periodically after `make install'.  Most modern distributions have
+an /etc/ld.so.conf.d/ directory where local configuration can be made.
+Later versions of Debian and derivatives have a file named 'libc.conf' in
+this directory.  The contents of libc.conf are:
+
+# libc default configuration
+/usr/local/lib
+
+If your system does not have such a file, one will need to be created and
+then `ldconfig' will need to be run as the root user so that applications
+using the Hamlib libraries can find them.
+
 
 * Structure:
 
@@ -109,15 +158,17 @@ time):
 alinco,aor,icom,
 jrc,kachina,kenwood,
 pcr,tentec,uniden,
-winradio,yaesu:     rig backends
+winradio,
+yaesu,etc:          rig backends
+easycomm,rotorez,
+sartek, etc:        rotator backends
+dummy:              virtual dummy rig and rotator, for developer's use.
 rpcrig:             special networked rig backend (through RPC)
 rpcrot:             special networked rotator backend (through RPC)
-easycomm:           rotator backends
-dummy:              virtual dummy rig and rotator, for developer's use.
-c++,tcl,kylix:      C++, tcl, and Kylix bindings
 lib:                library for functions missing on your system
 libltdl:            wrapper for shared module loader
-debian:             debian package scripts
+bindings            Perl, Python, Tcl, and Visual Basic bindings
+c++,kylix:          C++ and Kylix bindings
 doc:                documentation base and scripts to extract from src
 include/hamlib:     exported header files go here
 include:            non-distributed header files go there
@@ -127,9 +178,11 @@ tests:              rigctl/rotctl and various C programs for testing
 
 * testing Hamlib:
 
-Don't attempt to test Hamlib from the source directory unless you're a developer
+Don't attempt to test Hamlib from the source directory unless you're a
-and you understand the side effects of *not* installing freshly generated
+developer and you understand the side effects of *not* installing freshly
-objects (basically having to mess with LD_LIBRARY_PATH and .libs).
+generated objects (basically having to mess with LD_LIBRARY_PATH and
+.libs).  Do an `sudo make install' to install the libraries in the system
+area.  (You did run `ldconfig', right?)
 
 So here we go. First of all, identify your rig model id.  Make sure
 /usr/local/bin (or the path you set --prefix to above) is in your $PATH, as
@@ -137,8 +190,9 @@ rigctl has to be reachable by your shell.
 
 Run `rigctl -l' to get a list of rigs supported by Hamlib.
 
-If you cannot find your radio in the list, please report to the hamlib-developer
+If you cannot find your radio in the list, please report to the
-mailing list. The protocol manual and rig specifications will help us a lot.
+hamlib-developer mailing list. The protocol manual and rig specifications
+will help us a lot.
 
 You found your rig's ID?  Good!  You're almost ready to use rigctl.
 Have a quick look at its manual page:
@@ -180,15 +234,16 @@ _       get_info                should give remote Id and firmware vers
 NB: some functions may not be implemented in the backend or simply not
 available on this rig.
 
-When reporting to the hamlib-developer mailing list, please include traces and
+When reporting to the hamlib-developer mailing list, please include traces
-also comments to tell developers if the action performed correctly on the rig.
+and also comments to tell developers if the action performed correctly on
+the rig.
 
-Tip: traces can be hard to cut and paste sometimes. In that case,
+Tip: Traces can be hard to cut and paste sometimes. In that case, there's a
-    there's a handy tool for you:  script(1) (the (1) is not a part of the
+handy tool for you:  script(1) (the (1) is not a part of the command, rather
-    command, rather it is a Unix convention telling which section of the manual
+it is a Unix convention telling which section of the manual it is found, in
-    it is found, in this case section 1, user commands.  e.g. `man 1 script').
+this case section 1, user commands.  e.g. `man 1 script'). It will make a
-    It will make a typescript of everything printed on your terminal and save it
+typescript of everything printed on your terminal and save it to the file
-    to the file you give it.
+you give it.
 
     $ script my_rig_traces.txt
     Script started, file is my_rig_traces.txt
@@ -218,18 +273,20 @@ measurement.  It's easy, it takes only 10mn. Here's how to proceed:
  1. Fire up the rigctl program released with the Hamlib package,
     and pass along options as needed (serial speed, etc.).
  2. Tune to some frequency reporting S0 to the radio S-Meter.
- 3. At rigctl prompt, issue "get_level" ('l' in short) of the level RAWSTR.
+ 3. At rigctl prompt, issue "get_level" ('l' in short) of the level
- 4. Write down the S-level read on radio front panel, and the RAWSTR value
+    RAWSTR.
-    retrieved.
+ 4. Write down the S-level read on radio front panel, and the RAWSTR
+    value retrieved.
  5. Repeat from step 2 with S9 and S9+60dB. Actually the more plots,
     the better, otherwise Hamlib does interpolation.
- 6. Send the table to the hamlib-developer mailing list and it will be added
+ 6. Send the table to the hamlib-developer mailing list and it will be
-    in the next release of Hamlib.
+    added in the next release of Hamlib.
 
-NB: It is well known the S-Meter of any given radio is far from being accurate.
+NB: It is well known the S-Meter of any given radio is far from being
-For owners with a fully equipped lab, you may want to make the above-mentioned
+accurate. For owners with a fully equipped lab, you may want to make the
-measurements with a good signal generator and a set of calibrated attenuators.
+above-mentioned measurements with a good signal generator and a set of
-Greg W8WWV has an insightful page about S-Meter calibration:
+calibrated attenuators. Greg W8WWV has an insightful page about S-Meter
+calibration:
 
 http://www.seed-solutions.com/gregordy/Amateur%20Radio/Experimentation/SMeterBlues.htm
 

README.developer

@@ -42,8 +42,8 @@ Hamlib also enables developers to develop professional looking
 GUI's towards a standard control library API, and they would not have
 to worry about the underlying connection towards physical hardware.
 
-Initially serial (RS232) connectivity will be handled, but
+Serial (RS232) connectivity is built in as are IP (also via a socket
-I expect that IP, USB, and other connectivity will follow afterwards.
+utility) and USB.  Other connectivity will follow afterwards.
 
 
 General Guidelines.
@@ -133,7 +133,7 @@ svn co https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk hamlib
 
 N.B.:  If the "trunk" subdirectory is ommited then the entire SVN
 reposity will be downloaded!  This includes all branches and tags that
-have ever been created in the hostory of Hamlib.  That is quite large,
+have ever been created in the history of Hamlib.  That is quite large,
 abut 22 MiB as of this writing (March 2009).
 
 The check out has only to be done the first time.
@@ -203,6 +203,10 @@ Optional, but highly recommended:
 * libusb devel                      # libusb-config --version (not 1.0.0!)
 * RPC devel (libc-dev)              # rpcgen --version
 
+N.B  The libusb package is required for building most of the 'kit' backend.
+The older version is needed, not 1.0.0 or higher.  Debian and derivatives
+package libusb 0.1.12 which is what is needed.
+
 Documentation:
 * Doxygen
 * DocBook                           # Deprecated in favor of Doxygen
@@ -288,6 +292,20 @@ For a Tcl build, add this if needed:
 Note: C-shell users may have to run autogen.sh and make through a bourne
 shell instead, or pass "SHELL=bash" as a parameter to make.
 
+NOTE!  If Hamlib has not been previously installed as a locally built
+package you will need to make sure that `ldconfig' is configured correctly
+and run periodically after `make install'.  Most modern distributions have
+an /etc/ld.so.conf.d/ directory where local configuration can be made.
+Later versions of Debian and derivatives have a file named 'libc.conf' in
+this directory.  The contents of libc.conf are:
+
+# libc default configuration
+/usr/local/lib
+
+If your system does not have such a file, one will need to be created and
+then `ldconfig' will need to be run as the root user so that applications
+using the Hamlib libraries can find them.
+
 
 1.4. Feedback
 
@@ -433,7 +451,7 @@ Contributed code should always keep the source base in a compilable state,
 and not regress unless stated otherwise.
 
 There's no need to tag the source in a patch with your name in comments
-behind each modification, we already know the culprit :-)
+behind each modification, we already know the culprit from commit logs. :-)
 
 Patches should take portability issues into account.
 Keep in mind Hamlib has to run under: