Theo Todman's Web Page - Notes Pages
Website Documentation
Website Generator Documentation - Note References & Reading List
(Text as at 28/09/2022 10:24:58)
Introduction
- This document covers1 the production of the ‘References & Reading Lists’ appended to Notes.
- Currently, these are produced in a very convoluted, obscure and – as far as their contents are concerned – non-timely manner, which needs careful documenting before it can be corrected and improved.
- There is overlap with the Cross-Referencing2 re-engineering project, both for the obvious reason that cross-references are key to the production of the correct information, and also because ‘legacy’ tables are used. .
- So, how is the list generated? Well, it’s created by the function AddReading_List.
- This function is called from OutputNotesWebPage with third parameter “Non-Print”
- It’s also called identically from OutputNotesWebPage_Archived but – from a quick look – nothing comes out for Archived Notes.
- It’s also called from NoteForPrinting with third parameter “Yes” provided the variable strPrintReadingLists = "Yes".
- And, additionally for the parallel Archive Note if additionally Archive_Reading_Lists = True). I’m not sure if all this works as ‘Printable Notes3’ is currently switched off).
- An item is added to the ‘internal links’ banner-table at the top of the Note only if Note_Groups![ReadingList?] = “Yes”. This is not strictly correct, as we’ll see. There’s nothing analogous for Archived Notes.
- The primary data drivers of the ‘References & Reading Lists’ are the tables:-
→ Note_Book_Links and
→ Note_Paper_Links.
- These used to be maintained by
→ cmdBooksToNotes_Click, and
→ cmdPapersToNotes_Click
- For documentation, see Website Generator Documentation - Links & Link-Pages4), but this code was commented out as part of my Cross-Referencing re-engineering5 project. I’ve now re-instated it, so it appears in the documentation!
- They are probably maintained by the Full Regen6, but this doesn’t make for timeliness.
- My specific interest in this matter arose because of Thesis – References7 where initially the ‘References & Reading List’ was empty, but then – after a full Website Regen – was a diminutive list with a few items beginning with ‘A’! Something is clearly going wrong.
Detailed processing of AddReading_List
- The formatting of the table on the page is fairly straightforward, and I may document this later. In particular, I need to look into the “Source” column to see if it can provide better bibliographical detail for Books or Papers derived from Books. Currently if a Book is included because one of its Chapters is cited, but is not itself cited, Source is set to “Bibliographical details to be supplied”.
- The data on the table is driven by one of two queries:-
- Citations_List_Short, or
- Citations_List
- To determine which, the Note Title is used to interrogate Sub-Topics. If nothing is found, the short version is used. Usually, but not always, a PID Note has a sub-topic associated with it.
- For Citations_List_Short:
- The primary query is Citations_Union2, which is a union of:-
→ Books_Cited,
→ Papers_Cited, and
→ Books_from_Papers_Cited
- While these queries are named ‘cited’, things are more complicated in that they include both books and papers that are cited by this Note and also Books and papers that cite this Note. Whether this should be the case is subject to review!
- The first two queries select the relevant Note based on the row in Note_Usage_Temp which has been set by OutputNotesWebPage, or sundry other routines.
- Books_Cited: uses the table Note_Book_Links, ignoring anything with a Timestamp other than 0 (ie. Archived Notes). If the Origin on this table is “Note”, the book has been cited, otherwise it is Referencing the Note. There’s an external join on Citations_Note_Group, which gives the name of the Note Group, but it doesn’t seem to be used.
- Papers_Cited: uses the table Note_Paper_Links, with the same provisos as for the Books query above. The corresponding Book ID is determined from qryBooks via the Papers table.
- Books_from_Papers_Cited is driven from Papers_Cited and lists all the Books associated with the Papers in that query provided the Book is neither in:-
→ Books_By_SubTopic, nor in
→ Books_Cited, nor
→ has Author name starting with "Various", "zzz" or "Electronic" (which are used for pseudo-books in my database)
- For Citations_List:-
- The primary query is Citations_Union1, which is the same union query as used for Citations_List_Short, but with the addition of three further queries:-
→ Books_By_SubTopic
→ Papers_By_SubTopic
→ Books_from_Papers_By_Subtopic
- This second bunch of queries was very useful in developing the reading lists for the PID notes for which they were relevant, but are not so useful now that I’ve cherry-picked the interesting items.
- Books_By_SubTopic: This is a union of three further – almost identical – queries:-
- Books_By_SubTopic1: This uses the Note title to join to Books with this as Sub-Topic. Books already cited are excluded using Books_Cited. There’s an internal join on Citations_Note_Group but, as before, I can’t see that this does anything. Unlike for Papers, there’s no selection based on Priority or level in a hierarchy. As for direct citations, authors indicating pseudo-books are rejected.
- Books_By_SubTopic2: As above, but using Sub-Topic2.
- Books_By_SubTopic3: As above, but using Sub-Topic3.
- Papers_By_SubTopic: This is again a union of three very similar queries that are analogous to those for Books, but linking to Papers. There’s an exclusion for Papers already cited, using Papers_Cited, and the Book ID is determined as for direct citations. However, there’s also a fairly complex algorithm that selects based on their Priority and level in the hierarchy (based on parameters passed via Note_Usage_Temp). I think the hierarchy is only relevant for printable notes of depth > 1.
- Books_from_Papers_By_Subtopic is driven from Papers_By_SubTopic in a manner analogous to Books_from_Papers_Cited, with the same exclusions.
- So, the critical tables that drive the Citations processing are:-
→ Note_Book_Links, and
→ Note_Paper_Links
- How are these tables maintained? They ought to be maintained from – or superseded by – the Cross_Reference table, but it may be difficult to do this in an efficient manner.
Detailed processing for table Note_Book_Links
Detailed processing for table Note_Paper_Links
This Note is awaiting further attention10.
In-Page Footnotes:
Footnote 1:
- Or will do, once it has been written!
| Note last updated |
Reference for this Topic |
Parent Topic |
| 28/09/2022 10:24:58 |
1340 (Website Generator Documentation - Note References & Reading List) |
None |
Summary of Notes Referenced by This Note
To access information, click on one of the links in the table above.
Summary of Notes Citing This Note
To access information, click on one of the links in the table above.
Text Colour Conventions
- Blue: Text by me; © Theo Todman, 2023