Split the asciidoc source for WSJT-X User's Guide into many

smaller files, by section and sub-section.  

Also extensive editing up through section 7.  Sections 6.2, 8, and
beyond definitely need work.  Other polishing is also desirable, and
maybe also some additions and/or changes.



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

doc/build-doc.sh

@@ -1,48 +1,115 @@
 #!/usr/bin/env bash
-#
-# Part of the wsjtx-doc project
-# Builds all *.txt files found in $(PWD)/source
+# Title           : build-doc.sh
+# Description     : WSJT-X Documentation build script
+# Author          : KI7MT
+# Email           : ki7mt@yahoo.com
+# Date            : JAN-21-2014
+# Version         : 0.2
+# Usage           : ./build-doc.sh [ option ]
+# Notes           : requires asciidoc, source-highlight
+#==============================================================================
 
-# exit on any error
+# exit on error
 set -e
 
-# set script path's
+#add some color
+red='\033[01;31m'
+green='\033[01;32m'
+yellow='\033[01;33m'
+cyan='\033[01;36m'
+no_col='\033[01;37m'
+
+# misc var's
 base_dir=$(pwd)
 src_dir="$base_dir/source"
-style_dir="$base_dir/style"
-log_dir="$base_dir/logs"
-
-# style sheet selection
-main_style=asciidoc.css
-toc2_style=toc2.css
-
-# This is temporary. Final version will loop through a directory of files
 c_asciidoc="asciidoc -b xhtml11 -a max-width=1024px"    
+script_name=$(basename $0)
+doc_version="1.2.2"
+
+
+# build functions
+function build_no_toc() { # no toc
+    echo -e ${yellow}'Building Without TOC'${no_col}
+    $c_asciidoc -o wsjtx-main.html $src_dir/wsjtx-main.txt
+    echo -e ${green}'. Finished wsjtx-main.html'${no_col}
+}
+
+function build_toc1() { # top toc
+    echo -e ${yellow}'Building with Top TOC'${no_col}
+    $c_asciidoc -a toc -o wsjtx-main-toc1.html $src_dir/wsjtx-main.txt
+    echo -e ${green}'. Finished wsjtx-main-toc1.html'${no_col}
+}
+
+function build_toc2() { # left toc
+    echo -e ${yellow}'Building with Left TOC'${no_col}
+    $c_asciidoc -a toc2 -o wsjtx-main-toc2.html $src_dir/wsjtx-main.txt
+    echo -e ${green}'. Finished wsjtx-main-toc2.html'${no_col}
+}
+
+# start the main script
 clear
-echo Building Main Page HTML
-echo .. Main Page Without TOC
-$c_asciidoc -o wsjtx-main.html ${src_dir}/wsjtx-main.txt
-echo .. Done
+# Hard coded version info to build outside of source tree.
+echo -e ${yellow}"*** Building WSJT-X User Guide for:" ${cyan}$doc_version${no_col}${yellow}" ***\n" ${no_col}
 
-echo .. Main Page With TOC
-$c_asciidoc -a toc -o wsjtx-main-toc.html ${src_dir}/wsjtx-main.txt
-echo .. Done
+# without TOC
+if [[ $1 = "" ]]
+  then
+    build_no_toc
 
-echo .. Main Page With TOC2
-$c_asciidoc -a toc2 -o wsjtx-main-toc2.html ${src_dir}/wsjtx-main.txt
-echo .. Done
+# top TOC
+elif [[ $1 = "toc1" ]]
+  then
+    build_toc1
 
-echo Building Rig Configuration Sheets
-echo Building Yaesu
-$c_asciidoc -o yaesu.html ${src_dir}/yaesu.txt
-echo .. Done
+# left TOC
+elif [[ $1 = "toc2" ]]
+  then
+  build_toc2
 
-echo Building regtemplate
-$c_asciidoc -o rigtemplate.html ${src_dir}/rigtemplate.txt
-echo Done
-echo
-echo All HTML docs have been saved to "$base_dir"
+# all toc versions
+elif [[ $1 = "all" ]]
+  then
+    echo -e ${yellow}'Building all TOC versions'${no_col}
+    echo
+    build_no_toc
+    echo
+    build_toc1
+    echo
+    build_toc2
 
+# if something other than "", toc1, toc2 or all is entered as $1 display usage
+# message and exit. this should be re-written to redirect the user to select
+# 1 of 4 proper options v.s. exiting.
+else
+    clear
+    echo -e ${red}" * INPUT ERROR *\n"${no_col}
+    echo 'Script Usage: build-doc.sh [ option ]'
+    echo
+    echo 'For with No TOC: ' ./$script_name
+    echo 'For with Top TOC: './$script_name 'toc1'
+    echo 'For with Left TOC: './$script_name 'toc2'
+    echo 'For All Versions: ' ./$script_name 'all'
+    echo
+    echo Please re-enter using the examples above.
+    echo
+    exit 1
+fi
+
+# build the rig template page
+  echo
+  echo -e ${yellow}'Building Rig Template'${no_col}
+  $c_asciidoc -o rigtemplate.html $src_dir/rigtemplate.txt
+  echo -e ${green}'. Finished'${no_col}
+ 
+# build the rig sheets
+# this section will should be modified to loop through rig template(s) either by
+# name or directory ./rig/rig_* could be used.
+  echo
+  echo -e ${yellow}'Building Rig Configuration Sheets'${no_col}
+  $c_asciidoc -o yaesu.html $src_dir/yaesu.txt
+  echo -e ${green}'. Finished'${no_col}
+  echo
+  echo -e ${yellow}'All HTML files have been saved to:'${no_col}${cyan} "$base_dir" ${no_col}
+  echo
 exit 0
 
-

doc/source/acknowledgements.txt

@@ -0,0 +1,17 @@
+// Status=review
+- 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
+License (GPL).
+
+- For {wsjtx} in particular, I wish to acknowledge contributions from:
+*AC6SL, AE4JY, DJ0OT, G4KLA, G4WJS, K3WYC, KA6MAL, KA9Q, KK1D, PY2SDR,
+VK3ACF, VK4BDJ, and W4TV*.
+
+- Each has helped to bring the program’s design, code, and
+documentation to its present state. Most of the color palettes for the
+{wsjtx} waterfall were shamelessly copied from the excellent, well
+documented, open-source program fldigi, by W1HKJ and friends.
+

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

@@ -0,0 +1,39 @@
+// 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

@@ -0,0 +1,14 @@
+// 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

@@ -0,0 +1,28 @@
+// 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

@@ -0,0 +1,7 @@
+// 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

@@ -0,0 +1,44 @@
+// 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-b-installed-files.txt

