From 3d83bd458c8a6439f9053e5f435570d90553819a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc kop@karlpinc.com" Date: Tue, 28 Jul 2026 22:12:12 +0000 Subject: [PATCH] Make reference to useful views in each table's docs --- doc/src/epilog.inc.m4 | 6 ++++++ doc/src/tables/aggressions.m4 | 4 ++++ doc/src/tables/arrivals.m4 | 4 ++++ doc/src/tables/arrivals_a.m4 | 4 ++++ doc/src/tables/biography_data.m4 | 3 ++- doc/src/tables/brecord_notes.m4 | 13 +++++++++++-- doc/src/tables/colobus.m4 | 4 ++++ doc/src/tables/events.m4 | 7 +++++++ doc/src/tables/food_events.m4 | 4 ++++ doc/src/tables/groom_scans_b.m4 | 4 ++++ doc/src/tables/groomings.m4 | 4 ++++ doc/src/tables/humans.m4 | 6 +++++- doc/src/tables/locations_paper.m4 | 4 ++++ doc/src/tables/locations_utm.m4 | 4 ++++ doc/src/tables/matings.m4 | 4 ++++ doc/src/tables/pantgrunts.m4 | 8 ++++++++ doc/src/tables/roles.m4 | 5 +++++ doc/src/tables/species_present.m4 | 6 +++++- doc/src/tables/watches.m4 | 7 +++++++ 19 files changed, 96 insertions(+), 5 deletions(-) diff --git a/doc/src/epilog.inc.m4 b/doc/src/epilog.inc.m4 index 4dc776f..8167a77 100644 --- a/doc/src/epilog.inc.m4 +++ b/doc/src/epilog.inc.m4 @@ -1014,6 +1014,12 @@ elo_ranks_daily_rst(sdb_male, MT)dnl This condition is checked on :ref:`transaction commit `. +.. |OBS helpful| replace:: + The |OBS| view is likely to be helpful when working with this table. + +.. |DYADS helpful| replace:: + The |DYADS| view is likely to be helpful when working with this table. + .. Substitutions, used to give labels to internal links .. The upload schema, which is not yet documented diff --git a/doc/src/tables/aggressions.m4 b/doc/src/tables/aggressions.m4 index 0ef0666..365f3a4 100644 --- a/doc/src/tables/aggressions.m4 +++ b/doc/src/tables/aggressions.m4 @@ -31,6 +31,10 @@ AGGRESSIONS |AGGRESSIONS_summary| +.. sidebar:: + + |DYADS helpful| + When there are multiple individuals, whether aggressor or recipient, involved in simultaneous aggressive behavior, there should be multiple rows in the AGGRESSIONS table. diff --git a/doc/src/tables/arrivals.m4 b/doc/src/tables/arrivals.m4 index d73e603..71f35d3 100644 --- a/doc/src/tables/arrivals.m4 +++ b/doc/src/tables/arrivals.m4 @@ -36,6 +36,10 @@ This related |EVENTS| row supplies arrival and departure time values, and the |ROLES| role related to the event supplies information on the individual arriving and departing. +.. sidebar:: + + |OBS helpful| + The system will generate a warning when there are 2 different arrival events for the same arriving individual, in the same follow, that have an |EVENTS|.\ |EVENTS.Certainty| of ``sdb_identity_certain``, with diff --git a/doc/src/tables/arrivals_a.m4 b/doc/src/tables/arrivals_a.m4 index cc77bdf..559c440 100644 --- a/doc/src/tables/arrivals_a.m4 +++ b/doc/src/tables/arrivals_a.m4 @@ -30,6 +30,10 @@ ARRIVALS_A |ARRIVALS_A_summary| +.. sidebar:: + + |OBS helpful| + The system generates a warning when the sexual swelling information associated with an individual violates what is expected: diff --git a/doc/src/tables/biography_data.m4 b/doc/src/tables/biography_data.m4 index faa5740..9a89734 100644 --- a/doc/src/tables/biography_data.m4 +++ b/doc/src/tables/biography_data.m4 @@ -33,7 +33,8 @@ BIOGRAPHY_DATA |BIOGRAPHY_DATA_summary| BIOGRAPHY_DATA contains the basic demographic data of individual chimpanzees. -.. note:: +.. sidebar:: + The |BIOGRAPHY| view may be preferred to using the |BIOGRAPHY_DATA| table. A mother must be female; the |BIOGRAPHY_DATA.Sex| must be ``sdb_female`` diff --git a/doc/src/tables/brecord_notes.m4 b/doc/src/tables/brecord_notes.m4 index 48e8bf0..8a724ba 100644 --- a/doc/src/tables/brecord_notes.m4 +++ b/doc/src/tables/brecord_notes.m4 @@ -31,8 +31,17 @@ BRECORD_NOTES |BRECORD_NOTES_summary| -The related |EVENTS| row must be a B-Record translation event; it -must have an |EVENTS|.\ |EVENTS.Behavior| value of ``sdb_brec_note``. +.. sidebar:: + + It is likely that working with the |BREC_NOTES_VIEW| is easier than + working directly with BRECORD_NOTES. + The |BREC_NOTES_VIEW| contains all the columns that BRECORD_NOTES + contains, and additional columns from |OBS| that supply additional, + useful, data. + +The |EVENTS| row related to each BRECORD_NOTES row must be a B-Record +translation event; it must have an |EVENTS|.\ |EVENTS.Behavior| value +of ``sdb_brec_note``. This related |EVENTS| row supplies the time the note was taken. Because this is textual data, no attempt is made to make the table's diff --git a/doc/src/tables/colobus.m4 b/doc/src/tables/colobus.m4 index cf20a4e..197b0f1 100644 --- a/doc/src/tables/colobus.m4 +++ b/doc/src/tables/colobus.m4 @@ -31,6 +31,10 @@ COLOBUS (COLOBUS encounters) |COLOBUS_summary| +.. sidebar:: + + |OBS helpful| + The related |EVENTS| row must be a colobus monkey encounter event; it must have an |EVENTS|.\ |EVENTS.Behavior| value of ``sdb_colobus``. This related |EVENTS| row supplies the start and stop times for the diff --git a/doc/src/tables/events.m4 b/doc/src/tables/events.m4 index f97f41a..95cb57d 100644 --- a/doc/src/tables/events.m4 +++ b/doc/src/tables/events.m4 @@ -65,6 +65,13 @@ EVENTS |EVENTS_summary| +.. sidebar:: + + It is likely that working with either the |OBS| or |DYADS| views is + easier than working directly with the EVENTS table. + These views contain all the columns that EVENTS contains, and + additional columns which supply additional, useful, data. + Whether an event is related to a follow or to an attendance record or to something else is dependent upon the event's |EVENTS.Behavior| code. diff --git a/doc/src/tables/food_events.m4 b/doc/src/tables/food_events.m4 index 5e0b81b..63bfcb5 100644 --- a/doc/src/tables/food_events.m4 +++ b/doc/src/tables/food_events.m4 @@ -34,6 +34,10 @@ FOOD_EVENTS |FOOD_EVENTS_summary| +.. sidebar:: + + |OBS helpful| + .. sidebar:: The conversion of transcribed food-related text The MS Access database recorded |FOOD_EVENTS.FoodPartWritten| and diff --git a/doc/src/tables/groom_scans_b.m4 b/doc/src/tables/groom_scans_b.m4 index acdfb20..e0d4da4 100644 --- a/doc/src/tables/groom_scans_b.m4 +++ b/doc/src/tables/groom_scans_b.m4 @@ -33,6 +33,10 @@ GROOM_SCANS_B |GROOM_SCANS_B_summary| +.. sidebar:: + + |DYADS helpful| + In this data set, all groomings observed in periodic 5 minute intervals were recorded. diff --git a/doc/src/tables/groomings.m4 b/doc/src/tables/groomings.m4 index 2e7bf5f..bd25516 100644 --- a/doc/src/tables/groomings.m4 +++ b/doc/src/tables/groomings.m4 @@ -31,6 +31,10 @@ GROOMINGS |GROOMINGS_summary| +.. sidebar:: + + |DYADS helpful| + Should there be multiple individuals, whether groomer or recipient, involved in simultaneous grooming behavior, there should be multiple rows in the GROOMINGS table. diff --git a/doc/src/tables/humans.m4 b/doc/src/tables/humans.m4 index 1fb6ea8..22045e2 100644 --- a/doc/src/tables/humans.m4 +++ b/doc/src/tables/humans.m4 @@ -1,4 +1,4 @@ -.. Copyright (C) 2025 The Meme Factory, Inc. www.karlpinc.com +.. Copyright (C) 2025, 2026 The Meme Factory, Inc. www.karlpinc.com This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as @@ -30,6 +30,10 @@ HUMANS |HUMANS_summary| These are in addition to the observers that normally make the observations. +.. sidebar:: + + |OBS helpful| + The related |EVENTS| row must must be one that records the presence of other species; the |EVENTS| row with an |EVENTS.EID| value that matches the HUMANS row's |HUMANS.EID| value must have an |EVENTS|.\ diff --git a/doc/src/tables/locations_paper.m4 b/doc/src/tables/locations_paper.m4 index 416d60b..0472f6a 100644 --- a/doc/src/tables/locations_paper.m4 +++ b/doc/src/tables/locations_paper.m4 @@ -30,6 +30,10 @@ LOCATIONS_PAPER (spatial LOCATIONS in map numbers) |LOCATIONS_PAPER_summary| +.. sidebar:: + + |OBS helpful| + The system will generate a warning if the community of the follow related to the location information, or that of the |WATCHES| row that exists to support the location record, is not the community associated diff --git a/doc/src/tables/locations_utm.m4 b/doc/src/tables/locations_utm.m4 index 7878339..9fb4f8c 100644 --- a/doc/src/tables/locations_utm.m4 +++ b/doc/src/tables/locations_utm.m4 @@ -30,6 +30,10 @@ LOCATIONS_UTM (spatial LOCATIONS in UTM coordinates) |LOCATIONS_UTM_summary| +.. sidebar:: + + |OBS helpful| + The system will generate a warning if the community of the follow related to the location information, or that of the |WATCHES| row that exists to support the location record, is not the comm unity diff --git a/doc/src/tables/matings.m4 b/doc/src/tables/matings.m4 index f71650c..44dba27 100644 --- a/doc/src/tables/matings.m4 +++ b/doc/src/tables/matings.m4 @@ -31,6 +31,10 @@ MATINGS |MATINGS_summary| +.. sidebar:: + + |DYADS helpful| + The related |EVENTS| row must be a mating event; it must have an |EVENTS|.\ |EVENTS.Behavior| value of ``sdb_mating_event``. This related |EVENTS| row supplies the time of the mating and diff --git a/doc/src/tables/pantgrunts.m4 b/doc/src/tables/pantgrunts.m4 index 8360f42..65cd018 100644 --- a/doc/src/tables/pantgrunts.m4 +++ b/doc/src/tables/pantgrunts.m4 @@ -32,6 +32,14 @@ PANTGRUNTS |PANTGRUNTS_summary| +.. sidebar:: + + It is likely that working with the |PANTGRUNTS_VIEW| is easier than + working directly with PANTGRUNTS. + The |PANTGRUNTS_VIEW| contains all the columns that PANTGRUNTS + contains, and additional columns from |DYADS| that supply additional, + useful, data. + Should there be multiple individuals, whether the exhibitor or recipient, involved in simultaneous pantgrunt behavior, there should be multiple rows in the PANTGRUNTS table. diff --git a/doc/src/tables/roles.m4 b/doc/src/tables/roles.m4 index afac534..374160a 100644 --- a/doc/src/tables/roles.m4 +++ b/doc/src/tables/roles.m4 @@ -40,6 +40,11 @@ But this is not true of all events, for example events that are no more than a record of the presence of other species sighted during a follow. +.. sidebar:: + + It is likely that using the |OBS| or |DYADS| view is helpful when + working with this table. + The participant in the event is required to be under study on the date when the observation was made. This means that the |WATCHES|.\ |WATCHES.Date| related to the event diff --git a/doc/src/tables/species_present.m4 b/doc/src/tables/species_present.m4 index 1c94f10..d1c7a0c 100644 --- a/doc/src/tables/species_present.m4 +++ b/doc/src/tables/species_present.m4 @@ -1,4 +1,4 @@ -.. Copyright (C) 2025 The Meme Factory, Inc. www.karlpinc.com +.. Copyright (C) 2025, 2026 The Meme Factory, Inc. www.karlpinc.com This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as @@ -29,6 +29,10 @@ SPECIES_PRESENT |SPECIES_PRESENT_summary| +.. sidebar:: + + |OBS helpful| + The related |EVENTS| row must must be one that records the presence of other species; the |EVENTS| row with an |EVENTS.EID| value that matches the SPECIES_PRESENT row's |SPECIES_PRESENT.EID| value must diff --git a/doc/src/tables/watches.m4 b/doc/src/tables/watches.m4 index 0cc3f4e..f186365 100644 --- a/doc/src/tables/watches.m4 +++ b/doc/src/tables/watches.m4 @@ -38,6 +38,13 @@ WATCHES |WATCHES_summary| +.. sidebar:: + + It is likely that working with either the |OBS| or |DYADS| views is + easier than working directly with the WATCHES table. + These views contain all the columns that WATCHES contains, and + additional columns which supply additional, useful, data. + WATCHES does not contain a row for every day every individual was observed because SokweDB contains data on individuals collected due to proximity with the intended target of observation. -- 2.34.1