Another extensive round of edits for the WSJT-X User's Guide.

git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@3657 ab8295b8-cf94-4d9e-aec4-7959e3be5d79

doc/source/acknowledgements.txt

@@ -1,17 +1,19 @@
 // Status=review
-- Many users of WSJT, too numerous to mention here individually, have
+
+Many users of WSJT, too numerous to mention here individually, have
 contributed suggestions and advice that have greatly aided the
 development of {wsjtx} and its sister programs.  Since 2005 the
 overall project (including WSJT, MAP65, WSPR, {wsjtx}, and WSPR-X) has
-been “open source”, all code being licensed under the GNU Public
+been “open source”, with all code licensed under the GNU Public
 License (GPL).
 
-- For {wsjtx} in particular, I wish to acknowledge contributions from:
+For {wsjtx} in particular, we acknowledge contributions from *AC6SL,
-*AC6SL, AE4JY, DJ0OT, G4KLA, G4WJS, K3WYC, KA6MAL, KA9Q, KK1D, PY2SDR,
+AE4JY, DJ0OT, G4KLA, G4WJS, K3WYC, KA6MAL, KA9Q, KI7MT, KK1D, PY2SDR,
-VK3ACF, VK4BDJ, and W4TV*.
+VK3ACF, VK4BDJ, and W4TV*.  Each of these amateurs has helped to bring
+the program’s design, code, and documentation to its present
+state. 
 
-- Each has helped to bring the program’s design, code, and
+Most of the color palettes for the {wsjtx} waterfall were copied from
-documentation to its present state. Most of the color palettes for the
+the excellent, well documented, open-source program _fldigi_, by *W1HKJ*
-{wsjtx} waterfall were shamelessly copied from the excellent, well
+and friends.
-documented, open-source program fldigi, by W1HKJ and friends.
 

doc/source/app-a-functional-procedures.txt

@@ -1,39 +0,0 @@
-// Status=review
-.Algorithms and Source Code
-
-- For those wishing to study the program’s algorithms and source code,
-perhaps with an eye toward future improvements, the blocks are labeled
-here with the names of functional procedures in the code:
-
-.Block Steps
-[width="80%",cols="<2,60",options="header",valign="middle"]
-|========
-|Block/Step|Functional Procedure
-|sync9:|Use sync symbols to find candidate JT9 signals in the specified frequency range. +
-Then, at the frequency of each plausible candidate
-|downsam9:|Mix, filter and down-sample to 16 complex samples/symbol
-|peakdt9:|Using sync symbols, time-align to start of JT9 symbol sequence
-|afc9:|Measure frequency offset and any possible drift
-|twkfreq:|Remove frequency offset and drift
-|symspec2:|Compute 8-bin spectra for 69 information-carrying symbols, using the +
-time- and frequency-aligned data transform to yield 206 single-bit soft symbols
-|interleave9:|Remove single-bit symbol interleaving imposed at the transmitter
-|decode9:|Retrieve a 72-bit user message using the sequential ``Fano'' algorithm +
-for convolutional codes
-|unpackmsg:|Unpack a human-readable message from the 72-bit compressed format
-|========
-
-:shannonfano: http://en.wikipedia.org/wiki/Shannon%E2%80%93Fano_coding[ Fano Algorithm]
-
-- With marginal or unrecognizable signals the sequential {shannonfano}
-can take exponentially long times to completion.
-
-- If the first step in the above sequence finds many seemingly worthy
-candidate signals, and if many of them turn out to be undecodable, the
-decoding loop could take a very long time.
-
-- For this reason the decode9 step is programmed to “time out” and
-report failure if it takes too long.
-
-- The choice Fast | Normal | Deepest on the Decode menu provides a
-three-step control of this timeout limit.

doc/source/app-a-jt9-mode-table.txt

@@ -1,14 +0,0 @@
-// Status=review
-.JT9-Modes
-[width="80%",cols="<2,^2,^2,^2,^2,^2,^2",options="header",valign="middle"]
-|========
-|Submode|nsps|Symbol Duration (s)|Tone Spacing (Hz)|Signal Bandwidth (Hz)|S/N Threshold* (dB)|QSO Time (min)
-|JT9-1|6912|0.58|1.736|15.6|-27|6
-|JT9-2|15360|1.28|0.781|7.0|-30|12
-|JT9-5|40960|3.41|0.293|2.6|-34|30
-|JT9-10|82944|6.91|0.145|1.3|-37|60
-|JT9-30|252000|21.00|0.048|0.4|-42|180
-|========
-
-NOTE: Noise power measured in 2500 Hz bandwidth.
-

