RKRM - AmigaDOS work in progress

[Olaf Barthel]

Originally Posted by Thomas Richter

Even more so, I'm not even sure whether I would be the right author for the topics you mention as I lack the historic background and thus qualification. That would probably something for Dr. Tim King (and not for Dr. Thomas Richter), if he had any interest.

I would rather hope that dos.library becomes a regular library at some point. Such as "yes, you really must load a6 with the library basis" and "yes, the global vector is really gone now and we can retire support for it". That would be more my party time. (Well noted that OsGrind already checks for these kind of violations - failing to load a6 properly, or attempting to use the GV).

Fair enough, Ralph Babel's documentation on the use of the global vector in the original "Das Amiga-Guru-Buch" (1989) already comes with a caution and "The Amiga Guru Book" (1993) only goes so far as to explain what no longer works in dos.library V36 and beyond.

I won't argue that we lost something there. How the dos.library works is peculiar, though, as most of the legacy and also new functions in V36 pass through the same function invocation mechanism which the BCPL interface used to make use of. This has side effects, such as the InfoData and FileInfoBlock address alignment requirements in Info() and Examine()/ExNext(), respectively, which are otherwise hard to explain in context. TRIPOS favours simplicity in its implementation, and this choice repeatedly comes back to haunt you in the dos.library form, especially the file system interface

Some historic context is given by Dr. Tim King in this [ Show youtube player ], and it explains a lot. Not necessarily something that would naturally fit into the RKM format, though. As strange as dos.library is in context, the mystery of "why?" will linger. I would argue that you can ask the same kind of questions on why graphics.library was implemented that way, with a similar myster of "why?", but dos.library looks, by comparison, much more like an accomplished "juggling act"

[Thomas Richter]

Originally Posted by Olaf Barthel

Fair enough, Ralph Babel's documentation on the use of the global vector in the original "Das Amiga-Guru-Buch" (1989) already comes with a caution and "The Amiga Guru Book" (1993) only goes so far as to explain what no longer works in dos.library V36 and beyond.

I actually never owned the 1st edition and only have the 2nd edition here.


There is minimal information on the Global Vector in my work in section 11.5.4, which describes the Tripos - pardon - AmigaDos internal BCPL runtime binder which is used to populate the GV. It contains just enough information to write a BCPL hander or the CLI, both depending on this legacy interface. Unfortunately, you (still?) need such information if you want to replace the Port-Handler or the "CLI" segment (not the "shell" nor the "BootShell", both of which use "C linkage").


This is more practical information, and it's not found in Ralph's book nor anywere else, yet needed for some functionality. I would not want to go beyond that and explain what the GV entries are, and how to call a BCPL function since nothing depends on this interface anymore, and nobody shall depend on this mechanism anymore, and no advantage can be taken from it anymore.

Originally Posted by Olaf Barthel

This has side effects, such as the InfoData and FileInfoBlock address alignment requirements in Info() and Examine()/ExNext(), respectively, which are otherwise hard to explain in context.

As you know, I'm a "standards guy". In standards, you never explain *why* a particular structure or interface looks as it looks. You describe *how* to use it. The "why" is left to conference proceedings and journal articles. I derivate a little bit from that when necessary, but documented things that should better be left undocumented could motivate some fellow Amiga hack^H^H^H^H programmers to actually use or depend on such mechanisms that should better be removed from future versions, and thus documentation would be "in the way" for forwards compatibility. Be careful what you document, somebody might take it serious.

Originally Posted by Olaf Barthel

I would argue that you can ask the same kind of questions on why graphics.library was implemented that way, with a similar myster of "why?", but dos.library looks, by comparison, much more like an accomplished "juggling act"

graphics and its extensions, in particular those that came in with v36 with its "GfxAssociate()" function and "struct Monitor" is probably another such candidate indeed. Unfortunately, it does not really become much better with rtg graphics on top. graphics is seriously lacking an internal interface for such extensions - or rather, there is a tiny heavily underdocumented interface (struct VecInfo in graphics/displayinfo.h) that is so minimal that it does not serve well and missed some very important aspects. This was already somewhat fixed in v45 aka 3.1.4 with the new AllocBitMapTags() interface which could finally "bootstrap" an RTG viewport, but it is still insufficient in terms of abstracting blitting. This is something we should seriously attempt to fix at some point.



But first things first, I really want to get this book project out of the door, it is a bit more improtant to provide programmers a long missing up-to-date documentation.

[Thomas Richter]

Folks,

went through a third round and fixed a couple of more issues on the way. I also run the spell-checker on it.

