diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2649eedb..0319c1bf 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -67,6 +67,8 @@ jobs: runs-on: ubuntu-latest steps: + - uses: actions/checkout@v6 + - name: Get Zotero Version Information id: zoteroVersion run: | @@ -88,7 +90,7 @@ jobs: lookup-only: true path: | content/en/history/bibliography - key: bib-${{ steps.zoteroVersion.outputs.version }} + key: bib-${{ steps.zoteroVersion.outputs.version }}-${{ hashFiles('content/en/history/bibliography/_index.md', 'content/en/history/bibliography/intake/**') }} # ---------------------------------------------------------------------------- # Validate that README.md references the correct Hugo version. @@ -142,10 +144,8 @@ jobs: uses: actions/cache@v5 with: path: | - static/data/bibliography.json - static/data/bibItems content/en/history/bibliography - key: bib-${{ needs.check.outputs.zoteroVersion }} + key: bib-${{ needs.check.outputs.zoteroVersion }}-${{ hashFiles('content/en/history/bibliography/_index.md', 'content/en/history/bibliography/intake/**') }} - name: Install Bibliography if: steps.cache-bib.outputs.cache-hit != 'true' diff --git a/.gitignore b/.gitignore index 66e48255..20c2a6a9 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,5 @@ static/data/bibItems/ /scripts/*.err /content/en/history/bibliography/** !/content/en/history/bibliography/_index.md +!/content/en/history/bibliography/intake/ +!/content/en/history/bibliography/intake/** diff --git a/config/_default/params.yaml b/config/_default/params.yaml index 0ccd9e4d..c84702ac 100644 --- a/config/_default/params.yaml +++ b/config/_default/params.yaml @@ -157,6 +157,9 @@ ui: # Enable to show the side bar menu in its compact state. sidebar_menu_compact: true sidebar_menu_foldable: true + # ui_show is only valid with sidebar_menu_foldable is true. + # ul_show: 3 + # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) sidebar_search_disable: false @@ -172,8 +175,6 @@ ui: # Set to false to disable the About link in the site footer footer_about_enable: false - ul_show: 3 - # Set the navbar to dark mode, This keeps the fonts white, which works better with the blue background. navbar_theme: dark diff --git a/content/en/history/bibliography/_index.md b/content/en/history/bibliography/_index.md index a4ad1df1..1198c17f 100644 --- a/content/en/history/bibliography/_index.md +++ b/content/en/history/bibliography/_index.md @@ -9,4 +9,13 @@ aliases: - /bibliography/ --- -We generate this from our [Zotero collection library](https://www.zotero.org/groups/2914042/interlisp/library). + +#### Resources + +Bibliographic entries are generated from our [Zotero collection library](https://www.zotero.org/groups/2914042/interlisp/library). + +The [Interlisp Bibliography Intake Guide](intake) explains how to recommend new bibliography items. + +--- + +#### Bibliographic Entries diff --git a/content/en/history/bibliography/intake/_index.md b/content/en/history/bibliography/intake/_index.md new file mode 100644 index 00000000..97991332 --- /dev/null +++ b/content/en/history/bibliography/intake/_index.md @@ -0,0 +1,92 @@ +--- +title: Interlisp Bibliography Intake Guide +weight: 1 +type: docs +--- + +## I have something I think belongs in the Interlisp Bibliography! + +That’s great! The information below will help you figure out if it does in fact belong, and what to do with it if so. + +To begin, the Interlisp Bibliography aims to be what’s called an *exhaustive enumerative bibliography.* + +### Enumerative Bibliography? + +An enumerative bibliography is a collection of works on a particular topic — in our case, this topic is Interlisp. They are sometimes called systematic bibliographies, but I (Ellie) find the term “enumerative” more apt (and generally think it’s a more fun word to say). + +### Exhaustive? + +Rather than in the case of a selective bibliography, in which only certain documents within the bibliography’s scope would be included, **any** items that meet the bibliography’s scope (expanded below) are included in an exhaustive bibliography. + +### The Interlisp Bibliography’s Bibliographic Scope + +The Interlisp Bibliography aims to collect any and all works related to Interlisp and its various versions, including academic articles, reference manuals, software package documentation, advertisements, video lectures or demonstrations, and other files and documentation so long as they discuss or relate to Interlisp, Interlisp’s development history (such as BBN-Lisp and Common Lisp items, as well as some LISP items), or applications built in Interlisp. + +If your item falls within this scope, then it likely belongs in the Interlisp Bibliography. + +## It definitely belongs! How do I add it? {#it-definitely-belongs-how-do-i-add-it} + +If you’re certain it belongs in the bibliography, then great! There’s a few things that need to be covered before it’s in there, though, so please read the rest of this guide carefully. The bibliography is hosted in Zotero, an open-source bibliographic management software, and to ensure that items are as useful as they can be to those who need to find them, there’s a few steps that should be followed for an effective addition to the bibliography. + +1. Fill out the [Interlisp Bibliography Submission Form](https://docs.google.com/forms/d/e/1FAIpQLSekus0eYTsov17U554igvBDbsp-6KIHtUCfj6s6QvRWt_DL0g/viewform?usp=header). + - Provide information about your item in the appropriate fields throughout the form ([see what sort of information here](#what-sort-of-information-should-i-provide-for-my-entry)). +2. It sure would be convenient to add it myself… + - Even if you have the technical clearance in Zotero to add something to the bibliography yourself, it’s recommended that you fill out the submission form like anyone else to be sure items are entering the bibliography in the most uniform state possible. Refer to the [start of this section](#it-definitely-belongs-how-do-i-add-it) to learn how to get started on that, and the [next section](#what-sort-of-information-should-i-provide-for-my-entry) to learn what sort of information you should try to prepare alongside your request. + +## What sort of information should I provide for my entry? {#what-sort-of-information-should-i-provide-for-my-entry} + +As much as you can, generally. You don’t need to search to the ends of the Earth for pieces of non-key information, but there are some fields that should generally be filled (such as date and title). Zotero is also capable of importing some other bibliographic formats ([a list found here](https://www.zotero.org/support/dev/data_formats)), so if the item’s information is already held in another program, you might be able to save yourself some trouble by exporting that information as a file. + +If you’re working from scratch, include in [the form](https://docs.google.com/forms/d/e/1FAIpQLSekus0eYTsov17U554igvBDbsp-6KIHtUCfj6s6QvRWt_DL0g/viewform?usp=header) as much of the following information as you have access to for each individual item. + +1. Item Type + * Book, magazine article, video, etc. +2. Title + * If the item is untitled, you can supply one, but it’s helpful to mention that you are supplying the title rather than sourcing it from the item itself. +3. Author + * Author, creator, director, etc., if any. +4. Date of publication / creation + * Provide as precise a date as possible, but any date or a range of years is better than no date. Use a format like YYYY, YYYY-MM, or YYYY-MM-DD. If the date is approximate or not obvious, add a note explaining how you determined the value you arrived at. +5. Publisher / Publication name + * The publishing house, journal, or magazine, etc. +6. Journal/Magazine Volume + * If applicable. +7. Journal/Magazine Issue + * If applicable. +8. Abstract + * If applicable. +9. Who added the item and how they found it + * This would be your name (or username, if need be) and how you came upon it — useful information for tracking down other potential sources and generally keeping apprised of who’s adding what to the bibliography. + * This information will go in a Note attached to the item. + +For other kinds of information you could include, check the [bibliography’s entries in Zotero](https://www.zotero.org/groups/2914042/interlisp/library) and look at the metadata fields on different kinds of items. So long as the information is accurate, there’s no downside to having more of it. + +## Do I need to add any tags to my item? What kind of tags? + +Tags are keywords that help with both the precision and recall of searches within bibliographies. In addition to being useful for grouping items (e.g., searching for all items bearing the “BBN-Lisp” tag), it’s helpful to have tags that employ terms which don’t appear in the item’s other metadata fields. It’s very helpful to suggest tags in the submission form, so please do. + +
+{{< imgproc tags Resize "580x285">}} An example of tags{{< /imgproc >}} +
+ +Consider the following when suggesting tags or adding tags to an item after it has entered the bibliography: + +1. **Try to use tags that are already used on other items in the bibliography.** If you begin typing a tag and Zotero suggests a similar one, that means that the suggested tag is already on another item (or multiple other items!). Try to use those suggested tags whenever possible. If you feel it doesn’t capture the whole of an important aspect of your item but is still related, consider adding both the suggested tag and the original tag you were going to enter. + +2. **It’s okay to create tags that duplicate keywords already present in other parts of the item’s metadata.** Zotero searches all metadata fields, as well as tags. Even if information is already included elsewhere in the item’s metadata, it can still be helpful to tag terms that are integral to a given item. For instance, tagging an item called “History of Interlisp” with the tag “Interlisp” is a bit redundant, but it allows the item to show up in searches that explicitly retrieve items with the Interlisp tag. The same applies if the phrasing is different (such as a mention of Medley, but not “Medley Interlisp”); it can be helpful to use the full tag to be sure it gets picked up in searches. In either case, the important takeaway is that a redundant tag doesn’t hurt, *so long as it’s accurate.* + +3. **Add tags with the expectation that a researcher is studying something your item is about, and you want to help them find it.** The bibliography is a resource for hobbyists, researchers, computer historians, or anyone else who wants to find relevant things that might be there. Consider what sort of value your item could potentially have to a researcher, and tag it with terms that could cause it to show up in those researchers’ searches. For instance, if you add a paper that includes a significant discussion of garbage collection systems but isn’t primarily *about* garbage collection and doesn’t include that elsewhere in the metadata, you might add the “garbage collection” tag, since that paper could be useful to someone studying garbage collection even if it may not seem like it on the surface. + +4. **You don’t need to add a million tags, just *accurate* tags.** So long as the tags are accurate, it doesn’t hurt to have more of them, but you also don’t need to add anything close to dozens. Most items only have 4-8 tags covering the main points of an item. Add as many tags as are entirely accurate to the item. If a tag is ever “not really quite right” for an item, it shouldn’t be used, and should potentially be replaced by a more accurate tag or removed altogether if you can’t think of a suitable replacement. + +5. **Look at similar items in the bibliography for examples of tags.** This can be helpful to get an idea of what kind of tags are already in use, and help you come up with appropriate tags for your particular item. Looking at dissimilar items can be helpful sometimes as well. Follow in the footsteps of those that came before! (Disclaimer: not all items in the bibliography are currently tagged. It’s a work in progress. Find and reference the ones that are.) + +If you have permission to add the item to the bibliography yourself, you can tag it yourself as well. + +## Should I worry about those Zotero Collections all the items seem to be in? + +Items will be sorted into collections as they’re brought into the bibliography, and it tends to be fairly obvious which they belong in. If you feel that it’s less apparent with your particular submission, then feel free to suggest the collection(s) to which your submission might belong at the end of the Google Form. + +--- +*Written by Eleanor Young* +*Last revised: 7/25/2025* diff --git a/content/en/history/bibliography/intake/images/tags.png b/content/en/history/bibliography/intake/images/tags.png new file mode 100644 index 00000000..50081c0d Binary files /dev/null and b/content/en/history/bibliography/intake/images/tags.png differ diff --git a/scripts/bibSplit.pl b/scripts/bibSplit.pl index 8a9b77be..cfdeb650 100755 --- a/scripts/bibSplit.pl +++ b/scripts/bibSplit.pl @@ -190,6 +190,7 @@ sub sanitize_text { # Timestamp of last modification to bibliographic item lastmod: $dateModified +toc_hide: true --- ENDITEM