doc/source/app-a-rcv-decode.txt

@@ -1,28 +0,0 @@
-// Status=review
-- {wsjtx} acquires 16-bit integer samples from the sound card at a
-12000 Hz rate.  Spectra from overlapping data segments are computed
-for the waterfall display and saved at intervals of half the JT9
-symbol length.
-
-- As shown in screen shots earlier in this Guide, a *JT9* signal
-appears in the Cumulative spectrum as a nearly rectangular shape about
-16 Hz wide.  Although there is no clearly visible “sync tone” like the
-one in *JT65*, by convention the nominal frequency of a *JT9* signal
-is nevertheless taken to be that of the lowest tone at the left edge
-of the spectrum.
-
-- At the end of a reception sequence, about 50 seconds into the UTC
-minute, received data samples are forwarded to the decoder.  For
-operator convenience the decoder goes through its full procedure
-twice:
-
-* first over a narrow range around the selected Rx frequency
-
-* Then in the full displayed frequency range (or in *JT9+JT65* mode, the
-displayed range above the blue *JT65 nnnn JT9* marker).
-
-- Decoding of clean *JT9* signals in a white-noise background starts
-to fail around signal-to-noise ratio –25 dB and reached the 50% level
-at -26 dB
-
-- Each decoding pass can be described as a sequence of discrete blocks.

doc/source/app-a-transmitting.txt

@@ -1,7 +0,0 @@
-// Status=review
-- Immediately before the start of a transmission {wsjtx} encodes a
-user’s message and computes the sequence of tones to be sent.  The
-transmitted audio waveform is computed on-the-fly, with 16-bit integer
-samples at a 48000 Hz rate.  The digital samples are converted to an
-analog waveform in the sound card or equivalent USB interface.
-

doc/source/app-a.txt

@@ -1,44 +0,0 @@
-// Status=review
-//Needs work!
-.The JT9 Protocol and its Implementation
-
-- *JT9* is a mode designed for making QSOs at HF, MF, and LF.  The
-mode uses essentially the same 72-bit structured messages as *JT65*.
-
-- Error control coding (ECC) uses a strong convolutional code with
-constraint length K=32, rate r=1/2, and a zero tail.  WIth 72-bit
-user messages, this leads to an encoded message length of 
-(72+31) × 2 = 206 bits.
-
-- Modulation is 9-FSK: 8 tone frequencies for data, and one for
-synchronization.  In a given transmission sixteen tone intervals
-(those numbered 1, 2, 5, 10, 16, 23, 33, 35, 51, 52, 55, 60, 66, 73,
-83, and 85 in the sequence) are devoted to synchronization.  Thus, a
-transmission requires a total of (206 / 3) + 16 = 85 (rounded up) tone
-intervals.
-
-- Symbol lengths are chosen so that nsps, the number of samples
-per symbol (at 12000 samples per second) is a number with no prime
-factor greater than 7.  This choice makes for efficient FFTs. Tone
-spacing of the 9-FSK modulation is:
-
------  
-df = 1 / tsym = 12000 / nsps, equal to the keying rate
------
-
-- Symbol durations are approximately (TRperiod - 8) / 85, where
-TRperiod is the T/R sequence length in seconds.
-
-
-- The total occupied bandwidth is 9 × df. The generated signal has
-continuous phase and constant amplitude, so there are no key
-clicks. For experimental purposes, submodes of *JT9* were defined with
-transmission lengths greater than one minute.
-
-- Parameters of all submodes are summarized in the following table,
-along with approximate decoding thresholds measured by simulation on
-an additive white Gaussian noise (AWGN) channel. Numbers following
-*``JT9-''* in the submode names specify the T/R sequence length in
-minutes.  When not otherwise specified in this Guide, *JT9* implies
-submode *JT9-1*, the only submode implemented in current versions of
-{wsjtx}.

doc/source/app-c.txt

