hamlib.texi: Chapter 1 draft

Complete draft of Chapter 1, including the Hamlib-design.png image from
Martin, AA6E.

doc/Makefile.am

@@ -1,6 +1,6 @@
 EXTRA_DIST = hamlib.cfg index.doxygen hamlib.css footer.html
 
-dist_doc_DATA = hamlib.html hamlib.pdf
+dist_doc_DATA = Hamlib_design.png hamlib.html hamlib.pdf
 
 SRCDOCLST = ../src/rig.c ../src/rotator.c ../src/tones.c ../src/locator.c \
 		../src/event.c ../src/conf.c ../src/mem.c ../src/settings.c

doc/hamlib.texi

@@ -2,6 +2,7 @@
 @c %**start of header
 @setfilename hamlib.info
 @include version.texi
+@documentencoding UTF-8
 @settitle Ham Radio Control Libraries @value{VERSION}
 @c %**end of header
 
@@ -9,7 +10,7 @@
 This manual is for the Ham Radio Control Libraries (version @value{VERSION}
 updated @value{UPDATED}), which is a development effort to provide a
 consistent programming interface for programmers wanting to incorporate
-radio and rotator control into their programs.
+radio and rotor control into their programs.
 
 Copyright @copyright{} 2013 Nate Bargmann
 
@@ -42,79 +43,401 @@ License''.
 
 @ifnottex
 @node Top
-@top Hamlib
+@top Ham Radio Control Libraries
 
