The On-line help system

[colorrr]

This thread is to discuss how to do the online help system, the text source, mechanics and the interface.

As Chris says in the manual thread, the source for the manual and the on-line help should be the same to avoid duplicating the same text.


The source:

I suggest defining a set of simple text formatting rules, and use an XML file to define the text and its format. Later the online help and the manual can read those file to produce the output. This way, if something changes in the text it is automatically updated the next time someone accesses the manual or the help.
We could also use a simple text file, but since XML is bascially a simple text file with some more formatting rules, it sounds like a more robust choice.
A database could also be an option, MySQL is a free database that could be useful.


User interface:

There are several options here. We could opt for simple web pages, or/and we could make a thin Java client that connects to the clash site and reads the necessary files, then formats them using the rules defined. This Java client could be incorporated into the game itself. We would need to think more about what to do when a user is offline: maintain a off-line version with an upgrade button that connects via internet is an option.


Coding:

This depends on how we decide to implement the on-line help system, but right now Java or PHP seems like useful candidates.
Java: Servlets would be great, but that means we need a web server with an application server, not only the HTTP server.
PHP: plugs into an existing HTTP server and it's free.


Mechanics:

How should the user be able to navigate the help? What should be available in the help?

[Mark_Everson]

Re: The On-line help system

Thanks for taking this on Jorgen!

Originally posted by colorrr
I suggest defining a set of simple text formatting rules, and use an XML file to define the text and its format.

So long as you and Chris are both happy with the format, this sounds fine. But you need to work together on this aspect...

There are several options here. We could opt for simple web pages, or/and we could make a thin Java client that connects to the clash site and reads the necessary files, then formats them using the rules defined.

IMO we'd better just stick with a plain simple web page. Too many bells and whistles would IMO slow things down. I assume the client stuff can be done as a retro-fit later if we need it.

Coding:

This depends on how we decide to implement the on-line help system, but right now Java or PHP seems like useful candidates.
Java: Servlets would be great, but that means we need a web server with an application server, not only the HTTP server.
PHP: plugs into an existing HTTP server and it's free.

Best take this up with Gary to see what will fit best. Generally I would prefer pure java just for simplicity.

Mechanics:

How should the user be able to navigate the help? What should be available in the help?

I don't use that type of system much, so I'll stay out of that one!

[Gary Thomas]

The on-line help we have been talking about is on-line in the sense that it is built into the game. We aren't talking about on-line in the sense of being connected to the internet. There is a system of Java help available, though, to be honest I don't know a lot about it, and I don't have my reference books available right now.

So we would expect it to be a Java exercise, without the assistance of a browser!

Cheers

[LDiCesare]

I agree with Gary. This is online in-game, so it'd better be java for coding simplicity.
I'd also avoid databases since that would be needed on client and this is far too big to have in the game.

[colorrr]

Ok, so we are talking about a type of Clashopedia, a help system to be called from the game. I do not have much experience in that, as some suggested. They were probably refering to my client/server experience, which would be very useful if we were to do a server based internet help system.

How is this going to be integrated into the system?
I suggest making a separate Swing client that can be started separately or from within the game, with or without context sensitive help.
In the future this could also contain options for downloading the latest version of the manual text from a server somewhere.

Any thoughts on the layout of the help system?

I remember someone commenting that Clash would have a help system much better than in the Civ games.
In my opinion the help in these games is pretty good as it is, exactly what were the thoughts behind this statement?

Jorgen

[Mark_Everson]

Originally posted by colorrr
I suggest making a separate Swing client that can be started separately or from within the game, with or without context sensitive help.

Sounds good to me. I think it would be valuable to be able to leave it up and switch to it as needed. What do others think?

Any thoughts on the layout of the help system?

IMO the first thing to do is to look into JavaHelp and see if it can give us something useable long-term. IIRC Plutarck and Gary have already mentioned it in the Manual thread. It already has a layout that makes some sense. However its not very "sexy", at least in the screenshots I've seen.

I don't know if you can automatically link tooltips to the help system or not, but that seems useful to me. The idea is the player looks at a tooltip, and if that isn't enough info, clicking while the tooltip is up would bring them to more detailed help. But I'm not really familiar with the tooltips, so this might not make sense...

[LDiCesare]

I agree a Wing app that could be plugged in game or standalone would be nice.

[Gary Thomas]

And I definitely agree.

[colorrr]

Good to know we agree on the client interface.

Do you have any standards on the interface design, or do I just make something up myself?

I'll check out the javahelp.

Color

[colorrr]

Since last time I have been talking with Chris and thinking a bit.

