Disk Catalog PDF Doc Improvement

[kiwisincebirth]

I would like to raise an issue (enhancement) to improve the documentation for the project specifically in the Disk Catalog PDF document. This is primarily since I have put some time into this already, and think it can be greatly improved.

What is the Issue

• Firstly it is a bit incomplete, i.e. not all disks are described,
• A lot of files and or descriptions are missing descriptions
• Contains duplicate file information, which makes it harder to maintain this document

Sources for Information

• The "d_*" directories that actually contain a list of the files
• The individual readme files in the "d_*" directories actually contain a lot more information about the files than the PDF document, this is a big source of information
• The "hd_*.txt" files that contain definitions of what is copied onto the disk

Improvements

• Add sections for disks not already described, primary the standalone disks, e.g. d_games
• Create new section(s) which describes common files (e.g. Sound Files, Test Files, SIMH, etc) that are copied to multiple disks
• Remove the duplicate files from the main OS disk listings, and replace with pointers to the Common File sections.
• Copy disk and file descriptions from the individual readme files

Any comments, on how this could be improved. I will attach a sample showing where it is up to.

Mark.

RomWBW Disk Catalog.pdf

[wwarthen]

I strongly concur with the sentiment that the RomWBW disk catalog needs substantial improvement. There have been multiple prior attempts to clean this up. Sadly, none of them have "stuck".

From my point of view, the biggest issue is finding a way to keep the catalog up to date. Improving the content of the catalog is probably just work. Finding a process that makes maintenance of the catalog easier and more foolproof.

I also wish to solicit thoughts and ideas. Improving the disk catalog would greatly enhance RomWBW.

Thanks, Wayne

[kiwisincebirth]

@wwarthen You also made a comment in the document itself:

**NOTE:** This document has become somewhat out-of-date.  I apologize
for this.  It is very difficult to maintain due to the volume of
disk content updates and the way that files are dynamically merged
into disk images during the build process.

One of the primary changes I have made is to break up the content of the disk catalog into various sections, which are referenced , thus there should only be ONE place where a file is defined. e.g. "FDISK80.COM" appears once, previously it appeared 5 times. Thus :

This should hopefully improve the maintainability of the document

Th only downside of this is that the grouping of files in the document follows the underlying structure of where the file appears in the build structure. When reading the document (as a user it is a little arbitrary) e.g. Sections 3.3 and 3.4 specifically.

I have attached a new PDF which show the current state,

RomWBW Disk Catalog.pdf

[wwarthen]

@kiwisincebirth,

Your work on the Disk Catalog looks really good Mark. I like the organization and this would be much easier to maintain. Perhaps a bit harder for a user to find what they want for a specific disk, but the current organization was not very maintainable and so was not very useful.

Thanks! Wayne

[wwarthen]

@kiwisincebirth,

Here are the answers to your questions about the disk content at the end of the document:

In NZ-COM the Submit CPM22 is copied to U0. ALL OTHER CPM22 files are copied to U15 Is this correct, why is this different? Is there a technical readon. d_cpm22/u0/SUBMIT.COM 0:

It is required to be in user 0 to facilitate the auto submit at startup mechanism.

I have noticed ZPM3 distro includes CPM3LDR.SYS and CPM3LDR.COM. These disks already include the correct ZPMLDR.SYS COM files which boots the OS Not shure why both are included, are they included/needed for a specific purpose. Should we remove CPM3LDR.SYS and CPM3LDR.COM from ZPM disk distributions. change to *_zpm3.txt

There have been some issues with the ZPM variants in the past. I think I have fixed all the issues, but I'm not 100% sure. The CPM3 versions were there as a failsafe. Perhaps OK to remove now.

Why are we including sample music files on FLOPPY disk images. Surely these dont need to be here. On smaller media devices space is important Noting None of the Test programs are beeing included, and some music files are already commented (assume for space) on larger distro i.e. ZPM3.

I agree. Probably never gave it much thought.

Thanks, Wayne

[kiwisincebirth]

Hi Wayne, thank for the feedback. I'll submit some Pr,s and raise any further questions on this issue.

[kiwisincebirth]

Ps. Please review the first paragraph under section 5.2, I think there is room to delete several duplicate files from the build?

[wwarthen]

Hi @kiwisincebirth,

With respect to 5.2:

d_zpm3/u15 - Includes a copy of all the files from the CPM3/u0 folder The documentation states this files, stating they come from CPM3. Ideally the CPM3 files in the d_zpm3/u15 (duplicates) should be deleted and the d_zpm.txt fle should copy these files.

Yes, definitely. This should have been done long ago when I did the original dedup effort. I will take care of this myself because I want to review the files included there.

The /Source Apps folder has some off the appications directly in the Apps folder ideally they should be in sub folders, one per app, most but not all are.

Yes, definitely. Originally, all of the Apps were comingled directly in the Apps folder. At some point, I realized that was not a good long-term solution and started using sub-folders. I have never gone back and moved all the other apps to sub-folders, but I should. Feel free to pursue this or I can can look at it in the next few days.

And a couple of applcation are directly in the source folder, event though they are just a Binary Applicaton. TastyBasic is one that comes to mind Although I may be wrong, isnt this also distributed to ROM as an app but still might be better modev to apps folder

I agree, but I need to review this. I think these apps (including TastyBasic) are ROM apps. They may have some references into the HBIOS and may have dependencies on the hardware configuration. This does not mean they shouldn't be moved to a better location, but I need look at what is going on there.

Thanks, Wayne

[kiwisincebirth]

With respect to 5.2:

With resect to 5.2 I will leave this to you to look at for the moment. I have addressed the other items already in PR

[kiwisincebirth]

@wwarthen RE ZPM3

Yes, definitely. This should have been done long ago when I did the original dedup effort. I will take care of this myself because I want to review the files included there.

I would take a look at GENCPM (cpm3 utility) with all its associated files. I don't believe it is functional in (ZPM3) its current form, as it is missing a lot of critical SPR files. However there are a couple of remnants of it. The main GENCPM.COM is in U15, and ../ZPM3/gencpm.dat 0: is copied to U0. This should probably been cleaned up ; or completed and made to work.

[wwarthen]

@wwarthen RE ZPM3

Yes, definitely. This should have been done long ago when I did the original dedup effort. I will take care of this myself because I want to review the files included there.

I would take a look at GENCPM (cpm3 utility) with all its associated files. I don't believe it is functional in (ZPM3) its current form, as it is missing a lot of critical SPR files. However there are a couple of remnants of it. The main GENCPM.COM is in U15, and ../ZPM3/gencpm.dat 0: is copied to U0. This should probably been cleaned up ; or completed and made to work.

Hmmm... I just ran GENCPM on the vanilla ZPM3 drive and it worked. The resultant CPM3.SYS worked. Is it failing for you?

Thanks, Wayne

[kiwisincebirth]

Hmmm... I just ran GENCPM on the vanilla ZPM3 drive and it worked. The resultant CPM3.SYS worked. Is it failing for you?

No you are right, I have been looking at this too long. Will commit shortly. Suggestion would be place GENCPM.COM in U0 for consistency with CPM3. IMHO.