@@ -0,0 +1,47 @@
+// Status=review
+.Files Present After Installation
+
+[width="60%",cols="2,60",options="header",valign="middle"]
+|========
+|File Name|Description
+|afmhot.dat|Data for AFMHot palette
+|blue.dat|Data for Blue palette
+|CALL3.TXT|Callsign database
+|hamlib-alinco.dll|Hamlib, Alinco libraries
+|hamlib-amsat.dll|Hamlib, Asmat libraries
+|kamlib-dummy.dll|Hamlib, Dummy Kam libraries 
+|hamlib-flexradio.dll|Hamlib, Flex Radio libraries
+|hamlib-icom.dll|Hamkib, Icom libraries
+|hamlib-jrc.dll|Hamlib, JRC libraries
+|hamlib-kachina.dll|Hamlib, Kachina libraries
+|hamlib-kenwood.dll|Hamlib, Kenwood libraries
+|hamlib-kit.dll|Hamlib, Kit libraries
+|hamlib-tapr.dll|Hamlib, Tapr libraries
+|hamlib-tentec.dll|Hamlib, TenTec libraries
+|hamlib-winradio.dll|Hamlib, WinRadio libraries
+|hamlib-yaesu.dll|Hamlib, Yaesu libraries
+|HRDInterface001.dll|Ham Radio Deluxe interface library
+|jt9.exe|Executable for JT9 decoder
+|jt9code.exe|Test program to illustrate JT9 encoding
+|kvasd.dat|Data for Koetter-Vardy decoder
+|kvasd.exe|Executable Koetter-Vardy decoder
+|libfftw3f-3.dll|Optimized FFT library
+|libgcc_s_dw2-1.dll|gcc runtime
+|libhamlib-2.dll|Hamlib, Base library
+|libstdc\+\+-6.dll|Standard C function library
+|libusb0.dll|USB interface functions
+|mingwm10.dll|MinGW library
+|mouse_commands.txt|Special mouse commands
+|palir-02.dll|Linrad functions
+|PSKReporter.dll|Library for PSK reporter
+|QtCore4.dll|QtCore libraries
+|QtGui4.dll|QtGui4 libraries
+|QtNetwork4.dll|QtNetwork4 libraries		
+|save|Directory for saved .wav files
+|shortcuts.txt|Keyboard shortcuts
+|unins000.dat|Uninstall Data File
+|unins000.exe|Executable for uninstalling {wsjtx}
+|wsjt.ico|WSJT icon
+|wsjtx.exe|Executable for {wsjtx}
+|========
+

doc/source/app-b-runtime-files.txt

@@ -0,0 +1,18 @@
+// Status=review
+.After First Run
+
+- You might be curious about additional files that appear in the WSJTX
+installation directory after using the program for a while. These
+include:
+
+.Files Created After Running WSJT-X The First Time
+[width="60%",cols="2,60",options="header",valign="middle"]
+|========
+|File Name|Description
+|ALL.TXT|Log of all received and transmitted messages
+|decoded.txt|Decoded text from the most recent Rx interval
+|timer.out|Diagnostic information for decoder optimization
+|wsjtx.ini|Saved configuration parameters
+|wsjtx_log.adi|ADIF log 
+|wsjtx_status.txt|Information sent to companion program JT-Alert
+|========

doc/source/app-c.txt

@@ -0,0 +1,35 @@
+// 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-band-settings.txt

@@ -0,0 +1,6 @@
+// Status=review
+
+The Band Settings tab allows you to set the default frequency and a
+brief description of your antenna for each amateur band.  The antenna
+information will be included with reception reports, if they have been
+enabled.

doc/source/configuration-main-window.txt

@@ -0,0 +1,20 @@
+// Status=review
+To set the proper level of audio drive from {wsjtx} to your radio:
+
+* Click the Tune button on the main screen.{wsjtx} should set the
+radio into transmit mode and generate a steady audio tone at the 
+amplitude that will be used for a generated JT9 signal.
+
+* Listen to the generated audio tone using your radio’s Monitor
+facility. The tone should be perfectly smooth, with no clicks or
+glitches.
+
+* Open the computer’s audio mixer controls for output (“playback”)
+devices and adjust the volume slider downward from 100% until the RF
+output from your transmitter falls by around ten percent.  This will
+be a good level for audio drive.
+
+* Alternatively, you can make the same adjustment using the digital
+slider labeled *Pwr* at the right edge of the main window.
+
+* Toggle the Tune button once more to stop your test transmission. 

doc/source/configuration-station.txt

@@ -0,0 +1,68 @@
+// Status=review
+Start {wsjtx} and Select Configuration from its Setup menu.  Enter
+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,
+- *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.
+- *CW Interval*: set the time interval for sending your CW identification. 
+Default is 0 (never).
+
+{wsjtx} does not implement full transceiver control, but it provides a
+way to ensure that {wsjtx} can read and set the radio’s dial
+frequency. If you want this capability:
+
+- Check the box Enable CAT
+- Select your radio type from a drop-down list
+- Select a CAT port (not the same port selected for PTT control)
+- Set port parameters for your radio
+- If you use {dxlcommander} by DX Lab or {hrd} to control your
+transceiver, you can configure {wsjtx} to communicate with the radio
+through that program.  Entries for these programs appear at the end of
+the drop-down list of supported radios.
+
+[[X11]]
+image::images/r3563-config-screen-80.png[align="center",alt="Configuration Screen"]
+
+For now you should leave *Split Tx* unchecked. If you are using CAT
+control, most radios will allow you to set *PTT method* = CAT.  Some
+radios support two types of PTT assertion via CAT control: one takes
+audio input from the Mic connector, the other from a rear-panel Data
+connector.  The simplest CAT configuration sets *Polling interval* = 0
+(no polling the radio for dial frequency).  {wsjtx} will then be able
+to set the radio’s frequency, but the program will be unaware of
+subsequent changes made using the radio’s panel controls.
+
+TIP: If you need an additional item in the list of devices for the
+CAT port, edit the configuration file wsjtx.ini and add your
+requirement as CATdriver=yourdriver (for example, 
+CATdriver=/dev/ttyUSBserial ) in the group of entries marked
+[Common].
+
+With most radios you can set *Polling interval* to a small number (say
+1 – 3 s) and the program will follow any frequency changes made at the
+radio.  Note that you may not be able simultaneously to control your
+radio from {wsjtx} and from another program.  Some experimentation may
+be required, and you may need to refer to the documentation for your
+rig-control software and your radio.  It is best to have the radio and
+any interface equipment turned on and connected before starting
+{wsjtx}, and to exit the program before turning your equipment off.
+
+- Click the *Test CAT Control* and Test PTT buttons to see that you
+have established the desired control of station functions.  _ Select
+the devices you will use for Audio input and output.
+- Click OK to dismiss the Configuration window.
+
+- {wsjtx} expects your sound card to do its raw sampling at 48000 Hz.
+To ensure that this will be so when running under recent versions of
+Windows, open the system's Sound control panel and select in turn the
+“Recording” and “Playback” options.  Click on Properties, then
+Advanced, and select “16 bit, 48000 Hz (DVD Quality).”
+
+CAUTION: If you are using a sound card that is also the default device
+for Windows sounds, be sure to turn off all such sounds so they are
+not transmitted over the air.

doc/source/configuration-txmacros.txt

@@ -0,0 +1,7 @@
+// Status=review
+TX Macros are an aid for sending commonly used free-text messages.
+To enable a pull-down selection, add your custom messages to the entry
+fields provided.  Remember that the maximum free-text message length
+is 13 characters.  You access your macros by selecting Tx message #5
+(or the Free MSG Radio Button) on the main window, then right-click to
+select the message to be sent.

