Initial Commit

doc/user_guide/en/acknowledgements.adoc

@@ -0,0 +1,29 @@
+// Status=review
+
+The _WSJT_ project was started in 2001.  Since 2005 it has been an
+Open Source project, and it now includes programs _WSJT_, _MAP65_,
+_WSPR_, _WSJT-X_, and _WSPR-X_.  All code is licensed under the
+GNU Public License (GPL).  Many users of these programs, too numerous
+to mention here individually, have contributed suggestions and advice
+that have greatly aided the development of _WSJT_ and its sister
+programs.
+
+For _WSJT-X_ in particular, we acknowledge contributions from *AC6SL,
+AE4JY, DJ0OT, G3WDG, G4KLA, G4WJS, IV3NWV, IW3RAB, K3WYC, K9AN,
+KA6MAL, KA9Q, KB1ZMX, KD6EKQ, KI7MT, KK1D, ND0B, PY2SDR, VE1SKY, VK3ACF,
+VK4BDJ, VK7MO, W4TI, W4TV, and W9MDB*.  Each of these amateurs has helped to
+bring the program’s design, code, testing, and/or documentation to
+its present state.
+
+Most of the color palettes for the _WSJT-X_ waterfall were copied from
+the excellent, well documented, open-source program _fldigi_, by *W1HKJ*
+and friends.
+
+We use development tools and libraries from many sources.  We
+particularly wish to acknowledge importance of the GNU Compiler
+Collection from the Free Software Foundation, the "clang" compiler
+from LLVM at the University of Illinois, and the Qt Project from Digia
+PLC.  Other important resources include the FFTW library by Matteo
+Frigo and Steven G. Johnson; SLALIB, the Positional Astronomy Library
+by P. T.  Wallace; and a high-precision planetary ephemeris and
+associated software from NASA's Jet Propulsion Laboratory.

doc/user_guide/en/astro_data.adoc

@@ -0,0 +1,57 @@
+A text box entitled Astronomical Data provides information needed for
+tracking the sun or moon, compensating for EME Doppler shift, and
+estimating EME Doppler spread and path degradation. Toggle the
+*Astronomical data* on the *View* menu to display or hide this window.
+
+image::AstroData_2.png[align="center",alt="Astronomical Data"]
+
+Available information includes the current UTC *Date* and time; *Az*
+and *El*, azimuth and elevation of the moon at your own location, in
+degrees; *SelfDop*, *Width*, and *Delay*, the Doppler shift, full
+limb-to-limb Doppler spread in Hz, and delay of your own EME echoes in
+seconds; and *DxAz* and *DxEl*, *DxDop*, and *DxWid*, corresponding
+parameters for a station located at the *DX Grid* entered on the main
+window.  These numbers are followed by *Dec*, the declination of the
+moon; *SunAz* and *SunEl*, the azimuth and elevation of the Sun;
+*Freq*, your stated operating frequency in MHz; *Tsky*, the estimated
+sky background temperature in the direction of the moon, scaled to the
+operating frequency; *Dpol*, the spatial polarization offset in
+degrees; *MNR*, the maximum non-reciprocity of the EME path in dB,
+owing to a combination of Faraday rotation and spatial polarization;
+and finally *Dgrd*, an estimate of the signal degradation in dB,
+relative to the best possible time with the moon at perigee in a cold
+part of the sky.
+
+On the higher microwave bands, where Faraday rotation is minimal and
+linear polarization is often used, spatial offset will reduce signal
+levels.  Some stations have implemented mechanical polarisation
+adjustment to overcome this loss, and the amount of rotation needed is
+predicted in real time by the value of *Dpol*.  Positive Dpol means
+that the antenna should be rotated in a clockwise direction looking
+from behind the antenna towards the moon.  For a dish antenna, the
+feed should similarly be rotated clockwise looking into the mouth of
+the feed. A negative value for Dpol means anticlockwise rotation.
+
+
+The state of the art for establishing three-dimensional locations of
+the sun, moon, and planets at a specified time is embodied in a
+numerical model of the solar system maintained at the Jet Propulsion
+Laboratory. The model has been numerically integrated to produce
+tabular data that can be interpolated with very high accuracy. For
+example, the celestial coordinates of the moon or a planet can be
+determined at a specified time to within about 0.0000003 degrees. The
+JPL ephemeris tables and interpolation routines have been incorporated
+into _WSJT-X_.  Further details on accuracy, especially concerning
+calculated EME Doppler shifts, are described in {lunarEchoes} for
+November-December, 2016.
+
+The sky background temperatures reported by _WSJT-X_ are derived from
+the all-sky 408 MHz map of Haslam et al. (Astronomy and Astrophysics
+Supplement Series, 47, 1, 1982), scaled by frequency to the -2.6
+power. This map has angular resolution of about 1 degree, and of
+course most amateur EME antennas have much broader beamwidths than
+this. Your antenna will therefore smooth out the hot spots
+considerably, and the observed extremes of sky temperature will be
+less. Unless you understand your sidelobes and ground reflections
+extremely well, it is unlikely that more accurate sky temperatures
+would be of much practical use.

doc/user_guide/en/config-details.adoc

@@ -0,0 +1,4 @@
+// Status=review
+[[CONFIG_DETAILS]]
+
+Are we here?

doc/user_guide/en/controls-functions-center.adoc

@@ -0,0 +1,79 @@
+// Status=review
+
+At the center of the main window are a number of controls used when
+making QSOs.  Controls not relevant to a particular mode or submode
+may be "grayed out" (disabled) or removed from the display.
+
+//.Misc Controls Center
+image::misc-controls-center.png[align="center",alt="Misc Controls Center"]
+
+* Check *Tx even* to transmit in even-numbered UTC minutes or
+sequences, starting at 0.  Uncheck this box to transmit in the odd
+sequences.  The correct selection is made automatically when you
+double-click on a decoded text line, as described in the
+<<TUTORIAL,Basic Operating Tutorial>>.
+
+* The Tx and Rx audio frequencies can be set automatically by
+double-clicking on decoded text or a signal in the waterfall.  They
+can also be adjusted using the spinner controls.
+
+* You can force Tx frequency to the current Rx frequency by clicking
+the *Tx<-Rx* button, and vice-versa for *Rx<-Tx*.  The on-the-air
+frequency of your lowest JT9 or JT65 tone is the sum of dial frequency
+and audio Tx frequency.
+
+* Check the box *Lock Tx=Rx* to make the frequencies always track one
+another.
+
+IMPORTANT: In general we do not recommend using *Lock Tx=Rx* since it
+encourages poor radio etiquette when running a frequency.  With this
+box checked, your own Tx frequency will move around following your
+callers.
+
+* For modes lacking a multi-decode feature, or when *Enable
+VHF/UHF/Microwave features* has been checked on the *Settings ->
+General* tab, the *F Tol* control sets a frequency toilerance range
+over which decoding will be attempted, centered on the Rx frequency.
+
+* The *Report* control lets you change a signal report that has been
+inserted automatically. Typical reports for the various modes fall in
+the range –30 to +20 dB.  Remember that JT65 reports saturate at an
+upper limit of -1 dB.
+
+TIP: Consider reducing power if your QSO partner reports your
+signal above -5 dB in one of the _WSJT-X_ slow modes.  These are
+supposed to be weak signal modes!
+
+* In some circumstances, especially on VHF and higher bands, you can
+select a supported submode of the active mode by using the *Submode*
+control.  The *Sync* control sets a minimum threshold for establishing
+time and frequency synchronization with a received signal.
+
+* Spinner control *T/R xx s* sets sequence lengths for transmission
+and reception in ISCAT, MSK144, and the fast JT9 modes.
+
+* With *Split operation* activated on the *Settings -> Radio* tab, in
+MSK144 and the fast JT9 submodes you can activate the spinner control
+*Tx CQ nnn* by checking the box to its right.  The program will then
+generate something like `CQ nnn K1ABC FN42` for your CQ message, where
+`nnn` is the kHz portion of your current operating frequency.  Your CQ
+message *Tx6* will then be transmitted at the calling frequency
+selected in the *Tx CQ nnn* spinner control.  All other messages will
+be transmitted at your current operating frequency.  On reception,
+when you double-click on a message like `CQ nnn K1ABC FN42` your rig
+will QSY to the specified frequency so you can call the station at his
+specified response frequency.
+
+* Checkboxes at bottom center of the main window control special
+features for particular operating modes:
+
+** *Sh* enables shorthand messages in JT4, JT65, and MSK144 modes
+
+** *Fast* enables fast JT9 submodes
+
+** *Auto Seq* enables auto-sequencing of Tx messages
+
+** *Call 1st* enables automatic response to the first decoded
+responder to your CQ
+
+** *Tx6* toggles between two types of shorthand messages in JT4 mode

doc/user_guide/en/controls-functions-left.adoc