Thus, now is the time to report any spelling errors left in the text, and any other issues you find. Things should be in a much better shape now.

Edit: I also added now a cover page and a back page in the RKRM style. It is a tiny little bit customized, but fits quite nicely into the remaining series.

Happy Easter!

Thomas

[Pyromania]

How can I login to check for spelling errors for you. I would live to help out.

[jman]

Originally Posted by Thomas Richter

Thus, now is the time to report any spelling errors left in the text, and any other issues you find

@thomas I was also looking at both covers, they are pretty neat. I think I have a few minor suggestions. I assume you are still working on them?

[jman]

Originally Posted by Pyromania

How can I login to check for spelling errors for you. I would live to help out.

The book source code is located on GitHub at this link. Do you have a GitHub account? It is needed to open an issue and suggest changes (at this link).


If you don't have a GitHub account you can simply download the latest version of the book source code (this link) or of the PDF (this link) and proof-read it. Then probably report here any suggestions.

[Thomas Richter]

Originally Posted by jman

@thomas I was also looking at both covers, they are pretty neat. I think I have a few minor suggestions. I assume you are still working on them?

Yes, I am still working on them, of course. This is not yet the finite version.

[Dunny]

Just had a brief glance and it's very well written. So far just one thing to mention:

"Worth to remember" isn't correct English; should be "Worth remembering".

[Thomas Richter]

Thanks, fixed.

[fgh]

Great work, Thomas!
Here are a few suggestions:

Copyright page:
- ‘The program’ and ‘The archive’ -> ‘The publication’ ?
- There is a mix of lower case and upper case nouns. (Publication/publication, Stick, Disk)
- ‘in and of themselves’ : Sentence is better with this removed


Chapter 1 - Introduction:
- ‘the Tripos’ -> just ‘Tripos’.
- The tripos sentence says ‘Amiga, an experimental OS..’ perhaps rewrite to ‘..nothing but an amiga port of Tripos, an…’ ?
- ‘This book is, similar to AmigaDOS..’ -> ‘This book, like the AmigaDOS manual, is..’ ?
- ‘and answering’ -> ‘and for answering’
- ‘implements interface’ -> ‘implements an interface’ or ‘implements the interface’


Everywhere:
- AmigaOS has lowercase s everywhere.
- 4 uses of ‘obviously’. Has no place in a technical manual in my opinion
- ‘the dos.library’ -> Just ‘dos.library’ most places. (Purpose of the dos.library, the dos.library is, the dos.library does not..’’ etc. )

[Thomas Richter]

Thanks, I addressed most of your comments.

[Thomas Richter]

Today is "Labor Day" in Germany (and not in September, as in the US), and thus it meant some "labor" to continue cleaning up the RKRM AmigaDOS. Actually, lot happened in the last month, and I went a fourth time over the volume, fixing many tiny issues. In particular, I noted that I missed "StrToLong()", and thus also had to insert a subsection on an inverse function, namely how to print an integer to a string, and how to realize a "sprintf()" on AmigaDOS grounds. The index had been improved, false references are hopefully gone, grammar should have improved to a large extend (though note that I'm not a native speaker, so there is probably room for improvement - please report!).

Thus, at this point: Is there anything you still miss? Any function I might have forgotten? Any mistake you might have spotted? Any language issues you noted and want to get fixed? Any topics you believe that should go into the work?

Thanks, and happy to receive your ideas.

Thomas

[Thomas Richter]

A little bit of polish. The book has now a click-able index, and references within the book can now also be clicked on. I also changed the paper format to US Letter (despite my dislike of non-metric systems), but this way it would fit perfectly in the existing RKRM series also printed in letter. If my measurements are correct, even the yellow bar on the back of the book should align perfectly with the existing volumes.

[phx]

The last sentence of 11.6.8 (HUNK_EXT) confuses me:

However, the SAS/C compiler can also be configured to emit such common symbol references
  to implicitly create objects referenced through extern declarations missing a definition.

Being no native speaker I will not try to improve the wording, but it sounds as if you would need

extern int symbol;

to create a common symbol reference, while this actually avoids such a common symbol reference in all compilers.
A common symbol reference may be created by

int symbol;

, though.

Thanks for the acknowledgement in your book, BTW!

[Thomas Richter]

That's from what I remember, but I'll check with the SAS/C manual - namely it could create common symbols (if correctly configured) if you would reference a symbol with extern in all units but had no single definition of such an object. Edit: You are, of course, right. I'll fix that right away, thank you again.