You may be curious about the tools documentation we copied to the “ToolsDoc” directory/folder. While in theory you should be able to use Workbench to open these, it works better from the AmigaShell. Try this for example.
cd Workbench:ToolsDocs multiview lha.guide
Use the “Browse >” button to escape from the title page of this document and you will see some text and some buttons. If you click on the button starting “1.1” you will see a short section of text. Click on “Retrace” to go back to the previous page, and if you like do the same with the other buttons.
If you click on the “Index” button you will see a sort of contents listing, with “1 Introduction” being the section you last saw. You can click on the button to visit that section again, or more interestingly click on the “2 Reference guide” to explore how to use the “LhA” archiver tool. Try the “2.3” and then “2.3.2” buttons/links to see quite a good description of “pattern tokens” including “wildcards”. We used “#?” before so look into “2.3.2.1” for the question mark and “2.3.2.3” for the hash mark. The Amiga can be told to use asterisk for a wildcard from version 2 of the operating system, but the default is the classic “#?” pattern.
Close the documentation window and try the following.
multiview blink.doc
In this case, with this being just a plain text document, all you can do is scroll through the document. The navigation buttons seen previously do not appear. The Amiga program MultiView can view multiple types of document, by default allowing sampled sound files, AmigaGuide documents, simple animated graphics, a specific type of “movie” file called CDXL, a limited type of formatted document, Amiga “ILBM” format picture files, as well as plain text files. It can also be extended, for example to add JPEG/JFIF files, PNG files, MP3 files, even MPEG movies.
For normal text documents within the AmigaShell you can still use the “more” command as found in most operating systems, but try to get used to using “MultiView” instead. As well as being able to scroll it can handle much more than a plain text file.
Let’s take a look at the C compiler documentation folder though…
dir vbcc:doc
It includes some PDF files. MultiView is helpless when it comes to these, and while there are PDF viewers available on the Amiga platform, it is probably easier to just copy these back outside of our emulated environment.
copy vbcc:doc/#?.pdf xfer:
Try taking a peek at the vbcc.pdf file and locating the AmigaOS/68k section of the C library documentation (section 12.5). Scroll down a little to find the section on “Minimal Startup” (12.5.6) and look at the example demonstration of using only Amiga functions and nothing from the standard C library.
You will notice it doing almost everything shown in the assembly language test we did – it opens dos.library, gets the output handle, writes the message out to that handle, and closes the dos.library afterwards.
Now let’s look at little bit at the “dos.library” documentation. We’ll use the “Redit” editor because we want to search within the file easily.
Redit Work:NDK39/Documentation/Autodocs/dos.doc
Hold the PageDown (substitute for right-hand Amiga key, used for menu shortcuts) and press F. Type in “library/Output” into the find box and click on the “Find next” button twice. The second click will take a while to search. Close the find & replace window and scroll down the file a few lines. Observe the SYNOPSIS.
SYNOPSIS file = Output() D0
This indicates that the Output() function takes no parameters and returns a file handle for output. It also indicates that in calls from assembly the result is returned in the D0 register. Now try a search for “library/Write”. Just one click of the “Find next” buttons will do the trick as we have moved past the contents at the top.
SYNOPSIS returnedLength = Write( file, buffer, length ) D0 D1 D2 D3
Sadly Redit uses “narrow tab stops” so the alignment is a bit messed up… Using the “vim” editor shows it as intended… Using a UK keyboard with the emulated Amiga set to American keyboard access the ‘\’ character with the ‘#’ key.
vim Work:NDK39/Documentation/Autodocs/dos.doc /library\/Write / /
You should see the correct alignment. In this example it wasn’t too bad with the wrong tab widths but sometimes it helps to be able to see the intended formatting.
returnedLength = Write( file, buffer, length ) D0 D1 D2 D3
If you go back to the assembly language test program you will hopefully see how before “CALLDOS Write” we set the D1, D2 and D3 registers.
You could also use the more command. In the below we tap space after the first search to move beyond the contents page.
more Work:NDK39/Documentation/Autodocs/dos.doc /library/Write /library/Write
Alternatively after the more command tap space six times to work past the contents list (you should see “dos.library/AbortPkt” at the top) before typing one search string. In this case the “more” command is useful because of the search feature.
Try also looking up the OpenLibrary call from the “exec.doc” file and compare against the assembly language test code.
We’ll leave off here by letting you check out the documentation for ColdReboot system call from exec.library. You’re welcome!