Re-worked documentation for to/from_bcd functions in misc.c.

Re-worked INSTALL describing `configure' options.  Other minor
editing.


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

INSTALL

@@ -6,33 +6,50 @@ file. This source code distribution  is autoconfiguring and you should be
 able to compile it and install it without manual interventions such as 
 editing Makefiles, configuration files, and so on. These are generic 
 instructions for people who are not familiar with installing autoconfiguring
-software.
+software (along with some Hamlib-specific information).
 
 The simplest way to compile this package is to enter the source code
 main directory and do the following:
    
   1. Configure the source code by typing:
-        % sh ./configure
+        
+        $ sh ./configure
 
      If you're planning to install the package into your home directory
      or to a location other than `/usr/local' then add the flag
      `--prefix=PATH' to `configure'. For example, if your home directory  
-     is `/home/luser' you can configure the package to install itself there
+     is `/home/username' you can configure the package to install itself 
-     by invoking:
+     there by invoking:
-        % sh ./configure --prefix=/home/luser
+        
+        $ sh ./configure --prefix=/home/username
+
+     N.B. If you know that you won't be using scripting languages (Perl,
+     Python, or TCL) and that you won't need static libaries (most
+     applications dynamically link Hamlib by default) invoke `configure'
+     as follows:
+     
+        $ ./configure --without-perl-binding --without-python-binding \
+        --without-tcl-binding --disable-static
+
+     This will result in a much smaller Hamlib installation (and faster
+     compilation :-) ).  See also the "Hamlib specific Features" section 
+     below for other `configure' options.  
      
      While running, `configure' prints some messages telling which
      features is it checking for. 
 
   2. Compile the package by typing:
-        % make
+        
+        $ make
+     
      Running `make' takes a while. If this is a very large package, now
      is the time to go make some coffee.
      
   3. Some packages are bundled with self-tests for source-code 
      verification. If this package includes such tests, you can 
      optionally run them after compilation by typing 
-        % make check
+
+        $ make check
 
   4. Type `make install' to install the programs and any data files and
      documentation. Type `make uninstall' to undo the installation.
@@ -51,12 +68,16 @@ main directory and do the following:
      created on demand. 
 
      If you are installing in your home directory make sure that 
-     `/home/luser/bin' is in your path. If you're using the bash shell
+     `/home/username/bin' is in your path. If you're using the bash shell
-     add this line at the end of your .cshrc file:
+     add these lines at the end of your .bashrc file:
-        PATH="/home/luser/bin:${PATH}"
+
+        PATH="/home/username/bin:${PATH}"
         export PATH
+
      If you are using csh or tcsh, then use this line instead:
-        setenv PATH /home/luser/bin:${PATH}
+
+        setenv PATH /home/username/bin:${PATH}
+
      By prepending your home directory to the rest of the PATH you can
      override systemwide installed software with your own custom installation.
 
@@ -66,8 +87,10 @@ main directory and do the following:
      a different kind of computer), type `make distclean'.
 
   6. You can optionally generate the Doxygen documentation files:
+
         cd doc
         make doc
+
      The HTML output files are provided for binary releases on the hamlib.org
      web site.
 
@@ -91,12 +114,16 @@ Occasionally that confuses the debugger when code is inlined. To disable
 optimization and enable debugging, set the shell environment variables
 CFLAGS, CXXFLAGS, FFLAGS to `-g'. On the bash shell, you can do this
 like this:
+
   $ export CFLAGS="-g"
   $ export CXXFLAGS="-g"
   $ export FFLAGS="-g"
+
 On the tcsh shell, use the `setenv' command instead:
+
   % setenv CFLAGS "-g"
   ...etc...
+
 For other shell, please consult your shell's documentation.
 
 Similarly, you can increase the optimization level by assigning these
@@ -194,3 +221,6 @@ and/or '--without-python-binding'.
 in such a case, the rpcrig and rpcrot backends may be disabled 
 with the `--without-rpc-backends' option.
 