@@ -1,35 +0,0 @@
-// Status=review
-.Rig Specific Configuration
-
-- Some rigs work with DTR, RTS, Polling, CaT, PTT while others do
-not. The number of possible combinations is virtually endless.
-
-- The intent of this Appendix is to provide configuration information
-for specific rigs model, e.g. Icom 756 Pro-III, Yaesu FT-1000MP,
-Flex-5000, etc. in order to make Installation & Configuration
-easier. This is a work-in-progress. Some rigs may never be covered,
-but we should try to cover many as possible.
-
-- The table below will link brands (Yaesu, Icom, Kenwood, etc) to
-specific models within each brand. If a model is not available, please
-consider drafting a configuration file (a simple text file), using the
-template provided, and submit it to the development team for inclusion
-to future documentation releases.
-
-:yaesu: link:yaesu.html[Yaesu]
-:rigtemplate: link:rigtemplate.html[Template]
-
-
-NOTE: If your manufacturer is not listed, it means we do not have
-configuration files for any of the models for that particular
-manufacturer.  Please consider using the Rig Template and submit to
-the development team at: {devemail}
-
-.Select Manufacturer
-[align="center",valign="middle",halign="center"]
-|========
-|ADAT|AOR|Alinco|Drake|Electro Craft
-|Kenwood|Icom|SoftRock|Ten-Tec|{YAESU}
-|{rigtemplate}||||
-|========
-

doc/source/configuration-station.txt

@@ -5,7 +5,7 @@ the following information:
 - *Call Sign*: <Your Call Sign>
 - *Grid*: <Your Maidenhead Locator>
 - *PTT method*: choose from RTS, DTR, CAT, VOX, or None.
-- *PTT port*: if you will use RTS or DTR, choose a serial port,
+- *PTT port*: if you will use RTS or DTR, choose a serial port.
 - *PSK Reporter*: check to enable sending reception reports to the
 {pskreporter} mapping facility.
 - *CW ID*: Check to send your callsign in CW after sending 73.

doc/source/install-from-source.txt

@@ -18,8 +18,6 @@ following packages:
 
 The full source code for {wsjtx} can be downloaded with the command:
 
-[source,bash]
+ $ svn co svn://svn.berlios.de/wsjt/branches/wsjtx 
------
+
-$ svn co svn://svn.berlios.de/wsjt/branches/wsjtx 
------
 // Need further compiling Instructions

doc/source/install-mac.txt

@@ -1,6 +1,6 @@
 // Status=review
 
-- Read installation instructions {osx-instructions}.
+- Read the OS X installation instructions {osx-instructions}.
 - Download the required installation package
 * {osx-108}
 * {osx-109} 

doc/source/install-ubuntu.txt

@@ -6,17 +6,12 @@ available at {launchpadurl}
 Archive (PPA) at the above link, execute the following instruction at
 the command prompt:
 
-[source,bash]
+ $ sudo add-apt-repository ppa:jnogatch/wsjtx
------
-$ sudo add-apt-repository ppa:jnogatch/wsjtx
------
-Accept the PPA Key, then:
 
-[source,bash]
+- Accept the PPA Key, then:
------
+
-$ sudo apt-get update 
+ $ sudo apt-get update 
-$ sudo apt-get install wsjtx
+ $ sudo apt-get install wsjtx
------
 
 - Download the soft-decision Reed Solomon decoder {kvasd} and put it
 in the same directory as the executable binaries wsjtx and

doc/source/installed-files.txt

@@ -1,6 +1,8 @@
 // Status=review
-.Files Present After Installation
+After installing {wsjtx} as described in <<X3, Installation>>, the
+following files will be present in the installation directory:
 
+.Files Present After Installation
 [width="60%",cols="2,60",options="header",valign="middle"]
 |========
 |File Name|Description

doc/source/jt65-jt9-differences.txt

@@ -1,41 +1,37 @@
 // Status=review
-//This section needs work!
-- *JT65* is a mature mode described in the literature some years
-ago. Details of the *JT9* protocol are presented in <<X16,Appendix A>>
-of this Guide.
 
-- To users already familiar with *JT65*, the most striking difference
+The JT65 protocol was described in a {jt65protocol} in 2005; details
+of the JT9 protocol are presented in the next section of this Guide.
+To users already familiar with JT65, the most striking difference
 between the two modes is the much smaller occupied bandwidth of JT9:
