AmigaGuide library bug and inconsistancy

[xenic]

Someone at Amigans.net wants to open an AmigaGuide at a specified node from CLI and when I looked at the autodocs it looked like a simple task. However, there seems to be a bug in OpenAmigaGuide() or the autodoc is incorrect. The short example for OpenAmigaGuide() shows the return value (AMIGAGUIDECONTEXT) being checked for an error condition (which I assume is to be reported to the user). If there is no error then CloseAmigaGuide() is called. The problem is that a value is always returned even if there is an error (bad filename etc.). Also, the CloseAmigaGuide() autodoc specifies that it should be called to close a synchronous or asynchronous client. Since OpenAmigaGuide() is synchrouous and doesn't return until the client is closed, closing it with CloseAmigaGuide() makes no sense. Please copy & compile the source of the small command I wrote and test it to confirm these bugs. The command will not report an error if the amigaguide file doesn't exist, the node doesn't exist or the pubscreen doesn't exist. According to the docs and example that should not be the case. I'm listing my source instead of the autodoc example so it can be easily copied and compiled for testing:

Code: Select all

/* compile: gcc -N -O2 OpenGuide.c -o OpenGuide -Wall -lauto */

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/amigaguide.h>

#define TEMPLATE "NAME/A,NODE/K,PUBSCREEN/K"

enum
{
	OG_NAME, OG_NODE, OG_SCREEN, OG_MAX
};

int main(int argc, char **argv)
{
	int32 args[OG_MAX] = {0};
	struct RDArgs *argsdata;
	char *screen = NULL;
	char *node = NULL;
	struct NewAmigaGuide nag = { 0 };
	AMIGAGUIDECONTEXT handle;


	if (argc == 0)
	{
	IDOS->PutErrStr("Error: Shell program\n");
	return(RETURN_ERROR);
	}

	argsdata = IDOS->ReadArgs(TEMPLATE, args, NULL);
	if (!argsdata)
	{
	IDOS->PrintFault(IDOS->IoErr(), "Error");
	return(RETURN_ERROR);
	}

	if (args[OG_SCREEN]) screen = (char *)args[OG_SCREEN];
	if (args[OG_NODE]) node = (char *)args[OG_NODE];

	nag.nag_Name = (char *)args[OG_NAME];
	nag.nag_PubScreen = screen;
	nag.nag_Flags = 0;
	nag.nag_Node = node;
	nag.nag_Client = NULL;

	if((handle = IAmigaGuide->OpenAmigaGuide(&nag, NULL)))
	{
	IAmigaGuide->CloseAmigaGuide(handle);
	}
	else
	{
	IDOS->PrintFault(IDOS->IoErr(), "Error");
	if (argsdata)  IDOS->FreeArgs(argsdata);
	return(RETURN_ERROR);
	}

	if (argsdata)  IDOS->FreeArgs(argsdata);
	return(RETURN_OK);
}

[trixie]

@xenic

Since OpenAmigaGuide() is synchronous and doesn't return until the client is closed, closing it with CloseAmigaGuide() makes no sense.

Yes, you are right. This is indeed stupid. EDIT: On the other hand, my testing suggests that manually closing the client window does not free the AMIGAGUIDECONTEXT, as allocated by OpenAmigaGuide(), so calling CloseAmigaGuide() actually does make sense here.

Talking about AmigaGuide Library bugs and features - is it normal that OpenAmigaGuide() opens my client window just right, while OpenAmigaGuideAsync() opens nothing, despite me receiving an AmigaGuideMsg with agm_Type == ActiveToolID (indicating that the AmigaGuide asynchronous process has been started successfully)? The autodoc suggests, and existing code examples clearly show, that both functions should do the same, the only difference being the synchronous/asynchronous access. Is there a bug in the OS4 implementation of OpenAmigaGuideAsync() or what? I know that Tom Breeden has been struggling with this too, when working on his GuideMaker.

What I also loathe is that the AmigaGuide Library uses internal values for the client window and doesn't allow customizing its dimensions and position. While in the olden days it was normal, even necessary to open an AmigaGuide window fully sized across the screen, with today's resolutions it lacks sense and only hinders access to the screen. Also, the window opens (vertically) in the middle of the screen bar, not just below it (as used to be the case in OS3) so it appears that the Top position is hardcoded with a value from OS3 times.

