[Coco] NitrOS-9 Technical Reference

[Greg Law]

I just finished splitting the NitrOS-9 Technical Reference on the NitrOS-9 wiki page (https://sourceforge.net/apps/mediawiki/nitros9/index.php?title=NitrOS-9_Technical_Reference) into sections organized by chapter. When you click the link, you’ll be taken to essentially the table of contents in which you can click through to any of the available chapters. Also note that when you click on the System Calls chapters, all system calls, get status codes, and set status codes are broken out into individual pages. This means F$Link is on a page by itself.

I did it this way for a few reasons:

Although the NitrOS-9 Technical Reference is rather small in book standards, it’s huge in wiki standards and takes a long time to save in the bulk format primarily because wiki software has to diff the changes on every save (and some diff algorithms are less efficient than others).

I think this gives a somewhat cleaner organization that lets us focus on a specific section (although I admit this may not be so great if you want to read the whole thing from top to bottom) and it makes finding and editing a lot easier.

The most important reason in my mind is that it lets me break out links to system calls and status codes across all pages in the wiki. For example, I$Read and F$Link in the kernel chapter now actually link to the system calls and I plan to extend these links to other pages as appropriate.

One thing you’ll notice is that there are a lot of dead links on the System Calls page. This is because I initially created all links to the pages based on the OS9Defs file (or os9.d as it is named now). I included all of the SS.* codes in both the GetStatus and SetStatus sections and then filled in the pages based on whatever documentation I could find. The next step is to go through all the code to find out where these are defined and then to put together the missing documentation based on the actual implementation in the code.

Once this finished (and it’ll take a while to root through the code), I’ll remove any dead links (links to GetStatus code that exist only as SetStatus and vice versa) or add annotations that these apparently don’t exist (so the documentation matches os9.d).

On another note, does anyone know of a way to preprocess the defs files with the actual values emitted in the assembler listing? I was hoping I could use lwasm –l –P os9.d or mamou –p –l os9.d to have it emit the RMB values so I don’t have to do it by hand, but I haven’t been able find the magic incantation to make either assembler to do this. This would make it significantly easier to pull out documentation for the remainder of the defs files.