-This manual is for Ham Radio Control Libraries (version @value{VERSION},
+This manual is for Ham Radio Control Libraries (Hamlib) (version @value{VERSION},
 @value{UPDATED}).
 @end ifnottex
 
 @menu
 * Copying and Redistribution::
 * Hamlib in a Nutshell::
+* Getting started::
 * GNU Free Documentation License::
-* Index::
+* Working with Git::
+* List of Figures::
+* Concept Index::
 @end menu
 
+
 @node Copying and Redistribution
-@chapter Copying and Redistribution
+@unnumbered Copying and Redistribution
+@cindex Copying, redistribution
+@cindex Redistribution, copying
+@cindex Copyleft
 
-This manual describes Hamlib, a programming library and various supplied
-programs, which is Free Software.  Besides often being distributed at no
-cost to you, Free in this context means that the copyright holders to
-Hamlib have agreed to offer their collective work under terms that give you
+This manual documents Hamlib, a programming library and various supplied
+programs, which is
+@url{http://en.wikipedia.org/wiki/Free_Software_Definition, Free
+Software, Free Software}.  Besides often being distributed at no cost to
+you, Free in this context means that the copyright holders to Hamlib
+have agreed to offer their collective work under terms that give you
 certain rights that allow you to modify and/or redistribute Hamlib under
-the same terms that you received it.
+the same terms that you received it from them.
 
-Such licensing is often termed ``copyleft'' as a play against the common
-``all rights reserved'' terms of normal copyright.  In general, copyleft
-provides everyone with a license to modify and distribute the modified work
-or to simply distribute a copyrighted work under certain terms.  Hamlib
-source code is copyrighted by its authors and is licensed by them under two
-common licenses---the GNU Lesser General Public License (LGPL) for the
-``front end'' and ``back end'' library source code files, and the GNU
-General Public License (GPL) for the supplied programs source code files.
-The full text of the LGPL and the GPL can be found in the files COPYING.LIB
-and COPYING in the root directory of the Hamlib source archive.
+Such licensing is often termed
+@url{http://en.wikipedia.org/wiki/Copyleft, copyleft, copyleft} as a
+play against the common ``all rights reserved'' terms of normal
+@url{http://en.wikipedia.org/wiki/Copyright, copyright, copyright}.  In
+general, copyleft provides everyone with a license to modify and
+distribute the modified work or to simply distribute a copyrighted work
+under certain terms.  Hamlib source code is copyrighted by its authors
+and is licensed by them under two common licenses---the
+@url{http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License, GNU
+Lesser General Public License, GNU Lesser General Public License}
+@acronym{LGPL} for the ``front end'' and ``back end'' library source
+code files, and the
+@url{http://en.wikipedia.org/wiki/GNU_General_Public_License, GNU
+General Public License, GNU General Public License} @acronym{GPL} for
+the supplied programs source code files.  The full text of the LGPL and
+the GPL can be found in the files COPYING.LIB and COPYING in the root
+directory of the Hamlib source archive.
 
-This manual is covered by the GNU Free Documentation License, with no
-invariant and no cover texts.  Source code examples in this manual are
-parallel licensed under the GPL unless otherwise noted.
+This manual is covered by the
+@url{http://en.wikipedia.org/wiki/GNU_Free_Documentation_License, GNU
+Free Documentation License, GNU Free Documentation License}
+@acronym{GFDL} with no Invariant Sections, no Front-Cover Texts, and no
+Back-Cover Texts.  Source code examples in this manual are parallel
+licensed under the GPL unless otherwise noted.
 
-As part of the Copyleft nature of the licenses, the authors of Hamlib must
-forbid you from distributing Hamlib under terms that forbid others from
-exercising the same rights you received.  You must give anyone you
-distribute Hamlib to the same rights to obtain, modify, and distribute the
-Hamlib source code that you received nor may you license Hamlib under other
-terms than those you received.  Any recipients of Hamlib must be informed
-of the rights to the source code that they have received.
+As part of the Copyleft nature of the licenses, the authors of Hamlib
+must forbid you from distributing Hamlib under terms that forbid others
+from exercising the same rights you received.  You must give anyone you
+distribute Hamlib to the same rights to obtain, modify, and distribute
+the Hamlib source code that you received nor may you license Hamlib
+under other terms than those you received.  Any recipients of Hamlib
+must be informed of the rights to the source code that they have
+received.
 
-Finally, the authors of Hamlib require that it be understood that no
-warranty of any kind is offered to anyone receiving the Hamlib source code
-distribution.  Anyone distributing modified versions of Hamlib has the
-responsibility to inform any recipients that what they have is not the
-official release of Hamlib by its authors and should be prepared to support
-the modified version(s).  This is to preserve the reputations of the Hamlib
-authors and the Hamlib Project.  While it is not a requirement of the
-licenses, it is courteous to offer modifications back to the Hamlib authors
-for possible incorporation into their official release(s).
+@cindex NO WARRANTY
+Finally, the authors of Hamlib require that it be understood that NO
+WARRANTY of any kind is offered to anyone receiving the Hamlib source
+code distribution.  Anyone distributing modified versions of Hamlib has
+the responsibility to inform any recipients that what they have is not
+the official release of Hamlib by its authors and should be prepared to
+support the modified version(s).  This is to preserve the reputations of
+the Hamlib authors and the Hamlib Project.  While it is not a
+requirement of the licenses, it is courteous to offer modifications back
+to the Hamlib authors for possible incorporation into their official
+release(s).
 
+
+@c ------------ Chapter ------------
 @node Hamlib in a Nutshell
 @chapter Hamlib in a Nutshell
+@cindex Nutshell
 
-Hamlib is a ``front end'' library providing a C language Application
-Programming Interface (API) that provides a ``virtual radio'' or ``virtual
-rotator'' to an application.  The front end library uses a number of ``back
-end'' libraries to translate to individual radio models.  Hamlib also
-provides an interface library to several ``scripting'' languages such as
-Perl, Python, and TCL (known as ``bindings'').  A C++ language interface is
-also provided.
+The @dfn{Ham Radio Control Libraries}, @dfn{Hamlib} for short, is a
+development effort to provide a consistent interface for programmers
+wanting to incorporate radio control in their programs.
 
-Besides the C and supplemental APIs, Hamlib also provides a pair a network
-daemons that provide an API for controlling an attached radio or rotator
-through a network connection.
+Hamlib is not a complete user application, rather, it is a software
+layer intended to make controlling various radios and other shack
+hardware much easier. Hamlib will allow authors of such software as
+logging programs, digital communications programs, or those wanting to
+develop the ultimate radio control software to concentrate on the user
+interface and the basic function of the program rather than radio
+control.  Hamlib consists of several parts, the programming library,
+utility programs, and library interfaces to other programming languages.
+
+Most recent amateur radio transceivers allow external control of their
+functions through a serial interface. Unfortunately, control commands
+are not always consistent across a manufacturer's product line and each
+manufacturer's product line differs greatly from its competitors.
+
+Hamlib attempts to solve this problem by presenting a "virtual radio" to
+the programmer by providing an interface to actions such as setting a
+given VFO's frequency, setting the operating mode, querying the radio of
+its current status and settings, and giving the application a list of a
+given radio's capabilities. Unfortunately, what can be accomplished by
+Hamlib is limited by the radios themselves and some offer very limited
+capability.
+
+Other devices, such as antenna rotors, can be placed into the Hamlib
+control scheme. Other recent developments include network interface
+servers and a USB interface capability. Language bindings are provided
+for C, C++, Perl, Python, and TCL (more to come).
+
+@menu
+* Overview::
+* The Hamlib project::
+* Applications using Hamlib::
+* Licensing implications::
+* Radio cloning::
+* Pronunciation::
+@end menu
+
+@node Overview
+@section A view from the top of the tower
+@cindex Overview
+
+@cindex Front end library
+@cindex Virtual radio
+@cindex Virtual rotor
+Hamlib is a @dfn{front end} library providing a @emph{C} language
+Application Programming Interface @acronym{API} to programmers wishing
+to integrate radio or rotor control in their applications.  Hamlib
+presents a @dfn{virtual radio} or @dfn{virtual rotor} that is a
+consistent interface to an application despite wide differences in radio
+and rotor interfaces and capabilities.
+
+@cindex Back end library
+The front end library uses a number of @dfn{back end} libraries to
+translate from the front end to the various individual radio and
+rotor models.  A back end library handles conversion of the
+front end variables to the format needed by the radio or rotor
+device it controls.  The back end libraries are generally grouped by
+manufacturer and in some cases by a common control protocol.
+
+@quotation
+Since a picture is worth quite a few words, here is a visual representation
+of Hamlib's design.
+@ifhtml
+@*@*
+@end ifhtml
+@float Figure, fig:img1
+@image{Hamlib_design,,,Hamlib Design}
+@caption{Hamlib design---@i{courtesy of Martin Ewing, AA6E}.}
+@shortcaption{Hamlib design}
+@end float
+@*
+@end quotation
+
+@cindex Scripting languages
+@cindex Languages, scripting
+@cindex Interface, languages
+Hamlib also provides an interface library for each of several common
+@dfn{scripting} languages such as @url{http://www.perl.org, Perl, Perl},
+@url{http://www.python.org, Python, Python}, and @url{http://www.tcl.tk,
+TCL, TCL}.  These language @dfn{bindings} are generated through the use
+of @url{http://www.swig.org, SWIG, SWIG} a parser/generator for multiple
+language interfaces to a C library.  A native generated @emph{C++}
+language interface is also provided.
+
+@cindex Daemon, network
+@cindex Network, daemon
+Besides the C and supplemental APIs, Hamlib also provides a pair of
+network daemons that provide a text command based API for controlling
+an attached radio or rotor through a @emph{TCP/IP} network connection.
+The daemons then handle the interface to the Hamlib C API.
+
+More than one type of device, radio or rotor, may be controlled at a
+time, however, there is generally a limit of one device per serial port
+or other port.
+
+@node The Hamlib project
+@section Hamlib project information
+@cindex Hamlib project
+@cindex Project, Hamlib
+
+The Hamlib Project was founded by Frank Singleton,VK3FCS/KM5WS in July
+2000.  Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib
+project and the API and implementation development led to a reasonable
+level of maturity in a few years.  A major milestone was reached when
+Hamlib 1.2.0 was released in March 2004.  The API and Application
+Binary Interface (@acronym{ABI}) interfaces have remained stable since
+that time up to the latest release of 1.2.15.3 in late 2012.
+
+Development continues with a bump of the public version number to 3.0
+(essentially simply dropping the ``1.'' of previous releases).  While some
+API tweaks are planned, ABI compatibility with the prior 1.2.@i{x}
+releases remains a priority.  Other goals include streamlining the
+build system (done), improving the SWIG generated language bindings
+(in progress), improving the overall documentation (this manual, in
+progress), and other updates as warranted.
+
+The Project is hosted by @url{https://sourceforge.net/,
+SourceForge.net} at the @url{https://sourceforge.net/projects/hamlib/,
+Hamlib project page} and the
+@url{http://sourceforge.net/apps/mediawiki/hamlib/index.php, Hamlib
+Wiki}.
+
+Development discussion and most user support take place on the
+@url{https://sourceforge.net/p/hamlib/mailman/, hamlib-developer mailing
+list}.  While there are
+@url{https://sourceforge.net/p/hamlib/discussion/, SourceForge.net
+discussion forums}, they are rarely used and not as closely read by the
+developers as the mailing list.
+
+For @dfn{source code management}, the project uses
+@url{http://git-scm.com/, Git}, a fast, distributed content tracker.
+Among its features is that every developer has the complete Hamlib
+development history available locally.  While a canonical Git
+repository is hosted as SourceForge, its availability is not essential to
+continued development, although development work flows would change
+temporarily.  For more information on using Git, @pxref{Working with
+Git}.
+
+@quotation Note
+The SourceForge.net Web interface to the Hamlib Git repository is
+currently broken (a ticket is pending) as of late February, 2013.  A
+mirror exists at @url{https://github.com/N0NB/hamlib, GitHub} which
+supports browsing via the Web and other Git commands.  Access of the
+SF.net repository by other means (SSH or Git protocols) is unaffected
+by this issue.
+@end quotation
+
+@node Applications using Hamlib
+@section Applications using Hamlib
+@cindex Hamlib applications
+@cindex Applications, using Hamlib
+
+A number of application developers have taken advantage of Hamlib's
+capabilities to implement radio and/or rotor control.  While not
+exhaustive, a list is maintained at the Hamlib Wiki,
+@url{https://sourceforge.net/apps/mediawiki/hamlib/,
+Applications/Screenshots}.  Developers are encouraged to request their
+applications be added to the gallery by way of the hamlib-developer
+mailing list.
+
+@node Licensing implications
+@section Using Hamlib with your program
+@cindex Hamlib licensing
+@cindex Licensing, Hamlib
+
+As with other Free Software projects, Hamlib relies heavily on copyleft
+licensing to encourage development contributions and provide an open
+atmosphere for development.  Hamlib's source code is released under two
+licenses, the @acronym{LGPL} for the library portion, and the
+@acronym{GPL} for the utility programs.
+
+The LGPL allows the library to be used (linked) by programs regardless
+of their individual license.  However, any contributions to the library
+source remain under copyleft which means that the library source code
+may not be used in violation of the terms of the LGPL.
+
+The utility program source files are released under the GPL.  Any direct
+use of these sources must be in a form that complies with the terms of
+the GPL.  Concepts learned by studying these sources for the purpose of
+understanding the Hamlib API is not covered nor prohibited by the GPL,
+however, directly copying GPL sources into any work that is incompatible
+with the terms of the GPL is prohibited.
+
+@xref{Copying and Redistribution}.
+
+@node Radio cloning
+@section Radios with a clone capability
+@cindex Radio cloning
+@cindex Cloning, radio
+
+Hamlib's focus is on controlling rigs that employ a port and command
+protocol for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF
+transceivers do not employ such control capability but do provide for
+cloning the memory contents from radio to another of the same model. A
+related project, @url{http://chirp.danplanet.com/, CHIRP}, aims to
+support rigs with such a clone capability. Please contact the CHIRP
+project for support of such rigs.
+
+@node Pronunciation
+@section Pronouncing Hamlib
+@cindex Pronouncing Hamlib
+@cindex Hamlib, pronouncing
+
+English speakers seem to have two alternate pronunciations for our
+project:
+
+@itemize @bullet
+@item Hamlib (Ham - lib, long "i", as in library.) IPA style: /'ham læb/
+@item Hamlib (Ham - lib, short "i", as in liberty.) IPA style: /'ham lɪb/
+@end itemize
+
+Then again, we have people who say Linux "L-eye-nux" and those who say
+"L-in-nux"...
+
+If you're French, the above does not apply! :-)
+
+
+@c ------------ Chapter ------------
+@node Getting started
+@chapter Getting started
+
+There are several ways to obtain a working installation of Hamlib.  In
+the following sections discuss installing from a package manager,
+building from source, and installing Hamlib project supplied binaries on
+Microsoft Windows@registeredsymbol{}.
+
+@menu
+* Unix binary packages::
+* Source options::
+* Building from source::
+@end menu
+
+@node Unix binary packages
+@section Installing binary packages on Linux and BSD
+@cindex Binary packages, Linux, BSD
+@cindex Linux binary packages
+@cindex BSD binary packages
+
+The easiest way to install a released version of Hamlib on a Linux based
+distribution or a BSD variant is through the provided @dfn{package
+manager}.  While package managers vary according to the distribution
+(it's easy to lump BSD variants in this group too) their end goal is to
+provide ready to use packages.  Since such a wide variety of package
+managers exist, it is best to recommend that the documentation for your
+chosen distribution be your guide.
+
+
+@node Source options
+@section A variety of Hamlib sources
+
+Distribution packages are most often official Hamlib releases and in
+some cases could be quite old and lacking support for newer radios or
+rotors.  In some cases support is improved in existing radio or
+rotor back ends and bugs are fixed.  Often times to get improved
+support building from source will be required.  Relax, it's not hard.
+:-)
+
+Source code is available as official releases, testing snapshots, and
+the bleeding edge of development.  As a rule, even the bleeding edge
+tarballs should configure and compile without error even though certain
+implementation work may be in progress and be incomplete or have errors.
+
+@menu
+* Source releases::
+* Source snapshots::
+@end menu
+
+@node Source releases
+@subsection Getting released source
+@cindex Getting released source
+@cindex Source, getting released
+@cindex Source, obtaining releases
+
+Official Hamlib source releases, commonly called @dfn{tarballs} can be
+found on the @url{http://sourceforge.net/projects/hamlib/files/hamlib/,
+SourceForge.net Hamlib files} Web page.  The most recent release is
+listed first.
+
+@node Source snapshots
+@subsection Getting source snapshots
+@cindex Getting source snapshots
+@cindex Source, getting snapshots
+@cindex Source, obtaining snapshots
+@cindex Source, daily snapshots
+
+Testing release candidates and daily snapshots of the development
+repository are available via the World Wide Web from
+@url{http://n0nb.users.sourceforge.net/, Hamlib Git daily snapshots}.
+These are not official releases but are provided for testing new
+features and bug fixes.
+
+
+@node Building from source
+@section Building from source
+@cindex Building from source
+@cindex Source, building from
+
+Building from source will be required for various reasons including an
+older version provided by your distribution, you'd like to test recent
+changes to Hamlib---either a specific back end or API changes---and offer
+a report to the developers, or you'd like to take part in development
+and offer your contribution to the project, of you'd just like to learn
+how to build a relatively comprehensive package from source.  Let's get
+started.
+
+
+@c ----------------- Appendixes start here ------------------
 
-More than one device may be controlled at a time, however, there is
-generally a limit of one device per serial port, etc.
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
@@ -122,8 +445,20 @@ generally a limit of one device per serial port, etc.
 @include fdl.texi
 
 
-@node Index
-@unnumbered Index
+@node Working with Git
+@appendix Working with Git
+
+Git offers a myriad of commands and options.  Fortunately, only a few
+are needed for Hamlib development.
+
+
+@node List of Figures
+@unnumbered List of Figures
+@listoffloats Figure
+
+
+@node Concept Index
+@unnumbered Concept Index
 
 @printindex cp