-15.6 Hz, compared with 177.6 Hz for *JT65A*. Transmissions in the two
+15.6 Hz, compared with 177.6 Hz for JT65A.  Transmissions in the two
 modes are essentially the same length, and both modes use exactly 72
 bits to carry message information.  At the user level the two modes
-support the same message structures.
+support nearly identical message structures.
 
-- *JT65* signal reports are constrained to the range –1 to –30 dB —
+JT65 signal reports are constrained to the range –1 to –30 dB — more
-more than adequate for EME purposes, but not enough dynamic range for
+than adequate for EME purposes, but not enough dynamic range for ideal
-ideal use at HF and below.
+use at HF and below.  S/N values displayed by the JT65 decoder are
+clamped at an upper limit –1 dB, because that’s all the original
+protocol can handle.  Moreover, the S/N scale in present JT65 decoders
+becomes increasingly nonlinear above –10 dB.  By comparison, JT9
+allows for signal reports in the range –50 to +49 dB.  It manages this
+by co-opting a small portion of ``message space'' that would otherwise
+be used for grid locators within 1 degree of the south pole. The S/N
+scale of the present JT9 decoder is reasonably linear (although it’s
+not intended as a precision measurement tool).  With clean signals and
+a clean nose background, JT65 achieves nearly 100% probability of
+correct decoding down to S/N = –22 dB and 50% at –24 dB.  JT9 is about
+2 dB better, achieving 50% decoding at about –26 dB.  Both modes
+produce extremely low false-decode rates.
 
-- S/N values displayed by the *JT65* decoder are clamped at –1 dB,
+Early experience suggests that under most HF propagation conditions
-because that’s all the original protocol can handle; the S/N scale in
+the two modes have comparable reliability.  The tone spacing of JT9 is
-present *JT65* decoders becomes increasingly nonlinear above –10 dB.
+about two-thirds that of JT65, so in some disturbed ionospheric
+conditions in the higher portion of the HF spectrum, JT65 may do
+better. JT9 is an order of magnitude better in spectral efficiency.
+On a busy HF band, we often find the 2-kHz-wide JT65 sub-band filled
+wall-to-wall with signals.  Ten times as many JT9 signals can fit
+into the same frequency range, without overlap.
 
-- By comparison, *JT9* allows for signal reports in the range –50 to
-\+49 dB.  It manages this by co-opting a small amount of message space
-otherwise used for grid locator's within 1 degree of the south
-pole. The S/N scale of the present *JT9* decoder is reasonably linear,
-although it’s not intended as a precision measurement tool. With clean
-signals in a clean nose background, *JT65* achieves nearly 100%
-probability of correct decoding down to S/N = –22 dB and 50% at –24
-dB.  *JT9* is about 2 dB better, achieving 50% decoding at about –26
-dB.  Both modes produce extremely low false-decode rates.
-
-- Early experience suggests that under most HF propagation conditions
-the two modes have comparable reliability, with perhaps a slight edge
-to *JT9*. The tone spacing of *JT9* is about two-thirds that of
-*JT65*, so in some disturbed ionospheric conditions in the higher
-portion of the HF spectrum, *JT65* may do better. *JT9* is an order of
-magnitude better in spectral efficiency. On a busy HF band, we often
-find the 2-kHz-wide *JT65* sub-band filled wall-to-wall with signals.
-Ten times as many JT9 signals could fit into the same space, without
-overlap.
 

doc/source/jt9-protocol.txt

