MajorCool Help

MajorCool is a Web interface to the Majordomo mailing list management tool. Whereas Majordomo is a rather unforgiving command-driven application that utilizes e-mail for effecting changes, MajorCool adds a Web-based front-end to provide a user-friendly interface to list manager operations.

Rather than focusing on command syntax, MajorCool is designed around the practical activities of mailing list access such as browsing, modifying, creating, renaming, and deleting.

- "Browsing" is an end-user activity, allowing users to examine lists and change their subscriptions.
- "Modifying" is a list-owner function, enabling users to change the behavior of the lists that they maintain.
- "Creating", "Renaming", and "Deleting" are site-maintenance actions for adding new lists, changing list names, or deleting those no longer in use.

Each of these modes are optional, since the site administrator may elect to disable support for certain modules. They are accessed through the URL that MajorCool was installed as -- `/cgi-bin/majordomo` by default. In addition, multiple installations of MajorCool can be supported on the same system, each with its own unique URL. For instance, it is not uncommon to see the BROWSE and MODIFY modules split into separate MajorCool installations. (If some actions are unavailable in your instance of MajorCool, check with your site administrator to see if there might be alternative URLs available.)

The selection of actions is made from a menu-based interface (with the desired modules chosen via a button-bar), or full-screen with all actions visible on the main page. The display of menu- vs. full-screen is defined by a per-user Preferences setting. Since the menu interface is the default presentation, all references to MajorCool actions in this guide will be shown relative to menu mode. Pressing a menu button will take you to the appropriate module; the current module is indicated by a "depressed" (gray) button. What follows is a description of each available mode.

###

BROWSE mode is the act of viewing list information and/or changing subscription status to the lists served by Majordomo. In order for the browsing process to begin, the user is first queried for his/her e-mail address. The user also has the option at this time to limit the browsing to:

- lists currently subscribed to by the user
- lists currently unsubscribed to by the user
- list names or descriptions matching a search string
- all available lists on the server

To say that the user is prompted for an e-mail address may be an over-simplification, depending upon the installation. Although an e-mail address is required, how that address information is obtained is ultimately up to the site administrator. MajorCool has the ability to query external address mapping functions via it's `siteaddr()` interface, so it may be that a particular site prompts instead for a username, letting the defined mapping function produce a valid e-mail address in return.

When the "go" button is pressed, the e-mail address (or other appropriate value) is processed by the defined `siteaddr()` function to produce an address search string. This will be used to compare against the addresses in the Majordomo lists. A set of valid list-names will be displayed as a result. Since a `siteaddr()` function can produce an address pattern as well as a fixed string, the matching method allows MajorCool to catch multiple addresses that a user might be subscribed under rather than just a single address as is typical for Majordomo.

If "QuickView Mode" is selected prior to invoking the BROWSE, list subscription tests will be disabled, thus speeding access to the list overview at the cost of disabling subscription changes at the global list level. Even when in QuickView mode, the user will still have the ability to alter subscription choices at each individual List Detail view.

#### Subscribe/Unsubscribe Screen

If the "Find" option is used with "Exact Match" enabled, and assuming such a list exists, the user is taken directly to the List Details screen. In all other cases, the result of a BROWSE action is to display a set of list names (matching the selected criteria) as a table of checkboxes, list names, and list descriptions. The list names are hyperlinked to allow a drill-down to additional list details.

After modifying subscription selections via checkbox, the user applies the changes and the submission is compared against the last known subscription selections. Any changes will be converted into the appropriate Majordomo '`subscribe`' or '`unsubscribe`' commands using the user's "primary address" (as defined by the `siteaddr()` results).

If subscription tests were disabled via the "QuickView" option, there will be no checkboxes on this screen to indicate membership or allow the user to toggle subscriptions. Subscription changes, however, are available at the Details view for each list.

#### List Details

Drill-down to a particular list shows additional list information such as the list-owner address, access to the list's `info` and `intro` files, list membership, and other subscriber details. Depending on the security restrictions of the browsed list and how much the site administrator "trusts" its users, selected list details will either be presented onscreen or returned to the user via e-mail.

A button is available in the Detail view to toggle subscription status, allowing the user to subscribe using the primary address or unsubscribe the current subscribed-as address.

If the user browsing the the list has knowledge of the admin password, the Details screen also provides an entry-point into the MODIFY mode for the displayed list.

When viewing list subscribers, if the list contains other lists as members ("nested lists") the entries will be shown in bold or as hyperlinks, depending upon current preference settings. If linked, further drill-down will access the detail or subscriber screen for that nested list (also controlled by preferences).

###

