115 lines
3.2 KiB
Markdown
115 lines
3.2 KiB
Markdown
# 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)
|
|
|