@@ -0,0 +1,96 @@
+// Status=review
+//Needs work!
+.JT9 Protocol and Implementation
+
+JT9 is a mode designed for making minimal QSOs at LF, MF, and HF.  It
+uses 72-bit structured messages that are nearly identical (at the user
+level) to those in JT65.  Error control coding (ECC) uses a strong
+convolutional code with constraint length K=32, rate r=1/2, and a zero
+tail, leading to an encoded message length of (72+31) × 2 = 206
+information-carrying bits.  Modulation is 9-FSK: eight tones are used
+for data, one for synchronization.  Sixteen symbol intervals are
+devoted to synchronization, so a transmission requires a total of 206
+/ 3 + 16 = 85 (rounded up) channel symbols. The sync symbols are
+those numbered 1, 2, 5, 10, 16, 23, 33, 35, 51, 52, 55, 60, 66, 73,
+83, and 85 in the transmitted sequence. 
+
+Each symbol lasts for 6912 sample intervals at 12000 samples per
+second, or about 0.576 s.  Tone spacing of the 9-FSK modulation is
+12000/6912 = 1.736 Hz, the inverse of the symbol duration.  The total
+occupied bandwidth is therefore 9 × 1.736 = 15.6 Hz.  The generated
+JT9 signal has continuous phase and constant amplitude.  There are no
+key clicks, and the transmitter's power amplifier need not be highly
+linear.
+
+.Transmitting
+
+Immediately before the start of a transmission WSJT-X encodes a
+user’s message and computes the sequence of tones to be sent.  The
+transmitted audio waveform is computed on-the-fly, using 16-bit
+integer samples at a 48000 Hz rate.  The digital samples are converted
+to an analog waveform in the sound card (or equivalent D/A interface).
+
+.Receiving and Decoding
+
+WSJT-X acquires 16-bit integer samples from the sound card at a 48000
+Hz rate, and immediately downsamples the data stream to 12000 Hz.
+Spectra from overlapping data segments are computed for the waterfall
+display and saved at intervals of 0.188 s, half the JT9 symbol length.
+As shown in screen shots earlier in this guide, a JT9 signal appears
+in the *Cumulative* spectrum as a nearly rectangular shape about 16 Hz
+wide.  Although there is no clearly visible “sync tone” like the one
+at the low-frequency edge of a JT65 signal, by convention the nominal
+frequency of a JT9 signal is taken to be that of the lowest tone, at
+the left edge of the spectrum.
+
+At the end of a reception sequence, about 50 seconds into the UTC
+minute, received data samples are forwarded to the decoder.  For
+operator convenience the decoder goes through its full procedure
+twice: first at the selected Rx frequency, and then in the full
+displayed frequency range (or in JT9+JT65 mode, the displayed range
+above the blue *JT65 nnnn JT9* marker).  Decoding of clean JT9 signals
+in a white-noise background starts to fail around signal-to-noise
+ratio –25 dB and reaches 50% copy at -26 dB.
+
+Each decoding pass can be described as a sequence of discrete blocks.
+For those wishing to study the program’s algorithms and source code,
+perhaps with an eye toward future improvements, the blocks are labeled
+here with the names of functional procedures in the code.
+
+ sync9:	    Use sync symbols to find candidate JT9 signals 
+            in the specified frequency range
+
+Then, at the frequency of each plausible candidate:
+
+ downsam9:  Mix, filter and downsample to 16 complex 
+            samples/symbol
+
+ peakdt9:   Using sync symbols, time-align to start of JT9 symbol 
+            sequence
+
+ afc9:	    Measure frequency offset and any possible drift
+
+ twkfreq:   Remove frequency offset and drift
+
+ symspec2:  Compute 8-bin spectra for 69 information-carrying
+            symbols, using the time- and frequency-aligned data;
+            transform to yield 206 single-bit soft symbols
+
+ interleave9: Remove single-bit symbol interleaving imposed at the
+	    transmitter
+
+ decode9:   Retrieve a 72-bit user message using the sequential
+            Fano algorithm for convolutional codes
+
+
+ unpackmsg: Unpack a human-readable message from the 72-bit 
+            compressed format
+
+With marginal or unrecognizable signals the sequential Fano algorithm
+can take exponentially long times.  If the first step in the above
+sequence finds many seemingly worthy candidate signals, and if many of
+them turn out to be undecodable, the decoding loop could take a very
+long time.  For this reason the decode9 step is programmed to “time
+out” and report failure if it takes too long.  The choices *Fast |
+Normal | Deepest* on the Decode menu provide a three-step adjustment
+of this timeout limit.

doc/source/rig-configuration.txt

