1
0

README added

This commit is contained in:
acn 2020-03-18 15:37:21 +01:00
parent b325379050
commit 622ab0f96e
2 changed files with 117 additions and 11 deletions

View File

@ -1,8 +1,3 @@
# Also: help.raw => 0:HELP.DAT, "HELP [C]", to re-create HELP.HLP if 'makehelp'
# doesn't produce a working HELP.HLP file.
#
# Paragraphs may be justified using "par j".
HELPS = \
cpm3/*.help \
romwbw/*.help
@ -10,13 +5,13 @@ HELPS = \
all: makehelp help.hlp
help.hlp: $(HELPS)
cat $^ | unix2dos >help.raw
./makehelp help.raw >$@
@rm help.raw
cat $^ | unix2dos >help.dat
./makehelp help.dat >$@
# @rm help.raw
makehelp: src/makehelp.c
$(CC) -o $@ $^
clean:
$(RM) help.hlp help.raw makehelp
$(RM) help.hlp help.dat makehelp

115
README.md
View File

@ -1,3 +1,114 @@
# cpm3help
# 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)
CP/M 3 help files, including a help file converter