[xenic]

Yes, you are right. This is indeed stupid. EDIT: On the other hand, my testing suggests that manually closing the client window does not free the AMIGAGUIDECONTEXT, as allocated by OpenAmigaGuide(), so calling CloseAmigaGuide() actually does make sense here.

I had forgotten about my original post but I'm glad someone finally noticed it. You may be right about the freeing of AMIGAGUIDECONTEXT but I have to wonder about the fact that the context is returned even if there is an error.

Talking about AmigaGuide Library bugs and features - is it normal that OpenAmigaGuide() opens my client window just right, while OpenAmigaGuideAsync() opens nothing, despite me receiving an AmigaGuideMsg with agm_Type == ActiveToolID (indicating that the AmigaGuide asynchronous process has been started successfully)? The autodoc suggests, and existing code examples clearly show, that both functions should do the same, the only difference being the synchronous/asynchronous access. Is there a bug in the OS4 implementation of OpenAmigaGuideAsync() or what? I know that Tom Breeden has been struggling with this too, when working on his GuideMaker.

Since the individual who brought these issues to my attention at Amigans.net wanted to open an AmigaGuide at a
specified node from a shell or script, I wrote a command to accomplish his goal and uploaded the command to OS4Depot (OpenGuide). He also wanted to change nodes through ARexx but I discovered that there were actually 2 ARexx ports associated with the opened AmigaGuide. For example there would be GUIDE.1 and GUIDE.1.1 if you choose the name GUIDE for the ports. Some of the commands must be sent to the primary port and others to the secondary port. Here are the examples I included in the short docs for my OpenGuide command:
rx "ADDRESS OPENGUIDE.1.1;NEXT" (move to next node)
rx "ADDRESS OPENGUIDE.1.1;PREVIOUS" (move back one node)
rx "ADDRESS OPENGUIDE.1.1;RETRACE" (move to last viewed node)
rx "ADDRESS OPENGUIDE.1;LINK mylink" (move to specified node)
rx "ADDRESS OPENGUIDE.1;LINK main" (move to main node)
rx "ADDRESS OPENGUIDE.1;QUIT" (Close the AmigaGuide)

I don't know if there is a reason for having 2 ports or if it is a "bug". Either way, the asynchronous mode may need a command sent to a message port to actually open the window. You might try running Ranger to identify the ports that are opened in asynchronous mode. The autodocs seem to indicate that an AmigaGuide window will open in asynchronous mode but maybe some command may be required. Once again, is it a bug or inadequate documentation? If amigaguide datatype in Multiview worked as documented, we probably wouldn't need to use amigaguide.library. According to the amigaguide_dtc.doc autodoc the same ARexx commands I show in the above examples should work with an AmigaGuide in a Multiview window but they don't. Some work, some don't. Unfortunately, the most important command for program controlled documentation (i.e. LINK) doesn't seem to
work with Multiview.

What I also loathe is that the AmigaGuide Library uses internal values for the client window and doesn't allow customizing its dimensions and position. While in the olden days it was normal, even necessary to open an AmigaGuide window fully sized across the screen, with today's resolutions it lacks sense and only hinders access to the screen. Also, the window opens (vertically) in the middle of the screen bar, not just below it (as used to be the case in OS3) so it appears that the Top position is hardcoded with a value from OS3 times.

Actually there is a way to customize the client window but it is a user setting. If you open an AmigaGuide window with amigaguide.library, adjusting the window position & size and selecting the "Prefs/Save as defaults" menu item will save an environmental variable that specifies the window dimensions. The variable is set on a per screen basis. The Multiview variables are in a Multiview directory in ENVARC: and AmigaGuide variables are in an AmigaGuide directory in ENVARC: so the user may get different window dimensions depending on whether he opens a guide with Multiview or a program using amigaguide.library.

[trixie]

@xenic

Thanks for your feedback!

the asynchronous mode may need a command sent to a message port to actually open the window.

Yes, the asynchronous client window does open on SendAmigaGuideCmd(), but
- the autodoc doesn't mention that this is necessary;
- the fact that two almost identical functions require different code solutions smells with inconsistency;
- this OS3 example suggests that OpenAmigaGuideAsync() should work without calling SendAmigaGuideCmd():
http://aminet.net/package/dev/c/simpleguide1