@@ -0,0 +1,33 @@
+// Status=review
+.Rig Specific Configuration
+
+Some rigs work with DTR, RTS, Polling, CAT, and PTT while others do
+not. The number of possible combinations is virtually endless.  The
+intent of this Appendix is to provide configuration information for
+specific rig models, e.g. Icom 756 Pro-III, Kenwood TS-2000, Yaesu
+FT-1000MP, Flex-5000, etc., in order to make installation and
+configuration easier. This is a work-in-progress, and some rigs may
+never be covered.
+
+The table below will link manufacturer names (Icom, Kenwood, Yaesu,
+etc.) to specific models within each brand. If a model is not
+available, please consider drafting a configuration file (a simple
+text file), using the template provided, and submit it to the
+development team for inclusion in future documentation releases.
+
+:yaesu: link:yaesu.html[Yaesu]
+:rigtemplate: link:rigtemplate.html[Template]
+
+NOTE: If your manufacturer is not listed, it means we do not have
+configuration files for any of the models for that particular
+manufacturer.  Please consider using the Rig Template and submit to
+the development team at: {devmail}
+
+.Select Manufacturer
+[align="center",valign="middle",halign="center"]
+|========
+|ADAT|AOR|Alinco|Drake|Electro Craft
+|Kenwood|Icom|SoftRock|Ten-Tec|{YAESU}
+|{rigtemplate}||||
+|========
+

doc/source/runtime-files.txt

@@ -1,11 +1,10 @@
 // Status=review
-.After First Run
 
-- You might be curious about additional files that appear in the WSJTX
+You might be curious about additional files that appear in the WSJTX
-installation directory after using the program for a while. These
+installation directory after using the program. These include the 
-include:
+following:
 
-.Files Created After Running WSJT-X The First Time
+.Files created when running WSJT-X
 [width="60%",cols="2,60",options="header",valign="middle"]
 |========
 |File Name|Description

doc/source/wsjtx-main.txt

@@ -26,7 +26,7 @@
 :osx-108: http://physics.princeton.edu/pulsar/K1JT/wsjtx_3nov13.tar.gz[ OS X 10.6, 10.7, and 10.8 ]
 :osx-109: http://physics.princeton.edu/pulsar/K1JT/wsjtx_10.9_29nov13.tar.gz[OS X 10.9]
 :pskreporter: http://pskreporter.info/pskmap.html[PSK Reporter]
-
+:jt65protocol: http://physics.princeton.edu/pulsar/K1JT/JT65.pdf[QEX article]
 
 // These [[X?]] numbers are HTML anchors, and can be used to
 // navigate though the document easily: <<[X1],See Introduction]>> will
@@ -159,49 +159,29 @@ include::controls-functions-kb-shortcuts.txt[]
 === Mouse Commands
 include::controls-functions-special-mouse-cmds.txt[]
 
-[[X9]]
+[[X8]]
 == JT65 & JT9 Differences
 include::jt65-jt9-differences.txt[]
 
+[[X9]]
+== The JT9 Protocol
+include::jt9-protocol.txt[]
+
 [[XA10]]
 == Appendix A
-include::app-a.txt[]
 
+// Note to Dev-Team, this list of files needs to be updated.
 [[XA11]]
-=== JT9 Mode Table
+=== Installed Files
-include::app-a-jt9-mode-table.txt[]
+include::installed-files.txt[]
 
 [[XA12]]
-=== Transmitting
+=== Runtime Files
-include::app-a-transmitting.txt[]
+include::runtime-files.txt[]
-
-[[XA13]]
-=== Receiving & Decoding
-include::app-a-rcv-decode.txt[]
-
-[[XA14]]
-=== Functional Procedures
-include::app-a-functional-procedures.txt[]
 
 [[XB10]]
 == Appendix B
-.Installed Files
+include::rig-configuration.txt[]
-
-- After installing {wsjtx} as described in <<X3, Installation>>, the
-following files will be present in the installation directory:
-
-// Note to Dev-Team, this list of files needs to be updated.
-[[XB11]]
-=== Installed Files
-include::app-b-installed-files.txt[]
-
-[[XB12]]
-=== Runtime Files
-include::app-b-runtime-files.txt[]
-
-[[XC10]]
-== Appendix C
-include::app-c.txt[]
 
 [[XACK10]]
 == Acknowledgments

wsjtx.iss

@@ -1,6 +1,6 @@
 [Setup]
 AppName=wsjtx
-AppVerName=wsjtx Version 1.2.2 r3620
+AppVerName=wsjtx Version 1.2.2 r3644
 AppCopyright=Copyright (C) 2001-2014 by Joe Taylor, K1JT
 DefaultDirName=c:\wsjtx1.2
 DefaultGroupName=wsjtx1.2