doc/source/controls-functions-center.txt

@@ -0,0 +1,30 @@
+// Status=review
+At the center of the main window are a number of controls you will
+use when making QSOs:
+
+//.Misc Controls Center
+image::images/misc-controls-center.png[align="left",alt="Misc Controls Center"]
+
+* Select *Tx even* to transmit in even-numbered UTC minutes.  Uncheck
+this box to transmit in the odd intervals.  This selection is made
+automatically when you double-click on a decoded text line as
+described in the Basic Operating Tutorial, Sections 5.1 thru 5.8.
+
+* Your audio Tx and Rx frequencies are displayed and can be adjusted
+with spinner controls. These settings are usually handled
+automatically by the double-click procedure.
+
+* The on-the-air frequency of your lowest JT9 or JT65 tone is the sum
+of dial and audio frequencies.  You can force Tx frequency to the
+current Rx frequency by clicking the *Tx=Rx* button, and vice-versa
+for *Rx=Tx*.  Check the box *Lock Tx=Rx* to make the frequencies
+always track one another.
+
+* The *Report* control lets you change a signal report that has been
+inserted automatically. Most reports will fall in the range –26 to
+\+10 dB.  Remember that JT65 reports cannot be greater than -1 dB.
+
+IMPORTANT: When signals are close to or above 0 dB, you and your QSO
+partner should probably reduce power. JT65 and JT9 are supposed to be
+weak signal modes!
+

doc/source/controls-functions-kb-shortcuts.txt

