Here's some basic stuff to get a grip of things and get some background on Systers Mailman.
To the standard Mailman, Systers has added some features. These include dynamic lists, essays for subscribing, the use of Open ID to log in, the use of different email addresses - so called aliases - for sending emails, allowing the list creator to chose some of the things a subscriber has to supply to subscribe to a list and adapting certain texts the subscribers see, such as the footer of emails going out.
What dynamic lists are
Dynamic lists, or dlists, is a feature added by Systers. It allows the subscribers of a list to create new threads or conversations in the list. Each subscriber can choose to get or not to get new conversations as well as to (un)subscribe from/to the conversations as well and not just to the entire list. To send emails to a dlist, subscribers have to add +new in the email address and they can also add a name for the new conversation. This differs from the non dynamic lists (non dlists) that only allow subscribers to post to listname@domain and not to listname+new@domain or listname+new+name@domain. The information about the dlists, such as what thread the subscribers are subscribed to or what extra aliases they use, is handled in a separate postgreSQL database added by Systers.
Common variables in the code
A few terms often seen in the code are the following three, each with different use.
Essays
An essay is a set of questions that can be asked by the listadmin, which has to be answered by the subscriber in order to subscribe. The essay feature can be enabled by the list creator when creating the list, and at the same time the list creator can choose which questions to ask. The default when enabling this feature are the questions used for the Systers maillist but by simply editing the field with the questions the list creator can choose to have other questions instead. The field takes markdown syntax and if only plain text is entered, it will appear as just such. If the essay feature is enabled the subscribers can't subscribe to the list without entering at least some text in the appropriate field. Should list creators not want to have an essay, they can simply mark this when creating the list and ignore the questions field.
There are a few files that have been edited or added by Systers for dlists that differ from non dlists. The files added by Systers include its own runner and an extra database and the visible things include a change of the listinfo page (used to subscribe to a list) and the footer of emails.
DlistRunner
The dlistrunner handles and enables the threads for dlists. It directs emails from/to a dlist to enable checking of new threads (using +new in the email address creates a new thread). It also handles who is subscribed to each thread and should receive what message.
PostgreSQL Database
To deal with, among others, the threads or conversations, Systers has added a database in PostgreSQL. Each list has its own database containing information about who is subscribed to what conversation and with which other aliases can a subscriber send emails and still be allowed to post to a list.
Listinfo page
The listinfo page where users can subscribe to a list has a different list email address for dlists, which is given on the page. For dlists as well as for non dlists the creator of the list can chose to activate the essay feature, which is not in the standard Mailman. All listinfo pages are generated from the same template, listinfo_allow_essays.html, whose underlying python code checks the settings made when the list was created and generates the listinfo page each time the page is visited.
Footer of emails
In the emails sent out via a dlist, the footer is changed to give information on different features of the dlist. For instance, users can unsubscribe from a single conversation if they wish to, instead of unsubscribing from the entire list. The footer is (for dlists) stored in the mlist object and included by /usr/local/mailman/Handlers/Decorate.py. All mlist objects have the same footer.
Options Page
To the options page, Systers has added the possibility to add different aliases with whom the subscriber can send emails to the list. This feature is called “other incoming address” and is handled through the postgreSQL database.
The listinfo page as well as the options page and the subsciption results are all generated with the help of CGI. A html template file for each of these three can be found in /usr/local/mailman/templates/en. To get the appropriate information for the template, a number of “replacements” is applied to the template. These replacements are placeholders for variable content and the replacement mechanism implemented uses a dictionary in the function GetStandardReplacements in /usr/local/mailman/Mailman/HTMLformater.py. In the HTMLformater, the dictionary replaces the fields in the template with whatever information was saved when creating or editing the list. Most of the replacements are the same for all lists, only some can be adjusted to eg. change the standard appearance of the list. For example, the appearance changes if the list creator chooses to add an essay field or not.
When a new option is created, a couple of files need to be edited. First, depending on whether the option is for the listinfo page or the options page, either listinfo.py and subscribe.py or options.py need to get a “replacements['<new_option_name>'] = value” added. In create.py, the new option needs to be added to the mlist object to be accessible later on. To get the value for the mlist object, it's a good idea to use the function cgidata.getvalue('new_option_name', “default”) which retrieves the information needed. Futher down in create.py, if you wish to implement something that should be used for all lists after they have been created, you can add, for instance, a radiobutton or a textfield. Just follow the examples that are already in the code. Add the option you want to implement in the html template file and later use the replacement function to adapt the value of it. Typically, HTMLformater.py does not need to be edited since its GetStandardReplacements function just takes care of the standard replacements and not the edited ones.