README added

Makefile

@@ -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
 

README.md

@@ -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