Merge branch 'release-2.5.0' of bitbucket.org:k1jt/wsjtx into release-2.5.0

doc/CMakeLists.txt

@@ -53,7 +53,7 @@ set (UG_SRCS
   tutorial-example4.adoc
   tutorial-example5.adoc
   tutorial-example6.adoc
-  tutorial-main-window.adoc
+  tutorial-download-samples.adoc
   tutorial-wide-graph-settings.adoc
   utilities.adoc
   vhf-features.adoc

doc/user_guide/en/settings-radio.adoc

@@ -39,7 +39,7 @@ image::RadioTab.png[align="center",alt="Radio Tab"]
 +
 
 NOTE: A special value of *USB* is available for custom USB devices
-      like those used by some SDR kits. This is not the same a virtual
+      like those used by some SDR kits. This is not the same as the virtual
       serial port provided by USB connected transceivers and CAT
       interfaces, for those use the COM or serial port name that
       refers to them.

doc/user_guide/en/tutorial-download-samples.adoc

@@ -0,0 +1,16 @@
+// Status=review
+
+[[DOWNLOAD_SAMPLES]]
+=== Download Samples
+
+The following steps will download sample audio Wave files that were originally recorded
+by WSJT-X. These files can be read in and processed by WSJT-X to simulate realtime 
+operation. 
+ 
+- Select *Download samples...* from the *Help* menu.
+
+- Download some or all of the available sample files using checkboxes
+on the screen shown below.  For this tutorial you will need at least
+the FT8 files.
+
+image::download_samples.png[width=400,align="center",alt="Download Samples"]

doc/user_guide/en/tutorial-example3.adoc

@@ -1,27 +1,91 @@
 // Status=review
 .Main Window:
-- Select *FT8* on the *Mode* menu.
+- Click the *Stop* button on the main window to halt any data acquisition.  
+- Select *FT8* from the *Mode* menu and *Deep* from the *Decode* menu.
 - Double-click on *Erase* to clear both text windows.
 
-.Wide Graph Settings:
-
-- *Bins/Pixel* = 5, *Start* = 100 Hz, *N Avg* = 2
-- Adjust the width of the Wide Graph window so that the upper
-frequency limit is approximately 3300 Hz.
-
 .Open a Wave File:
 
 - Select *File | Open* and navigate to
-+...\save\samples\FT8\181201_180245.wav+.  The waterfall and Band
-Activity window should look something like the following screen shots.
-(This recording was made during the "FT8 Roundup" contest, so most
-transmissions happen to be using *RTTY Roundup* message formats.)
++...\save\samples\FT8\210703_133430.wav+.  The waterfall and Band
+Activity/Rx Frequency windows should look something like the following screen shots:
+
+- You may want to pretend you are K1JT
+by entering that callsign temporarily as *My Call* on the 
+*Settings | General* tab.  Your results should then be identical to
+those shown in the screen shot below. Don't forget to change *My Call*
+back to your own call when you are done!
 
 [[X15]]
-image::FT8_waterfall.png[align="left",alt="Wide Graph Decode 170709_135615"]
+image::FT8_waterfall.png[align="left",alt="Wide Graph Decode 210703_133430"]
 
 image::ft8_decodes.png[align="left"]
 
+
+.Decoding Overview
+
+Decoding takes place at the end of a receive sequence. With *Decode* set
+to *Deep*, three decoding passes will be done and the *Decode* button on the 
+mainwindow will illuminate three times, once for each pass. 
+The first decoding attempt in each decoding pass is done at the selected Rx frequency,
+indicated by the U-shaped green marker on the waterfall frequency
+scale. All decodes appear in the left (*Band Activity*) window. The right
+(*Rx Frequency*) text window displays any decodes obtained at the current
+Rx frequency along with any decodes addressed to *My Call* (K1JT in this case).
+The red marker on the waterfall scale indicates your
+Tx frequency.
+
+Twenty one FT8 signals are decoded from the example file. The number
+of decodes is shown in a box at the bottom of the main window.
+When this file was recorded HA5WA was finishing a QSO with K1JT, and
+his 73 message is shown in red because it is addressed to *My Call* (in this case K1JT). 
+By default, lines containing `CQ`
+are highlighted in green, and lines with *My Call* (K1JT)
+in red. Notice that K1JT has two callers; HA0DU and EA3AGB.  
+
+[[X13]]
+.Decoding Controls
+
+To gain some feeling for controls frequently used when making QSOs,
+try double-clicking with the mouse on the decoded text lines and on the
+waterfall spectral display. You should be able to confirm the
+following behavior:
+
+- Double-click on one of the decoded *CQ* messages highlighted in
+green. These actions produce the following results:
+
+** Callsign and locator of the station calling CQ are copied to the *DX
+Call* and *DX Grid* entry fields. 
+
+** Messages are generated for a standard minimal QSO.
+
+** The *Tx even* box is checked or cleared appropriately, so that you
+will transmit in the proper (odd or even) minutes.
+
+** The Rx frequency marker is moved to the frequency of the CQing
+station.
+
+** You can modify the double-click behavior by holding down the
+*Shift* key to move only the Tx frequency or the *Ctrl* key to move
+both Rx and Tx frequencies.
+
+** In addition, if *Double-click on call sets Tx enable* is checked on the 
+*Settings | General* tab then *Enable Tx* will be activated
+so that a transmission will start automatically at the proper time.
+
+
++
+
+NOTE: You can prevent your Tx frequency from being changed by checking the
+box *Hold Tx Freq*.
+
+- Double-click on the decoded message `K1JT HA0DU KN07`, highlighted
+in red.  Results will be similar to those in the previous step. The Tx
+frequency (red marker) is not moved unless *Shift* or *Ctrl* is held
+down.  Messages highlighted in red are usually in response to your own
+CQ or from a tail-ender, and you probably want your Tx frequency to
+stay where it was.
+
 - Click with the mouse anywhere on the waterfall display. The green Rx
 frequency marker will jump to your selected frequency, and the Rx
 frequency control on the main window will be updated accordingly.
@@ -38,11 +102,12 @@ things just described and also invokes the decoder in a small range
 around the Rx frequency.  To decode a particular signal, double-click
 near the left edge of its waterfall trace.
 
-- Now double-click on any of the lines of decoded text in the Band
-Activity window.  Any line will show the same behavior, setting
-Rx frequency to that of the selected message and leaving Tx frequency
-unchanged.  To change both Rx and Tx frequencies, hold *Ctrl* down
-when double-clicking.
+- Ctrl-double-click on a signal to set both Rx and Tx frequencies and
+decode at the new frequency.
+
+- Click *Erase* to clear the right window. 
+
+- Double-click *Erase* to clear both text windows.
 
 TIP: To avoid QRM from competing callers, it is usually best 
 to answer a CQ on a different frequency from that of the CQing
@@ -53,6 +118,11 @@ box *Hold Tx Freq*.
 TIP: Keyboard shortcuts *Shift+F11* and *Shift+F12* provide an easy
 way to move your Tx frequency down or up in 60 Hz steps.
 
+TIP: Sliders and spinner controls respond to *Arrow* key presses
+and *Page Up/Down* key presses, with the *Page* keys moving the
+controls in larger steps.  You can also type numbers directly into
+the spinner controls or use the mouse wheel.
+
 TIP: An online {ft8_tips} by ZL2IFB offers many additional tips on
 operating procedures.
 

doc/user_guide/en/tutorial-main-window.adoc

@@ -1,25 +0,0 @@
-// Status=review
-
-- Click the *Stop* button on the main window to halt any data acquisition.  
-
-- Select *JT9* from the *Mode* menu and *Deep* from the *Decode* menu.
-
-- Set the audio frequencies to *Tx 1224 Hz* and *Rx 1224 Hz*.  
-
-+
-
-TIP: Sliders and spinner controls respond to *Arrow* key presses
-and *Page Up/Down* key presses, with the *Page* keys moving the
-controls in larger steps.  You can also type numbers directly into
-the spinner controls or use the mouse wheel.
-
-[[DOWNLOAD_SAMPLES]]
-=== Download Samples
-
-- Select *Download samples...* from the *Help* menu.
-
-- Download some or all of the available sample files using checkboxes
-on the screen shown below.  For this tutorial you will need at least
-the JT9 files.
-
-image::download_samples.png[align="center",alt="Downlod Samples"]

doc/user_guide/en/tutorial-wide-graph-settings.adoc

@@ -1,13 +1,46 @@
 // Status=review
 
-- *Bins/Pixel* = 4
-- *Start* = 200 Hz
-- *N Avg* = 5
-- *Palette* = Digipan
-- *Flatten* = checked
-- Select *Cumulative* for data display
-- *Gain* and *Zero* sliders for waterfall and spectrum set near midscale
-- *Spec* = 25%
+The WSJT-X Wide Graph window displays the frequency spectrum of the received audio. Usually, the 
+upper portion of the window shows a waterfall plot of the frequency spectrum (a spectrogram) and 
+a line plot of the current or average spectrum. Controls at the bottom of the window are used to 
+set up the displayed audio frequency range, color palette, and scaling of the spectrum displays. 
+A control on the bottom right of the Wide Graph (displayed as *Spec nn%*) allows the user to control
+the vertical fraction of the window that is occupied by the spectrum line plot.
+It is important to set appropriate lower and upper 
+audio frequency limits for the Wide Graph because these limits define the FT8 decoder's search window.
+For this tutorial, the limits will be set to cover 100-3300 Hz:
 
+- Set *Start* = 100 Hz.
+- Set *Bins/Pixel* = 5. Smaller/larger values make the Wide Graph cover a smaller/larger 
+frequency range.
 - Use the mouse to grab the left or right edge of the *Wide Graph*, and
-adjust its width so that the upper frequency limit is about 2400 Hz.
+adjust its width so that the upper frequency limit is about 3300 Hz.
+
+The *N Avg* setting controls how many spectra are averaged to produce each line in the spectrogram. 
+Smaller values make the spectrogram update more frequently, resulting in signals being more spread
+out in the vertical (time) direction.
+On the other hand, larger values make it easier to detect very weak signals:
+
+- Set *N Avg* = 2. 
+
+The *Palette* setting controls the color scheme used for the spectrogram: 
+
+- Set *Palette* = Fldigi 
+
+When *Flatten* is checked, WSJT-X attempts to correct for rolloff at the lowest and highest
+frequencies in the spectrum: 
+
+- *Flatten* = checked 
+
+The line plot can be set up to display the current (un-averaged) spectrum or the cumulative (averaged)
+spectrum:
+
+- Select *Cumulative* for data display
+- Set the *Gain* and *Zero* sliders for the waterfall and spectrum to near midscale
+
+The *Spec nn%* setting determines what fraction of the vertical extent of the Wide Graph will
+be used for the line plot of the spectrum. Setting *Spec* to 0 will eliminate the line plot and
+a setting of 100 will eliminate the spectrogram and show only the line plot:
+
+- Set *Spec* = 50% 
+

doc/user_guide/en/wsjtx-main.adoc

@@ -141,27 +141,20 @@ include::transceiver-setup.adoc[]
 == Basic Operating Tutorial
 
 This section introduces the basic user controls and program behavior
-of _WSJT-X_, with particular emphasis on the JT9, JT65, and FT8 modes.
+of _WSJT-X_, with particular emphasis on the FT8 mode.
 We suggest that new users should go through the full HF-oriented
-tutorial, preferably while at your radio.  Note that as of late 2018,
-digital usage on the HF bands has mostly moved from JT65 and JT9 to FT8.  So
-you may wish to pay particular attention to *FT8*, in Section 6.6.
+tutorial, preferably while at your radio.  
 
 Subsequent sections cover additional details on <<MAKE_QSOS,Making
 QSOs>>, <<WSPR,WSPR mode>> and <<VHF_AND_UP,VHF+ Features>>.
 
-[[TUT_MAIN]]
-=== Main Window Settings
-include::tutorial-main-window.adoc[]
+[[TUT_SAMPLES]]
+include::tutorial-download-samples.adoc[]
 
 [[TUT_WIDE_GRAPH]]
 === Wide Graph Settings
 include::tutorial-wide-graph-settings.adoc[]
 
-[[TUT_EX1]]
-=== JT9
-include::tutorial-example1.adoc[]
-
 [[TUT_EX3]]
 === FT8
 include::tutorial-example3.adoc[]