diff --git a/wiki/Awards.md b/wiki/Awards.md index 0b557ba..88e861f 100644 --- a/wiki/Awards.md +++ b/wiki/Awards.md @@ -11,28 +11,76 @@ mode. ## How matching works -An award scans a **QSO field** for a reference, by one of: +An award scans a **QSO field** (state, QTH, address, notes, …) for a reference, +using one **Match by** mode: -- **code** — the field value is the reference (e.g. state = `NY`). -- **description** — the reference's name appears in the field (substring, case- - insensitive but **space-sensitive** — "Hongkong" won't match "Hong Kong"). -- **pattern** — a per-reference regex is tested against the field. +- **code** — the field value *is* the reference (e.g. state = `NY`). +- **description** — the reference's **name** appears in the field (substring, + space-sensitive — "Hongkong" won't match "Hong Kong"). +- **pattern** — the field is tested against a regex. -Plus **OR rules** (also match if any of these hit), a **leading/trailing** strip, -a **prefix** added to found references, and a **dynamic** mode (any value counts, -like POTA). +Plus a **leading/trailing** strip, a **prefix** prepended to found references, a +**dynamic** mode (any value counts, like POTA), and the **fallback searches** +described below. -> **Tip — Hong Kong / Macau style mismatches:** if the data says "Hong Kong" but -> the reference description is "Hongkong", either fix the description to match, or -> set that OR-search's *Match by* to **pattern** so the reference's own regex -> (e.g. `\bHong Kong\b`) is used. In *description* mode the per-reference pattern -> is ignored. +### The five rules to remember + +1. **Every regex is case-insensitive.** Award and per-reference patterns match + regardless of case (log fields are typed however the operator felt) — so + `\bTok[iy]o\b` catches `TOKYO`, `Tokyo` and even `TOKIO`. Set your own flag + group (e.g. `(?s)`) to override. + +2. **A reference's own `Pattern` is opt-in extra recognition.** On the + *References* tab each reference has a **Pattern (regex)** field. Fill it to + recognise a reference by more than its name — spelling variants, or the + **cities/terms** that imply it. Leave it empty and the reference is matched by + name only. Example — Jiangsu (China) carries the cities in its own regex: + `\b(Jiangyin|Wuxi|Suzhou|Nanjing|Changzhou)\b`. + +3. **`description` also runs the per-reference regexes** (on the same field). + A description search looks for the reference *name* **OR** fires each + reference's own Pattern — so a description award over the QTH/address will + auto-match your city regexes with no extra rule. (A reference with an empty + Pattern stays name-only.) + +4. **OR rules are ordered fallbacks (first hit wins).** The **Fallback searches** + section adds extra searches tried **in order, only while nothing has matched + yet** — the first that finds a reference wins and the rest are skipped + (short-circuit, like a chain of *else-if*). So a province already resolved by + name isn't also re-tagged, possibly differently, by a later city regex. + +5. **Scope is checked first — a manual reference does not bypass it.** DXCC + filter, valid bands / modes / emission and the valid-from/to dates gate every + QSO before any reference is looked at. A 17 m QSO can't count for an award + whose valid bands are 80/40/20/15/10 m, even if you assign the reference by + hand. Widen the award's bands if it *should* count. + +> **Tip — Hong Kong / Macau style mismatches:** if the log says "Hong Kong" but +> the reference name is "Hongkong", either fix the name, or give that reference a +> **Pattern** like `\bHong ?Kong\b`. Thanks to rule 3 the pattern now works even +> for a *description* award — no separate rule needed. + +### Worked example — Worked All Provinces of China (WAPC) + +A custom province award where the log rarely spells the province out (it names a +*city*). The clean setup: + +- **Primary:** *Search in* **QTH**, *Match by* **description**. +- **Fallback search:** *Search in* **address**, *Match by* **description**. +- On the *References* tab, give each province a Pattern listing its cities. + +Now a QSO is resolved by the province **name** if present, else by a **city** +regex — first in the QTH, then in the address. First hit wins. ## Live detection & manual refs - References are detected **live** as you enter a callsign. -- You can **manually assign** a reference to a QSO (stored in an ADIF extra so it - survives export/import — see [[Import and Export ADIF]]). +- You can **manually assign** a reference to a QSO (the *Award Refs* tab of the + QSO editor). It's stored in an ADIF extra (`APP_OPSLOG_AWARDREFS`) so it + survives export/import — see [[Import and Export ADIF]] — and is honoured + everywhere (award panel, grid columns, totals). For a list-backed award the + assigned reference must still be a **valid, listed** reference, and the QSO + must be **in scope** (rule 5) for it to count. ## Reference lists & display