The Help Command

Tom Van Vleck

This note describes the history of the Multics on-line help system.

CTSS proposal for HELP command

When I used the Compatible Time-Sharing System in the mid 60s at MIT Project MAC, many suggestions for system improvements came from CTSS users. I proposed several ideas; some were adopted. One idea that wasn't implemented was a HELP command.

In those days, every CTSS user had a manual, and referred to it often. The first edition of the CTSS manual was a slim paperback called the "candy stripe" manual, published in 1963. By 1965, the second edition of the CTSS manual was published: it was a looseleaf volume, hundreds of pages. The Computation Center published multiple updates to the manual. Toting this manual around and updating it was inconvenient: using a manual in a public terminal room ran the risk that that copy of the manual didn't have the latest updates.

Providing the manual content online would have been nice, but HELP was not implemented on CTSS, for several reasons.

• CTSS was seen as end-of-life by the MIT Computation Center. Users had a manual already. Multics was being worked on and maybe it would be best to defer these ideas until the new system was up.
• Putting the manual content online would be substantial work -- who would do it and how would it be maintained?
• CTSS disk space was very tight. An online manual would take up a lot of space, and would it be worth it?

For more info on CTSS, see the document published by the IEEE Computer Society History Committee in honor of the 50th anniversary of CTSS, titled The Compatible Time Sharing System (1961-1973) Fiftieth Anniversary Commemorative Overview, edited by Dave Walden and Tom Van Vleck.

Multics help command

Later, at MIT Project MAC, I worked on the Multics operating system, and helped launch Multics as a service at the MIT Information Processing Center. I revived and submitted my proposal for a "help" command (MCB-0376, 1969-12-01, Help Command), and this time it was accepted. Many members of the development team contributed guidance and suggestions. The initial version was a small program, maybe 50 lines long.

