===============================================================================
  505PROCESSOR  —  F!505 Area Assessment Record Processor
  Installation Guide  —  Version 1.0.0
===============================================================================

  Designed and developed by Stephen Clay McGehee, KN4AM
  SitRepNet.com

-------------------------------------------------------------------------------
  TABLE OF CONTENTS
-------------------------------------------------------------------------------

  1.  Requirements
  2.  Installing on Windows
  3.  Installing on Linux and Raspberry Pi
  4.  Running 505Processor
  5.  Upgrading to a New Version
  6.  Troubleshooting

===============================================================================
  SECTION 1 — REQUIREMENTS
===============================================================================

  All platforms:
      Python 3.7 or later, with tkinter included.
      No additional Python packages are required.

  Windows:
      Python 3.7 or later (download from python.org).
      Tkinter is included with the standard Python installer for Windows.
      Tested on Windows 10 and Windows 11.

  Linux and Raspberry Pi:
      Python 3.7 or later (usually pre-installed).
      The python3-tk package must be installed separately if not present
      (see Section 3).
      Tested on Raspberry Pi OS (Bookworm) and Debian/Ubuntu-based systems.

===============================================================================
  SECTION 2 — INSTALLING ON WINDOWS
===============================================================================

  Step 1 — Check Python
  ─────────────────────
  Open a Command Prompt (search for "cmd" in the Start menu) and run:

      python --version

  If Python 3.7 or later is shown (for example, Python 3.11.4), go to
  Step 2.

  If Python is not found, download and install it from:
      https://www.python.org/downloads/windows/

  During installation, check "Add Python to PATH."  This is required.
  After installing, close and reopen the Command Prompt, then verify:

      python --version

  Step 2 — Extract 505Processor
  ──────────────────────────────
  Unzip the 505Processor download to a folder of your choice.
  A path with no spaces is recommended.
  Example:  C:\505Processor

  Step 3 — Run Setup
  ──────────────────
  In the Command Prompt, navigate to the 505Processor folder and run:

      cd C:\505Processor
      python setup.py

  You will see confirmation that Python and tkinter are available and
  that setup completed successfully.  Setup also creates a 505Processor
  shortcut on your Desktop with the 505 icon.  This step only needs to
  be done once after a fresh install.

  Step 4 — Launch
  ────────────────
  Double-click the 505Processor icon on your Desktop.

  Alternatively, double-click run.bat in the 505Processor folder, or
  run it from a Command Prompt:

      run.bat

===============================================================================
  SECTION 3 — INSTALLING ON LINUX AND RASPBERRY PI
===============================================================================

  Step 1 — Check Python
  ─────────────────────
  Open a terminal and run:

      python3 --version

  Python 3.7 or later is required.  On most modern Raspberry Pi OS and
  Debian/Ubuntu systems, Python 3 is pre-installed.

  If Python 3 is not installed:

      sudo apt update
      sudo apt install python3

  Step 2 — Check tkinter
  ──────────────────────
  Test that tkinter is available:

      python3 -c "import tkinter; print('tkinter OK')"

  If you see "tkinter OK", proceed to Step 3.

  If you see an error, install python3-tk:

      sudo apt install python3-tk

  Then run the test again to confirm.

  Step 3 — Extract 505Processor
  ──────────────────────────────
  Copy or extract the 505Processor download to a convenient location.
  Example:  /home/pi/505processor

  Step 4 — Run Setup
  ──────────────────
  In a terminal, change to the 505Processor directory and run:

      cd /home/pi/505processor
      python3 setup.py

  You will see confirmation that Python, tkinter, and the virtual
  environment are ready.  Setup also marks run.sh executable, creates
  a 505Processor shortcut on your Desktop with the 505 icon, and on
  GNOME desktops pins the app icon to the dash (the vertical icon bar
  on the side of the screen).  This step only needs to be done once
  after a fresh install.

  Step 5 — Launch
  ────────────────
  Double-click the 505Processor icon on your Desktop.

  On GNOME desktops, you can also click the 505Processor icon in the
  dash.  While the app is running, the dash icon shows a dot indicator;
  clicking it brings the window to the foreground.

  Alternatively, open a terminal in the 505Processor directory and run:

      ./run.sh

===============================================================================
  SECTION 4 — RUNNING 505PROCESSOR
===============================================================================

  After installation, always use run.sh (Linux/Raspberry Pi) or run.bat
  (Windows) to start 505Processor.  These scripts use the private virtual
  environment created by setup.py and ensure the correct Python is used.

  Running processor505.py directly
      Advanced users may run the program directly using the system Python:

          python3 processor505.py

      If you do this, make sure Python 3 and tkinter are available in
      your environment.  The virtual environment (venv) created by setup.py
      is not required for direct invocation on a system with a compatible
      Python.

  Do not move the 505Processor folder after running setup.py
      The virtual environment stores absolute paths.  If you need to move
      the folder to a new location, delete the venv subfolder and run
      setup.py again from the new location.

===============================================================================
  SECTION 5 — UPGRADING TO A NEW VERSION
===============================================================================

  When a new version is available, 505Processor notifies you at startup
  (if auto-update checking is enabled in Preferences > Auto-Update).

  To upgrade:
      1. Download the new version from SitRepNet.com.
      2. Close 505Processor if it is running.
      3. Back up your IGNORE.TXT file if you have one.
      4. Replace the contents of your 505Processor folder with the new
         version files.  Do not delete the  data  subfolder — it contains
         your saved preferences (settings.json).
      5. The existing venv folder from your previous installation can
         usually be kept as-is.  If you experience problems after
         upgrading, delete the venv folder and run setup.py again.
      6. Copy your IGNORE.TXT back into the 505Processor folder.
      7. Launch using run.sh or run.bat as usual.

===============================================================================
  SECTION 6 — TROUBLESHOOTING
===============================================================================

  "505Processor setup has not been run yet."
      The run script could not find the virtual environment.  Run
      setup.py before using the launcher:

          python3 setup.py   (Linux / Raspberry Pi)
          python  setup.py   (Windows)

  "python3: command not found"  (Linux)
  "python is not recognized"    (Windows)
      Python is not installed or not in the system PATH.
      Install Python as described in Section 2 or 3 and ensure it is
      added to PATH.

  "ModuleNotFoundError: No module named '_tkinter'"  (Linux)
      tkinter is not installed.  Run:
          sudo apt install python3-tk
      Then run setup.py again.

  The program window does not appear after launch
      The window may have opened off-screen from a previous session on
      a different monitor or display.  To reset the window position:
          1. Close 505Processor.
          2. Open the file  data/settings.json  in a text editor.
          3. Delete the  "window_geometry"  line and save the file.
          4. Restart 505Processor.

  "Input folder not found" or "Input file not found"
      The path entered in the dialog does not exist.  Use the Browse
      button to select a valid folder or file.

  Output file contains fewer records than expected
      Check the summary in the log for "Duplicates removed" and
      "Invalid lines skipped" counts.  Records that fail parsing are
      counted but not written to the output.

  Combine Records finds no records
      Confirm the input folder contains .txt or .csv files with valid
      F!505 records.  Subfolders are not searched.

  IGNORE.TXT does not seem to filter any records
      Callsign filtering requires callsign data in the input file, which
      is only present in CSV exports.  Plain .txt export files do not
      include callsigns; IGNORE.TXT has no effect on them.

===============================================================================
  END OF INSTALLATION GUIDE
===============================================================================