@@ -0,0 +1,45 @@
+// Status=review
+
+Controls related to frequency selection, received audio level, the
+station being called, and date and time are found at lower left of the
+main window:
+
+//.Misc Controls Left
+image::misc-main-ui.png[align="center",alt="Misc Menu Items"]
+
+* A drop-down list of frequencies and bands at upper left lets you
+select the operating band and sets dial frequency to a value taken
+from the *Frequencies* tab on the *Settings* window.  If CAT control
+is active the radio's dial frequency will be set accordingly; if not,
+you must tune the radio manually.
+
+* Alternatively, you can enter a frequency (in MHz) or band name in
+recognized ADIF format, for example 630m, 20m, or 70cm.  The band-name
+format works only if a working frequency has been set for that band
+and mode, in which case the first such match is selected.
+
+* You can also enter a frequency increment in kHz above the currently
+displayed integer MHz. For example, if the displayed frequency is
+10,368.100, enter `165k` (don't forget the `k`!) to QSY to 10,368.165.
+
+* A small colored circle appears in green if the CAT control is
+activated and functional.  The green circle contains the character S
+if the rig is detected to be in *Split* mode.  The circle becomes red
+if you have requested CAT control but communication with the radio has
+been lost.
+
+TIP: Many Icom rigs cannot be queried for split status, current VFO or
+split transmit frequency. When using _WSJT-X_ with such radios you
+should not change the current VFO, split status or dial frequency
+using controls on the radio.
+
+* If *DX Grid* contains a valid Maidenhead locator, the corresponding
+great-circle azimuth and distance from your location are displayed.
+
+* The program can maintain a database of callsigns 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.  This feature is mainly useful for situations
+in which the number of active stations is modest and reasonably
+stable, such as EME (Earth-Moon-Earth) communication.  The callsign
+file name is `CALL3.TXT`.

doc/user_guide/en/controls-functions-main-window.adoc

@@ -0,0 +1,64 @@
+// Status=review
+The following buttons appear just under the decoded text windows on
+the main screen:
+
+//.Main UI 
+image::main-ui-controls.png[align="left",width=650,alt="Main UI Controls"]
+
+* *Log QSO* raises a dialog window 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 check *Prompt
+me to log QSO* on the *Settings -> Reporting* tab, the program will
+raise the confirmation screen automatically when you send a message
+containing +73+.  *Start Date* and *Start Time* are set when you click
+to send the *Tx 2* or *Tx 3* message, and backed up by one or two
+sequence lengths, respectively.  (Note that the actual start time may
+have been earlier if repeats of early transmissions were required.)
+End date and time are set when the *Log QSO* screen is invoked.
+
+//.Log QSO Window
+image::log-qso.png[align="center",alt="Log QSO"]
+
+* *Stop* will terminate normal data acquisition in case you want to
+freeze the waterfall or open and explore a previously recorded audio
+file.
+
+* *Monitor* toggles normal receive operation on or off.  This button
+is highlighted in green when the _WSJT-X_ is receiving.  If you are
+using CAT control, toggling *Monitor* OFF relinquishes control of the
+rig; if *Monitor returns to last used frequency* is selected on the
+*Settings | General* tab, toggling *Monitor* back ON will return to
+the original frequency.
+
+* *Erase* clears the right-hand decoded text window. 
+Double-clicking *Erase* clears both text windows.
+
+TIP: Right-clicking on either text window brings up a context menu
+with several options (including *Erase*) which operate on that window
+alone.
+
+* *Clear Avg* is present only in modes that support message averaging.
+It provides a way to erase the accumulating information, thus
+preparing to start a new average.
+
+* *Decode* tells the program to repeat the decoding procedure at the
+Rx frequency (green marker on waterfall scale), using the most recently
+completed sequence of received data.  
+
+* *Enable Tx* toggles automatic T/R sequencing mode on or off and
+highlights the button in red when ON.  A transmission will start at
+the beginning of the selected (odd or even) sequence, or immediately
+if appropriate.  Toggling the button to OFF during a transmission
+allows the current transmission to finish.
+
+* *Halt Tx* terminates a transmission immediately and disables
+automatic T/R sequencing.
+
+* *Tune* toggles the program into Tx mode and generates an unmodulated
+carrier at the specified Tx frequency (red marker on waterfall scale).
+This process is useful for adjusting an antenna tuner or tuning an
+amplifier.  The button is highlighted in red while *Tune* is active.
+Toggle the button a second time or click *Halt Tx* to terminate the
+*Tune* process.  Note that activating *Tune* interrupts a receive
+sequence and will prevent decoding during that sequence.
+

doc/user_guide/en/controls-functions-menus.adoc

@@ -0,0 +1,66 @@
+// Status=review
+
+Menus at top of the main window offer many options for configuration
+and operation.  Most of the items are self-explanatory; a few
+additional details are provided below.  Keyboard shortcuts for some
+frequently used menu items are listed at the right edge of the menu.
+
+==== _WSJT-X_ menu
+image::MacAppMenu.png[align="left",alt="Mac App Menu"]
+
+This menu appears on the Macintosh only. *Settings* appears here,
+labeled as *Preferences*, rather than on the *File* menu.  *About
+WSJT-X* appears here rather than on the *Help* menu.
+
+[[FILE_MENU]]
+==== File menu
+image::file-menu.png[align="left",alt="File Menu"]
+
+[[CONFIG_MENU]]
+==== Configuration Menu
+image::config-menu.png[align="left",alt="File Menu"]
+
+Many users prefer to create and use entries on the *Configurations*
+menu for switching between modes.  Simply *Clone* the *Default* entry,
+*Rename* it as desired, and then make all desired settings for that
+configuration.  These settings will be restored whenever you select
+that configuration.
+
+As well as switching between configurations while running _WSJT-X_ you
+can also start the application from the command line in any desired
+configuration.  Use the command-line option
+`--config <configuration-name>`, or `-c` for short, as in these
+examples for configurations `FT8` and `Echo`:
+
+ wsjtx --config FT8
+ wsjtx -c Echo
+
+[[VIEW_MENU]]
+==== View Menu
+image::view-menu.png[align="left",alt="View Menu"]
+
+[[MODE_MENU]]
+==== Mode Menu
+image::mode-menu.png[align="left",alt="Mode Menu"]
+
+[[DECODE_MENU]]
+==== Decode Menu
+image::decode-menu.png[align="left",alt="Decode Menu"]
+
+[[SAVE_MENU]]
+[[SAVE-WAV]]
+==== Save Menu
+image::save-menu.png[align="left",alt="Save Menu"]
+
+==== Tools Menu
+image::tools-menu.png[align="left",alt="Tools Menu"]
+
+[[HELP_MENU]]
+==== Help Menu
+image::help-menu.png[align="left",alt="Help Menu"]
+
+===== Keyboard Shortcuts (F3)
+image::keyboard-shortcuts.png[align="left",alt="Keyboard Shortcuts"]
+
+===== Special Mouse Commands (F5)
+image::special-mouse-commands.png[align="left",alt="Special Mouse Commands"]

doc/user_guide/en/controls-functions-messages.adoc

@@ -0,0 +1,61 @@
+// Status=review
+
+Two arrangements of controls are provided for generating and selecting
+Tx messages.  Controls familiar to users of program _WSJT_
+appear on *Tab 1*, providing six fields for message entry.
+Pre-formatted messages for the standard minimal QSO are generated when
+you click *Generate Std Msgs* or double-click on an appropriate line
+in one of the decoded text windows.
+
+//.Traditional Message Menu
+image::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 during a
+transmission, click on a rectangular button under the *Now* label.
+Changing a Tx message in mid-stream will slightly reduce the chance of
+a correct decode, but it is usually OK if done in the first 10-20% of
+a transmission.
+
+* All six Tx message fields are editable.  You can modify an
+automatically generated message or enter a desired message, keeping in
+mind the limits on message content.  See <<PROTOCOLS,Protocol
+Specifications>> for details.
+
+* Click on the pull-down arrow for message #5 to select one of the
+pre-stored messages entered on the *Settings | Tx Macros* tab.
+Pressing *Enter* on a modified message #5 automatically adds that
+message to the stored macros.
+
+* In some circumstances it may be desirable to make your QSOs as
+shiort as possible.  To configure the program to start contacts with
+message #2, disable message #1 by double-clicking on its round
+radio-button or rectangular *Tx 1* button.  Similarly, to send RR73
+rather than RRR for message #4, double-click on one of its buttons.
+
+The second arrangement of controls for generating and selecting
+Tx messages appears on *Tab 2* of the Message Control Panel:
+
+//.New Message Menu
+image::new-msg-box.png[align="center",alt="New Message Menu"]
+
+With this setup you normally follow a top-to-bottom sequence of
+transmissions from the left column if you are calling CQ, or the right
+column if answering a CQ.  
+
+* Clicking a button puts the appropriate message in the *Gen Msg* box.
+If you are already transmitting, the Tx message is changed
+immediately.
+
+* You can enter and transmit anything (up to 13 characters, including
+spaces) in the *Free Msg* box.
+
+* Click on the pull-down arrow in the *Free Msg* box to select a
+pre-stored macro.  Pressing *Enter* on a modified message here
+automatically adds that message to the table of stored macros.
+
+TIP: During a transmission the actual message being sent always
+appears in the first box of the status bar (bottom left of the main
+screen).

doc/user_guide/en/controls-functions-status-bar.adoc

@@ -0,0 +1,23 @@
+// Status=review
+
+A *Status Bar* at the bottom edge of the main window provides useful
+information about operating conditions.
+
+//.Status Bar
+image::status-bar-a.png[align="left",alt="Status Bar"]
+
+Labels on the *Status Bar* display such information as the program's
+current operating state, configuration name, operating mode, and the
+content of your most recent transmitted message. The first label
+(operating state) can be Receiving, Tx (for Transmitting), Tune, or
+the name of file opened from the *File* menu; this label is
+highlighted in green for Receiving, yellow for Tx, red for Tune, and
+light blue for a file name.  When transmitting, the Tx message is
+displayed exactly as it will be decoded by receiving stations.  The
+second label (as shown above) will be absent if you are using the
+*Default* setting on the *Configurations* menu.  A progress bar shows
+the elapsed fraction of a Tx or Rx sequence.  Finally, if the Watchdog
+(WD) timer was enabled on the *settings | General* tab, a label in the
+lower right-hand corner displays the number of minutes remaining
+before timeout.
+

doc/user_guide/en/controls-functions-wide-graph.adoc

@@ -0,0 +1,100 @@
+// Status=review
+
+The following controls appear at the bottom of the Wide Graph window.
+Decoding occurs only in the displayed frequency range; otherwise, with
+the exceptions of *Start NNN Hz* and of *JT65 nnnn JT9* when operating
+in JT9+JT65 mode, controls on the Wide Graph window have no effect on
+the decoding process.
+
+image::wide-graph-controls.png[align="center",alt="Wide Graph Controls"]
+
+- *Bins/Pixel* controls the displayed frequency resolution.  Set this
+value to 1 for the highest possible resolution, or to higher numbers
+to compress the spectral display. Normal operation with a convenient
+window size works well at 2 to 8 bins per pixel.
+
+- *JT65 nnnn JT9* sets the dividing point (blue marker) for wide-band
+decoding of JT65 and JT9 signals in *JT9+JT65* mode.  The decoder
+looks for JT65 signals everywhere, but JT9 signals only above this
+frequency. This setting is stored separately for each band.
+
+- *Start nnn Hz* sets the low-frequency starting point of the
+waterfall frequency scale.
+
+- *N Avg* is the number of successive spectra to be averaged before
+updating the display.  Values around 5 are suitable for normal JT9 and
+JT65 operation.  Adjust *N Avg* to make the waterfall move faster or
+slower, as desired.
+
+- A dropdown list below the *Palette* label lets you select from a
+wide range of waterfall color palettes.  
+
+- Click *Adjust* to activate a window that allows you to create a
+user-defined palette.
+
+- Check *Flatten* if you want _WSJT-X_ to compensate for a sloping or
+uneven response across the received passband.  For this feature to
+work properly, you should restrict the range of displayed frequencies
+so that only the active part of the spectrum is shown.
+
+- Select *Current* or *Cumulative* for the spectrum displayed 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 present UTC minute.
+*Linear Avg* is useful in JT4 mode, especially when short-form
+messages are used.
+
+- Four sliders control reference levels and scaling for waterfall
+colors and the spectrum plot.  Values around midscale are usually
+about right, depending on the input signal level, the chosen palette,
+and your own preferences. Hover the mouse over a control to display a
+tip reminding you of its function.
+
+- *Smoothing* is active only when *Linear Average* has been selected.
+Smoothing the displayed spectrum over more than one bin can enhance
+your ability to detect weak EME signals with Doppler spread more than
+a few Hz.
+
+[[CONTROLS_FAST]]
+=== Fast Graph
+
+The waterfall palette used for the Fast Graph is the same as the one
+selected on the Wide Graph.  Three sliders at the bottom of the Fast
+Graph window can be used to optimize gain and zero-offset for the
+displayed information.  Hover the mouse over a control to display a
+tip reminding you of its function.  Clicking the *Auto Level* button
+will produce reasonable settings as a starting point.
+
+image::fast-graph-controls.png[align="center",alt="Fast Graph Controls"]
+
+[[CONTROLS_ECHO]]
+=== Echo Graph
+
+The following controls appear at the bottom of the Echo Graph:
+
+image::echo-graph-controls.png[align="center",alt="EchoGraph Controls"]
+
+- *Bins/Pixel* controls the displayed frequency resolution.  Set this
+value to 1 for the highest possible resolution, or to higher numbers
+to compress the spectral display.
+
+- *Gain* and *Zero* sliders control scaling and offset of plotted
+spectra.
+
+- *Smooth* values greater than 0 apply running averages to the plotted
+spectra, thereby smoothing the curves over multiple bins.
+
+- Label *N* shows the number of echo pulses averaged.
+
+- Click the *Colors* button to cycle through 6 possible choices of
+color and line width for the plots.
+
+[[CONTROLS_MISCELLANEOUS]]
+=== Miscellaneous
+
+Most windows can be resized as desired.  If you are short of screen
+space you can make the Main Window and Wide Graph smaller by hiding
+some controls and labels.  To enable this feature type *Ctrl+M* with
+focus on the appropriate window.  (For the Main Window you can select
+*Hide menus and labels* on the *View* menu.)  Type *Ctrl+M* again
+to make the controls visible once more.

doc/user_guide/en/cooperating-programs.adoc

@@ -0,0 +1,39 @@
+_WSJT-X_ is programmed to cooperate closely with several other useful
+programs.  
+
+* {dxlsuite}, {omnirig}, and {hrd} were described in the section on
+<<RADIO,rig control>>.
+
+* {pskreporter}, by Philip Gladstone, is a web server that gathers
+reception reports sent by various other programs, including _WSJT-X_.
+The information is made available in near real time on a world map,
+and also as statistical summaries of various kinds.  A number of
+options are available to the user; for example, you can request a map
+showing world-wide JT65 activity on all amateur bands over the
+past hour.  Such a map might look like this, where different colors
+represent different bands:
+
+image::psk-reporter.png[align="left",alt="PSK Reporter"]
+
+The following screen shot shows the PSK Reporter map configured to
+show MSK144 reports:
+
+image::psk-reporter_2.png[align="left",alt="PSK Reporter"]
+
+* {jtalert}, by VK3AMA, is available only for Windows.  It provides
+many operating aids including automatic logging to several third-party
+logging programs, audio and visual alerts following a number of
+optional alert conditions (decoding of a new DXCC, new state, etc.),
+and convenient direct access to web services such as callsign lookup.
+
+image::jtalert.png[align="left",alt="JTAlert-X image"]
+
+* {alarmejt}, by F5JMH, is available only for Linux.  The program keeps
+its own logbook.  It fetches contact information from _WSJT-X_ and
+provides visual alerts for new DXCC entities and grid squares on the
+current band, as well as other options.
+
+* {jtbridge}, by SM0THU, is available for OS X. It works together with
+logging applications Aether, MacLoggerDX, RUMlog or RUMlogNG.  It
+checks QSO and QSL status of the call and DXCC entity, as well as many
+other features.

doc/user_guide/en/decoder_notes.adoc

@@ -0,0 +1,104 @@
+=== AP Decoding
+
+The _WSJT-X_ decoders for QRA64 and FT8 include optional procedures
+that use naturally accumulating information during a minimal QSO.
+This _a priori_ (AP) information increases sensitivity of the decoder
+by up to 4 dB, at the cost of a slightly higher rate of false decodes.
+
+For example: when you decide to answer a CQ, you already know your own
+callsign and that of your potential QSO partner.  The software
+therefore "`knows`" what to expect for 57 of the 72 message bits (28
+bits for each of two callsigns, 1 bit for message type) in the next
+received message.  The decoder's task can thus be reduced to
+determining the remaining 15 bits of the message and ensuring that the
+resulting solution is reliable.
+
+AP decoding starts by setting AP bits to the hypothesized values, as
+if they had been received correctly.  We then determine whether the
+remaining message and parity bits are consistent with the hypothesized
+AP bits, with a specified level of confidence.  Successful AP decodes
+are labeled with an end-of-line indicator of the form `aP`, where `P`
+is one of the single-digit AP decoding types listed in Table 1.  For
+example, `a2` indicates that the successful decode used MyCall as
+hypothetically known information.
+
+[[AP_INFO_TABLE]]
+.AP information types
+[width="35%",cols="h10,<m20",frame=topbot,options="header"]
+|===============================================
+|P | Message components
+|1 | CQ   &#160; &#160;   ?   &#160; &#160;   ? 
+|2 | MyCall &#160; &#160; ?   &#160; &#160;   ? 
+|3 | MyCall DxCall &#160; &#160;  ? 
+|4 | MyCall DxCall RRR
+|5 | MyCall DxCall 73
+|6 | MyCall DxCall RR73
+|===============================================
+
+If a codeword is found that is judged to have high (but not
+overwhelmingly high) probability of being correct, a `?` character is
+appended when the decoded message is displayed.  To avoid misleading
+spots of occasional false decodes, messages so marked are not
+forwarded to {pskreporter}.
+
+Table 2 lists the six possible QSO states that are tracked by the
+_WSJT-X_ auto-sequencer, along with the type of AP decoding that would
+be attempted in each state.
+
+[[AP_DECODING_TYPES_TABLE]]
+.AP decoding types for each QSO state
+[width="35%",cols="h10,<m20",frame=topbot,options="header"]
+|===========================================
+|State        |AP type
+|CALLING      |   1, 2
+|REPLYING     |   2, 3
+|REPORT       |   2, 3
+|ROGER_REPORT |   3, 4, 5, 6
+|ROGERS       |   3, 4, 5, 6
+|SIGNOFF      |   3, 1, 2
+|===========================================
+
+
+=== Decoded Lines
+
+Displayed information accompanying decoded messages generally includes UTC,
+signal-to-noise ratio in dB, time offset DT in seconds, and
+audio frequency in Hz.  Some modes include additional information such
+as frequency offset from nominal (DF), frequency drift (Drift or F1),
+or distance (km or mi).
+
+There may also be some cryptic characters with special meanings
+summarized in the following Table:
+
+[[DECODED_LINES_TABLE]]
+.Notations used on decoded text lines
+[width="50%",cols="h,3*^",frame=topbot,options="header"]
+|===========================================
+|Mode    |Mode character|Sync character|End of line information
+|FT8     | ~            |      | ? &#160; aP
+|JT4     | $            | *, # | f, fN, dNC
+|JT9     | @            |      |
+|JT65    | #            |      |
+|JT65 VHF| #            | *, # | f, fN, dNC
+|QRA64   | :            | *    | R
+|ISCAT   |              | *    | M  N  C  T
+|MSK144  | &            |      | N  H  E
+|===========================================
+Sync character::
+ `*` - Normal sync +
+ `#` - Alternate sync
+
+End of line information::
+ `?` - Decoded with lower confidence +
+ `a` - Decoded with aid of some a priori (AP) information +
+ `C` - Confidence indicator [ISCAT and Deep Search; (0-9,*)] +
+ `d` - Deep Search algorithm +
+ `E` - Size of MSK eye diagram opening - if negative, the eye is closed + 
+ `f` - Franke-Taylor or Fano algorithm +
+ `H` - Number of bit errors corrected +
+ `M` - Message length (characters) +
+ `N` - Number of Rx intervals or frames averaged +
+ `P` - Number indicating type of AP information (Table 1, above) +
+ `R` - Return code from QRA64 decoder +
+ `T` - Length of analyzed region (s)
+

doc/user_guide/en/docinfo.html

@@ -0,0 +1,17 @@
+<style>
+  html, body {
+  font-size: 90%;
+  }
+
+  body {
+  font-family: Arial, Helvetica, sans-serif;
+  }
+
+  h1, h2, h3, h4, h5, h6 {
+  font-family: Georgia, "Times New Roman", Times, serif;
+  }
+
+  a:visited {
+  color: purple;
+  }
+</style>

doc/user_guide/en/faq.adoc

@@ -0,0 +1,77 @@
+////
+Questions:
+ Should be short one liners ending with ?::
+ If your question is too long for one line, consider multiple questions or rephrase
+
+Answers:
+ Can be bullet or paragraphs. Bullets make for easier reading.
+
+Bullet Usage:
+ *  = a circle bullet single intent
+ ** = circle bullet double indent
+ .  = should be avoided as the questions are numbered
+ .. = bullet a, b, c, and so on, double indent
+
+Alternatives: Use a * Bullet, followed by .. for example, then have
+a multi-section answer using the * as the section header
+ 
+ * Section Header 1
+ .. Possible Answer a
+ .. Possible Answer b
+ * Section Header 2
+ .. Possible Answer a
+ .. Possible Answer b
+ 
+Link Usage:
+ Use the common/links.adoc for href links to maintain consistency. Try to avoid
+ apostrophes ` or ' as it breaks AsciiDoc syntax without special escaping 
+ and they do not translate into other languages well.
+
+////
+[qanda]
+My displayed spectrum is flatter when I do not check the *Flatten* box. What's wrong?::
+
+_WSJT-X_ does not expect a steep filter edge within the displayed
+passband. Use a wider IF filter or reduce the displayed passband by
+decreasing *Bins/Pixel*, increasing *Start*, or reducing the width of
+the *Wide Graph*.  You might also choose to re-center the filter
+passband, if such control is available.
+
+How should I configure _WSJT-X_ to run multiple instances?::
+
+Start _WSJT-X_ from a command-prompt window, assigning each instance a
+unique identifier as in the following two-instance example.  This
+procedure will isolate the *Settings* file and the writable file
+location for each instance of _WSJT-X_.
+
+ wsjtx --rig-name=TS2000
+ wsjtx --rig-name=FT847
+
+When setting up rig control through _OmniRig_, something goes wrong when I click *Test CAT*.  What can I do about it?::
+
+_OmniRig_ apparently has a bug that appears when you click *Test CAT*.
+Forget using *Test CAT* and just click *OK*.  _OmniRig_ then behaves
+normally.
+
+I am using _WSJT-X_ with _Ham Radio Deluxe_.  All seems well until I start HRD Logbook or DM780 running in parallel; then CAT control becomes unreliable.::
+
+You may see delays up to 20 seconds or so in frequency changes or
+other radio commands, due to a bug in HRD.  HRD folks are aware of the
+problem, and are working to resolve it.
+
+I am running _WSJT-X_ under Ubuntu.  The program starts, but menu bar is missing from the top of the main window and the hot-keys don't work.::
+
+Ubuntu's new "`Unity`" desktop puts the menu for the currently active
+window at the top of the primary display screen.  You can restore menu
+bars to their traditional locations by typing the following in a
+command-prompt window:
+
+ sudo apt remove appmenu-qt5
+
++
+Alternatively, you can disable the common menu bar for just _WSJT-X_
+by starting the application with the environment variable
+QT_QPA_PLATFORMTHEME set to empty (the space after the '=' character
+is necessary):
+
+ QT_QPA_PLATFORMTHEME= wsjtx

doc/user_guide/en/font-sizes.adoc

@@ -0,0 +1,15 @@
+// Status=review
+
+- You can control the program's font sizes by using a text editor
+(e.g., Windows Notepad or similar) to create a one-line file named
++fonts.txt+ in the _WSJT-X_ installation directory. Enter a single
+line of text with four numbers separated by spaces.  The first two
+numbers control the font size (in points) and weight (on a 0 – 100
+scale) of most labels on the user interface. The last two numbers
+control size and weight of text in the *Band Activity* and *Rx
+Frequency* windows.
+
+- By default the four numbers are "`8 50 10 50`". If you need larger
+fonts in the user interface and bold text in the decode windows, try
+something like "`10 50 12 100`" (without the quotes).
+

doc/user_guide/en/install-from-source.adoc

@@ -0,0 +1,29 @@
+// Status=review
+
+Source code for _WSJT-X_ is available from a public repository at
+{devsvn}. To compile the program you will need to install at least the
+following packages:
+
+- Subversion 1.8 or later
+- Qt 5.2 or later
+- g++ 4.8 or later
+- gfortran 4.8 or later
+- fftw3
+- MinGW (for Windows only)
+
+Source code for _WSJT-X_ v{VERSION} can be downloaded with the command:
+
+=====
+svn co svn://svn.code.sf.net/p/wsjt/wsjt/tags/wsjtx-{VERSION}
+=====
+
+and for the current development branch,
+
+=====
+svn co svn://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx
+=====
+
+If you are interested in contributing to the development and
+documentation of _WSJT_ and its sister programs, please join the
+developer's email list {devmail} and let us know of your areas of
+interest.

doc/user_guide/en/install-linux.adoc

@@ -0,0 +1,65 @@
+// Status=review
+
+Debian, Ubuntu, and other Debian-based systems including Raspbian:
+
+* 32-bit: {debian32}
+- To install:
++
+[example]
+sudo dpkg -i wsjtx_{VERSION}_i386.deb
+
+- Uninstall:
++
+[example]
+sudo dpkg -P wsjtx
+
+* 64-bit: {debian64}
+- To install:
++
+[example]
+sudo dpkg -i wsjtx_{VERSION}_amd64.deb
+
+* 64-bit: {raspbian}
+- To install:
++
+[example]
+sudo dpkg -i wsjtx_{VERSION}_armhf.deb
+
+- Uninstall:
++
+[example]
+sudo dpkg -P wsjtx
+
+You may also need to execute the following command in a terminal:
+
+[example]
+sudo apt install libqt5multimedia5-plugins libqt5serialport5 libfftw3-single3
+
+Fedora, Red Hat, and other rpm-based systems:
+
+* 32-bit: {fedora32}
+- To install:
++
+[example]
+sudo rpm -i wsjtx-{VERSION}-i686.rpm
+
+- Uninstall:
++
+[example]
+sudo rpm -e wsjtx
+
+* 64-bit: {fedora64}
+- To install:
++
+[example]
+sudo rpm -i wsjtx-{VERSION}-x86_64.rpm
+
+- Uninstall:
++
+[example]
+sudo rpm -e wsjtx
+
+You may also need to execute the following command in a terminal:
+
+[example]
+sudo dnf install fftw-libs-single qt5-qtmultimedia qt5-qtserialport 

doc/user_guide/en/install-mac.adoc

@@ -0,0 +1,20 @@
+// These instructions are up-to-date for WSJT-X v1.8
+
+*OS X 10.9* and later: Download the file {osx} to your desktop,
+double-click on it and consult its `ReadMe` file for important
+installation notes.  
+
+If you have already installed a previous version, you can retain it by
+changing its name in the *Applications* folder (say, from _WSJT-X_ to
+_WSJT-X_1.7_).  You can then proceed to the installation phase.
+
+Take note also of the following:
+
+* Use the Mac's *Audio MIDI Setup* utility to configure your sound
+card for 48000 Hz, two-channel, 16-bit format.
+
+* Use *System Preferences* to select an external time source to keep
+your system clock synchronized to UTC.
+
+* To uninstall simply drag the _WSJT-X_ application from *Applications* 
+to the *Trash Can*. 

doc/user_guide/en/install-windows.adoc

@@ -0,0 +1,34 @@
+// Status=review
+
+Download and execute the package file {win32}, following these
+instructions:
+
+- Install _WSJT-X_ into its own directory, for example `C:\WSJTX` or
+`C:\WSJT\WSJTX`, rather than the conventional location
+`C:\Program Files\WSJTX`.
+
+- All program files relating to _WSJT-X_ will be stored in the chosen
+installation directory and its subdirectories. 
+
+- Logs and other writeable files will normally be found in the 
+directory +
+`C:\Users\<username>\AppData\Local\WSJT-X`.
+
+TIP: Your computer may be configured so that this directory is
+"`invisible`".  It's there, however, and accessible.  An alternative
+(shortcut) directory name is `%LOCALAPPDATA%\WSJT-X\`.
+
+- The built-in Windows facility for time synchronization is usually
+not adequate. We recommend the program _Meinberg NTP_ (see {ntpsetup}
+for downloading and installation instructions) or _Dimension 4_ from
+{dimension4}.
+
+- _WSJT-X_ 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* tabs. Click on *Properties*, then
+*Advanced*, and select *16 bit, 48000 Hz (DVD Quality)*.
+
+- You can uninstall _WSJT-X_ by clicking its *Uninstall* link in the
+Windows *Start* menu, or by using *Uninstall a Program* on the
+Windows Control Panel.

doc/user_guide/en/introduction.adoc

@@ -0,0 +1,64 @@
+// Status=review
+
+_WSJT-X_ 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 "`**W**eak **S**ignal communication by
+K1**JT**,`" while the suffix "`-X`" indicates that _WSJT-X_ started as
+an extended and experimental branch of the program
+_WSJT_.
+
+_WSJT-X_ Version 1.8 offers nine different protocols or modes: *FT8*,
+*JT4*, *JT9*, *JT65*, *QRA64*, *ISCAT*, *MSK144*, *WSPR*, and *Echo*.
+The first five are designed for making reliable QSOs under extreme
+weak-signal conditions. They use nearly identical message structure
+and source encoding.  JT65 and QRA64 were designed for EME
+("`moonbounce`") on the VHF/UHF bands and have also proven very
+effective for worldwide QRP communication on the HF bands.  QRA64 has
+a number of advantages over JT65, including better performance on the
+very weakest signals.  We imagine that over time it may replace JT65
+for EME use.  JT9 was originally designed for the LF, MF, and lower HF
+bands.  Its submode JT9A is 2 dB more sensitive than JT65 while using
+less than 10% of the bandwidth.  JT4 offers a wide variety of tone
+spacings and has proven highly effective for EME on microwave bands up
+to 24 GHz.  These four "`slow`" 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.  FT8 is operationally
+similar but four times faster (15-second T/R sequences) and less
+sensitive by a few dB.  On the HF bands, world-wide QSOs are possible
+with any of these modes using power levels of a few watts (or even
+milliwatts) and compromise antennas.  On VHF bands and higher, QSOs
+are possible (by EME and other propagation types) at signal levels 10
+to 15 dB below those required for CW.
+
+*ISCAT*, *MSK144*, and optionally submodes *JT9E-H* are "`fast`"
+protocols designed to take advantage of brief signal enhancements from
+ionized meteor trails, aircraft scatter, and other types of scatter
+propagation. These modes use timed sequences of 5, 10, 15, or 30 s
+duration.  User messages are transmitted repeatedly at high rate (up
+to 250 characters per second, for MSK144) to make good use of the
+shortest meteor-trail reflections or "`pings`".  ISCAT uses free-form
+messages up to 28 characters long, while MSK144 uses the same
+structured messages as the slow modes and optionally an abbreviated
+format with hashed callsigns.  
+
+*WSPR* (pronounced "`whisper`") stands for **W**eak **S**ignal
+**P**ropagation **R**eporter.  The WSPR protocol was designed for probing
+potential propagation paths using low-power transmissions. WSPR
+messages normally carry the transmitting station’s callsign, grid
+locator, and transmitter power in dBm, and they can be decoded at
+signal-to-noise ratios as low as -28 dB in a 2500 Hz bandwidth.  WSPR
+users with internet access can automatically upload reception
+reports to a central database called {wsprnet} that provides a mapping
+facility, archival storage, and many other features.
+
+*Echo* mode allows you to detect and measure your own station's echoes
+from the moon, even if they are far below the audible threshold.
+
+_WSJT-X_ provides spectral displays for receiver passbands as wide as
+5 kHz, flexible rig control for nearly all modern radios used by
+amateurs, and a wide variety of special aids such as automatic Doppler
+tracking for EME QSOs and Echo testing.  The program runs equally well
+on Windows, Macintosh, and Linux systems, and installation packages
+are available for all three platforms.
+

doc/user_guide/en/logging.adoc

@@ -0,0 +1,47 @@
+A basic logging facility in _WSJT-X_ saves QSO information to files
+named `wsjtx.log` (in comma-separated text format) and `wsjtx_log.adi`
+(in standard ADIF format).  These files can be imported directly into
+other programs, for example spreadsheets and popular logging programs.
+As described in the <<INSTALL,Installation>> and <<PLATFORM,Platform
+Dependencies>> sections, different operating systems may place your
+local log files in different locations.  You can always navigate to
+them directly by selecting *Open log directory* from the *File* menu.
+
+More elaborate logging capabilities are supported by third party
+applications like {jtalert}, which can log QSOs automatically to other
+applications including {hrd}, {dxlsuite}, and {log4om}.  
+
+The program option *Show DXCC entity and worked before status*
+(selectable on the *Settings | General* tab) is intended mostly for
+use on non-Windows platforms, where {jtalert} is not available.  When
+this option is checked _WSJT-X_ appends some additional information to
+all CQ messages displayed in the _Band Activity_ window.  The name of
+the DXCC entity is shown, abbreviated if necessary.  Your "`worked
+before`" status for this callsign (according to log file
+`wsjtx_log.adi`) is flagged with a single character and a change of
+background color, as follows:
+
+[horizontal]
+!::  Default color bright purple: New DXCC entity
+~::  Light pink: You have already worked this DXCC entity but not 
+this station
+ ::  Green: You have previously worked the calling station
+
+In this respect the program does not distinguish between modes, but it
+does differentiate between bands.
+
+_WSJT-X_ includes a built-in `cty.dat` file containing DXCC prefix
+information.  Updated files can be downloaded from the {cty_dat} web
+site when required.  If an updated `cty.dat` is present in the logs
+folder and readable, it will be used in preference to the built-in
+one.
+
+The log file `wsjtx_log.adi` is updated whenever you log a QSO from
+_WSJT-X_.  (Keep in mind that if you erase this file you will lose all
+"`worked before`" information.)  You can append or overwrite the
+`wsjtx_log.adi` file by exporting your QSO history as an ADIF file
+from another logging program.  Turning *Show DXCC entity and worked
+before status* off and then on again will cause _WSJT-X_ to re-read
+the log file.  Very large log files may cause _WSJT-X_ to slow down
+when searching for calls.
+

doc/user_guide/en/make-qso.adoc

@@ -0,0 +1,214 @@
+// Status=review
+=== Standard Exchange
+By longstanding tradition, a minimally valid QSO requires the exchange
+of callsigns, a signal report or some other information, and
+acknowledgments.  _WSJT-X_ is designed to facilitate making such
+minimal QSOs using short, structured messages. The process works best
+if you use these formats and follow standard operating practices. The
+recommended basic QSO goes something like this:
+
+ CQ K1ABC FN42                          #K1ABC calls CQ
+                   K1ABC G0XYZ IO91     #G0XYZ answers
+ G0XYZ K1ABC –19                        #K1ABC sends report
+                   K1ABC G0XYZ R-22     #G0XYZ sends R+report
+ G0XYZ K1ABC RRR                        #K1ABC sends RRR
+                   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, R plus a signal report, or the final acknowledgements
+RRR or 73.  These messages are compressed and encoded in a highly
+efficient and reliable way.  In uncompressed form (as displayed
+on-screen) they may contain as many as 22 characters.
+
+*Signal reports* are specified as signal-to-noise ratio (S/N) in dB,
+using a standard reference noise bandwidth of 2500 Hz.  Thus, in the
+example message above, K1ABC is telling G0XYZ that his
+signal is 19 dB below the noise power in bandwidth 2500 Hz.  In the
+message at 0004, G0XYZ acknowledges receipt of that report and
+responds with a –22 dB signal report.  JT65 reports are constrained to
+lie in the range –30 to –1 dB, and values are significantly compressed
+above about -10 dB.  JT9 supports the extended range –50 to +49 dB and
+assigns more reliable numbers to relatively strong signals.
+
+NOTE: Signals become visible on the waterfall around S/N = –26 dB and
+audible (to someone with very good hearing) around –15 dB. Thresholds
+for decodability are around -20 dB for FT8, -23 dB for JT4, –25 dB for
+JT65, –27 dB for JT9.
+
+NOTE: Several options are available for circumstances where fast QSOs
+are desirable.  Double-click the *Tx1* control under _Now_ or _Next_
+to toggle use of the Tx2 message rather than Tx1 to start a QSO.
+Similarly, double-click the *Tx4* control to toggle between sending
+`RRR` and `RR73` in that message.  The `RR73` message should be used
+only if you are reasonably confident that no repititions will be
+required.
+
+=== Free-Text Messages
+
+Users often add some friendly chit-chat at the end of a QSO.
+Free-format messages such as "`TNX ROBERT 73`" or "`5W VERT 73 GL`"
+are supported, up to a maximum of 13 characters, including spaces.  In
+general you should avoid the character / in free-text messages, as the
+program may then try to interpret your construction as part of a
+compound callsign.  It should be obvious that the JT4, JT9, and JT65
+protocols are not designed or well suited for extensive conversations
+or rag-chewing.
+
+=== Auto-Sequencing
+
+The slow modes JT4, JT9, JT65, and QRA64 allow nearly 10 seconds at
+the end of each one-minute receiving sequence -- enough time for you
+to inspect decoded messages and decide how to reply.  The 15-second
+T/R cycles of FT8 allow only about two seconds for this task, which is
+often not enough.  For this reason a basic auto-sequencing feature is
+offered. Check *Auto Seq* on the main window to enable this feature:
+
+image::auto-seq.png[align="center",alt="AutoSeq"]
+
+When calling CQ you may also choose to check the box *Call 1st*.
+_WSJT-X_ will then respond automatically to the first decoded
+responder to your CQ.
+
+NOTE: When *Auto-Seq* is enabled the program de-activates *Enable Tx*
+at the end of each QSO.  It is not intended that _WSJT-X_ should make
+fully automated QSOs.
+
+=== VHF Contest Mode
+
+A special *NA VHF Contest* mode can be activated for FT8 and MSK144
+modes by checking a box on the main window.  This mode is configured
+especially for contests in which four-character grid locators are the
+required exchange.  When *NA VHF Contest* mode is active, the standard
+QSO sequence looks like this:
+
+ CQ K1ABC FN42
+                      K1ABC W9XYZ EN37
+ W9XYZ K1ABC R FN42
+                      K1ABC W9XYZ RRR
+ W9XYZ K1ABC 73
+
+In contest circumstances K1ABC might choose to call CQ again rather
+than sending 73 for his third transmission.
+
+IMPORTANT: Do not use VHF Contest Mode on an HF band or in conditions
+where worldwide propagation is available.  See
+<<PROTOCOL_OVERVIEW,Protocol Specifications>> for further details.
+
+[[COMP-CALL]] 
+=== Compound Callsigns
+
+Compound callsigns such as xx/K1ABC or K1ABC/x are handled in
+one of two possible ways:
+
+.Messages containing Type 1 compound callsigns
+
+A list of about 350 of the most common prefixes and suffixes can be
+displayed from the *Help* menu.  A single compound callsign involving
+one item from this list can be used in place of the standard third
+word of a message (normally a locator, signal report, RRR, or 73).
+The following examples are all acceptable messages containing *Type 1*
+compound callsigns:
+
+ CQ ZA/K1ABC
+ CQ K1ABC/4
+ ZA/K1ABC G0XYZ
+ G0XYZ K1ABC/4
+
+The following messages are _not_ valid, because a third word is not
+permitted in any message containing a *Type 1* compound callsign:
+
+ ZA/K1ABC G0XYZ -22        #These messages are invalid; each would 
+ G0XYZ K1ABC/4 73          # be sent without its third "word"
+
+A QSO between two stations using *Type 1* compound-callsign messages
+might look like this:
+
+ CQ ZA/K1ABC
+                     ZA/K1ABC G0XYZ
+ G0XYZ K1ABC –19
+                     K1ABC G0XYZ R–22
+ G0XYZ K1ABC RRR
+                     K1ABC G0XYZ 73
+
+Notice that the full compound callsign is sent and received in the
+first two transmissions.  After that, the operators omit the add-on
+prefix or suffix and use the standard structured messages.
+
+.Type 2 Compound-Callsign Messages
+
+Prefixes and suffixes _not_ found in the displayable short list are
+handled by using *Type 2* compound callsigns.  In this case the
+compound callsign must be the second word in a two- or three-word
+message, and the first word must be CQ, DE, or QRZ.  Prefixes can be 1
+to 4 characters, suffixes 1 to 3 characters.  A third word conveying a
+locator, report, RRR, or 73 is permitted.  The following are valid 
+messages containing *Type 2* compound callsigns:
+
+ CQ W4/G0XYZ FM07
+ QRZ K1ABC/VE6 DO33
+ DE W4/G0XYZ FM18
+ DE W4/G0XYZ -22
+ DE W4/G0XYZ R-22
+ DE W4/G0XYZ RRR
+ DE W4/G0XYZ 73
+
+In each case, the compound callsign is treated as *Type 2* because the
+add-on prefix or suffix is _not_ one of those in the fixed list.  Note
+that a second callsign is never permissible in these messages.
+
+NOTE: During a transmission your outgoing message is displayed in the
+first label on the *Status Bar* and shown exactly as another station
+will receive it.  You can check to see that you are actually
+transmitting the message you wish to send.
+
+QSOs involving *Type 2* compound callsigns might look like either
+of the following sequences:
+
+ CQ K1ABC/VE1 FN75
+                     K1ABC G0XYZ IO91
+ G0XYZ K1ABC –19
+                     K1ABC G0XYZ R–22
+ G0XYZ K1ABC RRR
+                     K1ABC/VE1 73
+
+
+ CQ K1ABC FN42
+                     DE G0XYZ/W4 FM18
+ G0XYZ K1ABC –19
+                     K1ABC G0XYZ R–22
+ G0XYZ K1ABC RRR
+                     DE G0XYZ/W4 73
+
+Operators with a compound callsign use its full form when calling CQ
+and possibly also in a 73 transmission, as may be required by
+licensing authorities.  Other transmissions during a QSO may use the
+standard structured messages without callsign prefix or suffix. 
+
+TIP: If you are using a compound callsign, you may want to
+experiment with the option *Message generation for type 2 compound
+callsign holders* on the *Settings | General* tab, so that messages
+will be generated that best suit your needs.
+
+=== Pre-QSO Checklist
+
+Before attempting your first QSO with one of the WSJT modes, be sure
+to go through the <<TUTORIAL,Basic Operating Tutorial>> above as well
+as 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 to UTC within ±1 s
+
+- Audio input and output devices configured for sample rate 48000 Hz,
+16 bits
+
+- Radio set to *USB* (upper sideband) mode
+
+- Radio filters centered and set to widest available passband (up to 5 kHz).
+
+TIP: Remember that in many circumstances FT8, JT4, JT9, JT65, and WSPR
+do not require high power. Under most HF propagation conditions, QRP
+is the norm.

doc/user_guide/en/measurement_tools.adoc

@@ -0,0 +1,226 @@
+=== Frequency Calibration
+
+Many _WSJT-X_ capabilities depend on signal-detection bandwidths no
+more than a few Hz.  Frequency accuracy and stability are therefore
+unusually important.  We provide tools to enable accurate frequency
+calibration of your radio, as well as precise frequency measurement of
+on-the-air signals.  The calibration procedure works by automatically
+cycling your CAT-controlled radio through a series of preset
+frequencies of carrier-based signals at reliably known frequencies,
+measuring the error in dial frequency for each signal.
+
+You will probably find it convenient to define and use a special
+<<CONFIG-MENU,Configuration>> dedicated to frequency calibration.
+Then complete the following steps, as appropriate for your system.
+
+- Switch to FreqCal mode
+
+- In the _Working Frequencies_ box on the *Settings -> Frequencies*
+tab, delete any default frequencies for *FreqCal* mode that are not
+relevant for your location.  You may want to replace some of them with
+reliably known frequencies receivable at your location.
+
+TIP: We find major-city AM broadcast stations generally serve well as
+frequency calibrators at the low frequency end of the spectrum.  In
+North America we also use the standard time-and-frequency broadcasts
+of WWV at 2.500, 5.000, 10.000, 15.000, and 20.000 MHz, and CHU at
+3.330, 7.850, and 14.670 MHz.  Similar shortwave signals are available
+in other parts of the world.
+
+- In most cases you will want to start by deleting any existing file
+`fmt.all` in the directory where your log files are kept.
+
+- To cycle automatically through your chosen list of calibration
+frequencies, check *Execute frequency calibration cycle* on the
+*Tools* menu.  _WSJT-X_ will spend 30 seconds at each
+frequency. Initially no measurement data is saved to the `fmt.all`
+file although it is displayed on screen, this allows you to check you
+current calibration parameters.
+
+- During the calibration procedure, the radio's USB dial frequency is
+offset 1500 Hz below each *FreqCal* entry in the default frequencies
+list.  As shown in the screen shot below, detected signal carriers
+therefore appear at about 1500 Hz in the _WSJT-X_ waterfall.
+
+- To start a measurement session check the *Measure* option and let
+the calibration cycle run for at least one complete sequence. Note
+that, while measuring, any existing calibration parameters are
+automatically disabled so you may have to increase the *FTol* range if
+your rig is off freqeuncy by more than a few Hertz in order to capture
+valid measurements.
+
+image::FreqCal.png[align="left",alt="FreqCal"]
+
+With modern synthesized radios, small measured offsets from 1500 Hz
+will exhibit a straight-line dependence on frequency.  You can
+approximate the calibration of your radio by simply dividing the
+measured frequency offset (in Hz) at the highest reliable frequency by
+the nominal frequency itself (in MHz).  For example, the 20 MHz
+measurement for WWV shown above produced a measured tone offset of
+24.6 Hz, displayed in the _WSJT-X_ decoded text window.  The resulting
+calibration constant is 24.6/20=1.23 parts per million.  This number
+may be entered as *Slope* on the *settings -> Frequencies* tab.
+
+A more precise calibration can be effected by fitting the intercept
+and slope of a straight line to the whole sequence of calibration
+measurements, as shown for these measurements in the graph plotted
+below.  Software tools for completing this task are included with the
+_WSJT-X_ installation, and detailed instructions for their use are
+available at https://physics.princeton.edu/pulsar/k1jt/FMT_User.pdf.
+
+Using these tools and no specialized hardware beyond your
+CAT-interfaced radio, you can calibrate the radio to better than 1 Hz
+and compete very effectively in the ARRL's periodic Frequency
+Measuring Tests.
+
+image::FreqCal_Graph.png[align="left",alt="FreqCal_Graph"]
+
+After running *Execute frequency calibration cycle* at least once with
+good results, check and edit the file `fmt.all` in the log directory
+and delete any spurious or outlier measurements.  The line-fitting
+procedure can then be carried out automatically by clicking *Solve for
+calibration parameters* on the *Tools* menu.  The results will be
+displayed as in the following screen shot.  Estimated uncertainties
+are included for slope and intercept; `N` is the number of averaged
+frequency measurements included in the fit, and `StdDev` is the root
+mean square deviation of averaged measurements from the fitted
+straight line. If the solution seems valid you will be offered an
+*Apply* button to push that will automatically set the calibration
+parameters in *Settings -> Frequencies -> Frequency Calibration*.
+
+image::FreqCal_Results.png[align="center",alt="FreqCal_Results"]
+
+For a quick visual check of the resulting calibration, stay in
+*FreqCal* mode with the *Measure* option cleared. _WSJT-X_ will show
+the adjusted results directly on the waterfall and the displayed
+records.
+
+=== Reference Spectrum
+
+_WSJT-X_ provides a tool that can be used to determine the detailed
+shape of your receiver's passband.  Disconnect your antenna or tune to
+a quiet frequency with no signals.  With _WSJT-X_ running in one of
+the slow modes, select *Measure reference spectrum* from the *Tools*
+menu.  Wait for about a minute and then hit the *Stop* button.  A file
+named `refspec.dat` will appear in your log directory.
+
+ [ ... more to come ... ]
+
+=== Phase Equalization
+
+*Measure phase response* under the *Tools* menu is for advanced MSK144
+users. Phase equalization is used to compensate for group-delay
+variation across your receiver passband. Careful application of this
+facility can reduce intersymbol interference, resulting in improved
+decoding sensitivity.  If you use a software-defined receiver with
+linear-phase filters there is no need to apply phase equalization.
+
+After a frame of received data has been decoded, *Measure phase
+response* generates an undistorted audio waveform equal to the one
+generated by the transmitting station.  Its Fourier transform is then
+used as a frequency-dependent phase reference to compare with the
+phase of the received frame's Fourier coefficients.  Phase differences
+between the reference spectrum and received spectrum will include
+contributions from the originating station's transmit filter, the
+propagation channel, and filters in the receiver. If the received
+frame originates from a station known to transmit signals having
+little phase distortion (say, a station known to use a properly
+adjusted software-defined-transceiver) and if the received signal is
+relatively free from multipath distortion so that the channel phase is
+close to linear, the measured phase differences will be representative
+of the local receiver's phase response.
+
+Complete the following steps to generate a phase equalization curve:
+
+- Record a number of wav files that contain decodable signals from
+your chosen reference station. Best results will be obtained when the
+signal-to-noise ratio of the reference signals is 10 dB or greater.
+
+- Enter the callsign of the reference station in the DX Call box.
+
+- Select *Measure phase response* from the *Tools* menu, and open each
+of the wav files in turn. The mode character on decoded text lines
+will change from `&` to `^` while _WSJT-X_ is measuring the phase
+response, and it will change back to `&`  after the measurement is
+completed. The program needs to average a number of high-SNR frames to
+accurately estimate the phase, so it may be necessary to process
+several wav files. The measurement can be aborted at any time by
+selecting *Measure phase response* again to toggle the phase
+measurement off.
+
++
+
+When the measurement is complete _WSJT-X_ will save the measured
+phase response in the *Log directory*, in a file with suffix
+".pcoeff". The filename will contain the callsign of the reference
+station and a timestamp, for example `K0TPP_170923_112027.pcoeff`.
+
+- Select *Equalization tools ...* under the *Tools* menu and click the
+*Phase ...* button to view the contents of the *Log directory*. Select
+the desired pcoeff file. The measured phase values will be plotted as
+filled circles along with a fitted red curve labeled "Proposed". This is
+the proposed phase equalization curve. It's a good idea to repeat the
+phase measurement several times, using different wav files for each
+measurement, to ensure that your measurements are repeatable.
+
+- Once you are satisfied with a fitted curve, push the *Apply* button
+to save the proposed response. The red curve will be replaced with a
+light green curve labeled "Current" to indicate that the phase
+equalization curve is now being applied to the received data. Another
+curve labeled "Group Delay" will appear. The "Group Delay" curve shows
+the group delay variation across the passband, in ms. Click the
+*Discard*  button to remove the captured data, leaving only the applied
+phase equalization curve and corresponding group delay curve.
+
+- To revert to no phase equalization, push the *Restore Defaults*
+button followed by the *Apply* button.
+
+The three numbers printed at the end of each MSK144 decode line can be
+used to assess the improvement provided by equalization. These numbers
+are: `N` = Number of frames averaged, `H` = Number of hard bit errors
+corrected, `E` = Size of MSK eye diagram opening.
+
+Here is a decode of K0TPP obtained while *Measure phase response* was measuring
+the phase response:
+
+  103900  17  6.5 1493 ^  WA8CLT K0TPP +07       1  0  1.2
+
+The "^" symbol indicates that a phase measurement is being accumulated
+but is not yet finished. The three numbers at the end of the line
+indicate that one frame was used to obtain the decode, there were no
+hard bit errors, and the eye-opening was 1.2 on a -2 to +2
+scale.  Here's how the same decode looks after phase equalization:
+
+  103900  17  6.5 1493 &  WA8CLT K0TPP +07       1  0  1.6
+
+In this case, equalization has increased the eye opening from 1.2 to
+1.6.  Larger positive eye openings are associated with reduced
+likelihood of bit errors and higher likelihood that a frame will be
+successfully decoded.  In this case, the larger eye-opening tells us
+that phase equalization was successful, but it is important to note
+that this test does not by itself tell us whether the applied phase
+equalization curve is going to improve decoding of signals other than
+those from the reference station, K0TPP.
+
+It's a good idea to carry out before and after comparisons using a
+large number of saved wav files with signals from many different
+stations, to help decide whether your equalization curve improves
+decoding for most signals. When doing such comparisons, keep in mind
+that equalization may cause _WSJT-X_ to successfully decode a frame
+that was not decoded before equalization was applied.  For this
+reason, be sure that the time "T" of the two decodes are the same
+before comparing their end-of-line quality numbers.
+
+When comparing before and after decodes having the same "T", keep in
+mind that a smaller first number means that decoding has improved,
+even if the second and third numbers appear to be "worse". For
+example, suppose that the end-of-line quality numbers before
+equalization are `2 0 0.2` and after equalization `1 5 -0.5`. These
+numbers show improved decoding because the decode was obtained using
+only a single frame after equalization whereas a 2-frame average was
+needed before equalization.  This implies that shorter and/or weaker
+pings could be decodable.
+
+NOTE: Further details on phase equalization and examples of fitted
+phase curves and eye diagrams can be found in the article on MSK144 by
+K9AN and K1JT published in {msk144}.

doc/user_guide/en/new_features.adoc

@@ -0,0 +1,55 @@
+=== New in Version 1.8
+
+For quick reference, here's a short list of features and capabilities
+added to _WSJT-X_ since Version 1.7.0:
+
+- New mode *FT8* designed for fast QSOs
+
+- New tool *FreqCal* for accurate frequency calibration of your radio
+
+- Improved decoding performance for JT65, QRA64, and MSK144
+
+- *SWL* option for third-party decoding short-format MSK144 messages
+
+- Experimental phase equalization for MSK144
+    
+- Options to minimize screen space used by *Main* and *Wide Graph*
+windows
+    
+- New set of suggested default frequencies specific to the three IARU
+regions
+
+- Enhanced scheme for managing table of suggested default operating
+frequencies
+
+- Improved CAT control for many radios, including those controlled
+through Commander or OmniRig
+
+- Bug fixes and minor tweaks to user interface
+
+=== Documentation Conventions
+
+In this manual the following icons call attention to particular types
+of information:
+
+NOTE: *Notes* containing information that may be of interest to
+particuar classes of users.
+
+TIP: *Tips* on program features or capabilities that might otherwise be
+overlooked.
+
+IMPORTANT: *Warnings* about usage that could lead to undesired
+consequences.
+
+=== How You Can Contribute
+
+_WSJT-X_ is part of an open-source project released under the
+{gnu_gpl} (GPL). 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 most
+communication among the developers takes place on the email reflector
+{devmail}.  Bug reports and suggestions for new features, improvements
+to the _WSJT-X_ User Guide, etc., may also be sent to the
+{wsjt_yahoo_group} email reflector.  You must join the relevant group
+before posting to either email list.

doc/user_guide/en/platform-dependencies.adoc

@@ -0,0 +1,41 @@
+// Status=review
+
+A few _WSJT-X_ features behave differently in Windows, Linux, or OS X,
+or may not be relevant to all operating platforms.
+
+.File locations
+* *Windows*
+
+- *Settings:*               %LOCALAPPDATA%\WSJT-X\WSJT-X.ini
+- *Log directory:*          %LOCALAPPDATA%\WSJT-X\
+- *Default save directory:* %LOCALAPPDATA%\WSJT-X\save\
+
+* *Windows, when using "--rig-name=xxx"*
+
+- *Settings:*               %LOCALAPPDATA%\WSJT-X - xxx\WSJT-X - xxx.ini
+- *Log directory:*          %LOCALAPPDATA%\WSJT-X - xxx\
+- *Default save directory:* %LOCALAPPDATA%\WSJT-X - xxx\save\
+
+* *Linux*
+
+- *Settings:*               ~/.config/WSJT-X.ini
+- *Log directory:*          ~/.local/share/WSJT-X/
+- *Default save directory:* ~/.local/share/WSJT-X/save/
+
+* *Linux, when using "--rig-name=xxx"*
+
+- *Settings:*               ~/.config/WSJT-X - xxx.ini
+- *Log directory:*          ~/.local/share/WSJT-X - xxx/
+- *Default save directory:* ~/.local/share/WSJT-X - xxx/save/
+
+* *Macintosh*
+
+- *Settings:*               ~/Library/Preferences/WSJT-X.ini
+- *Log directory:*          ~/Library/Application Support/WSJT-X/
+- *Default save directory:* ~/Library/Application Support/WSJT-X/save/
+
+* *Macintosh, when using "--rig-name=xxx"*
+
+- *Settings:*               ~/Library/Preferences/WSJT-X - xxx.ini
+- *Log directory:*          ~/Library/Application Support/WSJT-X - xxx/
+- *Default save directory:* ~/Library/Application Support/WSJT-X - xxx/save/

doc/user_guide/en/protocols.adoc

@@ -0,0 +1,337 @@
+[[PROTOCOL_OVERVIEW]]
+=== Overview
+
+All QSO modes except ISCAT use structured messages that compress
+user-readable information into fixed-length packets of 72 bits.  Each
+message consists of two 28-bit fields normally used for callsigns and
+a 15-bit field for a grid locator, report, acknowledgment, or 73.  An
+additional bit flags a message containing arbitrary alphanumeric text,
+up to 13 characters.  Special cases allow other information such as
+add-on callsign prefixes (e.g., ZA/K1ABC) or suffixes (e.g., K1ABC/P)
+to be encoded. The basic aim is to compress the most common messages
+used for minimally valid QSOs into a fixed 72-bit length.  Information
+payloads in FT8 include 3 additional bits (75 bits total), with
+definitions yet to be defined.
+
+A standard amateur callsign consists of a one- or two-character
+prefix, at least one of which must be a letter, followed by a digit
+and a suffix of one to three letters. Within these rules, the number
+of possible callsigns is equal to 37×36×10×27×27×27, or somewhat over
+262 million. (The numbers 27 and 37 arise because in the first and
+last three positions a character may be absent, or a letter, or
+perhaps a digit.) Since 2^28^ is more than 268 million, 28 bits are
+enough to encode any standard callsign uniquely. Similarly, the number
+of 4-digit Maidenhead grid locators on earth is 180×180 = 32,400,
+which is less than 2^15^ = 32,768; so a grid locator requires 15 bits.
+
+Some 6 million of the possible 28-bit values are not needed for
+callsigns.  A few of these slots have been assigned to special message
+components such as `CQ`, `DE`, and `QRZ`. `CQ` may be followed by three
+digits to indicate a desired callback frequency. (If K1ABC transmits
+on a standard calling frequency, say 50.280, and sends `CQ 290 K1ABC
+FN42`, it means that s/he will listen on 50.290 and respond there to
+any replies.) A numerical signal report of the form `–nn` or
+`R–nn` can be sent in place of a grid locator.  (As originally
+defined, numerical signal reports `nn` were required to fall between -01
+and -30 dB.  Recent program versions accommodate reports between
+-50 and +49 dB.) A country prefix or portable suffix may be
+attached to one of the callsigns.  When this feature is used the
+additional information is sent in place of the grid locator or by
+encoding additional information into some of the 6 million available
+slots mentioned above.
+
+As a convenience for sending directed CQ messages, the compression
+algorithm supports messages starting with `CQ AA` through `CQ ZZ`.
+These message fragments are encoded internally as if they were the
+callsigns `E9AA` through `E9ZZ`.  Upon reception they are converted
+back to the form `CQ AA` through `CQ ZZ`, for display to the user.
+
+The FT8 and MSK144 modes support a special feature allowing convenient
+transmission and acknowledgment of four-character grid locators, the
+required exchanges in most North American VHF contests.  With this
+Contest Mode enabled, _WSJT-X_ supports messages of the form `W9XYZ
+K1ABC R FN42` by converting the grid locator to that of its
+diametrically opposite point on Earth.  The receiving program
+recognizes a locator implying a distance greater than 10,000 km, does
+the reverse transformation, and inserts the implied "`R`".  Obviously,
+this mode should not be used on the HF bands or under other
+circumstances where world-wide propagation is possible.
+
+To be useful on channels with low signal-to-noise ratio, this kind of
+lossless message compression requires use of a strong forward error
+correcting (FEC) code.  Different codes are used for each mode.
+Accurate synchronization of time and frequency is required between
+transmitting and receiving stations.  As an aid to the decoders, each
+protocol includes a "`sync vector`" of known symbols interspersed with
+the information-carrying symbols.  Generated waveforms for all of the
+_WSJT-X_ modes have continuous phase and constant envelope.
+
+[[SLOW_MODES]]
+=== Slow Modes
+
+[[FT8PRO]]
+==== FT8
+
+Forward error correction (FEC) in FT8 uses a low-density parity check
+(LDPC) code with 75 information bits, a 12-bit cyclic redundancy check
+(CRC), and 87 parity bits making a 174-bit codeword.  It is thus
+called an LDPC (174,87) code.  Synchronization uses 7×7 Costas arrays
+at the beginning, middle, and end of each transmission.  Modulation is
+8-tone frequency-shift keying (8-FSK) at 12000/1920 = 6.25 baud.  Each
+transmitted symbol carries three bits, so the total number of channel
+symbols is 174/3 + 21 = 79.  The total occupied bandwidth is 8 × 6.25
+= 50 Hz.
+
+[[JT4PRO]]
+==== JT4
+
+FEC in JT4 uses a strong convolutional code with constraint length
+K=32, rate r=1/2, and a zero tail. This choice leads to an encoded
+message length of (72+31) x 2 = 206 information-carrying bits.
+Modulation is 4-tone frequency-shift keying (4-FSK) at 11025 / 2520 =
+4.375 baud.  Each symbol carries one information bit (the most
+significant bit) and one synchronizing bit.  The two 32-bit
+polynomials used for convolutional encoding have hexadecimal values
+0xf2d05351 and 0xe4613c47, and the ordering of encoded bits is
+scrambled by an interleaver.  The pseudo-random sync vector is the
+following sequence (60 bits per line):
+
+ 000011000110110010100000001100000000000010110110101111101000
+ 100100111110001010001111011001000110101010101111101010110101
+ 011100101101111000011011000111011101110010001101100100011111
+ 10011000011000101101111010
+
+
+[[JT9PRO]]
+==== JT9
+
+FEC in JT9 uses the same strong convolutional code as JT4: 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 nine-tone frequency-shift keying, 9-FSK at
+12000.0/6912 = 1.736 baud.  Eight tones are used for data, one for
+synchronization. Eight data tones means that three data bits are
+conveyed by each transmitted information symbol. 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.  Tone spacing of
+the 9-FSK modulation for JT9A is equal to the keying rate, 1.736 Hz.
+The total occupied bandwidth is 9 × 1.736 = 15.6 Hz.
+
+[[JT65PRO]]
+==== JT65
+
+A detailed description of the JT65 protocol was published in
+{jt65protocol} for September-October, 2005. A Reed Solomon (63,12)
+error-control code converts 72-bit user messages into sequences of 63
+six-bit information-carrying symbols.  These are interleaved with
+another 63 symbols of synchronizing information according to the
+following pseudo-random sequence:
+
+ 100110001111110101000101100100011100111101101111000110101011001
+ 101010100100000011000000011010010110101010011001001000011111111
+
+
+The synchronizing tone is normally sent in each interval having a
+"`1`" in the sequence. Modulation is 65-FSK at 11025/4096 = 2.692
+baud.  Frequency spacing between tones is equal to the keying rate for
+JT65A, and 2 and 4 times larger for JT65B and JT65C.  For EME QSOs the
+signal report OOO is sometimes used instead of numerical signal
+reports. It is conveyed by reversing sync and data positions in the
+transmitted sequence.  Shorthand messages for RO, RRR, and 73 dispense
+with the sync vector entirely and use time intervals of 16384/11025 =
+1.486 s for pairs of alternating tones. The lower frequency is the
+same as that of the sync tone used in long messages, and the frequency
+separation is 110250/4096 = 26.92 Hz multiplied by n for JT65A, with n
+= 2, 3, 4 used to convey the messages RO, RRR, and 73.
+
+[[QRA64_PROTOCOL]]
+==== QRA64
+
+QRA64 is intended for EME and other extreme weak-signal applications.
+Its internal code was designed by IV3NWV.  The protocol uses a (63,12)
+**Q**-ary **R**epeat **A**ccumulate code that is inherently better
+than the Reed Solomon (63,12) code used in JT65, yielding a 1.3 dB
+advantage. A new synchronizing scheme is based on three 7 x 7 Costas
+arrays.  This change yields another 1.9 dB advantage.
+
+In most respects the current implementation of QRA64 is operationally
+similar to JT65.  QRA64 does not use two-tone shorthand messages, and
+it makes no use of a callsign database.  Rather, additional
+sensitivity is gained by making use of already known information as a
+QSO progresses -- for example, when reports are being exchanged and
+you have already decoded both callsigns in a previous transmission.
+QRA64 presently offers no message averaging capability, though that
+feature may be added.  In early tests, many EME QSOs were made using
+submodes QRA64A-E on bands from 144 MHz to 24 GHz.  
+
+[[SLOW_SUMMARY]]
+==== Summary
+
+Table 2 provides a brief summary parameters for the slow modes in
+_WSJT-X_.  Parameters K and r specify the constraint length and rate
+of the convolutional codes; n and k specify the sizes of the
+(equivalent) block codes; Q is the alphabet size for the
+information-carrying channel symbols; Sync Energy is the fraction of
+transmitted energy devoted to synchronizing symbols; and S/N Threshold
+is the signal-to-noise ratio (in a 2500 Hz reference bandwidth) above
+which the probability of decoding is 50% or higher.
+
+[[SLOW_TAB]]
+.Parameters of Slow Modes
+[width="90%",cols="3h,^3,^2,^1,^2,^2,^2,^2,^2,^2",frame=topbot,options="header"]
+|===============================================================================
+|Mode |FEC Type |(n,k) | Q|Modulation type|Keying rate (Baud)|Bandwidth (Hz)
+|Sync Energy|Tx Duration (s)|S/N Threshold (dB)
+|FT8  |LDPC, r=1/2|(174,87)| 8| 8-FSK| 6.25 | 50.0 | 0.27| 12.6 | -21
+|JT4A |K=32, r=1/2|(206,72)| 2| 4-FSK| 4.375| 17.5 | 0.50| 47.1 | -23
+|JT9A |K=32, r=1/2|(206,72)| 8| 9-FSK| 1.736| 15.6 | 0.19| 49.0 | -27
+|JT65A |Reed Solomon|(63,12) |64|65-FSK| 2.692| 177.6 | 0.50| 46.8 | -25
+|QRA64A|Q-ary Repeat Accumulate|(63,12) |64|64-FSK|1.736|111.1|0.25|48.4| -26
+| WSPR |K=32, r=1/2|(162,50)| 2| 4-FSK| 1.465| 5.9 | 0.50|110.6 | -28
+|===============================================================================
+
+Submodes of JT4, JT9, JT65, and QRA64 offer wider tone spacings for
+circumstances that may require them, such significant Doppler spread.
+Table 3 summarizes the tone spacings, bandwidths, and approximate
+threshold sensitivities of the various submodes when spreading is
+comparable to tone spacing.
+
+[[SLOW_SUBMODES]]
+.Parameters of Slow Submodes
+[width="50%",cols="h,3*^",frame=topbot,options="header"]
+|=====================================
+|Mode  |Tone Spacing  |BW (Hz)|S/N (dB)
+|FT8   |6.25 |  50.0  |-21
+|JT4A  |4.375|  17.5  |-23
+|JT4B  |8.75 |  30.6  |-22
+|JT4C  |17.5 |  56.9  |-21
+|JT4D  |39.375| 122.5 |-20
+|JT4E  |78.75|  240.6 |-19
+|JT4F  |157.5|  476.9 |-18
+|JT4G  |315.0|  949.4 |-17
+|JT9A  |1.736|  15.6  |-27
+|JT9B  |3.472|  29.5  |-26
+|JT9C  |6.944|  57.3  |-25
+|JT9D  |13.889| 112.8 |-24
+|JT9E  |27.778| 224.0 |-23
+|JT9F  |55.556| 446.2 |-22
+|JT9G  |111.111|890.6 |-21
+|JT9H  |222.222|1779.5|-20
+|JT65A |2.692| 177.6  |-25
+|JT65B |5.383| 352.6  |-25
+|JT65C |10.767| 702.5 |-25
+|QRA64A|1.736| 111.1  |-26
+|QRA64B|3.472| 220.5  |-25
+|QRA64C|6.944| 439.2  |-24
+|QRA64D|13.889| 876.7 |-23
+|QRA64E|27.778|1751.7 |-22
+|=====================================
+
+[[FAST_MODES]]
+=== Fast Modes
+
+==== ISCAT
+
+ISCAT messages are free-form, up to 28 characters in length.
+Modulation is 42-tone frequency-shift keying at 11025 / 512 = 21.533
+baud (ISCAT-A), or 11025 / 256 = 43.066 baud (ISCAT-B).  Tone
+frequencies are spaced by an amount in Hz equal to the baud rate.  The
+available character set is:
+
+----
+ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ /.?@-
+----
+
+Transmissions consist of sequences of 24 symbols: a synchronizing
+pattern of four symbols at tone numbers 0, 1, 3, and 2, followed by
+two symbols with tone number corresponding to (message length) and
+(message length + 5), and finally 18 symbols conveying the user's
+message, sent repeatedly character by character.  The message always
+starts with `@`, the beginning-of-message symbol, which is not
+displayed to the user.  The sync pattern and message-length indicator
+have a fixed repetition period, recurring every 24 symbols.  Message
+information occurs periodically within the 18 symbol positions set
+aside for its use, repeating at its own natural length.
+
+For example, consider the user message `CQ WA9XYZ`.  Including the
+beginning-of-message symbol `@`, the message is 10 characters long.
+Using the character sequence displayed above to indicate tone numbers,
+the transmitted message will therefore start out as shown in the first
+line below:
+
+----
+ 0132AF@CQ WA9XYZ@CQ WA9X0132AFYZ@CQ WA9XYZ@CQ W0132AFA9X ...
+ sync##                  sync##                 sync##
+----
+
+Note that the first six symbols (four for sync, two for message
+length) repeat every 24 symbols.  Within the 18 information-carrying
+symbols in each 24, the user message `@CQ WA9XYZ` repeats at its own
+natural length, 10 characters.  The resulting sequence is extended as
+many times as will fit into a Tx sequence.
+
+==== JT9
+
+The JT9 slow modes all use keying rate 12000/6912 = 1.736 baud.  By contrast, with
+the *Fast* setting submodes JT9E-H adjust the keying rate to match the
+increased tone spacings.  Message durations are therefore much
+shorter, and they are sent repeatedly throughout each Tx sequence.
+For details see Table 4, below.
+
+==== MSK144
+
+Standard MSK144 messages are structured in the same way as those in
+the slow modes, with 72 bits of user information.  Forward error
+correction is implemented by first augmenting the 72 message bits with
+an 8-bit cyclic redundancy check (CRC) calculated from the message
+bits. The CRC is used to detect and eliminate most false decodes at
+the receiver. The resulting 80-bit augmented message is mapped to a
+128-bit codeword using a (128,80) binary low-density-parity-check
+(LDPC) code designed by K9AN specifically for this purpose.  Two 8-bit
+synchronizing sequences are added to make a message frame 144 bits
+long.  Modulation is Offset Quadrature Phase-Shift Keying (OQPSK) at
+2000 baud. Even-numbered bits are conveyed over the in-phase channel,
+odd-numbered bits on the quadrature channel.  Individual symbols are
+shaped with half-sine profiles, thereby ensuring a generated waveform
+with constant envelope, equivalent to a Minimum Shift Keying (MSK)
+waveform.  Frame duration is 72 ms, so the effective character
+transmission rate for standard messages is up to 250 cps.
+
+MSK144 also supports short-form messages that can be used after QSO
+partners have exchanged both callsigns.  Short messages consist of 4
+bits encoding R+report, RRR, or 73, together with a 12-bit hash code
+based on the ordered pair of "`to`" and "`from`" callsigns.  Another
+specially designed LDPC (32,16) code provides error correction, and an
+8-bit synchronizing vector is appended to make up a 40-bit frame.
+Short-message duration is thus 20 ms, and short messages can be
+decoded from very short meteor pings.
+
+The 72 ms or 20 ms frames of MSK144 messages are repeated without gaps
+for the full duration of a transmission cycle. For most purposes, a
+cycle duration of 15 s is suitable and recommended for MSK144.
+
+The modulated MSK144 signal occupies the full bandwidth of a SSB
+transmitter, so transmissions are always centered at audio frequency
+1500 Hz. For best results, transmitter and receiver filters should be
+adjusted to provide the flattest possible response over the range
+300Hz to 2700Hz. The maximum permissible frequency offset between you
+and your QSO partner ± 200 Hz.
+
+==== Summary
+
+.Parameters of Fast Modes
+[width="90%",cols="3h,^3,^2,^1,^2,^2,^2,^2,^2",frame="topbot",options="header"]
+|=====================================================================
+|Mode     |FEC Type   |(n,k)   | Q|Modulation Type|Keying rate (Baud)
+|Bandwidth (Hz)|Sync Energy|Tx Duration (s)
+|ISCAT-A  |   -       |  -     |42|42-FSK| 21.5 |  905  | 0.17| 1.176 
+|ISCAT-B  |   -       |  -     |42|42-FSK| 43.1 | 1809  | 0.17| 0.588 
+|JT9E     |K=32, r=1/2|(206,72)| 8| 9-FSK| 25.0 |  225  | 0.19| 3.400 
+|JT9F     |K=32, r=1/2|(206,72)| 8| 9-FSK| 50.0 |  450  | 0.19| 1.700 
+|JT9G     |K=32, r=1/2|(206,72)| 8| 9-FSK|100.0 |  900  | 0.19| 0.850 
+|JT9H     |K=32, r=1/2|(206,72)| 8| 9-FSK|200.0 | 1800  | 0.19| 0.425 
+|MSK144   |LDPC       |(128,80)| 2| OQPSK| 2000 | 2400  | 0.11| 0.072 
+|MSK144 Sh|LDPC       |(32,16) | 2| OQPSK| 2000 | 2400  | 0.20| 0.020 
+|=====================================================================

doc/user_guide/en/settings-advanced.adoc

@@ -0,0 +1,42 @@
+image::settings-advanced.png[align="center",alt="Settings Advanced"]
+
+_JT65 decoding parameters_ 
+
+- *Random erasure patterns* logarithmically scales the number of
+pseudo-random trials used by the Franke-Taylor JT65 decoder.  Larger
+numbers give slightly better sensitivity but take longer.  For most
+purposes a good setting is 6 or 7.
+
+- *Aggressive decoding level* sets the threshold for acceptable
+decodes using Deep Search.  Higher numbers will display results 
+with lower confidence levels.
+
+- Check *Two-pass decoding* to enable a second decoding pass after
+signals producing first-pass decodes have been subtracted from the
+received data stream.
+
+_Miscellaneous_
+
+- Set a positive number in *Degrade S/N of .wav file* to add known
+amounts of pseudo-random noise to data read from a .wav file.  To
+ensure that the resulting S/N degradation is close to the requested
+number of dB, set *Receiver bandwidth* to your best estimate of the
+receiver's effective noise bandwidth.
+
+- Set *Tx delay* to a number larger than the default 0.2 s to create
+a larger delay between execution of a command to enable PTT and onset
+of Tx audio.  
+
+IMPORTANT: For the health of your T/R relays and external
+preamplifier, we strongly recommend using a hardware sequencer and
+testing to make sure that sequencing is correct.
+
+- Check *FT8 and MSK144: NA VHF Contest Mode* to enable generation and
+auto-sequencing of messages using four-character grid locators in
+place of signal reports, as required for most North American VHF
+contests.
+
+- Check *x 2 Tone spacing* to generate Tx audio with twice the normal
+tone spacing.  This feature is intended for use with specialized LF/MF
+transmitters that divide the audio waveform by 2 before further
+processing.

doc/user_guide/en/settings-audio.adoc

@@ -0,0 +1,41 @@
+// Status=review
+
+image::settings-audio.png[align="center",alt="_WSJT-X_ Audio Configuration Screen"]
+
+Select the *Audio* tab to configure your sound system.
+
+- _Soundcard_: Select the audio devices to be used for *Input* and
+*Output*.  Usually the *Mono* settings will suffice, but in special
+cases you can choose *Left*, *Right*, or *Both* stereo channels.
+
+- Be sure that your audio device is configured to sample at 48000 Hz,
+16 bits.
+
+
+IMPORTANT: If you select the audio output device that is also your
+computer's default audio device, be sure to turn off all system sounds
+to prevent inadvertently transmitting them over the air.  
+
+NOTE: Windows Vista and later may configure audio devices using
+the Texas Instruments PCM2900 series CODEC for microphone input rather
+line input.  (This chip is used in many radios with built-in USB
+CODECs, as well as various other audio interfaces.)  If you are using
+such a device, be sure to set the mic level in the Recording Device
+Properties to 0 dB.
+
+- _Save Directory_: _WSJT-X_ can save its received audio sequences as
+`.wav` files.  A default directory for these files is provided; you
+can select another location if desired.
+
+- _AzEl Directory_: A file named `azel.dat` will appear in the
+specified directory.  The file contains information usable by another
+program for automatic tracking of the Sun or Moon, as well as
+calculated Doppler shift for the specified EME path.  The file is
+updated once per second whenever the <<ASTRODATA,Astronomical Data>>
+window is displayed.
+
+- _Remember power settings by band_: Checking either of these will
+cause _WSJT-X_ to remember the *Pwr* slider setting for that operation
+on a band-by-band basis.  For example, when *Tune* is checked here and
+you click the *Tune* button on the main window, the power slider will
+change to the most recent setting used for *Tune* on the band in use.

doc/user_guide/en/settings-colors.adoc

@@ -0,0 +1,5 @@
+image::colors.png[align="center",alt="Colors Screen"]
+
+_WSJT-X_ uses colors to highlight decoded messages containing
+information of particular interest.  Click on one of the buttons to
+select your preferred colors for any message category.

doc/user_guide/en/settings-frequencies.adoc

@@ -0,0 +1,61 @@
+// Status=review
+
+[[FIG_BAND_SETTINGS]]
+image::settings-frequencies.png[align="center",alt="Frequency Screen"]
+
+_Working Frequencies_: By default the *Working Frequencies* table
+contains a list of frequencies conventionally used for modes JT4, JT9,
+JT65, MSK144, WSPR, and Echo.  Conventions may change with time or
+by user preference; you can modify the frequency table as desired.
+
+- To change an existing entry, double-click to edit it, type a desired
+frequency in MHz or select from the drop down list of options, then
+hit *Enter* on the keyboard.  The program will format your changed
+entry appropriately.
+
+- To add a new entry, right-click anywhere on the frequency table and
+select *Insert*.  Enter a frequency in MHz in the pop-up box and
+select the desired mode (or leave the Mode selection as *All*).  Then
+click *OK*.  The table may include more than one frequency for a given
+band.
+
+- To delete an entry, right-click it and select *Delete*, multiple
+entries can be deleted in a single operation by selecting them before
+right-clicking.
+
+- Right-click any entry and click *Reset* button to return the table
+to its default configuration.
+
+Other  more  advanced  maintenance  operations are  available  on  the
+right-click context menu that should be self-explanatory.
+
+_Frequency Calibration_: If you have calibrated your radio using WWV
+or other reliable frequency references, or perhaps with the technique
+described in {fmt_wspr}, enter the measured values for _Intercept_ A
+and _Slope_ B in the equation
+
+ Dial error = A + B*f
+
+where "`Dial error`" and A are in Hz, f is frequency in MHz, and B is
+in parts per million (ppm). Frequency values sent to the radio and
+received from it will then be adjusted so that frequencies displayed
+by _WSJT-X_ are accurate.
+
+_Station Information_: You can save *Band*, *Offset* and *Antenna
+Description* information for your station.  The antenna information
+will be included in reception reports sent to {pskreporter}.  By
+default the frequency offset for each band is zero.  Nonzero offsets
+may be added if (for example) a <<VHF_SETUP,transverter>> is in use.
+
+- To simplify things you might want to delete any unwanted bands --
+for example, bands where you have no equipment.  Then click on a
+*Frequency* entry and type *Ctrl+A* to "`select all,`" and
+drag-and-drop the entries onto the _Station Information_ table.  You
+can then add any transverter offsets and antenna details.
+
+- To avoid typing the same information many times, you can
+drag-and-drop entries between the lines of the _Station Information_
+table.
+
+- When all settings have been configured to your liking, click *OK* to
+dismiss the *Settings* window.

doc/user_guide/en/settings-general.adoc

@@ -0,0 +1,22 @@
+// Status=review
+[[FIG_CONFIG_STATION]]
+image::settings-general.png[align="center",alt="Settings Window"]
+
+Select the *General* tab on the *Settings* window.  Under _Station
+Details_ enter your callsign, grid locator (preferably the 6-character
+locator) and IARU Region number.  Region 1 is Europe, Africa, the
+Middle East, and Northern Asia; Region 2 the Americas; and Region 3
+Southern Asia and the Pacific.  This information will be sufficient
+for initial tests.
+
+Meanings of remaining options on the *General* tab should be
+self-explanatory after you have made some QSOs using _WSJT-X_.  You
+may return to set these options to your preferences later.  
+
+NOTE: If you are using a callsign with an add-on prefix or
+suffix, or wish to work a station using such a call, be sure to read
+the section <<COMP-CALL,Compound Callsigns>>.
+
+NOTE: Enabling VHF/UHF/Microwave features necessarily disables the
+wideband multi-decode capability of JT65.  In most circumstances you
+should turn this feature off when operating at HF.

doc/user_guide/en/settings-radio.adoc

@@ -0,0 +1,77 @@
+// Status=review
+
+image::RadioTab.png[align="center",alt="Radio Tab"]
+
+_WSJT-X_ offers CAT (Computer Aided Transceiver) control of relevant
+features of most modern transceivers.  To configure the program for
+your radio, select the *Radio* tab.
+
+- Select your radio type from the drop-down list labeled *Rig*, or
+*None* if you do not wish to use CAT control.
+
+- Alternatively, if you have configured your station for control by
+*DX Lab Suite Commander*, *Ham Radio Deluxe*, *Hamlib NET rigctl*, or
+*OmniRig*, you may select one of those program names from the *Rig*
+list.  In these cases the entry field immediately under _CAT Control_
+will be relabeled as *Network Server*.  Leave this field blank to
+access the default instance of your control program, running on the
+same computer. If the control program runs on a different computer
+and/or port, specify it here.  Hover the mouse pointer over the entry
+field to see the required formatting details.
+
+- Select *OmniRig Rig 1* or *OmniRig Rig 2* to connect to an _OmniRig_
+server running on the same computer.  Note that _OmniRig_ is available
+only under Windows.
+
+- Set *Poll Interval* to the desired interval for _WSJT-X_ to query
+your radio.  For most radios a small number (say, 1 – 3 s) is
+suitable.
+
+- _CAT Control_: To have _WSJT-X_ control the radio directly rather
+than though another program, make the following settings:
+
+* Select the *Serial Port* used to communicate with your radio. 
+
+* _Serial Port Parameters_: Set values for *Baud Rate*, *Data Bits*,
+*Stop Bits*, and *Handshake* method.  Consult your radio's user guide
+for the proper parameter values.
+
+* _Force Control Lines_: A few station setups require the CAT serial
+port’s *RTS* and/or *DTR* control lines to be forced high or
+low. Check these boxes only if you are sure they are needed (for
+example, to power the radio serial interface).
+
+- _PTT Method_: select *VOX*, *CAT*, *DTR*, or *RTS* as the desired
+method for T/R switching.  If your choice is *DTR* or *RTS*, select
+the desired serial port (which may be the same one as used for
+CAT control).
+
+- _Transmit Audio Source_: some radios permit you to choose the
+connector that will accept Tx audio.  If this choice is enabled,
+select *Rear/Data* or *Front/Mic*.
+
+- _Mode_: _WSJT-X_ uses upper sideband mode for both transmitting and
+receiving.  Select *USB*, or choose *Data/Pkt* if your radio offers
+such an option and uses it to enable the rear-panel audio line input.
+Some radios also offer wider and/or flatter passbands when set to
+*Data/Pkt* mode.  Select *None* if you do not want _WSJT-X_ to change
+the radio's Mode setting.
+
+- _Split Operation_: Significant advantages result from using *Split*
+mode (separate VFOs for Rx and Tx) if your radio supports it.  If it
+does not, _WSJT-X_ can emulate such behavior.  Either method will
+result in a cleaner transmitted signal, by keeping the Tx audio always
+in the range 1500 to 2000 Hz so that audio harmonics cannot pass
+through the Tx sideband filter.  Select *Rig* to use the radio's Split
+mode, or *Fake It* to have _WSJT-X_ adjust the VFO frequency as
+needed, when T/R switching occurs.  Choose *None* if you do not
+wish to use split operation.
+
+When all required settings have been made, click *Test CAT* to test
+communication between _WSJT-X_ and your radio.  The button should turn
+green to indicate that proper communication has been established.
+Failure of the CAT-control test turns the button red and displays an
+error message.  After a successful CAT test, toggle the *Test PTT*
+button to confirm that your selected method of T/R control is working
+properly. (If you selected *VOX* for _PTT Method_, you can test T/R
+switching later by using the *Tune* button on the main window.)

doc/user_guide/en/settings-reporting.adoc

@@ -0,0 +1,15 @@
+// Status=review
+[[FIG_CONFIG_RPT]]
+image::reporting.png[align="center",alt="Reporting Screen"]
+
+- _Logging_: Choose any desired options from this group.
+
+- _Network Services_: Check *Enable PSK Reporter Spotting* to send
+reception reports to the {pskreporter} mapping facility.
+
+- _UDP Server_: This group of options controls the network name or
+address and port number used by a program that will receive status
+updates from _WSJT-X_.  Cooperating applications like _JTAlert_ use
+this feature to obtain information about a running _WSJT-X_ instance.
+If you are using _JTAlert_, be sure to check the three boxes at lower
+right.

doc/user_guide/en/settings-txmacros.adoc

@@ -0,0 +1,20 @@
+// Status=review
+
+[[FigTxMacros]]
+image::tx-macros.png[align="center",alt="Tx Macros Screen"]
+
+*Tx Macros* are an aid for sending brief, frequently used free-text
+messages such as the examples shown above.
+
+- To add a new message to the list, enter the desired text (up to 13
+characters) in the entry field at top, then click *Add*.
+
+- To remove an unwanted message, click on the message and then on
+*Delete*.
+
+- You can reorder your macro messages by using drag-and-drop. The
+new order will be preserved when _WSJT-X_ is restarted.
+
+- Messages can also be added from the main window's *Tx5* field on Tab
+1 or the *Free msg* field on Tab 2. Simply hit [Enter] after the
+message has been entered.