@@ -0,0 +1,36 @@
+// Status=review
+The following keyboard shortcuts give quick access to some
+frequently used program functions.
+
+//.Keyboard Shortcuts
+[width="70%",cols="2,30",options="header",align="center"]
+|=====
+|Key|Action Performed
+|F1|Display online User's Guide in browser
+|Ctrl+F1|About WSJT-X
+|F2|Open the Setup >> Configuration window
+|F3|Display keyboard shortcuts
+|F4|Clear Dx Call and Dx Grid entries
+|Alt+F4|Exit program
+|F5|Display special mouse commands
+|F6|Open next file in directory
+|Shift+F6|Decode all remaining files in directory
+|F11|Move Rx frequency down 1 Hz
+|Ctrl+F11|Move Rx and Tx frequencies down 1 Hz
+|F12|Move Rx frequency up 1 Hz
+|Ctrl+F12|Move Rx and Tx frequencies up 1 Hz
+|Alt+1-6|Set next transmission to this number on Tab 1
+|Alt+D|Decode again at Rx frequency
+|Shift+D|Full decode (both windows)
+|Alt+E|Erase
+|Ctrl+F|Edit the free text message box
+|Alt+G|Generate standard messages
+|Alt+H|Halt Tx
+|Ctrl+L|Lookup callsign in database, generate standard messages
+|Alt M|Monitor
+|Alt+N|Enable Tx
+|Alt+Q|Log QSO
+|Alt+S|Stop monitoring
+|Alt+T|Tune
+|Alt+V|Save the most recently completed `*.wav'' file
+|=====

doc/source/controls-functions-left.txt

@@ -0,0 +1,25 @@
+// Status=review
+
+Controls related to: *date*, *time*, *frequency*, *Rx Audio Level*,
+and the *Station Being Worked* are found at lower left of the main
+window:
+
+//.Misc Controls Left
+image::images/misc-main-ui.png[align="center",alt="Mist Menu Items"]
+
+* The drop-down *Band* selector at upper left lets you select the
+operating band and sets dial frequency to a default value taken from
+the *Default Frequencies* tab on the *Setup | Configuration* screen.
+
+* If you are using CAT control, a small colored square appears in
+green if the CAT control is two-way between {wsjtx} and your radio, or
+orange if the control is only from program to radio.  You can request
+a one-time interrogation of the radio’s dial frequency by clicking on
+the orange square. The square becomes red if you have requested CAT
+control but communication with the radio has been lost.  If the 
+*Dx Grid* is known, the great-circle azimuth and distance are given.
+
+* The program can keep a database of call-signs and locators for
+future reference.  Click *Add* to insert the present call and locator in
+the database; click *Lookup* to retrieve the locator for a previously
+stored call.

doc/source/controls-functions-main-window.txt

@@ -0,0 +1,44 @@
+// Status=review
+The following buttons appear just under the decoded text windows on
+the main screen:
+
+//.Main UI Controls
+image::images/main-ui-controls.png[align="left",alt="Main UI Controls"]
+
+* *Log QSO* pops up a confirmation screen pre-filled with known
+information about a QSO you have nearly completed.  You can edit or
+add to this information before clicking OK to log the QSO.  If you
+select ``Prompt me to log QSO'' on the Setup menu, the program will
+pop up the confirmation screen automatically when you send a ``73'' or
+free-text message.
+
+//.Log QSO Window
+image::images/log-qso.png[align="center",alt="Log QSO"]
+
+* *Stop* will stop normal data acquisition in case you want to open
+and explore previously recorded audio files.
+
+* *Monitor* restarts normal receive operation.  This button is
+highlighted in green when the program is receiving.
+
+* *Decode* tells the program to repeat the decoding procedure at the
+Rx frequency (green marker on waterfall), using the most recently
+completed sequence of Rx data.
+
+* *Erase* clears the right (Rx frequency) window. Double-clicking
+Erase clears both text windows.
+
+* *Tune* may be used to switch into Tx mode and generate an
+unmodulated carrier at the specified Tx frequency (red marker on
+waterfall).  This process may be seful for adjusting an antenna tuner,
+for example, toggle the button a second time to terminate the Tune
+process.
+
+* *Enable Tx* puts the program into automatic Rx/Tx sequencing mode
+and highlights the button in red.  A transmission will start at the
+beginning of the selected (odd or even) sequence, or immediately if
+appropriate.
+
+* *Halt Tx* terminates a transmission in progress and disables
+automatic Rx/Tx sequencing.
+

doc/source/controls-functions-menus.txt

@@ -0,0 +1,38 @@
+// Status=review
+
+Program menus offer many options for configuration and operation.
+You should explore them and test the resulting program actions.
+
+[[X771]]
+==== File menu
+//.File Menu
+image::images/file-menu.png[align="left",alt="File Menu"]
+[[X772]]
+==== Setup Menu
+//.Setup Menu
+image::images/setup-menu.png[align="left",alt="Setup Menu"]
+
+[[X773]]
+==== View Menu
+//.View Menu
+image::images/view-menu.png[align="left",alt="View Menu"]
+
+[[X774]]
+==== Mode Menu
+//.Mode Menu
+image::images/mode-menu.png[align="left",alt="Mode Menu"]
+
+[[X775]]
+==== Decode Menu
+//.Decode Menu
+image::images/decode-menu.png[align="left",alt="Decode Menu"]
+
+[[X776]]
+==== Save Menu
+//.Save Menu
+image::images/save-menu.png[align="left",alt="Save Menu"]
+
+[[X777]]
+==== Help Menu
+//.Help Menu
+image::images/help-menu.png[align="left",alt="Help Menu"]

doc/source/controls-functions-messages.txt

@@ -0,0 +1,45 @@
+// Status=review
+Two configurations of controls are provided for generating and
+selecting Tx messages.
+
+Traditional controls (carried over from program WSJT) appear on *Tab
+1* and provide six fields for message entry.  Pre-formatted messages
+for the standard minimal QSO are generated when you click *Generate
+Std Msgs* or when you double-click on an appropriate line of decoded
+text.
+
+//.Traditional Message Menu
+image::images/traditional-msg-box.png[align="center",alt="Traditional Message Menu"]
+
+* Select the next message to be transmitted (at the start of your next
+Tx sequence) by clicking on the circle under *Next*.
+
+* To change to a specified Tx message immediately, click on a
+rectangular button (e.g., Tx 3) under the *Now* label.  Changing Tx
+messages after a transmission has started reduces the chance of a
+correct decode, but in the first 10 s of a Tx period it will probably
+succeed.
+
+* Right-clicking on the entry field for message #5 pops up a list of
+free-text messages entered on the *Setup | Configuration | Tx Macros*
+dialog window.  You can select any of these pre-stored messages with
+the left mouse button.
+
+*Tab 2* of the Message Control Panel looks like this:
+
+//.New Message Menu
+image::images/new-msg-box.png[align="center",alt="New Message Menu"]
+
+With this setup you will normally follow a top-to-bottom sequence of
+transmissions from the left column if you are calling CQ, or the right
+column if you are answering a CQ.  Clicking a button puts the
+appropriate message in the *Gen Msg* box.  If you are already
+transmitting, it changes the Tx message immediately.  You can enter
+anything (up to 13 characters) in the *Free Msg* box.  Right-clicking on
+this entry field pops up your previously defined list of *Tx Macros*.
+
+IMPORTANT: WIth either of the message-control tabs, the actual message
+being transmitted always appears highlighted in yellow in the first
+box of the status bar, at bottom left of the main screen.  
+
+

doc/source/controls-functions-special-mouse-cmds.txt

@@ -0,0 +1,22 @@
+// Status=review
+The following special mouse commands are available:
+
+//.Special Mouse Commands
+[width="80%",cols="13,50",options="header",align="center"]
+|=====
+|Mouse-Click on|Action Performed
+|Waterfall|*Click*: set Rx frequency +
+*Double-click*: set Rx frequency and decode there +
+*Ctrl-click*: set Rx and Tx frequencies +
+*Ctrl-double-click*: set Rx and Tx frequencies and decode there
+|Decoded text|*Double-click*: copy second callsign to Dx Call,
+locator to Dx Grid; change Rx and Tx frequencies to decoded 
+signal's frequency; generate standard messages.  If first 
+callsign is your own, change Tx frequency only it Ctrl is
+held down when double-clicking.
+|*Erase* Button|*Click*: erase QSO window +
+*Double-click*: erase QSO and Band Activity windows
+|*Tx5* or +
+*Free Msg* box|*Right-click*: display the Tx macros +
+*Left-click*: select one of the Tx macros
+|=====

doc/source/controls-functions-status-bar.txt

@@ -0,0 +1,12 @@
+// Status=review
+
+A Status Bar at the bottom edge of the main window provides
+information about operating conditions.  
+
+//.Status Bar
+image::images/status-bar-a.png[align="left",alt="New Message Menu"]
+
+Reading from left to right, these labels provide information about the
+current operating state (Receiving, Transmitting, Tune, or an opened
+file name), operating mode, and content of the most recent transmitted
+message.

doc/source/controls-functions-wide-graph.txt

@@ -0,0 +1,32 @@
+// Status=review
+The following controls appear at the bottom of the Wide Graph window:
+
+image::images/wide-graph-controls.png[align="left",alt="Wide Graph Controls"]
+
+* *FFT Bins/Pixel* controls the displayed frequency resolution.  Set
+to 1 for the highest possible resolution, or to higher values to
+compress the spectral display. Normal operation with a convenient
+window size works well at 2 to 8 bins per pixel.
+
+* *N Avg* is the number of successive FFTs to be averaged before
+updating the spectral display.  Values around 5 are suitable for
+normal JT9 and JT65 operation.
+
+* *Gain* and *Zero* control the scaling and reference level for
+waterfall colors.  Values around 0 for both parameters are usually
+about right, depending on the input signal level and your own
+preferences.
+
+* *JT65 nnnn JT9* sets the dividing point for wide-band decoding of
+JT65 and JT9 signals in JT9+JT65 mode.  The decoder looks for JT65
+signals below nnnn Hz and JT9 signals above that frequency.
+
+* *Current / Cumulative* controls the graphical display in the bottom
+one-third of the Wide Graph window.  ** Current is the average
+spectrum over the most recent N Avg FFT calculations.  ** Cumulative
+is the average spectrum since the start of the current Rx sequence.
+
+* With the exception of *JT65 nnnn JT9*, controls on the Wide Graph
+window affect only the graphical displays — they have no effect
+on the decoding process.
+

doc/source/controls-functions.txt

@@ -0,0 +1,5 @@
+// Status=review
+
+This section describes the various menus, screens, controls, and
+functions for both the Main Window and Wide Graph. Small differences
+may exist between displayed images and that of the application.

doc/source/example1-decoding-controls.txt

@@ -0,0 +1,51 @@
+// Status=review
+- To gain some feeling for the controls you will use when making QSOs, try 
+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 either of the decoded lines highlighted in green. This action
+should produce the following:
+
+** Copies call-sign and locater of a station calling CQ to the “DX Call” 
+and “DX grid” entry fields.
+
+** Generates suitable messages for a minimal QSO and checks or clears the Tx
+even box so that you will transmit in the proper (odd or even) minutes.
+
+** Rx and Tx frequency markers will be moved to the CQ-ing station’s frequency,
+and the Gen Msg (“generated message”) radio button at bottom right of the main
+window will be selected.
+
+** If you had checked “Double-click on call sets Tx Enable” on the Setup menu,
+Enable Tx would also be activated, and you would start to transmit automatically,
+at the appropriate time.
+
+- Double-click on the decoded line with the message “K1JT N5KDV EM41”, 
+highlighted in [red]*RED*.
+
+- Results will be similar to (a), except the Tx frequency ([red]*RED* marker) is
+not moved.  Such messages 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.
+
+- By holding down the Ctrl key when double-clicking on the decoded line 
+(or checking Lock Tx=Rx) you can cause both Tx and Rx frequencies to be moved.
+
+- Double-click on the message from KF4RWA in either window. He is 
+sending “73” to K1JT, signifying that the QSO is over.  Most likely you 
+want to send 73 to him, so the message “KF4RWA K1JT 73” is automatically 
+generated and selected for your next transmission.  (Alternatively, you might 
+choose to send a free text message or to call CQ again.)
+
+- Clicking on the waterfall moves the Rx frequency ([green]*GREEN* marker) to the 
+selected frequency.
+
+- Ctrl-click on waterfall moves both Rx and Tx frequencies.
+
+- Double-click on the waterfall moves the Rx frequency and causes a 
+narrow-band decode there at the new QSO frequency. Decoded text appears in the 
+right window only.  Ctrl-double-click moves both Rx and Tx frequencies and 
+decodes at the new frequency. 
+
+- Clicking Erase clears the right window. Double-click on Erase to clear both 
+text windows.
+

doc/source/example1-decoding-overview.txt

@@ -0,0 +1,25 @@
+// Status=review
+- Notice the [green]*GREEN* and [red]*RED* markers on the waterfall
+frequency scale.  Decoding takes place at the end of a receive
+sequence and is organized in two stages.  The first decodes take place
+at the selected Rx frequency, indicated by the green marker.  Results
+appear in both the left (“Band Activity”) and right (“Rx Frequency”)
+text windows on the main screen. The decoder then finds and decodes
+all signals in the selected mode(s) and the displayed frequency range.
+The red marker indicates your Tx frequency.
+
+.Signal Presence
+
+NOTE: At least eight JT9 signals are present in the example file; all
+but one of them are decodable.  When this file was recorded KF4RWA was
+finishing a QSO with K1JT.  Since the green marker was placed at his
+audio frequency, 1224 Hz, his message “K1JT KF4RWA 73” appears in both
+decoded text windows.  The “Band Activity” window shows this message
+as well as all the other decodes at nearby frequencies.  The CQ lines
+are highlighted in [green]*GREEN*, and lines containing “My Call”, in
+this case K1JT, are highlighted in [red]*RED*.
+
+- For this step and the next, you may want to pretend you are K1JT by
+entering that call temporarily as “My Call” on the <<X11,Configuration
+Screen>>.  Your results should then be identical to those shown in the
+<<X12,figure above>>.

doc/source/example2-check-decodes.txt

@@ -0,0 +1,35 @@
+// Status=review
+- Double-click on the waterfall near 815 Hz: a signal originating
+from W7VP will be decoded and appear in the Rx Frequency Box:
+
+.W7VP Decode
+[width="70%",cols="3,^3,^3,^4,^4,30",options="header"]
+|=================================
+|UTC|db|dt|Freq|Mode|Message
+|2343|-7|0.3|815|#|KK4DSD W7VP -16
+|=================================
+
+- Double-click on the waterfall at 3196 Hz and the program will decode a JT9
+message from IZ0MIT:
+
+.IZ0MIT Decode
+[width="70%",cols="3,^3,^3,^4,^4,30",options="header"]
+|=====================================
+|UTC|db|dt|Freq|Mode|Message
+|2343|-7|0.3|3196|@|WB8QPG IZ0MIT -11
+|=====================================
+
+NOTE: Notice that when a signal is decoded in this way the Tx mode
+automatically switches to that of the decoded signal.  The Rx and Tx
+frequency markers on the waterfall scale resize themselves
+accordingly.
+
+- Scroll back in the Band Activity window (if necessary) and
+double-click on the message CQ DL7ACA JO40.  The program will set Tx
+mode to JT65 and Tx and Rx frequencies to that of DL7ACA, 975 Hz.  If
+you had checked *Double-click on call sets Tx Enable* on the Setup menu,
+the program would set up to start a QSO with DL7ACA.
+
+- Double-click on the decoded JT65 message CQ TA4A KM37.  The program
+will set Tx mode to JT9 and the Rx and Tx frequencies to 3567 Hz.
+You’re now configured properly for a JT9 QSO with TA4A.

doc/source/example2-main-window.txt

@@ -0,0 +1,5 @@
+// Status=review
+- Select JT9+JT65 on the Mode menu
+- Toggle the Tx mode button to read Tx JT65, and set the Tx and Rx frequencies
+to 1718 Hz.
+- Double-click on Erase to clear both text windows

doc/source/example2-wave-1742.txt

@@ -0,0 +1,20 @@
+// Status=review
+.Navigate and Open Wave File:
+
+*****
+
+Select File | Open and navigate to ...\save\samples\130418_1742.wav.
+
+*****
+
+- You can immediately see that these data were recorded with a much
+narrower Rx bandwidth, roughly 200 to 2600 Hz. If you have no Rx
+filter wider than about 2.7 kHz, you will be using data similar to
+this sample. For best viewing of such data adjust Bins/Pixel and the
+width of the Wide Graph so that only the active part of the spectrum
+shows, say 0 to 2600 Hz.  (Re-open the example file after any change
+of Bins/Pixel or Wide Graph width, to refresh the waterfall.)  The
+signals in this file are all JT9 signals.  To decode them in JT9+JT65
+mode you’ll need to move the JT65 nnnn JT9 delimiter down to 1000 Hz
+or less.
+

doc/source/example2-wave-2343.txt

@@ -0,0 +1,29 @@
+// Status=review
+.Navigate and Open Wave File:
+
+*****
+
+Select File | Open and navigate to ...\save\samples\130610_2343.wav.
+
+*****
+
+* The waterfall and main window should look like the figure below.
+This sample file contains 17 decodable signals — nine in JT65 mode
+(flagged with the character # in the decoded text windows), and eight
+in JT9 mode (flagged with @).  Since the Tx mode was set to Tx JT65,
+signals in that mode were decoded first.  If you had selected Tx JT9,
+JT9 signals would have been decoded first.
+
+.130610_2343.wav Decode
+[[X544]]
+image::images/130610_2343-wav-80.png[align="left",alt="Wide Graph Decode 130610_2343"]
+
+NOTE: Notice the [blue]*BLUE* marker on the waterfall scale, by
+default set at 2500 Hz.  Its position is set by the spinner control
+JT65 nnnn JT9, where nnnn is a frequency in Hz. In JT9+JT65 mode the
+program will decode JT65 signals below this frequency and JT9 signals
+above it.
+
+- Confirm that mouse-click behavior is similar to that described in
+the single-mode instructions at <<X13,Decoding Controls>>. The program
+automatically determines the mode of each JT9 or JT65 signal.

doc/source/example2-wide-graph-settings.txt

@@ -0,0 +1,8 @@
+// Status=review
+- Bins/Pixel = 7
+- Zero = -3
+
+[NOTE]
+If necessary, adjust the width of the Wide Graph Window so that the upper
+frequency limit is 4000 Hz.
+

doc/source/font-sizes.txt

@@ -0,0 +1,12 @@
+// Status=review
+- User control of font sizes can be effected by using a text editor
+(Windows Notepad or similar) to create a one-line file named fonts.txt
+in the wsjtx directory. A single line of text should contain four
+numbers separated by spaces.  The first two control the font size (in
+points) and weight (on a 0 – 100 scale) of most GUI labels. The last
+two numbers control size and weight of text in the Band Activity and
+Rx Frequency windows.
+
+- The default is ``8 50 10 50''. If you need larger fonts and bold
+text in the decode windows, try ``10 50 12 100'' (without the quotes).
+

doc/source/install-from-source.txt

@@ -0,0 +1,25 @@
+// Status=review
+// Note to developers. The URL http://developer.berlios.de/projects/wsjt/. is
+// to a very old src version of WSJT 5.7 or so. WSJTX is not listed at all.
+// Also, all the Qt4 stuff is now obsolete, and needs to be updated.
+
+{wsjtx} is an open-source program released under the GNU General
+Public License.  Source code is available from the public repository
+at {devsvn}. To compile the program you will need to install the 
+following packages:
+
+- Subversion
+- Qt 5.x
+- g++
+- gfortran or g95
+- fftw3
+- hamlib
+- MinGW (Windows only)
+
+The full source code for {wsjtx} can be downloaded with the command:
+
+[source,bash]
+-----
+$ svn co svn://svn.berlios.de/wsjt/branches/wsjtx 
+-----
+// Need further compiling Instructions

doc/source/install-mac.txt

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

doc/source/install-ubuntu.txt

@@ -0,0 +1,24 @@
+// Status=review
+- Installation packages for Ubuntu 12.04, 12.10, 13.04, 13.10 are
+available at {launchpadurl}
+
+- If you have not before obtained packages from the Personal Package
+Archive (PPA) at the above link, execute the following instruction at
+the command prompt:
+
+[source,bash]
+-----
+$ sudo add-apt-repository ppa:jnogatch/wsjtx
+-----
+Accept the PPA Key, then:
+
+[source,bash]
+-----
+$ sudo apt-get update 
+$ 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
+jt9. Normally (fter you have run the script /usr/bin/wsjtx at least
+once) this directory will be $HOME/.wsjtx.

doc/source/install-windows.txt

@@ -0,0 +1,15 @@
+// Status=review
+- Execute the downloaded file and follow its installation 
+instructions.
+
+- Install {wsjtx} into its own directory rather than the conventional
+C:\Program Files\WSJTX.  The suggested default directory is C:\WSJTX.
+
+- All files relating to {wsjtx} will be stored in your chosen
+installation directory and its subdirectories. You can uninstall
+{wsjtx} by removing the installation directory and its contents.
+
+- The built-in Windows facility for time synchronization is usually
+not adequate.  We recommend Meinberg NTP: see {ntpsetup} for
+downloading and installation instructions.  
+

doc/source/introduction.txt

@@ -0,0 +1,38 @@
+// Status=review
+{wsjtx} is a computer program designed to facilitate basic amateur
+radio communication using very weak signals.  The first four letters
+in the program name stand for “Weak Signal communication by K1JT”, and
+the “-X” suffix indicates that {wsjtx} started as an extended (and
+experimental) branch of program WSJT.
+
+{wsjtx} offers two protocols or “modes,” JT9 and JT65.  Both are
+designed for making reliable, confirmed QSOs under extreme weak-signal
+conditions. They use nearly identical message structure and source
+encoding.  JT65 was designed for EME (“moon-bounce”) on the VHF/UHF
+bands and has also proved very effective for worldwide QRP
+communication at HF.  JT9 is optimized for the LF, MF, and HF bands.
+It is about 2 dB more sensitive than JT65 while using less than 10% of
+the bandwidth.  Both modes use one-minute timed sequences of
+alternating transmission and reception, so a minimal QSO takes four to
+six minutes — two or three transmissions by each station, one sending
+in odd UTC minutes and the other even.  World-wide QSOs are possible
+with power levels of a few watts and compromise antennas.
+
+Starting with version 1.1, {wsjtx} can display a bandpass as large as
+5 kHz and provide dual-mode reception of both JT65 and JT9 signals.
+If your receiver can be configured with at least 4 kHz bandwidth in
+USB mode, you can set your dial frequency to one of the standard JT65
+frequencies — for example, 14.076 MHz for 20 meters — and have the
+full JT65 and JT9 sub-bands displayed simultaneously on the waterfall.
+You can make QSOs in both modes using nothing more than mouse clicks.
+
+Plans for future program development call for {wsjtx} and WSJT to
+merge together: {wsjtx} will gradually acquire the additional modes
+JT4, FSK441, and ISCAT that are now supported in WSJT.  The entire
+WSJT-related effort is an open-source project.  If you have
+programming or documentation skills or would like to contribute to the
+project in other ways, please make your interests known to the
+development team.  The project’s source-code repository can be found
+at {devsvn}, and communication among the developers takes place on the
+email reflector {devmail}.
+

doc/source/jt65-jt9-differences.txt

@@ -0,0 +1,41 @@
+// 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
+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
+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.
+
+- *JT65* signal reports are constrained to the range –1 to –30 dB —
+more than adequate for EME purposes, but not enough dynamic range for
+ideal use at HF and below.
+
+- S/N values displayed by the *JT65* decoder are clamped at –1 dB,
+because that’s all the original protocol can handle; 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 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/make-qso.txt

@@ -0,0 +1,109 @@
+// Status=review
+=== Standard Exchange
+By longstanding tradition, a minimal valid QSO requires the exchange
+of callsigns, a signal report or some other information, and
+acknowledgments.  {wsjtx} is designed to facilitate making such
+minimal QSOs using short, formatted messages.  The process works best
+if you use these formats and follow standard operating practices.  The
+recommended basic QSO goes something like this:
+
+[width="90%",cols="3,^3,^3,^4,10",options="header"]
+|=======================================
+|UTC|To|From|Grid/Rpt|Comment
+|0001|CQ|K1ABC|FN42|~ K1ABC calls CQ
+|0002|K1ABC|G0XYZ|IO91|~ G0XYZ answers
+|0003|G0XYZ|K1ABC|–19|~ K1ABC sends report
+|0004|K1ABC|G0XYZ|R–22|~ G0XYZ sends acknowledgment and report
+|0005|G0XYZ|K1ABC|RRR|~ K1ABC sends acknowledgment
+|0006|K1ABC|G0XYZ|73|~ G0XYZ sends 73
+|=======================================
+
+*Standard messages* consist of two callsigns (or CQ, QRZ, or DE and
+one callsign) followed by the transmitting station’s grid locator, a
+signal report, acknowledgement R plus a signal report, or the final
+acknowledgements “RRR” or “73”.  Messages are compressed and encoded
+in a highly efficient and reliable way.  
+
+*Signal reports* are specified as signal-to-noise ratio (S/N) in dB,
+using a standard reference noise bandwidth 2500 Hz.  JT65 reports must
+lie in the range –30 to –1 dB, while JT9 supports the extended range
+–50 to +49 dB.  Thus, in example message #0003, K1ABC is telling G0XYZ
+that his signal is 19 dB below the noise power in bandwidth 2500 Hz.
+In message #0004, G0XYZ acknowledges receipt of that report and
+responds with a –22 dB signal report.
+
+TIP: For operators with very good hearing, signals become audible
+around S/N = –15 dB and visible on the waterfall to –26 dB. The JT65
+decoder begins to fail around –24 dB, JT9 around –26 dB.
+
+*Free Text Messages*: Users often add some friendly chit-chat as a
+final transmission, in place of the formatted ``73'' message.
+Free-format messages such as ``TNX JOE 73 GL'' or `5W VERT 73 GL'' are
+supported, up to a maximum of 13 characters (including spaces).  It
+should be obvious that JT9 and JT65 are not suitable for extensive
+conversations or rag-chewing.
+
+=== Compound Callsigns
+//This section needs work!  Must describe and give examples for both 
+//JT65v1 and JT65v2 formats.
+Compound call-signs such as PJ4/K1ABC or G0XYZ/P are handled in a slightly 
+different way.  The following formats are all valid:
+
+.Valid Messages with Compound Callsigns
+
+[width="40%",cols="2,2,2",options="header"]
+|=====================
+|Action|Callsign|Grid
+|CQ|pfx/callsign|grid
+|QRZ|pfx/callsign|grid
+|DE|pfx/callsign|grid
+|CQ|callsign/sfx|grid
+|QRZ|callsign/sfx|grid
+|DE|callsign/sfx|grid
+|=====================
+
+- ``pfx'' is a 1-4 character prefix
+- ``callsign'' is a standard callsign
+- ``sfx'' is a 1-3 character suffix
+- ``grid'' is a 4-character Maidenhead locator
+
+- A signal report of the form “±nn” or “R±nn”, or the acknowledgment
+or sign-off messages “RRR” or “73”.  {wsjtx} generates messages in
+these forms automatically, as required.
+
+- A QSO between two stations using compound call-signs might look like this:
+
+ CQ KP4/K1ABC FK68
+                     DE G0XYZ/P IO91
+ G0XYZ K1ABC –19
+                     K1ABC G0XYZ R–22
+ G0XYZ K1ABC RRR
+                     DE G0XYZ/P 73
+
+////
+.Compound Exch Example
+[width="40%",cols="2,2,2",options="header"]
+|=====================
+|Action|Callsign|Grid
+|CQ|KP4/K1ABC|FK68
+|DE|G0XYZ/P|IO91
+|G0XYZ|K1ABC|–19
+|K1ABC|G0XYZ|R–22
+|G0XYZ|K1ABC|RRR
+|DE|G0XYZ/P|73
+|=====================
+////
+=== Pre-QSO Checklist
+
+Before attempting your first QSO with JT9 or JT65, be sure to go
+through the <<X15,Basic Tutorial>> above and the following checklist:
+
+- Your callsign and grid locator set to correct values
+- PTT and CAT control (if used) properly configured and tested
+- Computer clock properly synchronized with UTC to within ±1 s
+- Radio set to USB (upper sideband) mode
+- Radio's Split mode selected or not, consistent with your choice on
+*Station* tab of *Configuration* window.
+
+- Remember that JT9 and J65 generally do not require high power. Under
+most propagation conditions, [red]*QRP is the rule!*