Actually there is a way to customize the client window but it is a user setting.

Thanks, I didn't know that! You never stop learning.

[xenic]

@trixie
It would be nice if there were a simple way to add AmigaGuide help to Reaction programs In the SDK Reaction example "testapp.c" I see this:

case OBJ_HELP:
___MessageBox("OK",
______"Normally you would display an AmigaGuide with\n" \
______"your application's help page here\n" \
______"However, this is an example only.");
___break;

However, it's unlikely that most amatuer programmers will fugure out how to do that without better documentation and examples. There is this example in the old developer CD:

ADCD_2.1/NDK/NDK_3.1/Examples2/AmigaGuide/AG_V39/Src/aghelp.c

I can see by examining that code that the intent is to open and set up the amigaguide help so that a message can be sent to open the guide when the user presses help. It makes sense, but the OS4 autodocs don't make it clear that opening an amigaguide in asynchronous mode is only a prepatory step for using amigaguide as a help mechanism within a program. Considering the complicated and lengthy code used in the example, it would be useful to have a Reaction class that would handle amigaguide help in a simple and transparent way.

Amigaguide help from within a program would be even easier if Multiview responded to the all the ARexx commands that are listed in the amigaguide datatype autodoc. You could just open a Multiview window and send it ARexx commands when a program user presses the help key.

[trixie]

@xenic

It would be nice if there were a simple way to add AmigaGuide help to Reaction programs /.../ it would be useful to have a Reaction class that would handle amigaguide help in a simple and transparent way.

You must be a mind-reader I actually revived your thread because I had already started working on an AmigaGuide class. The BOOPSI side of things seems to work fine: I can now create the help file as an object, set/get its attributes, and I've also defined methods for opening and closing the client window. The programmer is spared from direct access to internals, like the AMIGAGUIDECONTEXT or struct NewAmigaGuide. The help file is manipulated like any other BOOPSI object.

But then I ran into problems with the asynchronous access, as described above. And if there's something wrong inside amigaguide.library, I'm afraid my class will never work plausibly because it just wraps BOOPSI code around the library.

[kas1e]

@Trixie

And if there's something wrong inside amigaguide.library, I'm afraid my class will never work plausibly because it just wraps BOOPSI code around the library.

But at least if you will find out any bugs in it, they can be reported and maybe fixed And if class will be almost done, i am almost sure that ssolie will help you with getting access to the amigaguide.library source code

[trixie]

@kas1e

I will do some more testing (on both OS3 and OS4) and let you know.

[chris]

You must be a mind-reader I actually revived your thread because I had already started working on an AmigaGuide class. The BOOPSI side of things seems to work fine: I can now create the help file as an object, set/get its attributes, and I've also defined methods for opening and closing the client window. The programmer is spared from direct access to internals, like the AMIGAGUIDECONTEXT or struct NewAmigaGuide. The help file is manipulated like any other BOOPSI object.

Oh, fantastic! I gave up with on-line help through amigaguide.library ages ago, because I couldn't figure out how to use it. I will definitely give this a try on release.

[trixie]

@chris

I gave up with on-line help through amigaguide.library ages ago, because I couldn't figure out how to use it.

Things got even more complicated with the introduction of the new window.class jumpscreen feature. Before, it was common - I'm not saying correct - practice to establish a global AMIGAGUIDECONTEXT and keep it throughout program lifetime. But as the context is always tied to a particular screen, the global context will no longer do good for programs that allow jumping screens. The programmer has to re-establish the context each time the screen changes - otherwise the online help window will open on a different screen than the program.

The intention behind my AmigaGuide class is to hide the context from the programmer completely. Instead of tying the online help to a particular screen, I thought of associating it with a particular window:

• This is more logical IMO: programs that want to open online help through a BOOPSI class will most likely have a window, but may not care about the screen this window runs on. So this solution would enable the class to always determine the current screen from the window.
• Of course I'll need to handle iconified windows correctly...
• For windowless programs, it will always be possible to pass a screen pointer to the class and a NULL pointer for the window. In such a case the class will use the screen specified by the programmer.

Any comments on how the class should be implemented are welcome, of course.