Multics > People > Stories
29 Nov 2021

The Help Command

History | People | Library | Sites | About Search

Tom Van Vleck

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.

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, and this time it was accepted in 1969. 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.

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.infoMessage Of The Day
mmtu.infograffiti, see below
sites.infolist of all Multics sites, and their status
crash.inforeverse chronological list of system crashes, date, time, reason
sched.infosystem schedule
shifts.infodefinition of system shifts
prices.infousage 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 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 We 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.

Structuring the system to make it easy to remember was one idea. Making all commands work the same way and obey the same conventions makes 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 structure the system to make it easier for people to remember and understand it. There was an internal document, Multics Standards SDN, AN82, shich provided guidance on naming conventions and consistent behavior.

Other systems' Help Commands

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

I think most Unix users don't use printed manuals at all.

Other systems with help... Junky articles on "online help" and "help command" in Wikipedia.

For a while, the Apple Macintosh had Human Interface Guidelines that prescribed a consistent user experience.

The Graffiti file at MIT

In the early 60s, the basement of MIT Building 26 was where users keypunched and submitted batch processing jobs and picked up their output. When their programs failed, they sometimes scribbled their frustration on the walls.

When MIT opened up Building 39 as its new Information Processing Center building in the late 60s, some of the staff were worried that disgruntled batch computing users would trash the nice new walls with graffiti. It was suggested that the staff put up a big sheet of paper on a bulletin board outside the counter where users dropped off jobs and picked up output: people could write whatever they wanted there, and staff would restate the comment and respond. This worked well: taking users' isses seriously and responding moderately seemed to improve communication, and reasonable suggestions were implemented.

But what about Multics, whose time-sharing users never came into Building 39? We set up a mail address mmtu (mene mene tekel uphairsin, the writing on the wall, name suggested by Charlie Garman). Comments sent to that address were anonymized and responded to in mmtu.info, accessible by help mmtu. Users sent mail to an account called something like mmtu, and the anonymized user message and its answer would be added to an on-line info segment. This also worked well.

Thanks toGary Dixon for history and advice.