1
0
cpm3help/README.md
2020-03-18 15:38:43 +01:00

3.2 KiB

CP/M 3 Help System

In this repository, I want to create help files for CP/M 3 and for RomWBW utilities so that a CP/M 3 RomWBW system can have a nice online help.

The CP/M help system

CP/M Version 3 introduced an online help system: HELP.COM. This uses HELP.HLP as its "database", where all help pages are stored.

To use it, just enter

A>HELP

and HELP will show all main topics that are available.

A specific topic can also be called as a command line parameter, e.g.

A>HELP DIR

will open the help page for DIR.

Help pages can have subtopics, e.g. DIR has "BUILT-IN" and "WITHOPTIONS" as subtopics.

A subtopic can either be called directly from the command line or inside HELP, e.g.:

A>HELP DIR BUILT-IN
HELP>DIR BUILT-IN

or after calling the main topic, a subtopic can be called with a dot as prefix, e.g.:

HELP>DIR
...
HELP>.BUILT-IN

Subtopics by itself can also have subtopics, e.g. DIR BUILT-IN has EXAMPLES as subtopic, here the same applies as before:

A>HELP DIR BUILT-IN EXAMPLES
HELP>DIR BUILT-IN EXAMPLES

HELP>DIR
...
HELP>.BUILT-IN
...
HELP>.EXAMPLES

See the help for HELP for more information :)

Creating HELP pages

A help page file starts with a blank line. The next line start with ///1TOPIC. The content of the page follows.

Subtopics are placed below, starting with a blank line followed by ///2SUBTOPIC. e.g.:


  ///1ASSIGN

  Syntax:

          ASSIGN D:[=[{D:|<device>[<unitnum>]:[<slicenum>]}]][,...]

  ...

  ///2EXAMPLES

  Examples...

Creating the help file database

In CP/M

In the standard Digital Research CP/M 3 source code, all help pages are kept together in one file, HELP.DAT. To create the help database (HELP.HLP), there are two ways in CP/M:

Either use MINHLP.COM to create this file, but I could not find a .COM file of it and had problems compiling and using the PL/M source code file.

The other CP/M way is to use HELP.COM with the parameter [C] which also compiles HELP.DAT to HELP.HLP.

On Linux/Unix

In this repository, the program makehelp is used to compile HELP.DAT to HELP.HLP.

The supplied Makefile contains all steps neccessary:

  • Concatenate all .help files from the subdirectories cpm3 and romwbw to form HELP.DAT
  • While doing this, the line endings will be converted from Unix (LF) to DOS (CRLF) using dos2unix - note that dos2unix has to be available on the system!
  • Run makehelp to compile HELP.DAT

The resulting HELP.HLP can now be copied to the CP/M file system, next to HELP.COM.

License

Makehelp is taken from this repository: https://github.com/durgadas311/MmsCpm3

The license is as following:

Copyright 2011,2017 Douglas Miller durgadas311@gmail.com

Permission to modify and/or redistribute is granted provided no fee is charged, original copyright messages are included, and modifications are submitted back to original author.

The original CP/M 3 help files are Copyright 1980,1984 Digital Research, Inc.

The RomWBW help file contents is in part by