The MODIFY module provides access to the list-manager functions for a selected list. The user is prompted for a list name (via typed entry or pull-down menu) and the list password. The list administrator has the option of choosing to modify the:

- list configuration options
- list subscribers
- list info file
- list intro file
- list approval queue

When the "go" button is pressed, the password is validated and, if successful, the user is given access to one of the following list configuration functions:

#### Configuration Options

From the CONFIGURATION OPTIONS screen, administrators can change configuration items such as list description, subscription policy, approve password, and much more. HTML buttons and other elements are used to simplify configuration for the beginner. Majordomo configuration option keyword entries are heavily commented, and MajorCool provides onscreen display of this field-level "help".

Admins can access a simplified set of list config keywords (defined by the site owner), the entire set of Majordomo keywords, or only those pertaining to a specific subsystem.

Although it is not the intent of this guide to provide a Majordomo tutorial, here are some list-management concepts to be aware of when configuring your list. Options in the Majordomo list configuration file control behaviors such as:

- Majordomo Access Control
  Subscriber Control
    List owners have the ability to define who may subscribe or unsubscribe to their lists. Options range from wide-open (allowing anyone to join) to closed (where any attempt requires your approval).

  User Access
    Various areas of a list configuration can be restricted from public view. Access to details such as list membership and `info` files can be disabled, granted only to list members, or completely unrestricted. List names can even be hidden from view based on the originating address.

  Passwords
    The administrator password controls who has the ability to alter list characteristics. Anyone with knowledge of this password can make configuration changes. The approval password overrides moderation and other checks & balances when sending mail to a list. Anyone with knowledge of this password can post freely to the list.