The first ideas were to define an XML-format for the help text. On the other hand the help system is made in an html format.
Since the two are related, I think the best idea here would be to join the manual and on-line help into one. Like a Clashopedia or a Clash bible, call it what you like.
Since The manual is already done in html, and this is a pretty good & well known format to make good looking documents, I think we should stick with that. No need inventing a complicated format to save the text & image layout with XML.
Now how could we incorporate that into a help system in the game?

Somehow the idea of using a help interface as an intermediate between the game an the manual seems like the best option to me. We use a Swing client that can be opened up standalone or as a window inside the game. The first option is a simple main() method, in the second option I visualize (code wise) the Clash program calling a static function of the help "server" class to show help on a specific item.
How that item is to be passed is yet to define.
I guess it depends on how and when help is called in the code. Gary, LDiCesare and other coders, I need your input here.
Could be :[list=1][*]A predefined constant identifying the desired help item[*]An object contaning the necessary information to reference the help information[*]The object that is the focus of the help request (the calling class?).[/list=1]

Option 1 would make for a huge list of constants.
Option 2 would imply making a system of classes to represent each help item in the game.
Option 3 would mean that when a help event is registered in the game somewhere, the source object is passed to the help system. Every object that needs help implements a help interface (a java interface object, not a user interface). The help system checks if the passed item implements the interface, if not a simple "There is no help for this item" message is shown. The help interface assures that the calling object contains the necessary reference information to encounter the help information. This sounds like the most flexible option as it means it would not be neccesary to create more classes or change any code in the help system everytime an object gets the help capability added.
In order to save the necessary information I would stick with a simple XML format like this:
- Help item identifier (hardcoded in option 1, 2 or 3).
- Topic search text.
- Short in game help text.
- Tooltip help text (are we going to use this???).
- link to manual page containing this subject.
The help item identifier would be hardcoded into the help system with option 1 & 2, and in the source class with option 3.

So when a user requests help clash shows a quick help text for that item, with a link to the manual pages for an in-depth explanation (as far as the manual goes in depth on that subject). Clicking on the link to get the manual page could mean one of 2:[list=1][*]Opening up an external browser client with the html help page[*]Showing the html page inside the client itself[/list=1]

Option 1 would mean opening up another operating system window. And a browser is a bit of overkill.
Option 2 sounds more elegant, but it would be necessary to incorporate some classes that read and show HTML pages. If the necessary classes does not exists as freeware somewhere, making them I would not consider an option.

This is where I am so far, I am really a bit stuck here with taking the decision on how to show the html manual pages, so any ideas or comments are welcome.

Color

[Gary Thomas]

Since the two are related, I think the best idea here would be to join the manual and on-line help into one. Like a Clashopedia or a Clash bible, call it what you like.

I entirely agree with this approach.

Since The manual is already done in html, and this is a pretty good & well known format to make good looking documents, I think we should stick with that.

Again, the best way to proceed.

Somehow the idea of using a help interface as an intermediate between the game an the manual seems like the best option to me. We use a Swing client that can be opened up standalone or as a window inside the game. The first option is a simple main() method, in the second option I visualize (code wise) the Clash program calling a static function of the help "server" class to show help on a specific item.

This is a clean way to separate the help code from the game code.

A predefined constant identifying the desired help item

No! This adds a level of dependency, it is hard to understand, fragile, and against the whole spirit of Java.

An object contaning the necessary information to reference the help information

Better, but will require a very large (and unnecessary) set of classes, one per help message.

The object that is the focus of the help request (the calling class?).

This is certainly my preferred option. I would, however, like to minimize the burden on the game code. We will need to be a bit careful here. A lot of the objects in the game code are static or ephemeral, neither of which will work very well with this system. Rather than anchor the help system to objects generally, I would be more inclined to anchor it to the visible Swing components, since it is these components that the players sees and reacts to.

In order to save the necessary information I would stick with a simple XML format like this:
- Help item identifier (hardcoded in option 1, 2 or 3).
- Topic search text.
- Short in game help text.
- Tooltip help text (are we going to use this???).
- link to manual page containing this subject.
The help item identifier would be hardcoded into the help system with option 1 & 2, and in the source class with option 3.

Not sure what is meant here.

So when a user requests help clash shows a quick help text for that item, with a link to the manual pages for an in-depth explanation (as far as the manual goes in depth on that subject).

I do really like this concept.

Opening up an external browser client with the html help page

A possibility, but probably slow and ugly.

Showing the html page inside the client itself

I prefer this option.

Option 1 would mean opening up another operating system window. And a browser is a bit of overkill.

I agree.

Option 2 sounds more elegant, but it would be necessary to incorporate some classes that read and show HTML pages. If the necessary classes does not exists as freeware somewhere, making them I would not consider an option.