Every system command had an info segment, stored on disk in a special directory as a text file. (Multics commands had a long name and a short name; info segments had additional names.) Paragraphs were separated by a line with the octal 006 character, ACK, which had the effect of turning the terminal printer back on if it was off. (I suggested this because if you printed an info segment on the line printer, the ACK character didn't print anything.) Info segments had a standard structure with different sections, e.g. Summary, Function, etc. When the user invoked the command, e.g. help pl1, the command would find >doc>info>pl1.info and print the first paragraph, and then ask "More help?" and wait for the user to reply yes for the next paragraph, or q to quit.

Besides commands, there were info segments for general topics, such as General info on path names. Later, we added info segments for every system library subroutine. Individual Multics sites also created local info segments for their administrative topics, phone lists, etc.

People liked the help command and used it often. Multics also had printed manuals, and the technical writing staff created RUNOFF macros so that a single source file could be used to produce both the printed manuals and the info segments.

A few years later, I wrote the check_info_segs command, which checks for info segments that are newer than the "last time checked," which is stored in the user's USERNAME.value segment in his or her home directory. Users could call check_info_segs from their start_up.ec to see a list of changed info segments when they logged in.

Multics system info segments (MR12)

Here are info segments describing the help command and auxiliary commands, as of the final Bull release of Multics.

• Info segment for help
• Info segment for list_help
• Info segment for validate_info_seg

Each Multics release provided manuals.gi.info, a general info segment listing the current versions of all Multics manuals. Specific manuals that were not republished might have an errata file listing corrections, such as errata.ag92.info.

Installation-local Info Segments

Each individual Multics installation could add local info segments for its users. Among others at the MIT site, there were

motd.info	Message Of The Day
mmtu.info	graffiti, see below
sites.info	list of all Multics sites, and their status
crash.info	reverse chronological list of system crashes, date, time, reason
sched.info	system schedule
shifts.info	definition of system shifts
prices.info	usage charges for various resources, per shift

Sadly, none have survived.

Later Improvements

The 006 character turned out to be a dumb idea. I wrote a technical bulletin proposing multiple changes, including replacing 006 by a double newline, to the MCR Board, in MTB-201 Van Vleck -- New Version of the Help Command -- 1975-06-01. This MTB also proposed a way to search info segments for a string, section titles, more responses to more help, and canonical section names. These changes were implemented.

A few years later, Cec Erickson proposed further changes to help, to make info segments easier to generate from RUNOFF and more consistent. MTB-331 Erickson -- Changes and Additions to help -- 1977-03-17 This proposal standardized and improved the info segment layout, and contained a revised command manual section for help.

Later Evolution of help

Here is a list of other Multics Change Requests related to help. (Our list of MCRs is incomplete.)

  MCR-0996-VanVleck  --  Add Selective Printing to Help Command -- 1975-01-28 -- MCR-0996
  MCR-1261-VanVleck  --  Install new program to validate info segments -- 1975-07-08 -- MCR-1261
  MCR-1262-VanVleck  --  Install new version of help -- 1975-07-08 -- MCR-1262
  MCR-1424-VanVleck  --  Fixes and improvements for help -- 1975-09-30 -- MCR-1424
  MCR-1737-Gintell   --  Reorganize info segment directories -- 1976-03-30 -- MCR-1737
  MCR-1738-Gintell   --  Replace all info segments in >doc>info -- 1976-03-30 -- MCR-1738
  MCR-2046-VanVleck  --  Fix bugs in help -- 1976-07-16 -- MCR-2046
  MCR-2146-Herbst    --  Make help accept pathnames -- 1976-08-31 -- MCR-2146

The list_help command was added in 1975. It could scan all system info segments and list those whose name contained a string. Initially it was an Author Maintained command at MIT.

Gary Dixon help was revamped in 1978, in part to properly support info segments describing active functions. The 1978 version also provided a help_ subroutine interface that could be called from interactive subsystems like send_mail, making it easier to provide internal help for subsystem requests. (This was before ssu_ was released; each subsystem writer devised his own mechanism for implementing requests, providing documentation for those requests, etc.)

Shortly after the 1978 version, help_ was tweaked again by me to provide support for documenting a subroutine's entry points in separate blocks of its subroutine_.info seg.

Context

help was an early attempt to think about the large amorphous problem of How Do People Find Out How To Do Tasks. Many of the attempts to make this easier turn out not to work, or not to work for everybody, or cost more than they save. As systems got more complex, and the manual got thicker and heavier, it became less useful to expect everyone to memorize the whole book and keep updating their knowledge in case they needed it.

Command Language

We tried structuring Multics features to make it easier to remember them. We tried to make all commands work the same way and obey the same conventions to make it easier to recall how to use them. (Multics users used to say they enjoyed the regularity and consistency of the command language, and pointed out places where there were inconsistencies.) We tried to construct command names in consistent ways, and a few commands were renamed to better obey these rules: for example dprint became enter_output_request.

The MCR Board had long discussions on how to change the system to make it easier for people to remember and understand it. There was an internal document, Multics Standards SDN, AN82, which provided guidance on naming conventions and consistent behavior.

I remember a series of MCR board conversations about "control arguments." AN82 specified that control arguments could appear in any order and all control arguments affect the whole command execution. In Multics, the command lines print -bf fred.pl1 and print fred.pl1 -bf did the same thing. (This is different from Unix, where options affect only the processing of arguments to the right.) But a few early commands didn't work that way, such as dprint. So dprint joe.pl1 -tlbl SECRET fred.pl1 applied the top label to fred.pl1 only. The command enter_output_request was created and dprint was deprecated but not deleted. See Multics Programmer's manual: Commands and Active Functions, AG92 for more info.

Other systems' Help Commands

The Unix man command took on many of the same problems Multics faced.
- substitute for a manual
- synchronize with OS releases
Doug McIlroy is credited with insisting that Unix have some documentation. The man command appeared in Unix release 3.

Beginning in the 1980s, the Apple Macintosh OS had Human Interface Guidelines that prescribed a consistent user experience.

The Graffiti file at MIT

See also the story about the MIT Graffiti file.

Thanks to Gary Dixon for history and advice.