Online HTML vers of A.Mail Vol2, Dev- , HW-, Libs-Manuals and Incl.&Autodocs 2.0/3.5

[Leffmann]

I appreciate this and use it now and then, too. It's great to have it all in one place with a search function. Thanks

[Jasmin68k]

Nice to have indeed, thank you

[JOB]

Thanks a lot. This is very useful, even after all these years

[Steam Ranger]

The two most useful reasources for me when learning to program on the Amiga:
1. These documents and includes, they're so useful!
2. English Amiga Board for when I have no clue what I'm doing.

[kamelito]

Amiga developer CD 2.1 too, I hope that Olsen he’s still working on improving developer material.

[Olaf Barthel]

Originally Posted by Steam Ranger

The two most useful reasources for me when learning to program on the Amiga:
1. These documents and includes, they're so useful!

Yes, but they are also 24 years old and document a state of the 68k operating system, as well as its legacy APIs and data structures, which has been superseded by more modern documentation several times over already (MorphOS, AmigaOS4, AmigaOS 3.1.4/3.2).

While this material, which came from the Amiga Developer CD 2.1 (I compiled that), is old, it's good that it is available in the first place. But it is painful for me to see that this documentation has aged so poorly. The Amiga ROM Kernel manual contents are an adaptation of the contents of the CATS Developer CD V2.0 from 1992, with the original manuscript text converted manually into the 1991 AmigaGuide format. I wrote the tools which converted them into HTML5 files, and they are available in this form on the web site. Let that sink in for a moment...

We ought to have something better than this, both in terms of what is available to developers, as well as what it contains. For example, there is no AmigaDOS documentation on the Amiga Developer CD 2.1 comparable in scope and quality to the Amiga ROM Kernel manual contents because none was available on the CATS Developer CD V2.0.

How to dissuade anybody from trying to develop software for the Amiga? Make her or him start by exploring the wonders of using the dos.library - works every time

[Olaf Barthel]

Originally Posted by kamelito

Amiga developer CD 2.1 too, I hope that Olsen he’s still working on improving developer material.

Yes, indeed. This is what I spent the past few months on, trying to finish the NDK 3.2R5. By accident, the focus of this NDK3.2 update shifted towards improving the dos.library documentation and the 'C' header files. The dos.library documentation has always been lacking, right from the start and while it improved over the decades, the "best" version in NDK 3.2R4 would still contain huge gaps which ought to have been filled a long time ago.

Unless something unexpected happens, you may be able to look forward to see a major rework of the dos.library AutoDocs.

The documentation has been reformatted to improve accessability. More bugs recently discovered (some of them are more than 30 years old) and fixed are now covered in the documentation. There is a completely new introduction to dos.library and its underpinnings, with a large section covering the limitations, unexpected constraints (e.g. stack size requirements, path length limitations and silent truncation) and even advice on what to watch out for, if you want to stay on dos.library's good side (if there is one; this is still part of cutting-edge research).

Every single AutoDoc entry for dos.library has been updated and the relevant data structures, e.g. used by Lock(), Open(), Examine(), Info(), are covered in context. The AutoDoc entries now feature new sections ("warnings" and "notes"), where needed, which describe what pitfalls lie ahead and which complex problems you might face. For example, NameFromLock() can produce path names which will be longer than Open(), Lock() or Rename() can handle. These warnings are repeated in the respective entries, rather than collected in one single section, so that you can look up the respective function and see what might be in store for you. The AutoDocs are supposed to be brief and to the point, but dos.library is arguably an exception. Next to graphics.library, it contains the most complex of the AmigaOS APIs, some of which are poisonously easy to get wrong ever so slightly (such as ExAll()).

The corresponding 'C' header files have been reformatted and updated in order to make them more accessible and provide more context. For example, the relationship between the DosPacket types and the dos.library functions is documented now.

These changes to the dos.library documentation spilled over into exec.library and expansion.library documentation changes, too.