- Posting Checks & Balances
  Moderation
    The practice of having one or more persons (the moderators) read and approve each message addressed to the list rather than allowing messages to pass freely. Posting is only allowed for those who know the password. This allows the moderator(s) to protect the subscribers from accidental or inappropriate messages.

  Restrict Post
    Similar to moderation, restricted posting limits who can send mail to a list. Posting is only allowed for those whose originating address matches the addresses in one or more "restrict_post" lists. A typical configuration might be to set the "restrict_post" list to the list itself in order to restrict posting to list members only. This prevents non-subscribers from interjecting into a forum.

  Administrivia Filtering
    Refers to a very limited form of moderation. The administrivia filter is a subsystem that attempts to detect Majordomo commands or requests that are intended for the list manager but are often sent by accident to the entire list. When the administrivia filter is in use, it examines each message addressed to the list for the presence of certain trigger words (such as '`help`' or '`unsubscribe`)' and forwards any such message to the moderator for a decision as to whether the message is actually intended for the list. Messages that do not trigger the administrivia filter are sent directly to the list with no intervention.

- Message Processing
  Headers & Footers
    Majordomo can modify messages as they are being sent to include new mail headers, message footers & fronters, and subject modifiers.

  Archiving
    The practice of keeping old mail messages that were sent to the list in a disk file for future reference. Archives are accessible via the Majordomo '`index`' and '`get`' commands.

  Digesting
    The process of combining multiple messages sent to the list into a single mail message. Some people find it more convenient to receive a single consolidated message than each of the messages individually. Many lists have a regular and a `-digest` form, allowing users to subscribe to whichever delivery method they prefer.

When changes are made to the config file and submitted, the update is carried out by sending a '`newconfig`' command to Majordomo.

Additional buttons are provided on the Options screen that will take the administrator to the other areas that can be modified (e.g. the list `intro` file or the list itself).

#### Subscriber Administration

The SUBSCRIBER ADMINISTRATION screen allows the list admin to view and modify the members of the list. Any changes submitted are converted to the appropriate '`subscribe`' or '`unsubscribe`' command and issued to Majordomo with the '`approve`' qualifier.

#### Info File

The `$list.info` file is sent to all new subscribers, or returned by request via the '`info`' command. Presence of a `$list.intro` file will override the use of the `$list.info` in the new subscriber greeting.

The INFO FILE page allows the list admin to view and modify this `$list.info` file. If changes are submitted, a '`newinfo`' command is issued to Majordomo.

#### Intro File

The `$list.intro` file is sent to all new subscribers, or returned by request via the '`intro`' command. Presence of a `$list.intro` file will override the use of the `$list.info` in the new subscriber greeting.

The INTRO FILE page allows the list admin to view and modify the `$list.intro` file. If changes are submitted, a '`newintro`' command is issued to Majordomo.

#### Approval Queue

If the installed version of Majordomo supports it, MajorCool will also provide an APPROVAL QUEUE option. The "approval queue" is where Majordomo stores messages that were sent to the list but require moderator approval before posting (e.g. moderated lists, administrivia checks, etc).

Normally, these messages are returned in their entirety to the moderator, who must then manipulate mail headers prior to sending the message back to the list. MajorCool eliminates the need to play with e-mail and instead offers push-button approval via the Web.

Access to the approval queue off the main screen is via the `admin_pass` or the `approve_pass` password (this is the only operation that accepts the moderator password in addition to that of the list owner). Examining the queue will show all pending messages as identified by the sender, subject, date, and message-id of the mail.

The administrator has the option to View or Edit the content of the messages prior to taking action. Such actions include approving, deleting, rejecting, or holding the message:

- The act of approving the message simply sends the mail on to the list with the appropriate `Approved:` header line added. Approved messages are removed from the queue once processed.
- Deleting a message from the queue removes the file; no message is sent to the list, and no acknowledgement is returned to the sender.
- Rejecting a message returns the message to the sender with a list of possible reasons for rejection. If an explicit reason is needed, the moderator should add via the Edit function.
- A message left in the Hold state will remain pending in the queue until another actionable operation is selected.

When editing messages in the Approval Queue, it is important to understand that the functionality is largely browser dependent. Large files, when loaded into a browser window, can be a very memory-intensive operation for the client.

#### Change List Password

If the site administrator has so chosen, the changing of the list-admin password can be moved to a "safer" double-entry method in this form. This section is not present if the option is disabled.

Normally, the password change is implemented as a config file update via the '`newconfig`' command. However, if MajorCool detects the presence of a legacy `list.pass` file, the deprecated '`password`' command is used instead. The exception to this is if MajorCool detects the implementation of the "master password file" technique of `list.pass` linked to a read-only `MASTER.PASSWD`.

#### Initiating A Digest

If the list is a digest, the owner is provided with a button to create a digest -- combining all unsent messages into a digested collection -- and sending that mail to all digest subscribers.

#### Send Full Config

The final form available at the list configuration level is the SEND FULL CONFIG BY EMAIL which simply issues a '`config`' command to retrieve the current configuration file in the user's name.

###

The CREATE form is provided to allow users and administrators to request that a new Majordomo list be created. The user is prompted for the list name, description, admin password, and list owner address. This request will be sent to the `Majordomo-owner` address. Alternatively (depending on the setting of `list_create_cmd`), the collected data can be passed on to an external program for more flexible and automated request processing.

The list name should consist of alphanumeric characters (a-z, 0-9), underscores (_), and hyphens (-). Only lowercase names are allowed, since sendmail will convert any address to lowercase prior to delivery.

The list description is a one-line text phrase to help clarify the purpose of the new list, since the character restrictions imposed on list names can often make them appear quite cryptic.

Every list must have a password associated with it. This password controls access to the list maintenance functions. No one can make any changes to the list (approving the addition/removal of members, updating the configuration, etc) without knowing the password. Do not pick obvious words, and if you must write it down, keep it in a safe place.

There must be an email address for the list owner. The list owner is the person who will have the duties of controlling any aspects of list operation which are not handled automatically. At the most basic level, these duties will include dealing with errors and mail delivery failures. Depending upon the configuration of the list, tasks may also include such actions as moderation and administrivia filtering.

###

The RENAME form is provided to allow administrators to request that an existing Majordomo list be renamed. The user is prompted for the list name and admin password. This request will be sent to the `Majordomo-owner` address. Alternatively (depending on the setting of `list_rename_cmd`), the collected data can be passed on to an external program for more flexible and automated request processing.

###

The DELETE form is provided to allow administrators to request that an existing Majordomo list be deleted. The user is prompted for the list name and admin password. This request will be sent to the `Majordomo-owner` address. Alternatively (depending on the setting of `list_delete_cmd`), the collected data can be passed on to an external program for more flexible and automated request processing.

###

The PREFS module is used to provide per-user Preference settings to all MajorCool users. Preferences are implemented via HTTP "Cookies" and are persistent across sessions. Settings are available to control admin keyword help, sorting options, and even module presentation in full-screen or menu modes.

### General Options

`Allow Browser To Cache Pages`
  Browsers can, in the interest of performance, save visited pages in their cache for easier recall. In the case of MajorCool, a cached page may reflect the state of some Majordomo data relative only to the current MajorCool session, even though changes may have been performed via e-mail or other Web users. With the Cache setting, users may enable or disable the caching of page data depending upon their own personal preferences. If caching is disabled, "backing up" to a previous screen will require the browser to re-query for current data.

`Enable Style Sheet Font Control (Where Supported)`
  If your browser supports HTML 4.0 "Style Sheets" (CSS), you may tailor the font family and point size used on all MajorCool pages to suit your liking. This preference can be used to toggle CSS support.

`Default Font Face & Point Size`
  Requires CSS support in the browser and the above Style Sheet Font Control preference enabled. Since not all browsers support Style Sheets or some of the referenced fonts, these settings will have no apparent effect if unsupported.

`Use JavaScript Enhancements`
  JavaScript offers some neat user-interface "bells & whistles" such as the ability to update the browser status line or swap images when "moused over". Most browsers will ignore what they can't understand, so there is no harm for those applications that do not support JavaScript. Naturally, none of these effects are particularly critical to the operation of MajorCool, but they are certainly "cool". However if a user finds them more "annoying" than "cool", they can be disabled.

`Sort Subscriber List in BROWSE and MODIFY Views`
  With large lists, it can be difficult at times to locate specific addresses for verification, modification, or deletion. Users may prefer to have the subscriber list sorted (using the site-configured `by_siteaddr()` function).

`Use 'Menu' Style User Interface`
  MajorCool can display configured modules (e.g., BROWSE, MODIFY, CREATE, DELETE, and PREFS) in two ways. In "Menu" mode, a selection of buttons is present across the top of the screen, with the 'active' (i.e., selected) action occupying the space between the header and footer. The alternative to Menu mode is to forego the button-bar and the concept of an 'active' action, showing all available actions on the main page. Menu mode is enabled by default.

`Default Action for Menu Mode`
  When in "Menu" mode, the initial screen shown on start-up or restart will be the first available module from the list of BROWSE/MODIFY/CREATE/DELETE. This preference is used to override that ordering and start specifically at a particular module. For example, in a BROWSE/MODIFY configuration, a list owner may choose MODIFY as the preferred action if that is the most frequently performed MajorCool activity. Selecting a module that has been disabled by the site admin will have no effect.

`Default Screen Width`
  The default screen size of MajorCool is designed to easily fit on a 640 pixel wide screen typical of most personal computers (your browser window may need to be widened accordingly). You can set your own desired pixel width, or even have the data follow the current width of the browser by setting the width to '100%'.

`Use Images for Form Buttons`
  MajorCool can be very graphics-intensive, all the way down to its use of images for traditional SUBMIT buttons. Some people find the plain-Jane SUBMIT/RESET buttons more effective (not to mention faster to load), so the use of images for FORM buttons can be enabled or disabled.

`Tool Tips on Button Bars`
  Tool Tips are available on the top (Menu Mode) and bottom button bars. Simply hold the mouse over the button and a window will pop up describing its function in more detail. Tool Tips require JavaScript Enhancements enabled (above).

### Browse Options

`Show Nested Lists As Hyperlinks`
  Subscriber lists may contain other local lists as members. These can be displayed as hyperlinks to facilitate the browsing of the nested list details.

`Link to Subscribers When Following Nested Lists`
  Nested lists can be linked to either the Detail view of the referenced list, or directly to the subscriber list itself. Detail view is the default link type.

`Show Line Numbers In Subscriber List`
  The subscriber list can be displayed with line numbers to ease viewing/searching. Note that these line numbers are not stored as part of the Majordomo list and are not permanently bound to individual addresses. In other words, the subscriber #1 in "sorted" mode may not be the same as subscriber #1 in the unsorted display.

### Modify Options

`Use 2-Column Table For Configuration File`
  MajorCool will, by default, display the list configuration file as a 2-column table: keywords on the left, values on the right. Although this makes it easy to locate keywords, it can make for a very wide display. If disabled, a more compact single-column format is used.

`Show Help With Configuration File Fields`
  Majordomo provides field-level help descriptions as comments in the list config file. If Help is enabled, these comments will also be visible on-screen when editing the list configuration. Since these comments use a significant amount of screen real estate, experienced users may disable their display.

`Show Majordomo Subsystem For Each Configuration Field`
  Majordomo consists of multiple subsystems -- the aliasing/address setup, the archive program, the digest program, the Majordomo command processor, and the list itself. This option will indicate which subsystem each keyword applies to.

`Maximum Size Supported By Browser TextArea`
  List member files are edited using what is called a TEXTAREA element. On many browsers, the number of bytes that can fit within a TEXTAREA is limited, which can cause a problem when managing lists with many subscribers. Changing the value of this Preference will not change the capability of the browser -- only the manufacturer can do that. However, what this value will do is implement a threshold at which MajorCool will attempt to take alternative actions in order to get around the limitation. Alternative actions include switching to 'append' mode, or editing a subset of the list that matches a pattern.