+   Building static libraries can be disabled by use of the `--disable-static'
+option.  This will reduce the installed size of Hamlib considerably.
+

README

@@ -1,5 +1,5 @@
 Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
-	 (C) Stephane Fillod 2000-2007
+         (C) Stephane Fillod 2000-2007
          (C) The Hamlib Group 2000-2007
 
 The purpose of this project is to provide stable, flexible,
@@ -70,11 +70,13 @@ Any documentation *must* be publically 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 file. IMPORTANT: If autoconf or automake are installed on
+to the INSTALL file. 
-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
+IMPORTANT: If autoconf or automake are installed on your system, make sure 
-builds and works on your system, especially on non-Linux system or 
+they are matching *at least* the version shown above.  The Hamlib team is 
-non-PC systems. We try to make Hamlib as portable as possible.
+very interrested to hear from you, how Hamlib builds and works on your system,
+especially on non-Linux system or non-PC systems. We try to make Hamlib as 
+portable as possible.
 
 Please report in case of problems at hamlib-developer@lists.sourceforge.net
 Patches are welcome too!

README.betatester

@@ -1,5 +1,5 @@
 Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
-	 (C) Stephane Fillod 2000-2007
+         (C) Stephane Fillod 2000-2007
          (C) The Hamlib Group 2000-2007
 
 * Why does Hamlib need beta-testers?

src/misc.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - toolbox
  *  Copyright (c) 2000-2005 by Stephane Fillod
  *
- *	$Id: misc.c,v 1.43 2007-11-26 20:54:11 n0nb Exp $
+ *	$Id: misc.c,v 1.44 2008-01-04 17:30:31 n0nb Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -55,15 +55,20 @@
  * \param bcd_len
  * \return bcd_data
  *
- * Convert a long long (eg. frequency in Hz) to 4-bit BCD digits, 
+ * Convert a long long (e.g. frequency in Hz) to 4-bit BCD digits,
- * packed two digits per octet, in little-endian order.
+ * packed two digits per octet, in little-endian order
- * bcd_len is the number of BCD digits, usually 10 or 8 in 1-Hz units, 
+ * (e.g. byte order 90 78 56 34 12 for 1234567890 Hz).
- *	and 6 digits in 100-Hz units for Tx offset data.
  *
- * Hope the compiler will do a good job optimizing it (esp. w/ the 64bit freq)
+ * bcd_len is the number of BCD digits, usually 10 or 8 in 1-Hz units, 
+ * and 6 digits in 100-Hz units for Tx offset data.
+ *
+ * Hope the compiler will do a good job optimizing it (esp. w/the 64bit freq)
+ *
+ * Returns a pointer to (unsigned char *)bcd_data.
+ *
+ * \sa to_bcd_be
  */
-unsigned char *
+unsigned char * HAMLIB_API to_bcd(unsigned char bcd_data[], unsigned long long freq, unsigned bcd_len)
-HAMLIB_API to_bcd(unsigned char bcd_data[], unsigned long long freq, unsigned bcd_len)
 {
 	int i;
 	unsigned char a;
@@ -87,15 +92,21 @@ HAMLIB_API to_bcd(unsigned char bcd_data[], unsigned long long freq, unsigned bc
 }
 
 /**
- * \brief Convert BCD digits to a long long (eg. frequency in Hz)
+ * \brief Convert BCD digits, little-endian, to a long long (e.g. frequency in Hz)
  * \param bcd_data
  * \param bcd_len
  * \return binary result (e.g. frequency)
  *
- * Convert BCD digits to a long long (eg. frequency in Hz)
+ * Convert BCD digits, little-endian, (byte order 90 78 56 34 12
+ * for 1234567890 Hz) to a long long (e.g. frequency in Hz)
+ *
  * bcd_len is the number of BCD digits.
  *
  * Hope the compiler will do a good job optimizing it (esp. w/ the 64bit freq)
+ *
+ * Returns frequency in Hz an unsigned long long integer.
+ *
+ * \sa from_bcd_be
  */
 unsigned long long HAMLIB_API from_bcd(const unsigned char bcd_data[], unsigned bcd_len)
 {
@@ -116,16 +127,18 @@ unsigned long long HAMLIB_API from_bcd(const unsigned char bcd_data[], unsigned
 }
 
 /**
- * \brief Convert binary to bcd, big-endian
+ * \brief Convert from binary to 4-bit BCD digits, big-endian
  * \param bcd_data
  * \param freq
  * \param bcd_len
  * \return bcd_data
  *
- * Same as to_bcd, but in Big Endian mode
+ * Same as to_bcd, but in big-endian order
+ * (e.g. byte order 12 34 56 78 90 for 1234567890 Hz)
+ *
+ * \sa to_bcd
  */
-unsigned char *
+unsigned char * HAMLIB_API to_bcd_be(unsigned char bcd_data[], unsigned long long freq, unsigned bcd_len)
-HAMLIB_API to_bcd_be(unsigned char bcd_data[], unsigned long long freq, unsigned bcd_len)
 {
 	int i;
 	unsigned char a;
@@ -150,12 +163,15 @@ HAMLIB_API to_bcd_be(unsigned char bcd_data[], unsigned long long freq, unsigned
 }
 
 /**
- * \brief Convert bcd to binary, big-endian
+ * \brief Convert 4-bit BCD digits to binary, big-endian
  * \param bcd_data
  * \param bcd_len
- * \return binary value, e.g., frequency
+ * \return binary result
  *
- * Same as from_bcd, but in Big Endian mode
+ * Same as from_bcd, but in big-endian order
+ * (e.g. byte order 12 34 56 78 90 for 1234567890 Hz)
+ *
+ * \sa from_bcd
  */
 unsigned long long HAMLIB_API from_bcd_be(const unsigned char bcd_data[], unsigned bcd_len)
 {