The classes exist in javax.swing.text.html. Have a browse - I think that everything we need to show the html is there.

Cheers

[colorrr]

Thanks for responing in such detail Gary.

Originally posted by Gary Thomas
This is certainly my preferred option. I would, however, like to minimize the burden on the game code. We will need to be a bit careful here. A lot of the objects in the game code are static or ephemeral, neither of which will work very well with this system. Rather than anchor the help system to objects generally, I would be more inclined to anchor it to the visible Swing components, since it is these components that the players sees and reacts to.

Since the programmers of the main code choose which objects needs help or not, I think your opinions are covered.
The objects that wants help needs to implement the help interface, which the programmer has to add to the the desired object. There is a little problem to resolve, and that is if you have a swing component, and need to add help interface. Maybe creating a class that inherits the swing component and implements the help interface is a solution.

> In order to save the necessary information I would stick with a simple XML format like this:
> - Help item identifier (hardcoded in option 1, 2 or 3).
> - Topic search text.
> - Short in game help text.
> - Tooltip help text (are we going to use this???).
> - link to manual page containing this subject.
> The help item identifier would be hardcoded into the help system with option 1 & 2, and in the source class with option 3.

Not sure what is meant here

I place of storing the help information for each help item in the class, I want to save it in an XML file so that the text is separated from the code. That way, if any changes are made to the help text, it is not necessary to touch the code.
The items are the information deemed neccesary to save for each object. What each class would need to store in the code is the help item identifier, so that the help system can find the information from the file. This would be part of the help interface that the class would need to implement.

About the tool tip help text, I would like to know if we are going to use this feature in our game.
The topic seach text is what is used to find this item when you use the help system to search for other items.

I'll have a look at the html classes. Thanks for the tip!

Jorgen

[Gary Thomas]

There is a little problem to resolve, and that is if you have a swing component, and need to add help interface. Maybe creating a class that inherits the swing component and implements the help interface is a solution.

All the swing panels we use are already extended from the JPanel class, so there is no problem here.

I place of storing the help information for each help item in the class, I want to save it in an XML file so that the text is separated from the code.

I understand now. The identifier will need to be a string, for visibility and comprehension.
In passing, I am very keen to include a possibility of translation to other languages, so I would push for all the text that the user sees to be in a form that is readily translated. I am uncertain whether resource bundles are the right way to go, but they should be considered. Look up Locale in the java classes.

About the tool tip help text, I would like to know if we are going to use this feature in our game.

The short answer is "Yes".

Clearly some of the items in this XML file will also be Locale sensitive. Notably the tooltip text and the search words.

Cheers

[colorrr]

Originally posted by Gary Thomas
All the swing panels we use are already extended from the JPanel class, so there is no problem here.

That sounds good, but ..
What if you want to get help on a button?
Or a text field inside a panel somewhere?
Since the way of adding the help capability is adding an interface and a class can implement various interfaces it would not interfere with the inherit option of the class. That would be no problem for the main panels that you create if you inherit them from a Swing component (JPanel); you just add the interface.
However if you create an instance of a JTextField or JButton to represent something in the game and you would like to get help on that item you cannot just add the interface since you are working with an instance of a Swing component, not a class inherited from that component. We would need to figure out that one.
That's where an intermediate class like "JButtonWithHelp" that inherits the the swing component and implements the help interface could be a solution. You would need to instanciate that class instead of the swing component class.
What are your thoughts on this Gary? Is there a better solution?

In passing, I am very keen to include a possibility of translation to other languages, so I would push for all the text that the user sees to be in a form that is readily translated. I am uncertain whether resource bundles are the right way to go, but they should be considered. Look up Locale in the java classes.

That should not be any problem. Would be the same XML file with a different name, and changed text, except the identifiers that stays the same.

Clearly some of the items in this XML file will also be Locale sensitive. Notably the tooltip text and the search words.

That should be possible to include in the help engine.


There is one more item. I suspect that this file might get big after a while, in which the reading of the file and the xml parsing might take some time. Dunno if that will be an issue.


Color

[Gary Thomas]

That's where an intermediate class like "JButtonWithHelp" that inherits the the swing component and implements the help interface could be a solution. You would need to instanciate that class instead of the swing component class.

That had not occurred to me, but your solution is a good one.

We have to decide what fires the help (right click menu? F1 click? both? some other mechanism?). Since that is what will trigger the help request, I have a little bit of difficulty seeing where the interface comes in.

I suspect that this file might get big after a while

Have you checked out Sun's JavaHelp system or the book on the subject "Creating Effective Java Help" by Kevin Lewis (O'Reilly). There are samplles available at the O'Reilly web site for the book. Both sites have downloads.

Cheers