doc/source/rigtemplate.txt

@@ -1,3 +1,4 @@
+// Status=review
 = Rig Template
 :Author: Greg Beam, KI7MT
 :Date: September 22, 2013, Copyleft © 2013

doc/source/system-requirments.txt

@@ -0,0 +1,10 @@
+// Status=review
+- SSB transceiver and antenna 
+- Computer running Windows (XP or later), Linux, or OS X
+- 1.5 GHz or faster CPU and 100 MB of available memory
+- Monitor with at least 1024 x 780 resolution (more is better)
+- Computer-to-radio interface using a serial port for T/R switching, or CAT 
+control, or VOX.
+- Audio input and output devices supported by your operating system
+- Audio or equivalent USB connections between transceiver and computer  
+- A means for synchronizing your computer clock to UTC to within ±1 s.

doc/source/transceiver-setup.txt

@@ -0,0 +1,36 @@
+// Status=review
+.Receiver Noise Level
+- Click the Monitor button to return to normal receive operation.
+- Set your transceiver to USB (or USB Data) mode.  
+- Use the receiver gain control(s) and/or the Windows mixer controls
+to set the background noise level to around 30 dB or mid-scale.  If
+necessary you can also use the slider next to the scale, but note that
+the overall dynamic range will be best with this slider not too far
+from its mid-point.
+
+.Bandwidth and Frequency Setting
+
+Taking full advantage of the wide-band, dual-mode capability of
+{wsjtx} requires a receiver bandwidth of at least 4 kHz. For example,
+on a Kenwood TS-2000 I set *Low Cut* to 200 and *High Cut* to 5000
+Hz. Note that most SSB transceivers have a fixed Tx filter that will
+not pass audio frequencies higher than about 2700 Hz.  {wsjtx} takes
+care of this by using Split mode, receiving with *VFO A* and
+transmitting with *VFO B*.  The Tx dial frequency (*VFO B*) is offset
+in 500 Hz steps, and the generated audio frequency is adjusted so that
+it always falls in the range 1500 – 2000 Hz. With *CAT* and *Split Tx*
+enabled on the configuration screen and your transceiver set to 
+*Tx Split* mode, frequency control will be handled automatically.  
+
+If your transceiver has only a standard SSB filter you won’t be able
+to use more than about 2.7 kHz bandwidth.  You can still have all of
+the JT9 sub-band and part of the JT65 sub-band available, however.  On
+20m, say, set dial frequency (*VFO A*) to 14.0774 and the *JT9 nnnn JT65*
+dividing line at 1600 Hz.  JT9 signals in their conventional sub-band
+will then appear at 1600 – 2600 Hz, while JT65 signals will be below
+1000 Hz.  Of course, you might prefer to concentrate on one mode at a
+time, setting your dial frequency to (say) 14.076 for JT65 and 14.078
+for JT9.  Present conventions have the nominal JT9 dial frequency 2
+kHz higher than the JT65 dial frequency, and the check-box labeled +2
+kHz, just below the band selector, makes the appropriate settings
+easy.

