This file is unlikely to have anything of general interest. It was created by the administrator to document how the poll directory was initially set up, including any edits necessary. Understanding the process may help us manage it better in the future.
The poll is managed through the website at hullworks.net/jazzpoll/. The top level contains some general information and an index of polls, starting with 2006. Each poll is in its own directory, the path the last two digits of the year (e.g., 25/). Mid-year polls follow the same convention, with a suffix (e.g., 25my/).
Day-to-day work on the website is done on a private copy by Tom Hull, and synched up as needed. New polls are generated by creating a new directory, copying the previous poll files, and editing them as needed. Thus there is a sort of ramshackle drift from year to year, with a lot of redundancy and drift.
A comprehensive redesign would be a good idea, but also a lot of work.
Start by creating a new directory for the mid-year poll:
# mkdir 26my
# cp 25/* 26my/
Edit index.php:
Note that the whole page needs massive redesign work, but not yet. The immediate need is to make the poll functional.
Edit Makefile:
My first decision was to copy files from 25/ instead of from 25my/. This picks up the latest voters file, and any other stylistic adjustments from the 25 poll, as well as better documentation. I can always compare these files against 25my files for mid-year poll customizations. If I recall correctly, I did the opposite last year, and regretted it.
Second decision was to change the *-notes.php naming convention to be notes-*.php, which will sort together. I believe that all of them need to be rewritten from scratch, although some of the structure and boilerplate may be retained. This file is a case in point.
First thing to do is to delete all of the unnecessary files.
To do this, I ran ls on the directory to get a list
of files. These roughly break down to the following categories:
Note that after deleting the intermediate output files, I started to get fopen() errors. The code is written to check for errors, and behave sensibly when the files don't open, but recent versions of PHP are throwing exceptions, which produce bogus error messages. The easiest way to fix these problems is to run make.
Data input files: These are field/record tables, which are typically emptied (or for critics commented out).
albums: One line per album. Zero out and rebuild from scratch as needed. (Some 2025 albums will get new votes, but I'm not encouraging that, and there's no need to preserve ID numbers.)
ballots-in: Multiple line blocks for each critic's ballot. Zero out. Since file is sorted by critic name, it might be convenient to include critic names in comments, but I haven't been doing that, and I'm not sure whether doing so might break. Not a big problem as is.
critics: One line per critic. Comment out each line, then uncomment as needed. I've kept ID numbers constant over the years, even though nothing depends on this.
footnotes: One per line, keyed to category and album number. Zero out.
oldvotes: One per line, keyed to category and album, used to add extra votes from previous year or wrong category. We don't credit old votes for mid-year poll, but it still might be useful for category mishaps. Zero out.
log-ballots: Not an input, but used to keep a plaintest log of incoming ballots (cut-and-pasted from email, with some markup to aid searching). Zero out, then insert critics list, which can be searched to keep the file in sorted order.
t: Template for entry ballots-in. Edit to delete [VDL] lines, as we're not processing special categories this year.
excludes: List of files (patterns) to be excluded when creating an archive of the directory. This is used by make when run from superior directory. No change?
Website presentation files: These are *.php files, starting with the home page (index.php) and including everything linked from it, plus include (*.inc) and stylesheet (.css) files used by web pages.
index.php: Home page. Minimal edits are to change date and add "Mid-Year" where appropriate, and remove to obsolete links. More detailed edits follow (more will eventually be necessary).
critics.php:
totals-new.php: Present totals table for New Jazz Albums.
alist.php: This prints out lists of albums that have received votes, without vote totals. This was made available through the voter notes, especially to provide a prompt on possible Debut albums. Unclear how useful this will be in the future, given that I've dropped the VDL categories.
album.php: Prints out list of voters for any given album. Page is empty without an album parameter, so unclear what (if anything) to do. We could, of course, delete the VDL categories.
std.inc: Common PHP code included in every web page.
std.css: Common CSS code included in every web page. No changes as yet.
std-ballots.inc: Extra functions for formatting ballot array pages. No changes as yet.
std-ballots.css: Extra CSS for formatting ballot array changes. No changes as yet.
Note that the following files were formerly used, but will not be used in this Mid-Year poll, or most likely in future EOY polls. While the infrastructure code remains in place, We might as well delete them here, rather than try to keep them current for no good reason:
Essays and documentation: These are also *.php files, but stand apart from the ballot tabulation. Essays are typically restarted from scratch with new each poll. Others may be edited, more or less substantially.
rip.php: I haven't been updating this file for Mid-Year polls, but it wouldn't be a bad idea to make a pass at this. Updated year, adding "So Far" as appropriate. Updated link to Jazz Passings. Deleted all table data. Left commented-out sections intact. I went ahead and added some names.
invite.php: This is the reference version of the standard invitation to vote, which will be sent out to the jazzpoll email list. I did considerable editing to this file.
notes-album.php: Edited from album-notes.php. Deleted the entire Debut section. Retained the following sections, with minor edits, while dropping all previous examples:
notes-admin.php: Based on admin-notes.php. Old text is commented out.
notes-install.php: Details on setting up the poll. Roughly based on similar install-notes.php file, but rewritten from scratch.
notes-voter.php: Based on voter-notes.php. This has been extensively rewritten.
invite2.php: This is the "short" version of invite.php, used for sending reminders. I'm not sure that I need this. For now, I just copied invite.php. I'll edit it down later.
I deleted last year's essay files:
Programming infrastructure: Makefile and various programs run from it (usually *.sh scripts).
Makefile: I had clean-temps set up to list (not delete) the temporary files. I copied that rule, renaming the list version list-temps, while changing clean-temps to delete the files. (Previous note suggests that the file list is "partial," so I should beware that.)
mkball.sh: Script run by make to make ballot and totals pages. Note that this still processes [VDL] lines, but none will be present. That should be harmless.
mkcrit.sh: Script run by make to make the files used by critics.php.
Output files: These are generated by the programs, based on the inputs. These can be listed using make list-temps, and removed using make clean-temps. These files are all removed. The initial list is:
albums.out albums.sort b.tmp ballots-[01]*.php critics.count critics.menu critics.out critics.urls totals-new totals-old totals-debut totals-latin totals-vocal totals-*.inc
It may help to manually initialize some of these files to avoid PHP script errors when fopen() fails to find the file. As I find them, I'm adding @ to the PHP code, which also works. The files will all exist once make is run.
Other stuff: during the course of a poll, the directory collects other scratch files, which are not part of the website. As a general rule, there is no reason to carry these forward.
NOTES.php: Originally used by TH to document any discrepancies and inconsistencies in data provided by FD, only thing here is a detailed configuration of the Mailman list, which exists elsewhere. Deleted.
mkdiff.sh: Utility script, runs diff between albums and albums.out. Unclear what this is good for. Deleted.
mksub.sh: Utility script. Unclear what this is good for. Deleted.
std-ext.inc: Orphaned PHP code. Deleted.
std-vl.inc: Orphaned PHP code. (Appears to have been started to implement a voter list option, but contains nothing of practical value.) Deleted.
menu.inc: Orphaned PHP code, accessed by std.inc function old_new_header_block() via new_menu_block(). I think it's safe to delete this file, and the two std.inc functions.
faq.php: Earlier attempt to document the poll with a Frequently Asked Questions list. It's been hit-and-miss (as nobody asks questions), and changes from year to year (e.g., the first question is "Why is December 1 the cutoff date for separating release years?"; it no longer is). Contents had been commented out, and links suppressed. Let's just delete it.
comment-notes.php: Outline for essays and invitation for submitting comments. This never amounted to much in 2025, and doesn't seem to be worth the effort. Deleted.
email-addrs, email-merewitz: Old voter tracking files. No need here. Deleted.
jpmedia-list: Scratch file. Deleted.
menu-test.php: Scratch file. Deleted.
ncinvite.php: Non-critic ballot invitation. Obsolete idea. Deleted.
playlists.php: Unused essay. Deleted.
ref-comments.php: Part of 2025's comments experiment. Deleted.
ref-voters.php: Unused table. Deleted.
tmp-downbeat*: Scratch files for DownBeat voter info. Deleted.
wikiobits25: Obituary data scraped from Wikipedia. At some point should be regenerated, but not here. Deleted.
Deleted forwarder for jcp to Francis Davis.
Added forwarder for 26votes to Tom Hull.
We have three GNU Mailman lists set up:
jazzpoll: All current voters in good standing, minus anyone who objects. We don't actively purge the list of people who stop voting, unless we see bounced emails, or have other reasons (like someone dies). This is a closed list, with subscription by invitation only. Only the adminstrator can send to the list. All other posts are blocked and discarded. Mail frequency is typically once per week in season, rare otherwise. List membership is ? as of 2026-06-07.
jpadmin: This is a list of voters (plus a few more) who are interested in poll administration details and have volumteered to help. Subscriptions are by administrator only. This is an open discussion list, so anyone who subscribes can send to it. Mail frequency increases from every 2-3 days early in season to daily late in season, plus a few scattered messages out of season. List membership is ? as of 2026-06-07.
jpmedia: This is a list of publicists and possibly others who do not vote in the poll but take an interest in following it. This is a closed list, but perhaps should allow for open enrollment. Only the administrator can post this list. All other posts are blocked and discarded. Frequency is undetermined. It was lightly used last year. List membership is ? as of 2026-06-07.
I also have several Thunderbird lists, where Jazzpoll is approximately equal to the jazzpoll Mailman list. Aside from identifying correspondents, these are used by MailMerge to generate personalized invitations. While it's easy to create these messages and store them in the drafts directory, it is tedious to send them out one-by-one via Yahoo (which throttles sends). I would like to avoid having to do this for the Mid-Year Poll, but they have a better track record of delivery than the Mailman list.
Once voting is closed, the website needs additional work to prepare for publication. The following was copied from the 2025 file. It will need to be edited for the present poll, but can stand for now.
Let me go back and try to organize this again:
totals-new.php: First step is to uncomment last year's notes, then remove last year's note data.
Most of this section is commented out.