AmigaGuide library bug and inconsistancy

[ssolie]

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...

That does sound logical to me. Tying help to a Screen makes no sense these days.

However, would it not make more sense to implement this functionality in window.class itself somehow?

[trixie]

@ssolie

would it not make more sense to implement this functionality in window.class itself somehow?

Of course, this would be even more logical! The window.class knows everything about the window state so it would mean even less work for the programmer if the AmigaGuide help was provided through the window.class.

I started with the AmigaGuide class as a learning exercise, and don't necessarily need to finish or release it. Having the same functionality in window.class would be perfect, instead of just another dependency. But Rigo is, I believe, pretty much snowed under so I dare not ask him to implement a feature that is not crucial. Frankly, I'd much rather have an updated CodeBench before the end of the year

On second thoughts - considering that AmigaGuide is neither a modern or at least cross-platform standard, nor it seems to be developed any further - it may be just the right time to muse upon:

• whether we still want AmigaGuide as the standard for Amiga documentation and help, and what we can do to improve it (because it does need improvement - both the format itself and the OS infrastructure that supports it);
• whether it wouldn't be a better idea to adopt a different format, instead of hardcoding into window.class a format that saw its heyday fifteen years ago.

[xenic]

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.

If you tie the context to a particular window, what happens when a program has multiple windows? MUI has builtin Amigaguide help that works like this:
You set the context by adding a line like: MUIA_Application_HelpFile, "Program.guide", to the application object initialization code and a line like: MUIA_HelpNode, "window-node", to window object intitialization code. The resulting behavior is that a press of the Help key in any window opens the guide at the node describing that window and subsequent Help key presses from other windows simply change the node in the already open guide. When the program is iconified or moved to another screen, the Amigaguide is closed but not automatically reopened when uniconified or opened on another screen.

Since so many of our important programs (YAM, MUI-OWB etc,) are MUI based it wouldn't hurt to have Reaction Amigaguide help work in a similar fashion for the sake of consistancy. In order to avoid a complete redesign of you class at a later time it might pay to think beyond a single window at the beginning of development. You might be better off passing a NULL pointer for the window in all cases and use some notification mechanism that passes the "Help" key input (and window identification ?) from any program window to your class. I don't know much about Reaction so my comments my seem rediculous but I think it would be useful to consider how your class would be applied to a program with multiple windows.

[trixie]

@xenic

Unlike MUI, ReAction has no class for applications, of which all program windows are children. So associating a help file with the application is something that ReAction is currently incapable of, because it doesn't know what an application is.

[xenic]

would it not make more sense to implement this functionality in window.class itself somehow?

Of course, this would be even more logical! The window.class knows everything about the window state so it would mean even less work for the programmer if the AmigaGuide help was provided through the window.class.

I started with the AmigaGuide class as a learning exercise, and don't necessarily need to finish or release it. Having the same functionality in window.class would be perfect, instead of just another dependency. But Rigo is, I believe, pretty much snowed under so I dare not ask him to implement a feature that is not crucial. Frankly, I'd much rather have an updated CodeBench before the end of the year

On second thoughts - considering that AmigaGuide is neither a modern or at least cross-platform standard, nor it seems to be developed any further - it may be just the right time to muse upon:

• whether we still want AmigaGuide as the standard for Amiga documentation and help, and what we can do to improve it (because it does need improvement - both the format itself and the OS infrastructure that supports it);
• whether it wouldn't be a better idea to adopt a different format, instead of hardcoding into window.class a format that saw its heyday fifteen years ago.

I seem to have finished a response that appeared after responses from you and Solie and now seems a little out of context. I will add that a lot of major applications currently in use with OS4 use AmigaGuide documentation and those programs are unlikely to be replaced any time soon. If AmigaGuide had the capability of including images mixed with the text, I think it would serve as well as any completely new method. I don't object to the idea of a new standard of documentation but I think it should be suitable as a seperately readable document and used in context from a program like AmigaGuide. OS4 programmers barely have the time to work on programs, let alone 2 sets of documentation. Some old programs used Texi documentation which could be converted to AmigaGuide, HTML etc. using the makeinfo command included in the texinfo package released by Solie in 2006. If we get a new documentation standard it would be handy if it could be easily converted into other document formats.

[chris]

@ssolie

would it not make more sense to implement this functionality in window.class itself somehow?

Of course, this would be even more logical! The window.class knows everything about the window state so it would mean even less work for the programmer if the AmigaGuide help was provided through the window.class.

I started with the AmigaGuide class as a learning exercise, and don't necessarily need to finish or release it. Having the same functionality in window.class would be perfect, instead of just another dependency.

It could be integrated quite nicely into window.class with a WINDOW_HelpGuide tag to specify the AmigaGuide document filename. Individual gadgets could have a GA_HelpNode (or IA_HelpNode) tag to specify which node of that document to open. I suppose a WINDOW_HelpNode might be useful too, to provide a default other than "Main".

I think an external amigaguide.class is fine for now, and that can then be utilised by window.class and gadgetclass through tags like the above at a later date, and probably very easily.

On second thoughts - considering that AmigaGuide is neither a modern or at least cross-platform standard, nor it seems to be developed any further - it may be just the right time to muse upon:

• whether we still want AmigaGuide as the standard for Amiga documentation and help, and what we can do to improve it (because it does need improvement - both the format itself and the OS infrastructure that supports it);
• whether it wouldn't be a better idea to adopt a different format, instead of hardcoding into window.class a format that saw its heyday fifteen years ago.

As xenic says, the ability to inline images into AmigaGuide documents is the main thing that is missing. If you're going for a very context-sensitive help where individual gadgets have their own nodes, anything more complicated than AmigaGuide is completely unnecessary (full documentation can always be PDF or HTML, neither of which are really suitable for context-sensitive help). I doubt the OS4 devs have the time or resources to write a replacement anyway.

Also, there's no reason why a WINDOW_HelpFormat tag couldn't be added at a later date to choose a format other than AmigaGuide.