doc/source/tutorial-example1.txt

@@ -0,0 +1,89 @@
+// Status=review
+.Open a Wave File:
+
+- Select File | Open and navigate to ...\save\samples\130418_1742.wav
+under your program installation directory.  
+
+When the file opens you should see something similar to the to the
+following screen shot:
+
+[[X12]]
+image::images/r3556-main-ui-80.png[align="center",alt="Main UI and Wide Graph"]
+
+.Decoding Overview
+
+Notice the [green]*GREEN* and [red]*RED* markers on the waterfall
+frequency scale.  Decoding takes place at the end of a receive
+sequence and is organized in two stages.  The first decodes take place
+at the selected Rx frequency, indicated by the green marker.  Results
+appear in both the left (“Band Activity”) and right (“Rx Frequency”)
+text windows on the main screen. The decoder then finds and decodes
+all signals in the selected mode(s) and the displayed frequency
+range. The red marker indicates your Tx frequency.
+
+At least eight JT9 signals are present in the example file; all
+but one of them are decodable.  When this file was recorded KF4RWA was
+finishing a QSO with K1JT.  Since the green marker was placed at his
+audio frequency, 1224 Hz, his message “K1JT KF4RWA 73” appears in both
+decoded text windows.  The “Band Activity” window shows this message
+as well as all the other decodes at nearby frequencies.  The CQ lines
+are highlighted in [green]*GREEN*, and lines containing “My Call”, in
+this case K1JT, are highlighted in [red]*RED*.
+
+TIP: For this step and the next, you may want to pretend you are K1JT by
+entering that call temporarily as “My Call” on the <<X11,Configuration
+Screen>>.  Your results should then be identical to those shown in the
+<<X12,screen shot>> above.
+
+[[X13]]
+.Decoding Controls
+To gain some feeling for the controls you will use when making QSOs, try 
+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 either of the decoded lines highlighted in green. This action
+should produce the following:
+
+** Copies call-sign and locater of a station calling CQ to the “DX Call” 
+and “DX grid” entry fields.
+
+** Generates suitable messages for a minimal QSO and checks or clears the Tx
+even box so that you will transmit in the proper (odd or even) minutes.
+
+** Rx and Tx frequency markers will be moved to the CQ-ing station’s frequency,
+and the Gen Msg (“generated message”) radio button at bottom right of the main
+window will be selected.
+
+** If you had checked “Double-click on call sets Tx Enable” on the Setup menu,
+Enable Tx would also be activated, and you would start to transmit automatically,
+at the appropriate time.
+
+- Double-click on the decoded line with the message “K1JT N5KDV EM41”,
+highlighted in [red]*RED*.  Results will be similar to those in the
+previous step, except the Tx frequency ([red]*RED* marker) is not
+moved.  Such messages 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.
+
+- By holding down the Ctrl key when double-clicking on the decoded line 
+you can cause both Tx and Rx frequencies to be moved.  This behavior
+can also be forced by checking Lock Tx=Rx. 
+
+- Double-click on the message from KF4RWA in either window. He is 
+sending “73” to K1JT, signifying that the QSO is over.  Most likely you 
+want to send 73 to him, so the message “KF4RWA K1JT 73” is automatically 
+generated and selected for your next transmission.  (Alternatively, you might 
+choose to send a free text message or to call CQ again.)
+
+- Clicking on the waterfall moves the Rx frequency ([green]*GREEN* marker) to the 
+selected frequency.
+
+- Ctrl-click on waterfall moves both Rx and Tx frequencies.
+
+- Double-click on the waterfall moves the Rx frequency and causes a 
+narrow-band decode there at the new QSO frequency. Decoded text appears in the 
+right window only.  Ctrl-double-click moves both Rx and Tx frequencies and 
+decodes at the new frequency. 
+
+- Clicking Erase clears the right window. Double-click on Erase to clear both 
+text windows.

