add an explanatory glossary

(also a reminder to me to stay at least somewhat consistent with names)

1 files changed, 63 insertions, 0 deletions

diff --git a/GLOSSARY.org b/GLOSSARY.org
new file mode 100644
index 0000000..3334c29
--- /dev/null
+++ b/GLOSSARY.org
@@ -0,0 +1,63 @@
+#+TITLE: Glossary of Terms
+
+This is meant to give a rough overview of (train-related) terms used in this
+code; both for others as a reference and for me so I can remember to use them
+in a (somewhat) consistent way, since they are somewhat arbitrary (though I've
+tried to stick close to the terminology used in GTFS).
+
+* Terms
+** (Calendar-)Date / Day
+A single, unique day (e.g. 1970-01-01). Usually used to indicate if a /trip/
+is running on that day or not.
+
+** Time (of Day)
+Time on a given day, given in minutes since midnight. Trips going across
+midnight simply count minutes up from the previous day.
+
+** Trip (don't confuse with Train)
+Used as in GTFS: a trip is a defined sequence of /stops/, referred to by a
+number (called its trip ID, e.g. IC 94). Usually runs on multiple days.
+Always has an associated /shape/.
+
+(might match your intuition for "train line")
+
+** Stop
+A /station/ with associated arrival/departure /time/
+
+** Station
+A train station. Tracktrain refers to each by an ID, and hopefully knows
+its geolocation.
+
+** Shape
+A sequence of geolocations describing a line between stations, describing
+the physical railway along which trains travel.
+
+** Train (don't confuse with Trip)
+A single instance of a /trip/ on a concrete /date/. Tracktrain mostly concerns
+itself with keeping track of those; the rest is just additional stuff.
+
+** Vehicle
+An actual, physical vehicle, which might act as the /train/ going along a
+/trip/ on a certain /date/.
+
+For now tracktrain doesn't really care about them (but if it's curious it
+might yet learn about them!)
+
+** Announcement
+The thing that GTFS calls "Service Alert" — a text message giving
+human-readable information about some /train/.
+
+** (Train-)Ping
+A single packet of data sent from a train's /OBU/. Might arrive in some
+arbitrary order.
+
+** Control Room
+The "admin interface" of tracktrain, which is not meant to be used by on-board
+staff.
+
+** On-Board Unit (OBU)
+A thing on a vehicle which does geolocation tracking and yells at tracktrain
+about it.
+
+If we ever run into potential confusion regarding this term we're probably
+way too professional to actually use tracktrain for anything.