cpm3help/README.md

# 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
* Wayne Warthen (wwarthen@gmail.com)
* Anna Christina Naß (acn@acn.wtf)