doc/source/tutorial-example2.txt

@@ -0,0 +1,96 @@
+// Status=review
+.Wide Graph Settings:
+- Bins/Pixel = 7
+- Zero = -3
+- If necessary, adjust the width of the Wide Graph Window so that its upper
+frequency limit is 4000 Hz.
+
+.Main Window:
+- Select JT9+JT65 on the Mode menu
+- Toggle the Tx mode button to read Tx JT65, and set the Tx and Rx
+frequencies to 1718 Hz.
+- Double-click on Erase to clear both text windows
+
+.Open a Wave File:
+- Select File | Open and navigate to ...\save\samples\130610_2343.wav.
+
+The waterfall should look like the figure below.
+
+//.130610_2343.wav Decode
+[[X14]]
+image::images/130610_2343-wav-80.png[align="left",alt="Wide Graph Decode 130610_2343"]
+
+This sample file contains 17 decodable signals — nine in JT65 mode
+(flagged with the character # in the decoded text windows), and eight
+in JT9 mode (flagged with @).  Since the Tx mode was set to Tx JT65,
+signals in that mode were decoded first.  If you had selected Tx JT9,
+JT9 signals would have been decoded first.
+
+TIP: Notice the [blue]*BLUE* marker on the waterfall scale, by
+default set at 2500 Hz.  Its position is set by the spinner control
+JT65 nnnn JT9, where nnnn is a frequency in Hz. In JT9+JT65 mode the
+program will decode JT65 signals below this frequency and JT9 signals
+above it.
+
+- Confirm that mouse-click behavior is similar to that described
+<<X13,earlier>>. The program automatically determines the mode of each
+JT9 or JT65 signal.
+
+- Double-click on the waterfall near 815 Hz: a JT65 message
+originating from W7VP will be decoded and appear in the Rx Frequency
+Box:
+
+[width="70%",cols="3,^3,^3,^4,^4,30",options="header"]
+|=================================
+|UTC|db|dt|Freq|Mode|Message
+|2343|-7|0.3|815|#|KK4DSD W7VP -16
+|=================================
+
+- Double-click on the waterfall at 3196 Hz and the program will decode a JT9
+message from IZ0MIT:
+
+[width="70%",cols="3,^3,^3,^4,^4,30",options="header"]
+|=====================================
+|UTC|db|dt|Freq|Mode|Message
+|2343|-7|0.3|3196|@|WB8QPG IZ0MIT -11
+|=====================================
+
+TIP: Notice that when a signal is decoded in this way, the Tx mode
+automatically switches to that of the decoded signal and the Rx and Tx
+frequency markers on the waterfall scale resize themselves
+accordingly.
+
+- Scroll back in the Band Activity window and double-click on the
+message CQ DL7ACA JO40.  The program will set Tx mode to JT65 and Tx
+and Rx frequencies to that of DL7ACA, 975 Hz.  If you had checked
+*Double-click on call sets Tx Enable* on the Setup menu, the program
+would configure itself to start a QSO with DL7ACA.
+
+- Double-click on the decoded JT65 message CQ TA4A KM37.  The program
+will set Tx mode to JT9 and the Rx and Tx frequencies to 3567 Hz.  The
+program is now configured properly for a JT9 QSO with TA4A.
+
+IMPORTANT: Don’t forget to re-enter your own call-sign as “My Call”.  
+
+.Reopen the First Sample File:
+- Select File | Open and navigate to ...\save\samples\130418_1742.wav.
+
+These data were recorded with a much narrower Rx bandwidth, roughly
+200 to 2600 Hz. If you have no Rx filter wider than about 2.7 kHz, you
+will be using data like this. For best viewing of such data adjust
+Bins/Pixel and the width of the Wide Graph so that only the active
+part of the spectrum shows, say 0 to 2600 Hz.  Re-open the example
+file after any change of Bins/Pixel or Wide Graph width, to refresh
+the waterfall.
+
+The signals in this file are all JT9 signals.  To decode them in
+JT9+JT65 mode you’ll need to move the JT65 nnnn JT9 delimiter down to
+1000 Hz or less.
+
+.Start, Zero, and Gain
+Now is a good time to experiment with the *Start*, *Zero*, and
+*Gain* parameters.  *Start* sets the starting frequency at the left
+side of the waterfall scale.  *Zero* sets the baseline level for
+colors, and *Gain* sets the sensitivity for color changes.  For the
+receiver setup of this file good values are *Zero*=0, *Gain*=0.
+Re-open the wave file after each change, to see the new results.

doc/source/tutorial-main-window.txt

@@ -0,0 +1,5 @@
+// Status=review
+- Click the *Stop* button on the main window to halt any data acquisition.  
+- Select JT9 from the *Mode* menu and Deepest from the *Decode* menu.
+- Set the audio Tx and Rx frequencies to 1224 Hz.
+//Maybe  show small screen shots here?

doc/source/tutorial-wide-graph-settings.txt

@@ -0,0 +1,10 @@
+// Status=review
+* Bins/Pixel = 4
+* N Avg = 5
+* Gain = 0,
+* Zero = –10
+* Flatten = checked
+* Cumulative for data display.
+* Select Tab 2 (below the Erase button on the main window) to
+choose the alternative set of controls for generating and selecting
+Tx messages.

doc/source/yaesu.txt

@@ -1,3 +1,4 @@
+// Status=review
 // This is a comment line, anything with // is ignored at process time.
 = Yaesu Configuration Guide
 :Author: Greg Beam, KI7MT